Learn › AI Agents: Building & Production › Build Your First Agent in Python

Build Your First Agent in Python

Intermediate 🕐 16 min Lesson 2 of 7
What you'll learn
  • 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 client
  • python-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:

  1. Create an agent with a name, instructions (system prompt), and a list of tools
  2. Create a runner and call run(agent, user_message)
  3. The SDK handles the loop: the model reasons, calls tools, reads results, and continues until it produces a final response
  4. Inspect the RunResult to 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_turns limit so the agent stops if it gets stuck; the OpenAI Agents SDK supports this natively
  • Legacy API patterns — many tutorials online use initialize_agent from 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.

Key takeaways
  • 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
Learn more every week Get 5 hand-picked prompts + new AI tools every Monday. Free.