How to run a first agent with the OpenAI Agents SDK for Python

A first agent in the Agents SDK is a name, instructions, and one awaited run. This walkthrough follows only the official quickstart: install openai-agents, call Runner, add a @tool, then hand the turn to a specialist. It stops at the dashboard trace viewer. For how to read or score a trace, use the tracing guide already on this desk.

Create a project and virtual environment

You only need to create the project once.

mkdir my_project
cd my_project
python -m venv .venv

Activate the environment every time you start a new terminal session.

On macOS or Linux:

source .venv/bin/activate

On Windows:

.venv\Scripts\activate

Install the SDK. The page does not pin a version, and it does not state a required Python version.

pip install openai-agents # or `uv add openai-agents`, etc

Set an OpenAI API key

If you do not have a key, follow the platform instructions the quickstart links for creating and exporting one. These commands set the key for the current terminal session. The page uses sk-... as the stand-in. Put your own key there.

On macOS or Linux:

export OPENAI_API_KEY=sk-...

On Windows PowerShell:

$env:OPENAI_API_KEY = "sk-..."

On Windows Command Prompt:

set "OPENAI_API_KEY=sk-..."

Create your first agent

Agents are defined with instructions, a name, and optional configuration such as a specific model. This first agent sets the name and instructions only. It does not set a model.

from agents import Agent

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

Run your first agent

Use Runner to execute the agent and get a RunResult back. Await Runner.run, then print result.final_output.

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

async def main():
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Use a plain Agent plus Runner when the task mainly lives in prompts, tools, and conversation state. If the agent should inspect or modify real files in an isolated workspace, jump to the Sandbox agents quickstart. This page does not show that setup.

Continue a second turn

For a second turn, pass result.to_input_list() back into Runner.run(...), attach a session, or reuse OpenAI server-managed state with conversation_id / previous_response_id. The running-agents guide is where the quickstart sends you for the comparison.

The quickstart names those options. It does not show a Runner.run call that passes session, conversation_id, or previous_response_id. Leave those arguments to the running-agents guide rather than guessing the call.

Give your agent tools

You can give an agent tools to look up information or perform actions. Import tool from agents.decorators, decorate the function, and pass it in tools.

import asyncio
from agents import Agent, Runner
from agents.decorators import tool

@tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."

agent = Agent(
    name="History Tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)

async def main():
    result = await Runner.run(
        agent,
        "Tell me something surprising about ancient life on Earth.",
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

The tool is the decorated history_fun_fact function. Its body returns the string in the snippet. The instructions tell the tutor to use that function when it helps.

Choose handoffs, then define them

Before you choose a multi-agent pattern, decide who should own the final answer:

• Handoffs: a specialist takes over the conversation for that part of the turn.
• Agents as tools: an orchestrator stays in control and calls specialists as tools.

This quickstart continues with handoffs because it is the shortest first example. The manager-style pattern is documented under agent orchestration and under tools as agents-as-tools. Those guides are outside this first run.

Additional agents are defined the same way. handoff_description gives the routing agent extra context about when to delegate.

from agents import Agent

history_tutor_agent = Agent(
    name="History Tutor",
    handoff_description="Specialist agent for historical questions",
    instructions="You answer history questions clearly and concisely.",
)

math_tutor_agent = Agent(
    name="Math Tutor",
    handoff_description="Specialist agent for math questions",
    instructions="You explain math step by step and include worked examples.",
)

On an agent, you can define an inventory of outgoing handoff options that it can choose from while solving the task.

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route each homework question to the right specialist.",
    handoffs=[history_tutor_agent, math_tutor_agent],
)

Run the agent orchestration

The runner handles executing individual agents, any handoffs, and any tool calls. The run below is the quickstart's snippet. It uses triage_agent from the definition above and does not repeat those definitions.

import asyncio
from agents import Runner

async def main():
    result = await Runner.run(
        triage_agent,
        "Who was the first president of the United States?",
    )
    print(result.final_output)
    print(f"Answered by: {result.last_agent.name}")

if __name__ == "__main__":
    asyncio.run(main())

result.final_output is the answer text. result.last_agent.name is the agent that finished the turn. The page does not include a sample console log, so the check is those two fields, not a fixed sentence.

The repository includes full scripts for the same core patterns: examples/basic/hello_world.py for the first run, examples/basic/tools.py for function tools, and examples/agent_patterns/routing.py for multi-agent routing.

View traces, then stop

To review what happened during your agent run, open the trace viewer in the OpenAI dashboard. That is the tracing step on this page. It does not replace the tracing guide already on this desk. Go there if you need to inspect or score the run. Do not treat this quickstart as that guide.

What to run next

Save the History Tutor run, then the tool example, then the triage handoff, and print result.last_agent.name after the history question. For a follow-up turn, start from the table above and read the running-agents guide before you pass conversation_id or previous_response_id. For the trace, leave this page and use the desk tracing guide. The quickstart's own next steps after that are configuring agents, running agents and sessions, sandbox agents when the work should happen inside a real workspace, and tools, guardrails, and models.

Sources

• OpenAI Agents SDK for Python quickstart