Metadata-Version: 2.2
Name: openai-agents
Version: 0.0.1
Summary: OpenAI Agents SDK
Author-email: OpenAI <support@openai.com>
Project-URL: Homepage, https://github.com/openai/openai-agents-python
Project-URL: Repository, https://github.com/openai/openai-agents-python
Classifier: Typing :: Typed
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: openai@ {root:parent:uri}/openai-1.30.1-py3-none-any.whl
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: griffe<2,>=1.5.6
Requires-Dist: typing-extensions<5,>=4.12.2
Requires-Dist: requests<3,>=2.0
Requires-Dist: types-requests<3,>=2.0

# OpenAI Agents SDK

The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.

### Core concepts: 
1. [**Agents,**](docs/agents.md) which are LLMs configured with instructions, tools, guardrails, and handoffs
2. [**Handoffs,**](docs/handoffs.md) which allow agents to transfer control to other agents for specific tasks
3. [**Guardrails,**](docs/guardrails.md) which makes it easy to watch an agent execution and validate inputs/outputs
4. [**Tracing,**](docs/tracing.md) which automatically captures the entire agentic run, allowing you to view, debug and optimize your workflows

Explore examples of the SDK in action in the [examples](examples) directory.

## Using the SDK

1. Set up python env

```
python -m venv env
source env/bin/activate
```

2. Install Agents SDK

```
pip install git+ssh://git@github.com/openai/agentsdk_prototype.git#subdirectory=agents
```

## 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/setup virtual environment

```bash
uv sync
```

2. Install the dependencies

```bash
uv sync --all-extras --all-packages
```

3. Activate the virtual environment

```bash
source .venv/bin/activate
```

## Tests

Make sure the virtual environment is activated first.

```bash
pytest
```

## Hello world example

```py
from agents.agent import Agent
from agents.run import Runner
import asyncio

agent = Agent(
  name="Hello world",
  instructions="You are a helpful agent."
)

async def main():
    out = await Runner.run(agent, input="Hola, ¿cómo estás?")
    print(out)


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

# The capital of the United States is Washington, D.C.
```

## Handoffs example

```py
from agents.agent import Agent
from agents.run import 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():
    out = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(out)


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

# ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?
```

## Functions example

```python
from agents.agent import Agent
from agents.run import Runner
import asyncio
from agents.tool import function_tool


@function_tool
def get_weather(city: str) -> str:
    print(f"Getting weather for {city}")
    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():
    out = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(out.final_output)


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

For more complex systems, we recommend including detailed instructions about handoffs. We have a recommendation in `handoff.RECOMMENDED_PROMPT_PREFIX` that can be used to add these instructions to an agent.

```py
agent = Agent(
    ...,
    instructions=f"{handoff.RECOMMENDED_PROMPT_PREFIX}\n\n{instructions}"
)
```

## 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 the 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 messsages. 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

There are two ways to get a **final output**:

1. If you set an `output_type` on the agent, the LLM is given a special tool called `final_output`. If it uses this tool, the output of the tool is the final output.
2. If there's no `output_type`, then we assume the final output is a string. As soon as the LLM produces a message without any tool calls, that is considered 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 uses that tool to return the final output.
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.

## Common agent patterns

There are a number of useful patterns in agentic apps. There are a number of examples in [`examples/agent_patterns`](examples/agent_patterns), and we recommend reading them.
