Introduction
AI agents are no longer just a buzzword — they are the defining technology trend of 2026. From automating customer support to orchestrating complex business workflows, AI agents are transforming how we work and build software. According to recent industry reports, the global AI automation market has surpassed $50 billion, and developers who can build intelligent agents are in higher demand than ever.
But what exactly is an AI agent? At its core, an AI agent follows a simple architecture formula: Agent = LLM (Brain) + Planning + Memory + Tool Use. Unlike a basic chatbot that only responds to prompts, an agent can reason about goals, break tasks into steps, remember context across interactions, and take real actions by calling external tools and APIs.
In this tutorial, you will learn how to build a fully functional AI agent from scratch using Python and the OpenAI API. We will cover everything from setting up your environment to implementing tool-calling, memory management, and a practical agent loop. By the end, you will have a working agent that can search the web, fetch real-time data, and execute multi-step tasks autonomously.
Prerequisites
Before we begin, make sure you have the following:
- Python 3.10+ installed on your system
- An OpenAI API key — you can get one at platform.openai.com
- Basic familiarity with Python programming
- A code editor (VS Code recommended)
Step 1: Set Up Your Project Environment
Let us start by creating a clean project structure and installing the required dependencies.
mkdir ai-agent-tutorial
cd ai-agent-tutorial
python -m venv venv
# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
# source venv/bin/activate
pip install openai httpx python-dotenvCreate a .env file in your project root to store your API key securely:
OPENAI_API_KEY=sk-your-api-key-hereNever hardcode your API key in source code. Using python-dotenv keeps your credentials safe and makes your project portable.
Step 2: Define Your Agent’s Tools
Tools are the “hands” of your AI agent. Without tools, the agent can only generate text. With tools, it can interact with the real world — fetching data, making API calls, and performing actions.
We will define three practical tools: getting the current time, checking the weather, and performing web searches.
import json
import httpx
from datetime import datetime, timezone
# Tool 1: Get current time in any timezone
def get_current_time(timezone_str: str = "UTC") -> str:
"""Get the current date and time for a given timezone."""
now = datetime.now(timezone.utc)
return now.strftime(f"%Y-%m-%d %H:%M:%S {timezone_str}")
# Tool 2: Check weather for any city
def get_weather(city: str) -> str:
"""Get current weather for a city using wttr.in API."""
try:
response = httpx.get(
f"https://wttr.in/{city}?format=3",
timeout=10.0,
headers={"User-Agent": "curl/7.68.0"}
)
return response.text.strip()
except Exception as e:
return f"Weather lookup failed: {str(e)}"
# Tool 3: Simple web search (using DuckDuckGo)
def web_search(query: str) -> str:
"""Search the web using DuckDuckGo Instant Answer API."""
try:
response = httpx.get(
"https://api.duckduckgo.com/",
params={"q": query, "format": "json", "no_html": 1},
timeout=10.0
)
data = response.json()
abstract = data.get("AbstractText", "")
if abstract:
return abstract
related = data.get("RelatedTopics", [])
results = []
for topic in related[:3]:
if isinstance(topic, dict) and "Text" in topic:
results.append(topic["Text"])
return "\n".join(results) if results else "No results found."
except Exception as e:
return f"Search failed: {str(e)}"Each tool function follows a consistent pattern: it accepts clear parameters, performs an action, and returns a string result. This makes it easy for the LLM to interpret the output and decide what to do next.
Step 3: Register Tools with OpenAI Function Calling
OpenAI’s function calling feature lets the model know which tools are available and how to use them. We need to define a JSON schema for each tool:
tools_schema = [
{
"type": "function",
"function": {
"name": "get_current_time",
"description": "Get the current date and time for a specified timezone.",
"parameters": {
"type": "object",
"properties": {
"timezone_str": {
"type": "string",
"description": "The timezone, e.g., 'UTC', 'US/Eastern', 'Asia/Shanghai'"
}
},
"required": []
}
}
},
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a specified city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name, e.g., 'New York', 'Tokyo', 'London'"
}
},
"required": ["city"]
}
}
},
{
"type": "function",
"function": {
"name": "web_search",
"description": "Search the web for information on a given query.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query"
}
},
"required": ["query"]
}
}
}
]
# Map function names to their implementations
tool_functions = {
"get_current_time": get_current_time,
"get_weather": get_weather,
"web_search": web_search,
}The schema tells the model the function name, what it does, and exactly what parameters it expects. The model uses this information to generate properly structured tool calls.
Step 4: Build the Agent Loop
The agent loop is the heart of your AI agent. It follows a cycle of thinking, acting, and observing — similar to how a human would approach a task:
- Think: The LLM decides what to do next
- Act: If the LLM calls a tool, execute it
- Observe: Feed the tool result back to the LLM
- Repeat: Until the LLM produces a final answer
import os
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
SYSTEM_PROMPT = """You are a helpful AI assistant with access to tools for getting
the current time, checking weather, and searching the web.
When a user asks a question:
1. Think about whether you need a tool to answer it
2. If yes, call the appropriate tool
3. Use the tool's result to provide an accurate answer
4. If you need multiple pieces of information, call multiple tools
Always be concise and factual. If a tool fails, explain what went wrong."""
def run_agent(user_message: str, max_iterations: int = 5) -> str:
"""Run the AI agent loop until a final answer is produced."""
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_message}
]
for iteration in range(max_iterations):
print(f"\n--- Iteration {iteration + 1} ---")
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools_schema,
tool_choice="auto"
)
assistant_message = response.choices[0].message
messages.append(assistant_message)
# If no tool calls, the agent is done — return the final answer
if not assistant_message.tool_calls:
return assistant_message.content
# Execute each tool call and feed results back
for tool_call in assistant_message.tool_calls:
function_name = tool_call.function.name
function_args = json.loads(tool_call.function.arguments)
print(f" Calling: {function_name}({function_args})")
# Execute the tool
if function_name in tool_functions:
result = tool_functions[function_name](**function_args)
else:
result = f"Error: Unknown function '{function_name}'"
print(f" Result: {result[:100]}...")
# Append tool result to conversation
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": str(result)
})
return "Agent reached maximum iterations without a final answer."The max_iterations parameter prevents infinite loops. In production, you would also add error handling, rate limiting, and logging. But this core loop captures the essential reasoning pattern that powers even the most sophisticated agents.
Step 5: Add Conversation Memory
A real agent needs to remember context across multiple user messages. Let us wrap the agent in a class that maintains conversation history:
class AIAgent:
"""An AI agent with persistent conversation memory and tool-calling abilities."""
def __init__(self, system_prompt: str = SYSTEM_PROMPT):
self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
self.history = [{"role": "system", "content": system_prompt}]
def chat(self, user_message: str, max_iterations: int = 5) -> str:
"""Send a message and get a response, maintaining context."""
self.history.append({"role": "user", "content": user_message})
for iteration in range(max_iterations):
response = self.client.chat.completions.create(
model="gpt-4o",
messages=self.history,
tools=tools_schema,
tool_choice="auto"
)
assistant_message = response.choices[0].message
self.history.append(assistant_message)
if not assistant_message.tool_calls:
return assistant_message.content
for tool_call in assistant_message.tool_calls:
function_name = tool_call.function.name
function_args = json.loads(tool_call.function.arguments)
result = tool_functions.get(function_name, lambda **kw: "Unknown function")(**function_args)
self.history.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": str(result)
})
return "Agent reached maximum iterations."
def reset(self):
"""Clear conversation history (keep system prompt)."""
self.history = [self.history[0]]Now your agent remembers previous exchanges and can handle multi-turn conversations naturally.
Step 6: Test Your Agent
Let us put it all together and test with some real queries:
if __name__ == "__main__":
agent = AIAgent()
# Test 1: Simple weather query
print("=" * 50)
print("Test 1: Weather Query")
print("=" * 50)
response = agent.chat("What's the weather like in Tokyo right now?")
print(f"Agent: {response}")
# Test 2: Multi-step reasoning
print("\n" + "=" * 50)
print("Test 2: Multi-Step Reasoning")
print("=" * 50)
response = agent.chat("Compare the weather in New York and London, and tell me which city is warmer.")
print(f"Agent: {response}")
# Test 3: Using memory from previous conversation
print("\n" + "=" * 50)
print("Test 3: Context Memory")
print("=" * 50)
response = agent.chat("Based on the weather you just checked, what should I wear if I'm in the warmer city?")
print(f"Agent: {response}")Expected output for Test 2 might look something like this:
--- Iteration 1 ---
Calling: get_weather({'city': 'New York'})
Result: New York: ☀️ +72°F...
--- Iteration 1 ---
Calling: get_weather({'city': 'London'})
Result: London: 🌧️ +58°F...
Agent: Based on the current weather data:
- New York: ☀️ 72°F (22°C)
- London: 🌧️ 58°F (14°C)
New York is currently warmer by about 14°F (8°C). New York has clear sunny skies while London is experiencing rain.Step 7: Going Further — Production Tips
Now that you have a working agent, here are key improvements for production use:
1. Add Error Handling and Retries
API calls can fail due to network issues or rate limits. Wrap your tool calls in retry logic:
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
def call_tool_safely(function_name, **kwargs):
"""Call a tool with automatic retries on failure."""
return tool_functions[function_name](**kwargs)2. Implement Token Budget Management
Long conversations consume more tokens and cost more. Trim old messages when the context gets too long:
def trim_history(history, max_messages=20):
"""Keep the system prompt and the most recent messages."""
if len(history) > max_messages:
return [history[0]] + history[-(max_messages - 1):]
return history3. Add Structured Output Validation
Validate tool call arguments before executing them to prevent injection attacks and malformed inputs:
from pydantic import BaseModel, field_validator
class WeatherArgs(BaseModel):
city: str
@field_validator('city')
@classmethod
def city_must_be_reasonable(cls, v):
if len(v) > 100 or any(c in v for c in '<>{}'):
raise ValueError("Invalid city name")
return v.strip()4. Consider the OpenAI Agents SDK
OpenAI has released the Agents SDK in 2026, which provides a standardized framework for building agents with built-in sandboxing, tool orchestration, and safety guardrails. For production deployments, it is worth exploring as it handles many edge cases that a custom implementation might miss.
Conclusion
Building an AI agent with Python and the OpenAI API is more accessible than you might think. The core architecture is elegant: define your tools, register them with the LLM, and run a loop that lets the model reason, act, and observe. In this tutorial, we built a complete agent from scratch with tool calling, conversation memory, and multi-step reasoning capabilities.
The key takeaways are:
- Tools are everything — an agent without tools is just a chatbot. The more relevant tools you provide, the more capable your agent becomes.
- The agent loop is the foundation — the think-act-observe cycle powers everything from simple assistants to complex autonomous systems.
- Memory enables context — persistent conversation history transforms a stateless API into a coherent conversational partner.
- Production needs guardrails — error handling, token management, and input validation are essential before deploying to real users.
Whether you want to automate your workflow, build a smart assistant, or create the next breakthrough AI product, the skills you learned here form the foundation. Start small, iterate often, and keep adding tools to make your agent more powerful.
Happy building! 🚀