Skip to content

Commit aaec57a

Browse files
rm-openairm-openai
committed
Initial commit
0 parents  commit aaec57a

File tree

723 files changed

+37387
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

723 files changed

+37387
-0
lines changed

‎.github/workflows/docs.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Deploy docs
2+
3+
on:
4+
workflow_run:
5+
workflows: ["Tests"]
6+
types:
7+
- completed
8+
9+
permissions:
10+
contents: write # This allows pushing to gh-pages
11+
12+
jobs:
13+
deploy_docs:
14+
if: ${{ github.event.workflow_run.conclusion == 'success' }}
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout repository
18+
uses: actions/checkout@v4
19+
- name: Setup uv
20+
uses: astral-sh/setup-uv@v5
21+
with:
22+
enable-cache: true
23+
- name: Install dependencies
24+
run: make sync
25+
- name: Deploy docs
26+
run: make deploy-docs

‎.github/workflows/publish.yml

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types:
6+
- created
7+
8+
jobs:
9+
publish:
10+
environment:
11+
name: pypi
12+
url: https://pypi.org/p/openai-agents
13+
permissions:
14+
id-token: write # Important for trusted publishing to PyPI
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v4
20+
- name: Setup uv
21+
uses: astral-sh/setup-uv@v5
22+
with:
23+
enable-cache: true
24+
- name: Install dependencies
25+
run: make sync
26+
- name: Run tests
27+
run: make tests
28+
- name: Run mypy
29+
run: make mypy
30+
- name: Run Python 3.9 tests
31+
run: make old_version_tests
32+
- name: Build package
33+
run: uv build
34+
- name: Publish to PyPI
35+
uses: pypa/gh-action-pypi-publish@release/v1

‎.github/workflows/tests.yml

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
jobs:
12+
lint:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout repository
16+
uses: actions/checkout@v4
17+
- name: Setup uv
18+
uses: astral-sh/setup-uv@v5
19+
with:
20+
enable-cache: true
21+
- name: Install dependencies
22+
run: make sync
23+
- name: Run lint
24+
run: make lint
25+
26+
typecheck:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout repository
30+
uses: actions/checkout@v4
31+
- name: Setup uv
32+
uses: astral-sh/setup-uv@v5
33+
with:
34+
enable-cache: true
35+
- name: Install dependencies
36+
run: make sync
37+
- name: Run typecheck
38+
run: make mypy
39+
40+
tests:
41+
runs-on: ubuntu-latest
42+
env:
43+
OPENAI_API_KEY: fake-for-tests
44+
steps:
45+
- name: Checkout repository
46+
uses: actions/checkout@v4
47+
- name: Setup uv
48+
uses: astral-sh/setup-uv@v5
49+
with:
50+
enable-cache: true
51+
- name: Install dependencies
52+
run: make sync
53+
- name: Run tests
54+
run: make tests
55+
56+
build-docs:
57+
runs-on: ubuntu-latest
58+
env:
59+
OPENAI_API_KEY: fake-for-tests
60+
steps:
61+
- name: Checkout repository
62+
uses: actions/checkout@v4
63+
- name: Setup uv
64+
uses: astral-sh/setup-uv@v5
65+
with:
66+
enable-cache: true
67+
- name: Install dependencies
68+
run: make sync
69+
- name: Build docs
70+
run: make build-docs
71+
72+
old_versions:
73+
runs-on: ubuntu-latest
74+
env:
75+
OPENAI_API_KEY: fake-for-tests
76+
steps:
77+
- name: Checkout repository
78+
uses: actions/checkout@v4
79+
- name: Setup uv
80+
uses: astral-sh/setup-uv@v5
81+
with:
82+
enable-cache: true
83+
- name: Install dependencies
84+
run: make sync
85+
- name: Run tests
86+
run: make old_version_tests

‎.prettierrc

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"tabWidth": 4,
3+
"overrides": [
4+
{
5+
"files": "*.yml",
6+
"options": {
7+
"tabWidth": 2
8+
}
9+
}
10+
]
11+
}

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 OpenAI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.PHONY: sync
2+
sync:
3+
uv sync --all-extras --all-packages --group dev
4+
5+
.PHONY: format
6+
format:
7+
uv run ruff format
8+
9+
.PHONY: lint
10+
lint:
11+
uv run ruff check
12+
13+
.PHONY: mypy
14+
mypy:
15+
uv run mypy .
16+
17+
.PHONY: tests
18+
tests:
19+
uv run pytest
20+
21+
.PHONY: old_version_tests
22+
old_version_tests:
23+
UV_PROJECT_ENVIRONMENT=.venv_39 uv run --python 3.9 -m pytest
24+
UV_PROJECT_ENVIRONMENT=.venv_39 uv run --python 3.9 -m mypy .
25+
26+
.PHONY: build-docs
27+
build-docs:
28+
uv run mkdocs build
29+
30+
.PHONY: serve-docs
31+
serve-docs:
32+
uv run mkdocs serve
33+
34+
.PHONY: deploy-docs
35+
deploy-docs:
36+
uv run mkdocs gh-deploy --force --verbose
37+

