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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.0.5
+Version: 0.0.6
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://github.com/openai/openai-agents-python
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -24,6 +24,9 @@ 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: 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 +61,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.6}/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.6/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.6/docs/ref/voice/events.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openai_agents-0.0.6/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.

openai_agents-0.0.6/docs/voice/quickstart.md

@@ -0,0 +1,189 @@
+# Quickstart
+
+## Prerequisites
+
+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:
+
+```bash
+pip install openai-agents[voice]
+```
+
+## Concepts
+
+The main concept to know about is a [`VoicePipeline`][agents.voice.pipeline.VoicePipeline], which is a 3 step process:
+
+1. Run a speech-to-text model to turn audio into text.
+2. Run your code, which is usually an agentic workflow, to produce a result.
+3. Run a text-to-speech model to turn the result text 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;
+
+```
+
+## Agents
+
+First, let's set up some Agents. This should feel familiar to you if you've built any agents with this SDK. We'll have a couple of Agents, a handoff, and a tool.
+
+```python
+import asyncio
+import random
+
+from agents import (
+    Agent,
+    function_tool,
+)
+from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
+
+
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Get the weather for a given city."""
+    print(f"[debug] get_weather called with city: {city}")
+    choices = ["sunny", "cloudy", "rainy", "snowy"]
+    return f"The weather in {city} is {random.choice(choices)}."
+
+
+spanish_agent = Agent(
+    name="Spanish",
+    handoff_description="A spanish speaking agent.",
+    instructions=prompt_with_handoff_instructions(
+        "You're speaking to a human, so be polite and concise. Speak in Spanish.",
+    ),
+    model="gpt-4o-mini",
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions=prompt_with_handoff_instructions(
+        "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
+    ),
+    model="gpt-4o-mini",
+    handoffs=[spanish_agent],
+    tools=[get_weather],
+)
+```
+
+## Voice pipeline
+
+We'll set up a simple voice pipeline, using [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] as the workflow.
+
+```python
+from agents import SingleAgentVoiceWorkflow, VoicePipeline,
+pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
+```
+
+## Run the pipeline
+
+```python
+import numpy as np
+import sounddevice as sd
+
+# For simplicity, we'll just create 3 seconds of silence
+# In reality, you'd get microphone data
+audio = np.zeros(24000 * 3, dtype=np.int16)
+result = await pipeline.run(audio_input)
+
+# Create an audio player using `sounddevice`
+player = sd.OutputStream(samplerate=24000, channels=1, dtype=np.int16)
+player.start()
+
+# Play the audio stream as it comes in
+async for event in result.stream():
+    if event.type == "voice_stream_event_audio":
+        player.write(event.data)
+
+```
+
+## Put it all together
+
+```python
+import asyncio
+import random
+
+import numpy as np
+import sounddevice as sd
+
+from agents import (
+    Agent,
+    AudioInput,
+    SingleAgentVoiceWorkflow,
+    VoicePipeline,
+    function_tool,
+    set_tracing_disabled,
+)
+from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
+
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Get the weather for a given city."""
+    print(f"[debug] get_weather called with city: {city}")
+    choices = ["sunny", "cloudy", "rainy", "snowy"]
+    return f"The weather in {city} is {random.choice(choices)}."
+
+
+spanish_agent = Agent(
+    name="Spanish",
+    handoff_description="A spanish speaking agent.",
+    instructions=prompt_with_handoff_instructions(
+        "You're speaking to a human, so be polite and concise. Speak in Spanish.",
+    ),
+    model="gpt-4o-mini",
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions=prompt_with_handoff_instructions(
+        "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
+    ),
+    model="gpt-4o-mini",
+    handoffs=[spanish_agent],
+    tools=[get_weather],
+)
+
+
+async def main():
+    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
+    buffer = np.zeros(24000 * 3, dtype=np.int16)
+    audio_input = AudioInput(buffer=buffer)
+
+    result = await pipeline.run(audio_input)
+
+    # Create an audio player using `sounddevice`
+    player = sd.OutputStream(samplerate=24000, channels=1, dtype=np.int16)
+    player.start()
+
+    # Play the audio stream as it comes in
+    async for event in result.stream():
+        if event.type == "voice_stream_event_audio":
+            player.write(event.data)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+If you run this example, the agent will speak to you! Check out the example in [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) to see a demo where you can speak to the agent yourself.

openai_agents-0.0.6/docs/voice/tracing.md

