openai-agents 0.0.5__tar.gz → 0.0.7__tar.gz

{openai_agents-0.0.5 → openai_agents-0.0.7}/.github/workflows/issues.yml

@@ -17,7 +17,10 @@ jobs:
           stale-issue-label: "stale"
           stale-issue-message: "This issue is stale because it has been open for 7 days with no activity."
           close-issue-message: "This issue was closed because it has been inactive for 3 days since being marked as stale."
-          days-before-pr-stale: -1
-          days-before-pr-close: -1
-          any-of-labels: 'question,needs-more-info'
+          any-of-issue-labels: 'question,needs-more-info'
+          days-before-pr-stale: 10
+          days-before-pr-close: 7
+          stale-pr-label: "stale"
+          stale-pr-message: "This PR is stale because it has been open for 10 days with no activity."
+          close-pr-message: "This PR was closed because it has been inactive for 7 days since being marked as stale."
           repo-token: ${{ secrets.GITHUB_TOKEN }}

{openai_agents-0.0.5 → openai_agents-0.0.7}/.github/workflows/tests.yml

@@ -8,6 +8,9 @@ on:
     branches:
       - main
 
+env:
+  UV_FROZEN: "1"
+
 jobs:
   lint:
     runs-on: ubuntu-latest

{openai_agents-0.0.5 → openai_agents-0.0.7}/.gitignore

@@ -135,10 +135,10 @@ dmypy.json
 cython_debug/
 
 # PyCharm
-#.idea/
+.idea/
 
 # Ruff stuff:
 .ruff_cache/
 
 # PyPI configuration file
-.pypirc
+.pypirc

{openai_agents-0.0.5 → openai_agents-0.0.7}/Makefile

@@ -5,6 +5,7 @@ sync:
 .PHONY: format
 format: 
 	uv run ruff format
+	uv run ruff check --fix
 
 .PHONY: lint
 lint: 
@@ -36,7 +37,6 @@ snapshots-create:
 .PHONY: old_version_tests
 old_version_tests: 
 	UV_PROJECT_ENVIRONMENT=.venv_39 uv run --python 3.9 -m pytest
-	UV_PROJECT_ENVIRONMENT=.venv_39 uv run --python 3.9 -m mypy .
 
 .PHONY: build-docs
 build-docs:

