-
-### Core concepts:
-
-1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs
-2. [**Handoffs**](https://openai.github.io/openai-agents-python/handoffs/): A specialized tool call used by the Agents SDK for transferring control between agents
-3. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): Configurable safety checks for input and output validation
-4. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
-
-Explore the [examples](examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details.
-
-## Get started
-
-1. Set up your Python environment
-
-```
-python -m venv env
-source env/bin/activate
-```
-
-2. Install Agents SDK
-
-```
-pip install openai-agents
-```
-
-For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
-
-## Hello world example
-
-```python
-from agents import Agent, Runner
-
-agent = Agent(name="Assistant", instructions="You are a helpful assistant")
-
-result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
-print(result.final_output)
-
-# Code within the code,
-# Functions calling themselves,
-# Infinite loop's dance.
-```
-
-(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_)
-
-(_For Jupyter notebook users, see [hello_world_jupyter.py](examples/basic/hello_world_jupyter.py)_)
-
-## Handoffs example
-
-```python
-from agents import Agent, Runner
-import asyncio
-
-spanish_agent = Agent(
- name="Spanish agent",
- instructions="You only speak Spanish.",
-)
-
-english_agent = Agent(
- name="English agent",
- instructions="You only speak English",
-)
-
-triage_agent = Agent(
- name="Triage agent",
- instructions="Handoff to the appropriate agent based on the language of the request.",
- handoffs=[spanish_agent, english_agent],
-)
-
-
-async def main():
- result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
- print(result.final_output)
- # ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?
-
-
-if __name__ == "__main__":
- asyncio.run(main())
-```
-
-## Functions example
-
-```python
-import asyncio
-
-from agents import Agent, Runner, function_tool
-
-
-@function_tool
-def get_weather(city: str) -> str:
- return f"The weather in {city} is sunny."
-
-
-agent = Agent(
- name="Hello world",
- instructions="You are a helpful agent.",
- tools=[get_weather],
-)
-
-
-async def main():
- result = await Runner.run(agent, input="What's the weather in Tokyo?")
- print(result.final_output)
- # The weather in Tokyo is sunny.
-
-
-if __name__ == "__main__":
- asyncio.run(main())
-```
-
-## The agent loop
-
-When you call `Runner.run()`, we run a loop until we get a final output.
-
-1. We call the LLM, using the model and settings on the agent, and the message history.
-2. The LLM returns a response, which may include tool calls.
-3. If the response has a final output (see below for more on this), we return it and end the loop.
-4. If the response has a handoff, we set the agent to the new agent and go back to step 1.
-5. We process the tool calls (if any) and append the tool responses messages. Then we go to step 1.
-
-There is a `max_turns` parameter that you can use to limit the number of times the loop executes.
-
-### Final output
-
-Final output is the last thing the agent produces in the loop.
-
-1. If you set an `output_type` on the agent, the final output is when the LLM returns something of that type. We use [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) for this.
-2. If there's no `output_type` (i.e. plain text responses), then the first LLM response without any tool calls or handoffs is considered as the final output.
-
-As a result, the mental model for the agent loop is:
-
-1. If the current agent has an `output_type`, the loop runs until the agent produces structured output matching that type.
-2. If the current agent does not have an `output_type`, the loop runs until the current agent produces a message without any tool calls/handoffs.
-
-## Common agent patterns
-
-The Agents SDK is designed to be highly flexible, allowing you to model a wide range of LLM workflows including deterministic flows, iterative loops, and more. See examples in [`examples/agent_patterns`](examples/agent_patterns).
-
-## Tracing
-
-The Agents SDK automatically traces your agent runs, making it easy to track and debug the behavior of your agents. Tracing is extensible by design, supporting custom spans and a wide variety of external destinations, including [Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents), [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk), [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk), [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration), and [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent). For more details about how to customize or disable tracing, see [Tracing](http://openai.github.io/openai-agents-python/tracing), which also includes a larger list of [external tracing processors](http://openai.github.io/openai-agents-python/tracing/#external-tracing-processors-list).
-
-## Development (only needed if you need to edit the SDK/examples)
-
-0. Ensure you have [`uv`](https://docs.astral.sh/uv/) installed.
-
-```bash
-uv --version
-```
-
-1. Install dependencies
-
-```bash
-make sync
-```
-
-2. (After making changes) lint/test
-
-```
-make tests # run tests
-make mypy # run typechecker
-make lint # run linter
-```
-
-## Acknowledgements
-
-We'd like to acknowledge the excellent work of the open-source community, especially:
-
-- [Pydantic](https://docs.pydantic.dev/latest/) (data validation) and [PydanticAI](https://ai.pydantic.dev/) (advanced agent framework)
-- [MkDocs](https://github.com/squidfunk/mkdocs-material)
-- [Griffe](https://github.com/mkdocstrings/griffe)
-- [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff)
-
-We're committed to continuing to build the Agents SDK as an open source framework so others in the community can expand on our approach.
diff --git a/agents/index.html b/agents/index.html
new file mode 100644
index 00000000..1d7d810a
--- /dev/null
+++ b/agents/index.html
@@ -0,0 +1,2620 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Agents are the core building block in your apps. An agent is a large language model (LLM), configured with instructions and tools.
+The most common properties of an agent you'll configure are:
+instructions: also known as a developer message or system prompt.model: which LLM to use, and optional model_settings to configure model tuning parameters like temperature, top_p, etc.tools: Tools that the agent can use to achieve its tasks.from agents import Agent, ModelSettings, function_tool
+
+@function_tool
+def get_weather(city: str) -> str:
+ return f"The weather in {city} is sunny"
+
+agent = Agent(
+ name="Haiku agent",
+ instructions="Always respond in haiku form",
+ model="o3-mini",
+ tools=[get_weather],
+)
+Agents are generic on their context type. Context is a dependency-injection tool: it's an object you create and pass to Runner.run(), that is passed to every agent, tool, handoff etc, and it serves as a grab bag of dependencies and state for the agent run. You can provide any Python object as the context.
@dataclass
+class UserContext:
+ uid: str
+ is_pro_user: bool
+
+ async def fetch_purchases() -> list[Purchase]:
+ return ...
+
+agent = Agent[UserContext](
+ ...,
+)
+By default, agents produce plain text (i.e. str) outputs. If you want the agent to produce a particular type of output, you can use the output_type parameter. A common choice is to use Pydantic objects, but we support any type that can be wrapped in a Pydantic TypeAdapter - dataclasses, lists, TypedDict, etc.
from pydantic import BaseModel
+from agents import Agent
+
+
+class CalendarEvent(BaseModel):
+ name: str
+ date: str
+ participants: list[str]
+
+agent = Agent(
+ name="Calendar extractor",
+ instructions="Extract calendar events from text",
+ output_type=CalendarEvent,
+)
+Note
+When you pass an output_type, that tells the model to use structured outputs instead of regular plain text responses.
Handoffs are sub-agents that the agent can delegate to. You provide a list of handoffs, and the agent can choose to delegate to them if relevant. This is a powerful pattern that allows orchestrating modular, specialized agents that excel at a single task. Read more in the handoffs documentation.
+from agents import Agent
+
+booking_agent = Agent(...)
+refund_agent = Agent(...)
+
+triage_agent = Agent(
+ name="Triage agent",
+ instructions=(
+ "Help the user with their questions."
+ "If they ask about booking, handoff to the booking agent."
+ "If they ask about refunds, handoff to the refund agent."
+ ),
+ handoffs=[booking_agent, refund_agent],
+)
+In most cases, you can provide instructions when you create the agent. However, you can also provide dynamic instructions via a function. The function will receive the agent and context, and must return the prompt. Both regular and async functions are accepted.
def dynamic_instructions(
+ context: RunContextWrapper[UserContext], agent: Agent[UserContext]
+) -> str:
+ return f"The user's name is {context.context.name}. Help them with their questions."
+
+
+agent = Agent[UserContext](
+ name="Triage agent",
+ instructions=dynamic_instructions,
+)
+Sometimes, you want to observe the lifecycle of an agent. For example, you may want to log events, or pre-fetch data when certain events occur. You can hook into the agent lifecycle with the hooks property. Subclass the AgentHooks class, and override the methods you're interested in.
Guardrails allow you to run checks/validations on user input, in parallel to the agent running. For example, you could screen the user's input for relevance. Read more in the guardrails documentation.
+By using the clone() method on an agent, you can duplicate an Agent, and optionally change any properties you like.
pirate_agent = Agent(
+ name="Pirate",
+ instructions="Write like a pirate",
+ model="o3-mini",
+)
+
+robot_agent = pirate_agent.clone(
+ name="Robot",
+ instructions="Write like a robot",
+)
+Supplying a list of tools doesn't always mean the LLM will use a tool. You can force tool use by setting ModelSettings.tool_choice. Valid values are:
auto, which allows the LLM to decide whether or not to use a tool.required, which requires the LLM to use a tool (but it can intelligently decide which tool).none, which requires the LLM to not use a tool.my_tool, which requires the LLM to use that specific tool.Note
+To prevent infinite loops, the framework automatically resets tool_choice to "auto" after a tool call. This behavior is configurable via agent.reset_tool_choice. The infinite loop is because tool results are sent to the LLM, which then generates another tool call because of tool_choice, ad infinitum.
If you want the Agent to completely stop after a tool call (rather than continuing with auto mode), you can set [Agent.tool_use_behavior="stop_on_first_tool"] which will directly use the tool output as the final response without further LLM processing.