You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/agents.md
+3-1
Original file line number
Diff line number
Diff line change
@@ -142,4 +142,6 @@ Supplying a list of tools doesn't always mean the LLM will use a tool. You can f
142
142
143
143
!!! note
144
144
145
-
If requiring tool use, you should consider setting [`Agent.tool_use_behavior`] to stop the Agent from running when a tool output is produced. Otherwise, the Agent might run in an infinite loop, where the LLM produces a tool call , and the tool result is sent to the LLM, and this infinite loops because the LLM is always forced to use a tool.
145
+
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`][agents.agent.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.
146
+
147
+
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.
Copy file name to clipboardExpand all lines: docs/guardrails.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -29,7 +29,7 @@ Output guardrails run in 3 steps:
29
29
30
30
!!! Note
31
31
32
-
Output guardrails are intended to run on the final agent input, so an agent's guardrails only run if the agent is the *last* agent. Similar to the input guardrails, we do this because guardrails tend to be related to the actual Agent - you'd run different guardrails for different agents, so colocating the code is useful for readability.
32
+
Output guardrails are intended to run on the final agent output, so an agent's guardrails only run if the agent is the *last* agent. Similar to the input guardrails, we do this because guardrails tend to be related to the actual Agent - you'd run different guardrails for different agents, so colocating the code is useful for readability.
The [Model context protocol](https://modelcontextprotocol.io/introduction) (aka MCP) is a way to provide tools and context to the LLM. From the MCP docs:
4
+
5
+
> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
6
+
7
+
The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools to your Agents.
8
+
9
+
## MCP servers
10
+
11
+
Currently, the MCP spec defines two kinds of servers, based on the transport mechanism they use:
12
+
13
+
1.**stdio** servers run as a subprocess of your application. You can think of them as running "locally".
14
+
2.**HTTP over SSE** servers run remotely. You connect to them via a URL.
15
+
16
+
You can use the [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse] classes to connect to these servers.
17
+
18
+
For example, this is how you'd use the [official MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem).
MCP servers can be added to Agents. The Agents SDK will call `list_tools()` on the MCP servers each time the Agent is run. This makes the LLM aware of the MCP server's tools. When the LLM calls a tool from an MCP server, the SDK calls `call_tool()` on that server.
33
+
34
+
```python
35
+
36
+
agent=Agent(
37
+
name="Assistant",
38
+
instructions="Use the tools to achieve the task",
39
+
mcp_servers=[mcp_server_1, mcp_server_2]
40
+
)
41
+
```
42
+
43
+
## Caching
44
+
45
+
Every time an Agent runs, it calls `list_tools()` on the MCP server. This can be a latency hit, especially if the server is a remote server. To automatically cache the list of tools, you can pass `cache_tools_list=True` to both [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse]. You should only do this if you're certain the tool list will not change.
46
+
47
+
If you want to invalidate the cache, you can call `invalidate_tools_cache()` on the servers.
48
+
49
+
## End-to-end examples
50
+
51
+
View complete working examples at [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp).
Copy file name to clipboardExpand all lines: docs/tracing.md
+11-1
Original file line number
Diff line number
Diff line change
@@ -35,6 +35,9 @@ By default, the SDK traces the following:
35
35
- Function tool calls are each wrapped in `function_span()`
36
36
- Guardrails are wrapped in `guardrail_span()`
37
37
- Handoffs are wrapped in `handoff_span()`
38
+
- Audio inputs (speech-to-text) are wrapped in a `transcription_span()`
39
+
- Audio outputs (text-to-speech) are wrapped in a `speech_span()`
40
+
- Related audio spans may be parented under a `speech_group_span()`
38
41
39
42
By default, the trace is named "Agent trace". You can set this name if you use `trace`, or you can can configure the name and other properties with the [`RunConfig`][agents.run.RunConfig].
40
43
@@ -76,7 +79,11 @@ Spans are automatically part of the current trace, and are nested under the near
76
79
77
80
## Sensitive data
78
81
79
-
Some spans track potentially sensitive data. For example, the `generation_span()` stores the inputs/outputs of the LLM generation, and `function_span()` stores the inputs/outputs of function calls. These may contain sensitive data, so you can disable capturing that data via [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data].
82
+
Certain spans may capture potentially sensitive data.
83
+
84
+
The `generation_span()` stores the inputs/outputs of the LLM generation, and `function_span()` stores the inputs/outputs of function calls. These may contain sensitive data, so you can disable capturing that data via [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data].
85
+
86
+
Similarly, Audio spans include base64-encoded PCM data for input and output audio by default. You can disable capturing this audio data by configuring [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data].
80
87
81
88
## Custom tracing processors
82
89
@@ -92,6 +99,7 @@ To customize this default setup, to send traces to alternative or additional bac
Agent visualization allows you to generate a structured graphical representation of agents and their relationships using **Graphviz**. This is useful for understanding how agents, tools, and handoffs interact within an application.
4
+
5
+
## Installation
6
+
7
+
Install the optional `viz` dependency group:
8
+
9
+
```bash
10
+
pip install "openai-agents[viz]"
11
+
```
12
+
13
+
## Generating a Graph
14
+
15
+
You can generate an agent visualization using the `draw_graph` function. This function creates a directed graph where:
16
+
17
+
-**Agents** are represented as yellow boxes.
18
+
-**Tools** are represented as green ellipses.
19
+
-**Handoffs** are directed edges from one agent to another.
20
+
21
+
### Example Usage
22
+
23
+
```python
24
+
from agents import Agent, function_tool
25
+
from agents.extensions.visualization import draw_graph
26
+
27
+
@function_tool
28
+
defget_weather(city: str) -> str:
29
+
returnf"The weather in {city} is sunny."
30
+
31
+
spanish_agent = Agent(
32
+
name="Spanish agent",
33
+
instructions="You only speak Spanish.",
34
+
)
35
+
36
+
english_agent = Agent(
37
+
name="English agent",
38
+
instructions="You only speak English",
39
+
)
40
+
41
+
triage_agent = Agent(
42
+
name="Triage agent",
43
+
instructions="Handoff to the appropriate agent based on the language of the request.",
44
+
handoffs=[spanish_agent, english_agent],
45
+
tools=[get_weather],
46
+
)
47
+
48
+
draw_graph(triage_agent)
49
+
```
50
+
51
+
52
+
53
+
This generates a graph that visually represents the structure of the **triage agent** and its connections to sub-agents and tools.
54
+
55
+
56
+
## Understanding the Visualization
57
+
58
+
The generated graph includes:
59
+
60
+
- A **start node** (`__start__`) indicating the entry point.
61
+
- Agents represented as **rectangles** with yellow fill.
62
+
- Tools represented as **ellipses** with green fill.
63
+
- Directed edges indicating interactions:
64
+
-**Solid arrows** for agent-to-agent handoffs.
65
+
-**Dotted arrows** for tool invocations.
66
+
- An **end node** (`__end__`) indicating where execution terminates.
67
+
68
+
## Customizing the Graph
69
+
70
+
### Showing the Graph
71
+
By default, `draw_graph` displays the graph inline. To show the graph in a separate window, write the following:
72
+
73
+
```python
74
+
draw_graph(triage_agent).view()
75
+
```
76
+
77
+
### Saving the Graph
78
+
By default, `draw_graph` displays the graph inline. To save it as a file, specify a filename:
Copy file name to clipboardExpand all lines: docs/voice/quickstart.md
+10-5
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@
5
5
Make sure you've followed the base [quickstart instructions](../quickstart.md) for the Agents SDK, and set up a virtual environment. Then, install the optional voice dependencies from the SDK:
6
6
7
7
```bash
8
-
pip install openai-agents[voice]
8
+
pip install 'openai-agents[voice]'
9
9
```
10
10
11
11
## Concepts
@@ -91,7 +91,7 @@ agent = Agent(
91
91
We'll set up a simple voice pipeline, using [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] as the workflow.
92
92
93
93
```python
94
-
from agents import SingleAgentVoiceWorkflow, VoicePipeline,
94
+
from agents.voiceimport SingleAgentVoiceWorkflow, VoicePipeline
0 commit comments