{openai_agents-0.0.5 → openai_agents-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.0.5
+Version: 0.0.7
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://github.com/openai/openai-agents-python
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -19,11 +19,17 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
+Requires-Dist: mcp; python_version >= '3.10'
 Requires-Dist: openai>=1.66.5
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0
 Requires-Dist: typing-extensions<5,>=4.12.2
+Provides-Extra: viz
+Requires-Dist: graphviz>=0.17; extra == 'viz'
+Provides-Extra: voice
+Requires-Dist: numpy<3,>=2.2.0; (python_version >= '3.10') and extra == 'voice'
+Requires-Dist: websockets<16,>=15.0; extra == 'voice'
 Description-Content-Type: text/markdown
 
 # OpenAI Agents SDK
@@ -58,6 +64,8 @@ source env/bin/activate
 pip install openai-agents
 ```
 
+For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
+
 ## Hello world example
 
 ```python

{openai_agents-0.0.5 → openai_agents-0.0.7}/README.md

@@ -30,6 +30,8 @@ source env/bin/activate
 pip install openai-agents
 ```
 
+For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
+
 ## Hello world example
 
 ```python

{openai_agents-0.0.5 → openai_agents-0.0.7}/docs/agents.md

@@ -142,4 +142,6 @@ Supplying a list of tools doesn't always mean the LLM will use a tool. You can f
 
 !!! note
 
-    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.
+    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.
+
+    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.

{openai_agents-0.0.5 → openai_agents-0.0.7}/docs/context.md

@@ -41,14 +41,14 @@ async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:  # (2)!
     return f"User {wrapper.context.name} is 47 years old"
 
 async def main():
-    user_info = UserInfo(name="John", uid=123)  # (3)!
+    user_info = UserInfo(name="John", uid=123)
 
-    agent = Agent[UserInfo](  # (4)!
+    agent = Agent[UserInfo](  # (3)!
         name="Assistant",
         tools=[fetch_user_age],
     )
 
-    result = await Runner.run(
+    result = await Runner.run(  # (4)!
         starting_agent=agent,
         input="What is the age of the user?",
         context=user_info,

openai_agents-0.0.7/docs/examples.md

@@ -0,0 +1,36 @@
+# Examples
+
+Check out a variety of sample implementations of the SDK in the examples section of the [repo](https://github.com/openai/openai-agents-python/tree/main/examples). The examples are organized into several categories that demonstrate different patterns and capabilities.
+
+
+## Categories
+
+- **agent_patterns:**
+  Examples in this category illustrate common agent design patterns, such as
+  
+    - Deterministic workflows
+    - Agents as tools
+    - Parallel agent execution
+
+- **basic:**
+  These examples showcase foundational capabilities of the SDK, such as
+  
+    - Dynamic system prompts
+    - Streaming outputs
+    - Lifecycle events
+
+- **tool examples:**
+  Learn how to implement OAI hosted tools such as web search and file search,
+   and integrate them into your agents.
+
+- **model providers:**
+  Explore how to use non-OpenAI models with the SDK.
+
+- **handoffs:**
+  See practical examples of agent handoffs.
+
+- **customer_service** and **research_bot:**
+  Two more built-out examples that illustrate real-world applications
+  
+    - **customer_service**: Example customer service system for an airline.
+    - **research_bot**: Simple deep research clone.

{openai_agents-0.0.5 → openai_agents-0.0.7}/docs/guardrails.md

@@ -29,7 +29,7 @@ Output guardrails run in 3 steps:
 
 !!! Note
 
-    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.
+    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.
 
 ## Tripwires
 

openai_agents-0.0.7/docs/mcp.md

@@ -0,0 +1,51 @@
+# Model context protocol
+
+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:
+
+> 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.
+
+The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools to your Agents.
+
+## MCP servers
+
+Currently, the MCP spec defines two kinds of servers, based on the transport mechanism they use:
+
+1. **stdio** servers run as a subprocess of your application. You can think of them as running "locally".
+2. **HTTP over SSE** servers run remotely. You connect to them via a URL.
+
+You can use the [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse] classes to connect to these servers.
+
+For example, this is how you'd use the [official MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem).
+
+```python
+async with MCPServerStdio(
+    params={
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
+    }
+) as server:
+    tools = await server.list_tools()
+```
+
+## Using MCP servers
+
+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.
+
+```python
+
+agent=Agent(
+    name="Assistant",
+    instructions="Use the tools to achieve the task",
+    mcp_servers=[mcp_server_1, mcp_server_2]
+)
+```
+
+## Caching
+
+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.
+
+If you want to invalidate the cache, you can call `invalidate_tools_cache()` on the servers.
+
+## End-to-end example
+
+View complete working examples at [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp).

openai_agents-0.0.7/docs/ref/mcp/server.md

@@ -0,0 +1,3 @@
+# `MCP Servers`
+
+::: agents.mcp.server

openai_agents-0.0.7/docs/ref/mcp/util.md

@@ -0,0 +1,3 @@
+# `MCP Util`
+
+::: agents.mcp.util

openai_agents-0.0.7/docs/ref/voice/events.md

@@ -0,0 +1,3 @@
+# `Events`
+
+::: agents.voice.events

openai_agents-0.0.7/docs/ref/voice/exceptions.md

@@ -0,0 +1,3 @@
+# `Exceptions`
+
+::: agents.voice.exceptions

openai_agents-0.0.7/docs/ref/voice/input.md

@@ -0,0 +1,3 @@
+# `Input`
+
+::: agents.voice.input

openai_agents-0.0.7/docs/ref/voice/model.md

@@ -0,0 +1,3 @@
+# `Model`
+
+::: agents.voice.model

openai_agents-0.0.7/docs/ref/voice/models/openai_provider.md

@@ -0,0 +1,3 @@
+# `OpenAIVoiceModelProvider`
+
+::: agents.voice.models.openai_model_provider

openai_agents-0.0.7/docs/ref/voice/models/openai_stt.md

@@ -0,0 +1,3 @@
+# `OpenAI STT`
+
+::: agents.voice.models.openai_stt

openai_agents-0.0.7/docs/ref/voice/models/openai_tts.md

@@ -0,0 +1,3 @@
+# `OpenAI TTS`
+
+::: agents.voice.models.openai_tts

openai_agents-0.0.7/docs/ref/voice/pipeline.md

@@ -0,0 +1,3 @@
+# `Pipeline`
+
+::: agents.voice.pipeline

openai_agents-0.0.7/docs/ref/voice/pipeline_config.md

@@ -0,0 +1,3 @@
+# `Pipeline Config`
+
+::: agents.voice.pipeline_config

openai_agents-0.0.7/docs/ref/voice/result.md

@@ -0,0 +1,3 @@
+# `Result`
+
+::: agents.voice.result

openai_agents-0.0.7/docs/ref/voice/utils.md

@@ -0,0 +1,3 @@
+# `Utils`
+
+::: agents.voice.utils

openai_agents-0.0.7/docs/ref/voice/workflow.md

@@ -0,0 +1,3 @@
+# `Workflow`
+
+::: agents.voice.workflow

{openai_agents-0.0.5 → openai_agents-0.0.7}/docs/tracing.md

@@ -35,6 +35,9 @@ By default, the SDK traces the following:
 -   Function tool calls are each wrapped in `function_span()`
 -   Guardrails are wrapped in `guardrail_span()`
 -   Handoffs are wrapped in `handoff_span()`
+-   Audio inputs (speech-to-text) are wrapped in a `transcription_span()`
+-   Audio outputs (text-to-speech) are wrapped in a `speech_span()`
+-   Related audio spans may be parented under a `speech_group_span()`
 
 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].
 
@@ -76,7 +79,11 @@ Spans are automatically part of the current trace, and are nested under the near
 
 ## Sensitive data
 
-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].
+Certain spans may capture potentially sensitive data.
+
+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].
+
+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].
 
 ## Custom tracing processors
 
@@ -92,6 +99,7 @@ To customize this default setup, to send traces to alternative or additional bac
 
 ## External tracing processors list
 
+-   [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents)
 -   [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk)
 -   [MLflow](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
 -   [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)
@@ -102,3 +110,4 @@ To customize this default setup, to send traces to alternative or additional bac
 -   [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk)
 -   [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk)
 -   [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
+-   [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents)

openai_agents-0.0.7/docs/visualization.md

@@ -0,0 +1,86 @@
+# Agent Visualization
+
+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.
+
+## Installation
+
+Install the optional `viz` dependency group:
+
+```bash
+pip install "openai-agents[viz]"
+```
+
+## Generating a Graph
+
+You can generate an agent visualization using the `draw_graph` function. This function creates a directed graph where:
+
+- **Agents** are represented as yellow boxes.
+- **Tools** are represented as green ellipses.
+- **Handoffs** are directed edges from one agent to another.
+
+### Example Usage
+
+```python
+from agents import Agent, function_tool
+from agents.extensions.visualization import draw_graph
+
+@function_tool
+def get_weather(city: str) -> str:
+    return f"The weather in {city} is sunny."
+
+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],
+    tools=[get_weather],
+)
+
+draw_graph(triage_agent)
+```
+
+![Agent Graph](./assets/images/graph.png)
+
+This generates a graph that visually represents the structure of the **triage agent** and its connections to sub-agents and tools.
+
+
+## Understanding the Visualization
+
+The generated graph includes:
+
+- A **start node** (`__start__`) indicating the entry point.
+- Agents represented as **rectangles** with yellow fill.
+- Tools represented as **ellipses** with green fill.
+- Directed edges indicating interactions:
+  - **Solid arrows** for agent-to-agent handoffs.
+  - **Dotted arrows** for tool invocations.
+- An **end node** (`__end__`) indicating where execution terminates.
+
+## Customizing the Graph
+
+### Showing the Graph
+By default, `draw_graph` displays the graph inline. To show the graph in a separate window, write the following:
+
+```python
+draw_graph(triage_agent).view()
+```
+
+### Saving the Graph
+By default, `draw_graph` displays the graph inline. To save it as a file, specify a filename:
+
+```python
+draw_graph(triage_agent, filename="agent_graph.png")
+```
+
+This will generate `agent_graph.png` in the working directory.
+
+

openai_agents-0.0.7/docs/voice/pipeline.md

@@ -0,0 +1,75 @@
+# Pipelines and workflows
+
+[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] is a class that makes it easy to turn your agentic workflows into a voice app. You pass in a workflow to run, and the pipeline takes care of transcribing input audio, detecting when the audio ends, calling your workflow at the right time, and turning the workflow output back into audio.
+
+```mermaid
+graph LR
+    %% Input
+    A["🎤 Audio Input"]
+
+    %% Voice Pipeline
+    subgraph Voice_Pipeline [Voice Pipeline]
+        direction TB
+        B["Transcribe (speech-to-text)"]
+        C["Your Code"]:::highlight
+        D["Text-to-speech"]
+        B --> C --> D
+    end
+
+    %% Output
+    E["🎧 Audio Output"]
+
+    %% Flow
+    A --> Voice_Pipeline
+    Voice_Pipeline --> E
+
+    %% Custom styling
+    classDef highlight fill:#ffcc66,stroke:#333,stroke-width:1px,font-weight:700;
+
+```
+
+## Configuring a pipeline
+
+When you create a pipeline, you can set a few things:
+
+1. The [`workflow`][agents.voice.workflow.VoiceWorkflowBase], which is the code that runs each time new audio is transcribed.
+2. The [`speech-to-text`][agents.voice.model.STTModel] and [`text-to-speech`][agents.voice.model.TTSModel] models used
+3. The [`config`][agents.voice.pipeline_config.VoicePipelineConfig], which lets you configure things like:
+    - A model provider, which can map model names to models
+    - Tracing, including whether to disable tracing, whether audio files are uploaded, the workflow name, trace IDs etc.
+    - Settings on the TTS and STT models, like the prompt, language and data types used.
+
+## Running a pipeline
+
+You can run a pipeline via the [`run()`][agents.voice.pipeline.VoicePipeline.run] method, which lets you pass in audio input in two forms:
+
+1. [`AudioInput`][agents.voice.input.AudioInput] is used when you have a full audio transcript, and just want to produce a result for it. This is useful in cases where you don't need to detect when a speaker is done speaking; for example, when you have pre-recorded audio or in push-to-talk apps where it's clear when the user is done speaking.
+2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] is used when you might need to detect when a user is done speaking. It allows you to push audio chunks as they are detected, and the voice pipeline will automatically run the agent workflow at the right time, via a process called "activity detection".
+
+## Results
+
+The result of a voice pipeline run is a [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]. This is an object that lets you stream events as they occur. There are a few kinds of [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent], including:
+
+1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio], which contains a chunk of audio.
+2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle], which informs you of lifecycle events like a turn starting or ending.
+3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError], is an error event.
+
+```python
+
+result = await pipeline.run(input)
+
+async for event in result.stream():
+    if event.type == "voice_stream_event_audio":
+        # play audio
+    elif event.type == "voice_stream_event_lifecycle":
+        # lifecycle
+    elif event.type == "voice_stream_event_error"
+        # error
+    ...
+```
+
+## Best practices
+
+### Interruptions
+
+The Agents SDK currently does not support any built-in interruptions support for [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]. Instead for every detected turn it will trigger a separate run of your workflow. If you want to handle interruptions inside your application you can listen to the [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] events. `turn_started` will indicate that a new turn was transcribed and processing is beginning. `turn_ended` will trigger after all the audio was dispatched for a respective turn. You could use these events to mute the microphone of the speaker when the model starts a turn and unmute it after you flushed all the related audio for a turn.