{"author":null,"author_email":"OpenAI ","bugtrack_url":null,"classifiers":["Intended Audience :: Developers","License :: OSI Approved :: MIT License","Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.9","Topic :: Software Development :: Libraries :: Python Modules","Typing :: Typed"],"description":"# OpenAI Agents SDK\n\nThe OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs.\n\n $\"Image$ \n\n### Core concepts:\n\n1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs\n2. [**Handoffs**](https://openai.github.io/openai-agents-python/handoffs/): A specialized tool call used by the Agents SDK for transferring control between agents\n3. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): Configurable safety checks for input and output validation\n4. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows\n\nExplore the [examples](examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details.\n\n## Get started\n\n1. Set up your Python environment\n\n```\npython -m venv env\nsource env/bin/activate\n```\n\n2. Install Agents SDK\n\n```\npip install openai-agents\n```\n\nFor voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.\n\n## Hello world example\n\n```python\nfrom agents import Agent, Runner\n\nagent = Agent(name=\"Assistant\", instructions=\"You are a helpful assistant\")\n\nresult = Runner.run_sync(agent, \"Write a haiku about recursion in programming.\")\nprint(result.final_output)\n\n# Code within the code,\n# Functions calling themselves,\n# Infinite loop's dance.\n```\n\n(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_)\n\n(_For Jupyter notebook users, see [hello_world_jupyter.py](examples/basic/hello_world_jupyter.py)_)\n\n## Handoffs example\n\n```python\nfrom agents import Agent, Runner\nimport asyncio\n\nspanish_agent = Agent(\n name=\"Spanish agent\",\n instructions=\"You only speak Spanish.\",\n)\n\nenglish_agent = Agent(\n name=\"English agent\",\n instructions=\"You only speak English\",\n)\n\ntriage_agent = Agent(\n name=\"Triage agent\",\n instructions=\"Handoff to the appropriate agent based on the language of the request.\",\n handoffs=[spanish_agent, english_agent],\n)\n\n\nasync def main():\n result = await Runner.run(triage_agent, input=\"Hola, ¿cómo estás?\")\n print(result.final_output)\n # ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Functions example\n\n```python\nimport asyncio\n\nfrom agents import Agent, Runner, function_tool\n\n\n@function_tool\ndef get_weather(city: str) -> str:\n return f\"The weather in {city} is sunny.\"\n\n\nagent = Agent(\n name=\"Hello world\",\n instructions=\"You are a helpful agent.\",\n tools=[get_weather],\n)\n\n\nasync def main():\n result = await Runner.run(agent, input=\"What's the weather in Tokyo?\")\n print(result.final_output)\n # The weather in Tokyo is sunny.\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## The agent loop\n\nWhen you call `Runner.run()`, we run a loop until we get a final output.\n\n1. We call the LLM, using the model and settings on the agent, and the message history.\n2. The LLM returns a response, which may include tool calls.\n3. If the response has a final output (see below for more on this), we return it and end the loop.\n4. If the response has a handoff, we set the agent to the new agent and go back to step 1.\n5. We process the tool calls (if any) and append the tool responses messages. Then we go to step 1.\n\nThere is a `max_turns` parameter that you can use to limit the number of times the loop executes.\n\n### Final output\n\nFinal output is the last thing the agent produces in the loop.\n\n1. 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.\n2. 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.\n\nAs a result, the mental model for the agent loop is:\n\n1. If the current agent has an `output_type`, the loop runs until the agent produces structured output matching that type.\n2. 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.\n\n## Common agent patterns\n\nThe 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).\n\n## Tracing\n\nThe 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).\n\n## Development (only needed if you need to edit the SDK/examples)\n\n0. Ensure you have [`uv`](https://docs.astral.sh/uv/) installed.\n\n```bash\nuv --version\n```\n\n1. Install dependencies\n\n```bash\nmake sync\n```\n\n2. (After making changes) lint/test\n\n```\nmake tests # run tests\nmake mypy # run typechecker\nmake lint # run linter\n```\n\n## Acknowledgements\n\nWe'd like to acknowledge the excellent work of the open-source community, especially:\n\n- [Pydantic](https://docs.pydantic.dev/latest/) (data validation) and [PydanticAI](https://ai.pydantic.dev/) (advanced agent framework)\n- [MkDocs](https://github.com/squidfunk/mkdocs-material)\n- [Griffe](https://github.com/mkdocstrings/griffe)\n- [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff)\n\nWe're committed to continuing to build the Agents SDK as an open source framework so others in the community can expand on our approach.\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":null,"license":null,"license_expression":"MIT","license_files":["LICENSE"],"maintainer":null,"maintainer_email":null,"name":"openai-agents","package_url":"https://pypi.org/project/openai-agents/","platform":null,"project_url":"https://pypi.org/project/openai-agents/","project_urls":{"Homepage":"https://github.com/openai/openai-agents-python","Repository":"https://github.com/openai/openai-agents-python"},"provides_extra":["litellm","viz","voice"],"release_url":"https://pypi.org/project/openai-agents/0.0.16/","requires_dist":["griffe<2,>=1.5.6","mcp<2,>=1.8.0; python_version >= \"3.10\"","openai>=1.81.0","pydantic<3,>=2.10","requests<3,>=2.0","types-requests<3,>=2.0","typing-extensions<5,>=4.12.2","litellm<2,>=1.67.4.post1; extra == \"litellm\"","graphviz>=0.17; extra == \"viz\"","numpy<3,>=2.2.0; python_version >= \"3.10\" and extra == \"voice\"","websockets<16,>=15.0; extra == \"voice\""],"requires_python":">=3.9","summary":"OpenAI Agents SDK","version":"0.0.16","yanked":false,"yanked_reason":null}

Dependency	Optional
griffe	false
mcp	false
openai	false
pydantic	false
requests	false
types-requests	false
typing-extensions	false
graphviz	true
litellm	true
numpy	true
websockets	true

Package search

openai-agents

project_urls

Dependencies

All package metadata

Releases