@@ -0,0 +1,14 @@
+# Tracing
+
+Just like the way [agents are traced](../tracing.md), voice pipelines are also automatically traced.
+
+You can read the tracing doc above for basic tracing information, but you can additionally configure tracing of a pipeline via [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig].
+
+Key tracing related fields are:
+
+-   [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: controls whether tracing is disabled. By default, tracing is enabled.
+-   [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: controls whether traces include potentially sensitive data, like audio transcripts. This is specifically for the voice pipeline, and not for anything that goes on inside your Workflow.
+-   [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: controls whether traces include audio data.
+-   [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: The name of the trace workflow.
+-   [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: The `group_id` of the trace, which lets you link multiple traces.
+-   [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: Additional metadata to include with the trace.

openai_agents-0.0.6/examples/financial_research_agent/README.md

@@ -0,0 +1,38 @@
+# Financial Research Agent Example
+
+This example shows how you might compose a richer financial research agent using the Agents SDK. The pattern is similar to the `research_bot` example, but with more specialized sub‑agents and a verification step.
+
+The flow is:
+
+1. **Planning**: A planner agent turns the end user’s request into a list of search terms relevant to financial analysis – recent news, earnings calls, corporate filings, industry commentary, etc.
+2. **Search**: A search agent uses the built‑in `WebSearchTool` to retrieve terse summaries for each search term. (You could also add `FileSearchTool` if you have indexed PDFs or 10‑Ks.)
+3. **Sub‑analysts**: Additional agents (e.g. a fundamentals analyst and a risk analyst) are exposed as tools so the writer can call them inline and incorporate their outputs.
+4. **Writing**: A senior writer agent brings together the search snippets and any sub‑analyst summaries into a long‑form markdown report plus a short executive summary.
+5. **Verification**: A final verifier agent audits the report for obvious inconsistencies or missing sourcing.
+
+You can run the example with:
+
+```bash
+python -m examples.financial_research_agent.main
+```
+
+and enter a query like:
+
+```
+Write up an analysis of Apple Inc.'s most recent quarter.
+```
+
+### Starter prompt
+
+The writer agent is seeded with instructions similar to:
+
+```
+You are a senior financial analyst. You will be provided with the original query
+and a set of raw search summaries. Your job is to synthesize these into a
+long‑form markdown report (at least several paragraphs) with a short executive
+summary. You also have access to tools like `fundamentals_analysis` and
+`risk_analysis` to get short specialist write‑ups if you want to incorporate them.
+Add a few follow‑up questions for further research.
+```
+
+You can tweak these prompts and sub‑agents to suit your own data sources and preferred report structure.

openai_agents-0.0.6/examples/financial_research_agent/agents/financials_agent.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+
+from agents import Agent
+
+# A sub‑agent focused on analyzing a company's fundamentals.
+FINANCIALS_PROMPT = (
+    "You are a financial analyst focused on company fundamentals such as revenue, "
+    "profit, margins and growth trajectory. Given a collection of web (and optional file) "
+    "search results about a company, write a concise analysis of its recent financial "
+    "performance. Pull out key metrics or quotes. Keep it under 2 paragraphs."
+)
+
+
+class AnalysisSummary(BaseModel):
+    summary: str
+    """Short text summary for this aspect of the analysis."""
+
+
+financials_agent = Agent(
+    name="FundamentalsAnalystAgent",
+    instructions=FINANCIALS_PROMPT,
+    output_type=AnalysisSummary,
+)

openai_agents-0.0.6/examples/financial_research_agent/agents/planner_agent.py

@@ -0,0 +1,35 @@
+from pydantic import BaseModel
+
+from agents import Agent
+
+# Generate a plan of searches to ground the financial analysis.
+# For a given financial question or company, we want to search for
+# recent news, official filings, analyst commentary, and other
+# relevant background.
+PROMPT = (
+    "You are a financial research planner. Given a request for financial analysis, "
+    "produce a set of web searches to gather the context needed. Aim for recent "
+    "headlines, earnings calls or 10‑K snippets, analyst commentary, and industry background. "
+    "Output between 5 and 15 search terms to query for."
+)
+
+
+class FinancialSearchItem(BaseModel):
+    reason: str
+    """Your reasoning for why this search is relevant."""
+
+    query: str
+    """The search term to feed into a web (or file) search."""
+
+
+class FinancialSearchPlan(BaseModel):
+    searches: list[FinancialSearchItem]
+    """A list of searches to perform."""
+
+
+planner_agent = Agent(
+    name="FinancialPlannerAgent",
+    instructions=PROMPT,
+    model="o3-mini",
+    output_type=FinancialSearchPlan,
+)

openai_agents-0.0.6/examples/financial_research_agent/agents/risk_agent.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+
+from agents import Agent
+
+# A sub‑agent specializing in identifying risk factors or concerns.
+RISK_PROMPT = (
+    "You are a risk analyst looking for potential red flags in a company's outlook. "
+    "Given background research, produce a short analysis of risks such as competitive threats, "
+    "regulatory issues, supply chain problems, or slowing growth. Keep it under 2 paragraphs."
+)
+
+
+class AnalysisSummary(BaseModel):
+    summary: str
+    """Short text summary for this aspect of the analysis."""
+
+
+risk_agent = Agent(
+    name="RiskAnalystAgent",
+    instructions=RISK_PROMPT,
+    output_type=AnalysisSummary,
+)

openai_agents-0.0.6/examples/financial_research_agent/agents/search_agent.py

@@ -0,0 +1,18 @@
+from agents import Agent, WebSearchTool
+from agents.model_settings import ModelSettings
+
+# Given a search term, use web search to pull back a brief summary.
+# Summaries should be concise but capture the main financial points.
+INSTRUCTIONS = (
+    "You are a research assistant specializing in financial topics. "
+    "Given a search term, use web search to retrieve up‑to‑date context and "
+    "produce a short summary of at most 300 words. Focus on key numbers, events, "
+    "or quotes that will be useful to a financial analyst."
+)
+
+search_agent = Agent(
+    name="FinancialSearchAgent",
+    instructions=INSTRUCTIONS,
+    tools=[WebSearchTool()],
+    model_settings=ModelSettings(tool_choice="required"),
+)

openai_agents-0.0.6/examples/financial_research_agent/agents/verifier_agent.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel
+
+from agents import Agent
+
+# Agent to sanity‑check a synthesized report for consistency and recall.
+# This can be used to flag potential gaps or obvious mistakes.
+VERIFIER_PROMPT = (
+    "You are a meticulous auditor. You have been handed a financial analysis report. "
+    "Your job is to verify the report is internally consistent, clearly sourced, and makes "
+    "no unsupported claims. Point out any issues or uncertainties."
+)
+
+
+class VerificationResult(BaseModel):
+    verified: bool
+    """Whether the report seems coherent and plausible."""
+
+    issues: str
+    """If not verified, describe the main issues or concerns."""
+
+
+verifier_agent = Agent(
+    name="VerificationAgent",
+    instructions=VERIFIER_PROMPT,
+    model="gpt-4o",
+    output_type=VerificationResult,
+)

openai_agents-0.0.6/examples/financial_research_agent/agents/writer_agent.py

@@ -0,0 +1,34 @@
+from pydantic import BaseModel
+
+from agents import Agent
+
+# Writer agent brings together the raw search results and optionally calls out
+# to sub‑analyst tools for specialized commentary, then returns a cohesive markdown report.
+WRITER_PROMPT = (
+    "You are a senior financial analyst. You will be provided with the original query and "
+    "a set of raw search summaries. Your task is to synthesize these into a long‑form markdown "
+    "report (at least several paragraphs) including a short executive summary and follow‑up "
+    "questions. If needed, you can call the available analysis tools (e.g. fundamentals_analysis, "
+    "risk_analysis) to get short specialist write‑ups to incorporate."
+)
+
+
+class FinancialReportData(BaseModel):
+    short_summary: str
+    """A short 2‑3 sentence executive summary."""
+
+    markdown_report: str
+    """The full markdown report."""
+
+    follow_up_questions: list[str]
+    """Suggested follow‑up questions for further research."""
+
+
+# Note: We will attach handoffs to specialist analyst agents at runtime in the manager.
+# This shows how an agent can use handoffs to delegate to specialized subagents.
+writer_agent = Agent(
+    name="FinancialWriterAgent",
+    instructions=WRITER_PROMPT,
+    model="gpt-4.5-preview-2025-02-27",
+    output_type=FinancialReportData,
+)

openai_agents-0.0.6/examples/financial_research_agent/main.py

@@ -0,0 +1,17 @@
+import asyncio
+
+from .manager import FinancialResearchManager
+
+
+# Entrypoint for the financial bot example.
+# Run this as `python -m examples.financial_bot.main` and enter a
+# financial research query, for example:
+# "Write up an analysis of Apple Inc.'s most recent quarter."
+async def main() -> None:
+    query = input("Enter a financial research query: ")
+    mgr = FinancialResearchManager()
+    await mgr.run(query)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())