‎README.md

+174
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# OpenAI Agents SDK
2+
3+
The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.
4+
5+
<img src="docs/assets/images/orchestration.png" alt="Image of the Agents Tracing UI" style="max-height: 803px;">
6+
7+
### Core concepts:
8+
9+
1. [**Agents**](docs/agents.md): LLMs configured with instructions, tools, guardrails, and handoffs
10+
2. [**Handoffs**](docs/handoffs.md): Allow agents to transfer control to other agents for specific tasks
11+
3. [**Guardrails**](docs/guardrails.md): Configurable safety checks for input and output validation
12+
4. [**Tracing**](docs/tracing.md): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
13+
14+
Explore the [examples](examples) directory to see the SDK in action.
15+
16+
## Get started
17+
18+
1. Set up your Python environment
19+
20+
```
21+
python -m venv env
22+
source env/bin/activate
23+
```
24+
25+
2. Install Agents SDK
26+
27+
```
28+
pip install openai-agents
29+
```
30+
31+
## Hello world example
32+
33+
```python
34+
from agents import Agent, Runner
35+
36+
agent = Agent(name="Assistant", instructions="You are a helpful assistant")
37+
38+
result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
39+
print(result.final_output)
40+
41+
# Code within the code,
42+
# Functions calling themselves,
43+
# Infinite loop's dance.
44+
```
45+
46+
(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_)
47+
48+
## Handoffs example
49+
50+
```py
51+
from agents import Agent, Runner
52+
import asyncio
53+
54+
spanish_agent = Agent(
55+
name="Spanish agent",
56+
instructions="You only speak Spanish.",
57+
)
58+
59+
english_agent = Agent(
60+
name="English agent",
61+
instructions="You only speak English",
62+
)
63+
64+
triage_agent = Agent(
65+
name="Triage agent",
66+
instructions="Handoff to the appropriate agent based on the language of the request.",
67+
handoffs=[spanish_agent, english_agent],
68+
)
69+
70+
71+
async def main():
72+
result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
73+
print(result.final_output)
74+
# ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?
75+
76+
77+
if __name__ == "__main__":
78+
asyncio.run(main())
79+
```
80+
81+
## Functions example
82+
83+
```python
84+
import asyncio
85+
86+
from agents import Agent, Runner, function_tool
87+
88+
89+
@function_tool
90+
def get_weather(city: str) -> str:
91+
return f"The weather in {city} is sunny."
92+
93+
94+
agent = Agent(
95+
name="Hello world",
96+
instructions="You are a helpful agent.",
97+
tools=[get_weather],
98+
)
99+
100+
101+
async def main():
102+
result = await Runner.run(agent, input="What's the weather in Tokyo?")
103+
print(result.final_output)
104+
# The weather in Tokyo is sunny.
105+
106+
107+
if __name__ == "__main__":
108+
asyncio.run(main())
109+
```
110+
111+
## The agent loop
112+
113+
When you call `Runner.run()`, we run a loop until we get a final output.
114+
115+
1. We call the LLM, using the model and settings on the agent, and the message history.
116+
2. The LLM returns a response, which may include tool calls.
117+
3. If the response has a final output (see below for the more on this), we return it and end the loop.
118+
4. If the response has a handoff, we set the agent to the new agent and go back to step 1.
119+
5. We process the tool calls (if any) and append the tool responses messsages. Then we go to step 1.
120+
121+
There is a `max_turns` parameter that you can use to limit the number of times the loop executes.
122+
123+
### Final output
124+
125+
Final output is the last thing the agent produces in the loop.
126+
127+
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.
128+
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.
129+
130+
As a result, the mental model for the agent loop is:
131+
132+
1. If the current agent has an `output_type`, the loop runs until the agent produces structured output matching that type.
133+
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.
134+
135+
## Common agent patterns
136+
137+
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).
138+
139+
## Tracing
140+
141+
The Agents SDK includes built-in tracing, 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), and [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk). See [Tracing](http://openai.github.io/openai-agents-python/tracing.md) for more details.
142+
143+
## Development (only needed if you need to edit the SDK/examples)
144+
145+
0. Ensure you have [`uv`](https://docs.astral.sh/uv/) installed.
146+
147+
```bash
148+
uv --version
149+
```
150+
151+
1. Install dependencies
152+
153+
```bash
154+
make sync
155+
```
156+
157+
2. (After making changes) lint/test
158+
159+
```
160+
make tests # run tests
161+
make mypy # run typechecker
162+
make lint # run linter
163+
```
164+
165+
## Acknowledgements
166+
167+
We'd like to acknowledge the excellent work of the open-source community, especially:
168+
169+
- [Pydantic](https://docs.pydantic.dev/latest/) (data validation) and [PydanticAI](https://ai.pydantic.dev/) (advanced agent framework)
170+
- [MkDocs](https://github.com/squidfunk/mkdocs-material)
171+
- [Griffe](https://github.com/mkdocstrings/griffe)
172+
- [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff)
173+
174+
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.

0 commit comments

Comments
 (0)