How to Build Your First AI Agent in Python

What we are building

A minimal research agent. You give it a question, it searches the web, reads the top results, and writes a concise summary. It runs as a loop until it decides it has enough information.

Step 1 — Install dependencies

pip install openai tavily-python truststore

Set your API keys as environment variables:

export OPENAI_API_KEY="sk-..."
export TAVILY_API_KEY="tvly-..."

Step 2 — Define the tools

We will give the agent one tool: web search. We define it as a Python function and describe it in the OpenAI tool-calling format so the LLM knows when and how to use it.

# tools.py
import os
from tavily import TavilyClient

client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def web_search(query: str) -> str:
    """Search the web and return a summary of the top results."""
    results = client.search(query=query, max_results=3)
    output = []
    for r in results["results"]:
        output.append(f"Title: {r['title']}\nURL: {r['url']}\nSnippet: {r['content']}\n")
    return "\n---\n".join(output)


# OpenAI tool definition
TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "Search the web for up-to-date information on a topic.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "The search query"}
                },
                "required": ["query"],
            },
        },
    }
]

Step 3 — Write the agent loop

This is the core of the agent. We send messages to the LLM, check whether it wants to call a tool, execute the tool if so, and add the result back to the messages — then loop.

# agent.py
import json
import os

import truststore
truststore.inject_into_ssl()

from openai import OpenAI
from tools import TOOLS, web_search

openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])


def run_agent(goal: str, max_steps: int = 10) -> str:
    messages = [
        {
            "role": "system",
            "content": (
                "You are a research assistant. Use the web_search tool to find information, "
                "then write a concise summary. When you have enough information, respond "
                "directly without calling any more tools."
            ),
        },
        {"role": "user", "content": goal},
    ]

    for _ in range(max_steps):
        response = openai_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
            tools=TOOLS,
            tool_choice="auto",
        )
        msg = response.choices[0].message

        if not msg.tool_calls:
            return msg.content

        messages.append(msg)
        for call in msg.tool_calls:
            args = json.loads(call.function.arguments)
            result = web_search(**args)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })

    return "Max steps reached without a final answer."


if __name__ == "__main__":
    goal = input("Research goal: ")
    print("\n" + run_agent(goal))

Step 4 — Run it

python agent.py
Research goal: What are the top Python web frameworks in 2025?

The agent will call the search tool one or more times, read the results, and write a summary — all automatically.

What just happened?

Let's trace through the agent loop for this run:

Extending the agent

To add more tools, just define another function and add it to the TOOLS list:

• A save_to_file(filename, content) tool to persist the summary
• A run_python(code) tool to let the agent execute calculations
• A fetch_url(url) tool to read a specific webpage in full

The LLM will automatically use whichever tool is most appropriate given the goal.

Demo

Common pitfalls when building your first agent

Most first-time agent builders hit the same problems. Knowing them in advance saves hours of debugging.

How to debug agent loops

Agents are harder to debug than regular programs because the LLM's reasoning is a black box. These techniques make agent behavior visible and predictable.

• Print every iteration. Log the iteration number, which tool was called, the arguments, and a truncated version of the result. This gives you a trace you can read top-to-bottom to understand what the agent did and why.
• Use a system prompt that encourages reasoning. Adding "Think step-by-step before choosing a tool" to the system message makes the LLM write its reasoning in the response, which you can read in the logs. This is the ReAct pattern in practice.
• Test tools in isolation first. Call each tool function directly with known inputs and verify the output format before wiring it into the agent. If the tool returns unexpected JSON, the agent will not know how to interpret the result.
• Replay with fixed messages. Save the full message list from a failed run. Replay it by passing those messages directly to the LLM call — you will get the same (or very similar) response, which lets you experiment with prompt changes without running the full loop.

Build Your First AI Agent FAQ

Continue learning

Want to use a framework instead of plain Python? See the agent frameworks overview to compare LangChain, CrewAI, and more. For real-world inspiration, check out AI agent use cases. You can also explore our full tutorials catalog for more hands-on guides.