Build Your First Agent in Python
- List the prerequisites for building a Python-based AI agent
- Describe the core pattern of the OpenAI Agents SDK agent loop
- Identify three common gotchas when building a first agent
What You'll Need
Before you start, you'll need:
- Python 3.10+ installed on your machine
- An API key — either an OpenAI API key (platform.openai.com → API keys) or an Anthropic API key (console.anthropic.com → API keys). Both have free trial credits. This lesson uses OpenAI's API; Anthropic's works the same way with different package names. API keys are required — there is no free local option for this approach without substituting an open-source model.
- Basic Python familiarity — you should be comfortable with functions, variables, and importing packages
The Setup
Create a new directory, set up a virtual environment, and install the required packages:
openai— the OpenAI Python clientpython-dotenv— to load your API key from a .env file safely
Create a file named .env in your project directory and add your key: OPENAI_API_KEY=sk-.... Never commit this file to version control — add .env to your .gitignore.
Defining Your Tools
Tools are ordinary Python functions. The key is writing a clear docstring — the model reads it to decide when and how to call your function. A vague docstring produces unreliable tool selection; a precise one with an example input produces reliable results.
For a simple research assistant, two tools are enough to start:
- A
search_web(query)function that calls a search API and returns a list of results - A
get_current_date()function so the model knows today's date
Both functions should return structured text the model can easily read. Avoid returning raw HTML or deeply nested objects — the model will struggle to parse them reliably.
The Agent Loop
With the OpenAI Agents SDK, the core pattern is:
- Create an agent with a name, instructions (system prompt), and a list of tools
- Create a runner and call
run(agent, user_message) - The SDK handles the loop: the model reasons, calls tools, reads results, and continues until it produces a final response
- Inspect the
RunResultto read the final output and the full trace of steps
The first time you run it, read the trace carefully. Watch the sequence of tool calls, the arguments the model chose, and the results it received. This is the fastest way to understand how the loop actually behaves — and to spot where your tool descriptions could be clearer.
Common Gotchas
- Tool description clarity — if your agent calls the wrong tool or skips a tool you expected it to use, improve the description first before changing anything else
- Missing error handling in tools — if a tool throws an exception, the SDK may fail silently; return a structured error string instead of raising
- Infinite loops — set a
max_turnslimit so the agent stops if it gets stuck; the OpenAI Agents SDK supports this natively - Legacy API patterns — many tutorials online use
initialize_agentfrom older versions of LangChain; these patterns are deprecated; check the current docs before copying from a tutorial
What to Build Next
Once your first agent is running, the best next step is to add a third tool that writes output to a file. This introduces the read-modify-write pattern and surfaces how the agent reasons about state across steps. From there, the standard progression is: add memory, switch to LangGraph for more complex flows, and add evaluation to understand where your agent makes mistakes.
- You need Python 3.10+, an API key (OpenAI or Anthropic — both require an account), and basic Python familiarity to build a simple agent
- The core loop: define tools as Python functions with clear docstrings → create agent with instructions → run → read trace and final output
- Tool description quality is the most common bottleneck — when behavior is wrong, improve the description before changing the code
- Always set a max_turns limit and return structured error strings from tools instead of raising exceptions
Progress is saved in this browser only — clear your cache or switch device and it's gone. Create a free account and it follows you everywhere.