openai-agents 0.3.1__tar.gz → 0.3.2__tar.gz

{openai_agents-0.3.1 → openai_agents-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.3.1
+Version: 0.3.2
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://openai.github.io/openai-agents-python/
 Project-URL: Repository, https://github.com/openai/openai-agents-python

openai_agents-0.3.2/docs/llms-full.txt

@@ -0,0 +1,112 @@
+# OpenAI Agents SDK Documentation (Full Context)
+
+> Extended reference map for the OpenAI Agents SDK documentation site. Use these curated links when assembling prompts that need authoritative guidance on building, operating, and extending agentic applications with the SDK.
+
+The Agents SDK delivers a focused set of Python primitives—agents, tools, guardrails, handoffs, sessions, and tracing—plus voice and realtime interfaces. The pages below provide detailed walkthroughs, architectural patterns, and API-level documentation for integrating those capabilities into production systems.
+
+## Getting Started and Orientation
+- [Overview](https://openai.github.io/openai-agents-python/): Conceptual tour of the SDK, covering the core agent loop, motivation, installation snippet, and a runnable hello-world.
+- [Quickstart](https://openai.github.io/openai-agents-python/quickstart/): Guided setup from environment preparation through running and monitoring your first agent, including troubleshooting tips.
+- [Example Gallery](https://openai.github.io/openai-agents-python/examples/): Realistic Python samples that demonstrate tool orchestration, guardrails, streaming, and integrations with external systems.
+- [Release notes](https://openai.github.io/openai-agents-python/release/): Version-by-version change log with migration notes for breaking updates.
+- [Usage and pricing](https://openai.github.io/openai-agents-python/usage/): Explains how token usage is tracked, how to retrieve usage metadata, and how to forecast cost for different deployment patterns.
+- [Configuration](https://openai.github.io/openai-agents-python/config/): Centralized reference for tuning model settings, retries, rate limits, timeouts, logging, and runner behavior.
+
+## Core Agent Workflows
+- [Agents](https://openai.github.io/openai-agents-python/agents/): Defines agent objects, instruction design, tool registration, guardrail attachment, streaming options, and lifecycle hooks.
+- [Running agents](https://openai.github.io/openai-agents-python/running_agents/): Covers synchronous and asynchronous execution, concurrency controls, background tasks, cancellation, and handling failures.
+- [Sessions](https://openai.github.io/openai-agents-python/sessions/): Describes persistent session state, conversation threading, history pruning, and custom session storage backends.
+- [Context strategies](https://openai.github.io/openai-agents-python/context/): Techniques for tailoring prompts, managing attachments, trimming history, and injecting auxiliary context into runs.
+- [Results](https://openai.github.io/openai-agents-python/results/): Breaks down the result object, including final output, tool call transcripts, intermediate messages, and metadata fields.
+- [Streaming](https://openai.github.io/openai-agents-python/streaming/): Shows how to subscribe to incremental events, stream tool progress, and render partial model outputs in real time.
+- [REPL](https://openai.github.io/openai-agents-python/repl/): Interactive runner for exploring agent behavior, step-by-step execution, and debugging tool calls.
+- [Visualization](https://openai.github.io/openai-agents-python/visualization/): Demonstrates embeddable visualizations for session timelines, message flows, and tool interactions.
+
+## Coordination, Safety, and Tooling
+- [Handoffs](https://openai.github.io/openai-agents-python/handoffs/): Implements delegation between agents, argument passing, completion handling, and error recovery across agent boundaries.
+- [Multi-agent patterns](https://openai.github.io/openai-agents-python/multi_agent/): Architecture playbook for designing specialist teams, escalation workflows, and role-based collaboration strategies.
+- [Guardrails](https://openai.github.io/openai-agents-python/guardrails/): Create synchronous or asynchronous checks, short-circuit runs, and emit structured validation reports.
+- [Tools](https://openai.github.io/openai-agents-python/tools/): Turn Python callables into structured tools, manage schemas, compose tool contexts, and test tool execution paths.
+- [Model Context Protocol](https://openai.github.io/openai-agents-python/mcp/): Integrate MCP servers so agents can dynamically request data or actions from external providers via a standard protocol.
+
+## Modality-Specific Guides
+- [Voice quickstart](https://openai.github.io/openai-agents-python/voice/quickstart/): Build an end-to-end voice assistant with streaming transcription, text-to-speech, and event-driven responses.
+- [Voice pipeline](https://openai.github.io/openai-agents-python/voice/pipeline/): Customize audio capture, buffering, model invocation, and playback in voice-first experiences.
+- [Voice tracing](https://openai.github.io/openai-agents-python/voice/tracing/): Inspect voice session traces, latency breakdowns, and audio event timelines.
+- [Realtime quickstart](https://openai.github.io/openai-agents-python/realtime/quickstart/): Launch realtime agents over WebRTC or websockets, subscribe to events, and manage low-latency execution.
+- [Realtime guide](https://openai.github.io/openai-agents-python/realtime/guide/): Deep dive into realtime session lifecycle, event schemas, concurrency, and backpressure handling.
+
+## Models and Provider Integrations
+- [Model catalog](https://openai.github.io/openai-agents-python/models/): Lists supported OpenAI and partner models with guidance on selecting capabilities for different workloads.
+- [LiteLLM integration](https://openai.github.io/openai-agents-python/models/litellm/): Configure LiteLLM as a provider, map model aliases, and route requests across heterogeneous backends.
+
+## API Reference – Agents SDK Core
+- [API index](https://openai.github.io/openai-agents-python/ref/index/): Directory of all documented modules, classes, and functions in the SDK.
+- [agents.Agent](https://openai.github.io/openai-agents-python/ref/agent/): Constructor arguments, behaviors, guardrail hooks, and serialization helpers.
+- [runs and runners](https://openai.github.io/openai-agents-python/ref/run/): Runner interfaces for launching agents, streaming events, handling cancellations, and background execution.
+- [memory interfaces](https://openai.github.io/openai-agents-python/ref/memory/): Session memory primitives, storage adapters, and utilities for retrieving historical context.
+- [repl utilities](https://openai.github.io/openai-agents-python/ref/repl/): Programmatic access to the interactive REPL loop and inspection helpers.
+- [tool base classes](https://openai.github.io/openai-agents-python/ref/tool/): Tool registration, invocation, and structured argument parsing.
+- [tool context helpers](https://openai.github.io/openai-agents-python/ref/tool_context/): Manage shared resources, dependency injection, and cleanup for tool execution.
+- [result objects](https://openai.github.io/openai-agents-python/ref/result/): Fields exposed on run results, including final content, tool call summaries, and attachments.
+- [stream events](https://openai.github.io/openai-agents-python/ref/stream_events/): Event models emitted during streaming runs and their payload schemas.
+- [handoffs module](https://openai.github.io/openai-agents-python/ref/handoffs/): Programmatic API for defining, routing, and resolving handoffs between agents.
+- [lifecycle callbacks](https://openai.github.io/openai-agents-python/ref/lifecycle/): Hooks for intercepting agent stages, customizing evaluation, and logging intermediate data.
+- [items API](https://openai.github.io/openai-agents-python/ref/items/): Low-level primitives that represent agent messages, tool calls, and attachments.
+- [run context utilities](https://openai.github.io/openai-agents-python/ref/run_context/): Context managers and helpers for passing metadata through nested tool executions.
+- [usage tracking](https://openai.github.io/openai-agents-python/ref/usage/): Inspect token usage, durations, and cost metrics from completed runs.
+- [exceptions](https://openai.github.io/openai-agents-python/ref/exceptions/): Exception hierarchy raised by the SDK and recommendations for resilient error handling.
+- [guardrail APIs](https://openai.github.io/openai-agents-python/ref/guardrail/): Build custom guardrails, interpret validation outcomes, and integrate enforcement logic.
+- [model settings](https://openai.github.io/openai-agents-python/ref/model_settings/): Shared configuration objects for model parameters, temperature, and tool invocation settings.
+- [agent output models](https://openai.github.io/openai-agents-python/ref/agent_output/): Typed models describing message content, tool calls, and aggregated agent responses.
+- [function schema utilities](https://openai.github.io/openai-agents-python/ref/function_schema/): Helpers for generating JSON schemas from Python functions and Pydantic models.
+- [model interfaces](https://openai.github.io/openai-agents-python/ref/models/interface/): Abstractions for pluggable model providers.
+- [OpenAI chat completions provider](https://openai.github.io/openai-agents-python/ref/models/openai_chatcompletions/): Implementation details for the chat-completions-based model adapter.
+- [OpenAI responses provider](https://openai.github.io/openai-agents-python/ref/models/openai_responses/): Implementation details for the responses API adapter.
+- [MCP server helpers](https://openai.github.io/openai-agents-python/ref/mcp/server/): Utilities for building MCP servers that expose tools to agents.
+- [MCP client utilities](https://openai.github.io/openai-agents-python/ref/mcp/util/): Helpers for consuming MCP servers from within agents.
+
+## API Reference – Tracing
+- [Tracing overview](https://openai.github.io/openai-agents-python/ref/tracing/index/): End-to-end API documentation for tracing components.
+- [Creating traces](https://openai.github.io/openai-agents-python/ref/tracing/create/): Programmatic APIs for instantiating traces and attaching metadata.
+- [Trace model](https://openai.github.io/openai-agents-python/ref/tracing/traces/): Data models representing traces and their relationships.
+- [Span model](https://openai.github.io/openai-agents-python/ref/tracing/spans/): Span structure, timing data, and message attribution.
+- [Processor interface](https://openai.github.io/openai-agents-python/ref/tracing/processor_interface/): Contract for custom processors that consume trace events.
+- [Bundled processors](https://openai.github.io/openai-agents-python/ref/tracing/processors/): Built-in processors for exporting traces to external systems.
+- [Tracing scope](https://openai.github.io/openai-agents-python/ref/tracing/scope/): Context managers that manage active traces and spans.
+- [Tracing setup](https://openai.github.io/openai-agents-python/ref/tracing/setup/): Configuration helpers for initializing tracing in applications and tests.
+- [Span data utilities](https://openai.github.io/openai-agents-python/ref/tracing/span_data/): Helper models for span payloads and events.
+- [Tracing utility helpers](https://openai.github.io/openai-agents-python/ref/tracing/util/): Miscellaneous tracing utilities, exporters, and logging helpers.
+
+## API Reference – Realtime
+- [Realtime agent API](https://openai.github.io/openai-agents-python/ref/realtime/agent/): Programmatic interface for realtime agents.
+- [Realtime runner](https://openai.github.io/openai-agents-python/ref/realtime/runner/): Manage realtime execution loops, concurrency, and cleanup.
+- [Realtime session](https://openai.github.io/openai-agents-python/ref/realtime/session/): Lifecycle and state management for realtime sessions.
+- [Realtime events](https://openai.github.io/openai-agents-python/ref/realtime/events/): Event payload types delivered over realtime channels.
+- [Realtime config](https://openai.github.io/openai-agents-python/ref/realtime/config/): Configuration models for realtime transports and behaviors.
+- [Realtime model interface](https://openai.github.io/openai-agents-python/ref/realtime/model/): Interfaces for plugging in realtime-capable models.
+
+## API Reference – Voice
+- [Voice pipeline API](https://openai.github.io/openai-agents-python/ref/voice/pipeline/): Programmatic control over the voice pipeline and event flow.
+- [Voice workflow helpers](https://openai.github.io/openai-agents-python/ref/voice/workflow/): Orchestrate conversational voice workflows.
+- [Voice input models](https://openai.github.io/openai-agents-python/ref/voice/input/): Structured representations of microphone and streaming audio input.
+- [Voice result models](https://openai.github.io/openai-agents-python/ref/voice/result/): Output schema for voice responses, transcripts, and tool invocations.
+- [Voice pipeline config](https://openai.github.io/openai-agents-python/ref/voice/pipeline_config/): Configuration options for buffer sizes, concurrency, and model routing.
+- [Voice events](https://openai.github.io/openai-agents-python/ref/voice/events/): Event payloads describing voice session updates.
+- [Voice exceptions](https://openai.github.io/openai-agents-python/ref/voice/exceptions/): Exception types for voice pipelines and error handling guidance.
+- [Voice model adapters](https://openai.github.io/openai-agents-python/ref/voice/model/): Interfaces for voice-enabled models and synthesis engines.
+- [Voice utility helpers](https://openai.github.io/openai-agents-python/ref/voice/utils/): Audio conversion, streaming helpers, and testing utilities.
+- [OpenAI voice provider](https://openai.github.io/openai-agents-python/ref/voice/models/openai_provider/): Adapter for OpenAI voice models.
+- [OpenAI speech-to-text provider](https://openai.github.io/openai-agents-python/ref/voice/models/openai_stt/): Integration for STT models used in the pipeline.
+- [OpenAI text-to-speech provider](https://openai.github.io/openai-agents-python/ref/voice/models/openai_tts/): Adapter for OpenAI TTS output.
+
+## API Reference – Extensions
+- [Handoff filters extension](https://openai.github.io/openai-agents-python/ref/extensions/handoff_filters/): Build filters that decide whether to trigger a handoff.
+- [Handoff prompt extension](https://openai.github.io/openai-agents-python/ref/extensions/handoff_prompt/): Customize prompt templates used when transferring control.
+- [LiteLLM extension](https://openai.github.io/openai-agents-python/ref/extensions/litellm/): Adapter for using LiteLLM-managed providers inside the SDK.
+- [SQLAlchemy session memory](https://openai.github.io/openai-agents-python/ref/extensions/memory/sqlalchemy_session/): Persist agent session history to SQL databases.
+
+## Optional
+- [Japanese documentation](https://openai.github.io/openai-agents-python/ja/): Localized guides mirroring the core English documentation.
+- [GitHub repository](https://github.com/openai/openai-agents-python): Source code, issues, and contribution resources.
+- [Agents SDK package on PyPI](https://pypi.org/project/openai-agents/): Distribution page with installation command and release history.

openai_agents-0.3.2/docs/llms.txt

@@ -0,0 +1,60 @@
+# OpenAI Agents SDK Documentation
+
+> Official documentation for building production-ready agentic applications with the OpenAI Agents SDK, a Python toolkit that equips LLM-powered assistants with tools, guardrails, handoffs, sessions, tracing, voice, and realtime capabilities.
+
+The SDK focuses on a concise set of primitives so you can orchestrate multi-agent workflows without heavy abstractions. These pages explain how to install the library, design agents, coordinate tools, handle results, and extend the platform to new modalities.
+
+## Start Here
+- [Overview](https://openai.github.io/openai-agents-python/): Learn the core primitives—agents, handoffs, guardrails, sessions, and tracing—and see a minimal hello-world example.
+- [Quickstart](https://openai.github.io/openai-agents-python/quickstart/): Step-by-step setup for installing the package, configuring API keys, and running your first agent locally.
+- [Example Gallery](https://openai.github.io/openai-agents-python/examples/): Task-oriented examples that demonstrate agent loops, tool usage, guardrails, and integration patterns.
+
+## Core Concepts
+- [Agents](https://openai.github.io/openai-agents-python/agents/): Configure agent instructions, tools, guardrails, memory, and streaming behavior.
+- [Running agents](https://openai.github.io/openai-agents-python/running_agents/): Learn synchronous, asynchronous, and batched execution, plus cancellation and error handling.
+- [Sessions](https://openai.github.io/openai-agents-python/sessions/): Manage stateful conversations with automatic history persistence and memory controls.
+- [Results](https://openai.github.io/openai-agents-python/results/): Inspect agent outputs, tool calls, follow-up actions, and metadata returned by the runner.
+- [Streaming](https://openai.github.io/openai-agents-python/streaming/): Stream intermediate tool usage and LLM responses for responsive UIs.
+- [REPL](https://openai.github.io/openai-agents-python/repl/): Use the interactive runner to prototype agents and inspect execution step by step.
+- [Context strategies](https://openai.github.io/openai-agents-python/context/): Control what past messages, attachments, and tool runs are injected into prompts.
+
+## Coordination and Safety
+- [Handoffs](https://openai.github.io/openai-agents-python/handoffs/): Delegate tasks between agents with intent classification, argument passing, and return values.
+- [Multi-agent patterns](https://openai.github.io/openai-agents-python/multi_agent/): Architect teams of agents that collaborate, escalate, or specialize by capability.
+- [Guardrails](https://openai.github.io/openai-agents-python/guardrails/): Define validators that run alongside the agent loop to enforce business and safety rules.
+- [Tools](https://openai.github.io/openai-agents-python/tools/): Register Python callables as structured tools, manage schemas, and work with tool contexts.
+- [Model Context Protocol](https://openai.github.io/openai-agents-python/mcp/): Connect MCP servers so agents can request external data or actions through standardized tool APIs.
+
+## Operations and Configuration
+- [Usage and pricing](https://openai.github.io/openai-agents-python/usage/): Understand token accounting, usage metrics, and cost estimation.
+- [Configuration](https://openai.github.io/openai-agents-python/config/): Tune model selection, retry logic, rate limits, and runner policies for production workloads.
+- [Visualization](https://openai.github.io/openai-agents-python/visualization/): Embed tracing dashboards and visualize agent runs directly in notebooks and web apps.
+
+## Observability and Tracing
+- [Tracing](https://openai.github.io/openai-agents-python/tracing/): Capture spans for every agent step, emit data to OpenAI traces, and integrate third-party processors.
+
+## Modalities and Interfaces
+- [Voice quickstart](https://openai.github.io/openai-agents-python/voice/quickstart/): Build speech-enabled agents with streaming transcription and TTS.
+- [Voice pipeline](https://openai.github.io/openai-agents-python/voice/pipeline/): Customize audio ingestion, tool execution, and response rendering.
+- [Realtime quickstart](https://openai.github.io/openai-agents-python/realtime/quickstart/): Stand up low-latency realtime agents with WebRTC and websocket transports.
+- [Realtime guide](https://openai.github.io/openai-agents-python/realtime/guide/): Deep dive into session lifecycle, event formats, and concurrency patterns.
+
+## API Reference Highlights
+- [Agents API index](https://openai.github.io/openai-agents-python/ref/index/): Entry point for class and function documentation throughout the SDK.
+- [Agent lifecycle](https://openai.github.io/openai-agents-python/ref/lifecycle/): Understand the runner, evaluation phases, and callbacks triggered during execution.
+- [Runs and sessions](https://openai.github.io/openai-agents-python/ref/run/): API for launching runs, streaming updates, and handling cancellations.
+- [Results objects](https://openai.github.io/openai-agents-python/ref/result/): Data structures returned from agent runs, including final output and tool calls.
+- [Tool interfaces](https://openai.github.io/openai-agents-python/ref/tool/): Create tools, parse arguments, and manage tool execution contexts.
+- [Tracing APIs](https://openai.github.io/openai-agents-python/ref/tracing/index/): Programmatic interfaces for creating traces, spans, and integrating custom processors.
+- [Realtime APIs](https://openai.github.io/openai-agents-python/ref/realtime/agent/): Classes for realtime agents, runners, sessions, and event payloads.
+- [Voice APIs](https://openai.github.io/openai-agents-python/ref/voice/pipeline/): Configure voice pipelines, inputs, events, and model adapters.
+- [Extensions](https://openai.github.io/openai-agents-python/ref/extensions/handoff_filters/): Extend the SDK with custom handoff filters, prompts, LiteLLM integration, and SQLAlchemy session memory.
+
+## Models and Providers
+- [Model catalog](https://openai.github.io/openai-agents-python/models/): Overview of supported model families and configuration guidance.
+- [LiteLLM integration](https://openai.github.io/openai-agents-python/models/litellm/): Configure LiteLLM as a provider to fan out across multiple model backends.
+
+## Optional
+- [Release notes](https://openai.github.io/openai-agents-python/release/): Track SDK changes, migration notes, and deprecations.
+- [Japanese documentation](https://openai.github.io/openai-agents-python/ja/): Localized overview and quickstart for Japanese-speaking developers.
+- [Repository on GitHub](https://github.com/openai/openai-agents-python): Source code, issues, and contribution guidelines for the SDK.

{openai_agents-0.3.1 → openai_agents-0.3.2}/examples/basic/dynamic_system_prompt.py

@@ -1,13 +1,14 @@
 import asyncio
 import random
+from dataclasses import dataclass
 from typing import Literal
 
 from agents import Agent, RunContextWrapper, Runner
 
 
+@dataclass
 class CustomContext:
-    def __init__(self, style: Literal["haiku", "pirate", "robot"]):
-        self.style = style
+    style: Literal["haiku", "pirate", "robot"]
 
 
 def custom_instructions(
@@ -27,11 +28,9 @@ agent = Agent(
     instructions=custom_instructions,
 )
 
-
 async def main():
-    choice: Literal["haiku", "pirate", "robot"] = random.choice(["haiku", "pirate", "robot"])
-    context = CustomContext(style=choice)
-    print(f"Using style: {choice}\n")
+    context = CustomContext(style=random.choice(["haiku", "pirate", "robot"]))
+    print(f"Using style: {context.style}\n")
 
     user_message = "Tell me a joke."
     print(f"User: {user_message}")
@@ -43,6 +42,7 @@ async def main():
 if __name__ == "__main__":
     asyncio.run(main())
 
+
 """
 $ python examples/basic/dynamic_system_prompt.py
 

{openai_agents-0.3.1 → openai_agents-0.3.2}/examples/basic/lifecycle_example.py

@@ -46,7 +46,7 @@ class ExampleHooks(RunHooks):
     async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None:
         self.event_counter += 1
         print(
-            f"### {self.event_counter}: Tool {tool.name} started. Usage: {self._usage_to_str(context.usage)}"
+            f"### {self.event_counter}: Tool {tool.name} started. name={context.tool_name}, call_id={context.tool_call_id}, args={context.tool_arguments}. Usage: {self._usage_to_str(context.usage)}"  # type: ignore[attr-defined]
         )
 
     async def on_tool_end(
@@ -54,7 +54,7 @@ class ExampleHooks(RunHooks):
     ) -> None:
         self.event_counter += 1
         print(
-            f"### {self.event_counter}: Tool {tool.name} ended with result {result}. Usage: {self._usage_to_str(context.usage)}"
+            f"### {self.event_counter}: Tool {tool.name} finished. result={result}, name={context.tool_name}, call_id={context.tool_call_id}, args={context.tool_arguments}. Usage: {self._usage_to_str(context.usage)}"  # type: ignore[attr-defined]
         )
 
     async def on_handoff(
@@ -128,19 +128,19 @@ Enter a max number: 250
 ### 1: Agent Start Agent started. Usage: 0 requests, 0 input tokens, 0 output tokens, 0 total tokens
 ### 2: LLM started. Usage: 0 requests, 0 input tokens, 0 output tokens, 0 total tokens
 ### 3: LLM ended. Usage: 1 requests, 143 input tokens, 15 output tokens, 158 total tokens
-### 4: Tool random_number started. Usage: 1 requests, 143 input tokens, 15 output tokens, 158 total tokens
-### 5: Tool random_number ended with result 69. Usage: 1 requests, 143 input tokens, 15 output tokens, 158 total tokens
+### 4: Tool random_number started. name=random_number, call_id=call_IujmDZYiM800H0hy7v17VTS0, args={"max":250}. Usage: 1 requests, 143 input tokens, 15 output tokens, 158 total tokens
+### 5: Tool random_number finished. result=107, name=random_number, call_id=call_IujmDZYiM800H0hy7v17VTS0, args={"max":250}. Usage: 1 requests, 143 input tokens, 15 output tokens, 158 total tokens
 ### 6: LLM started. Usage: 1 requests, 143 input tokens, 15 output tokens, 158 total tokens
 ### 7: LLM ended. Usage: 2 requests, 310 input tokens, 29 output tokens, 339 total tokens
 ### 8: Handoff from Start Agent to Multiply Agent. Usage: 2 requests, 310 input tokens, 29 output tokens, 339 total tokens
 ### 9: Agent Multiply Agent started. Usage: 2 requests, 310 input tokens, 29 output tokens, 339 total tokens
 ### 10: LLM started. Usage: 2 requests, 310 input tokens, 29 output tokens, 339 total tokens
 ### 11: LLM ended. Usage: 3 requests, 472 input tokens, 45 output tokens, 517 total tokens
-### 12: Tool multiply_by_two started. Usage: 3 requests, 472 input tokens, 45 output tokens, 517 total tokens
-### 13: Tool multiply_by_two ended with result 138. Usage: 3 requests, 472 input tokens, 45 output tokens, 517 total tokens
+### 12: Tool multiply_by_two started. name=multiply_by_two, call_id=call_KhHvTfsgaosZsfi741QvzgYw, args={"x":107}. Usage: 3 requests, 472 input tokens, 45 output tokens, 517 total tokens
+### 13: Tool multiply_by_two finished. result=214, name=multiply_by_two, call_id=call_KhHvTfsgaosZsfi741QvzgYw, args={"x":107}. Usage: 3 requests, 472 input tokens, 45 output tokens, 517 total tokens
 ### 14: LLM started. Usage: 3 requests, 472 input tokens, 45 output tokens, 517 total tokens
 ### 15: LLM ended. Usage: 4 requests, 660 input tokens, 56 output tokens, 716 total tokens
-### 16: Agent Multiply Agent ended with output number=138. Usage: 4 requests, 660 input tokens, 56 output tokens, 716 total tokens
+### 16: Agent Multiply Agent ended with output number=214. Usage: 4 requests, 660 input tokens, 56 output tokens, 716 total tokens
 Done!
 
 """

{openai_agents-0.3.1 → openai_agents-0.3.2}/examples/basic/stream_function_call_args.py

@@ -1,5 +1,5 @@
 import asyncio
-from typing import Any
+from typing import Annotated, Any, Optional
 
 from openai.types.responses import ResponseFunctionCallArgumentsDeltaEvent
 
@@ -7,14 +7,18 @@ from agents import Agent, Runner, function_tool
 
 
 @function_tool
-def write_file(filename: str, content: str) -> str:
+def write_file(filename: Annotated[str, "Name of the file"], content: str) -> str:
     """Write content to a file."""
     return f"File {filename} written successfully"
 
 
 @function_tool
-def create_config(project_name: str, version: str, dependencies: list[str]) -> str:
-    """Create a configuration file for a project."""
+def create_config(
+    project_name: Annotated[str, "Project name"],
+    version: Annotated[str, "Project version"],
+    dependencies: Annotated[Optional[list[str]], "Dependencies (list of packages)"],
+) -> str:
+    """Generate a project configuration file."""
     return f"Config for {project_name} v{version} created"
 
 

{openai_agents-0.3.1 → openai_agents-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-agents"
-version = "0.3.1"
+version = "0.3.2"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/extensions/models/litellm_model.py

@@ -39,7 +39,7 @@ from ...items import ModelResponse, TResponseInputItem, TResponseStreamEvent
 from ...logger import logger
 from ...model_settings import ModelSettings
 from ...models.chatcmpl_converter import Converter
-from ...models.chatcmpl_helpers import HEADERS, USER_AGENT_OVERRIDE
+from ...models.chatcmpl_helpers import HEADERS, HEADERS_OVERRIDE
 from ...models.chatcmpl_stream_handler import ChatCmplStreamHandler
 from ...models.fake_id import FAKE_RESPONSES_ID
 from ...models.interface import Model, ModelTracing
@@ -385,11 +385,7 @@ class LitellmModel(Model):
         return value
 
     def _merge_headers(self, model_settings: ModelSettings):
-        merged = {**HEADERS, **(model_settings.extra_headers or {})}
-        ua_ctx = USER_AGENT_OVERRIDE.get()
-        if ua_ctx is not None:
-            merged["User-Agent"] = ua_ctx
-        return merged
+        return {**HEADERS, **(model_settings.extra_headers or {}), **(HEADERS_OVERRIDE.get() or {})}
 
 
 class LitellmConverter:

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/models/chatcmpl_converter.py

@@ -107,7 +107,7 @@ class Converter:
             if hasattr(message, "thinking_blocks") and message.thinking_blocks:
                 # Store thinking text in content and signature in encrypted_content
                 reasoning_item.content = []
-                signature = None
+                signatures: list[str] = []
                 for block in message.thinking_blocks:
                     if isinstance(block, dict):
                         thinking_text = block.get("thinking", "")
@@ -116,15 +116,12 @@ class Converter:
                                 Content(text=thinking_text, type="reasoning_text")
                             )
                         # Store the signature if present
-                        if block.get("signature"):
-                            signature = block.get("signature")
+                        if signature := block.get("signature"):
+                            signatures.append(signature)
 
-                # Store only the last signature in encrypted_content
-                # If there are multiple thinking blocks, this should be a problem.
-                # In practice, there should only be one signature for the entire reasoning step.
-                # Tested with: claude-sonnet-4-20250514
-                if signature:
-                    reasoning_item.encrypted_content = signature
+                # Store the signatures in encrypted_content with newline delimiter
+                if signatures:
+                    reasoning_item.encrypted_content = "\n".join(signatures)
 
             items.append(reasoning_item)
 
@@ -483,7 +480,20 @@ class Converter:
                 # If we have pending thinking blocks, use them as the content
                 # This is required for Anthropic API tool calls with interleaved thinking
                 if pending_thinking_blocks:
-                    asst["content"] = pending_thinking_blocks  # type: ignore
+                    # If there is a text content, save it to append after thinking blocks
+                    # content type is Union[str, Iterable[ContentArrayOfContentPart], None]
+                    if "content" in asst and isinstance(asst["content"], str):
+                        text_content = ChatCompletionContentPartTextParam(
+                            text=asst["content"], type="text"
+                        )
+                        asst["content"] = [text_content]
+
+                    if "content" not in asst or asst["content"] is None:
+                        asst["content"] = []
+
+                    # Thinking blocks MUST come before any other content
+                    # We ignore type errors because pending_thinking_blocks is not openai standard
+                    asst["content"] = pending_thinking_blocks + asst["content"]  # type: ignore
                     pending_thinking_blocks = None  # Clear after using
 
                 tool_calls = list(asst.get("tool_calls", []))
@@ -518,7 +528,8 @@ class Converter:
             elif reasoning_item := cls.maybe_reasoning_message(item):
                 # Reconstruct thinking blocks from content (text) and encrypted_content (signature)
                 content_items = reasoning_item.get("content", [])
-                signature = reasoning_item.get("encrypted_content")
+                encrypted_content = reasoning_item.get("encrypted_content")
+                signatures = encrypted_content.split("\n") if encrypted_content else []
 
                 if content_items and preserve_thinking_blocks:
                     # Reconstruct thinking blocks from content and signature
@@ -532,9 +543,9 @@ class Converter:
                                 "type": "thinking",
                                 "thinking": content_item.get("text", ""),
                             }
-                            # Add signature if available
-                            if signature:
-                                thinking_block["signature"] = signature
+                            # Add signatures if available
+                            if signatures:
+                                thinking_block["signature"] = signatures.pop(0)
                             pending_thinking_blocks.append(thinking_block)
 
             # 8) If we haven't recognized it => fail or ignore

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/models/chatcmpl_helpers.py

@@ -10,8 +10,8 @@ from ..version import __version__
 _USER_AGENT = f"Agents/Python {__version__}"
 HEADERS = {"User-Agent": _USER_AGENT}
 
-USER_AGENT_OVERRIDE: ContextVar[str | None] = ContextVar(
-    "openai_chatcompletions_user_agent_override", default=None
+HEADERS_OVERRIDE: ContextVar[dict[str, str] | None] = ContextVar(
+    "openai_chatcompletions_headers_override", default=None
 )
 
 

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/models/openai_chatcompletions.py

@@ -25,7 +25,7 @@ from ..tracing.spans import Span
 from ..usage import Usage
 from ..util._json import _to_dump_compatible
 from .chatcmpl_converter import Converter
-from .chatcmpl_helpers import HEADERS, USER_AGENT_OVERRIDE, ChatCmplHelpers
+from .chatcmpl_helpers import HEADERS, HEADERS_OVERRIDE, ChatCmplHelpers
 from .chatcmpl_stream_handler import ChatCmplStreamHandler
 from .fake_id import FAKE_RESPONSES_ID
 from .interface import Model, ModelTracing
@@ -351,8 +351,8 @@ class OpenAIChatCompletionsModel(Model):
         return self._client
 
     def _merge_headers(self, model_settings: ModelSettings):
-        merged = {**HEADERS, **(model_settings.extra_headers or {})}
-        ua_ctx = USER_AGENT_OVERRIDE.get()
-        if ua_ctx is not None:
-            merged["User-Agent"] = ua_ctx
-        return merged
+        return {
+            **HEADERS,
+            **(model_settings.extra_headers or {}),
+            **(HEADERS_OVERRIDE.get() or {}),
+        }

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/models/openai_responses.py

@@ -50,9 +50,9 @@ if TYPE_CHECKING:
 _USER_AGENT = f"Agents/Python {__version__}"
 _HEADERS = {"User-Agent": _USER_AGENT}
 
-# Override for the User-Agent header used by the Responses API.
-_USER_AGENT_OVERRIDE: ContextVar[str | None] = ContextVar(
-    "openai_responses_user_agent_override", default=None
+# Override headers used by the Responses API.
+_HEADERS_OVERRIDE: ContextVar[dict[str, str] | None] = ContextVar(
+    "openai_responses_headers_override", default=None
 )
 
 
@@ -334,11 +334,11 @@ class OpenAIResponsesModel(Model):
         return self._client
 
     def _merge_headers(self, model_settings: ModelSettings):
-        merged = {**_HEADERS, **(model_settings.extra_headers or {})}
-        ua_ctx = _USER_AGENT_OVERRIDE.get()
-        if ua_ctx is not None:
-            merged["User-Agent"] = ua_ctx
-        return merged
+        return {
+            **_HEADERS,
+            **(model_settings.extra_headers or {}),
+            **(_HEADERS_OVERRIDE.get() or {}),
+        }
 
 
 @dataclass

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/realtime/session.py

@@ -408,6 +408,7 @@ class RealtimeSession(RealtimeModelListener):
                 usage=self._context_wrapper.usage,
                 tool_name=event.name,
                 tool_call_id=event.call_id,
+                tool_arguments=event.arguments,
             )
             result = await func_tool.on_invoke_tool(tool_context, event.arguments)
 
@@ -432,6 +433,7 @@ class RealtimeSession(RealtimeModelListener):
                 usage=self._context_wrapper.usage,
                 tool_name=event.name,
                 tool_call_id=event.call_id,
+                tool_arguments=event.arguments,
             )
 
             # Execute the handoff to get the new agent

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/run.py

@@ -53,7 +53,7 @@ from .items import (
     ToolCallItemTypes,
     TResponseInputItem,
 )
-from .lifecycle import RunHooks
+from .lifecycle import AgentHooksBase, RunHooks, RunHooksBase
 from .logger import logger
 from .memory import Session, SessionInputCallback
 from .model_settings import ModelSettings
@@ -461,13 +461,11 @@ class AgentRunner:
     ) -> RunResult:
         context = kwargs.get("context")
         max_turns = kwargs.get("max_turns", DEFAULT_MAX_TURNS)
-        hooks = kwargs.get("hooks")
+        hooks = cast(RunHooks[TContext], self._validate_run_hooks(kwargs.get("hooks")))
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
         conversation_id = kwargs.get("conversation_id")
         session = kwargs.get("session")
-        if hooks is None:
-            hooks = RunHooks[Any]()
         if run_config is None:
             run_config = RunConfig()
 
@@ -668,14 +666,12 @@ class AgentRunner:
     ) -> RunResultStreaming:
         context = kwargs.get("context")
         max_turns = kwargs.get("max_turns", DEFAULT_MAX_TURNS)
-        hooks = kwargs.get("hooks")
+        hooks = cast(RunHooks[TContext], self._validate_run_hooks(kwargs.get("hooks")))
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
         conversation_id = kwargs.get("conversation_id")
         session = kwargs.get("session")
 
-        if hooks is None:
-            hooks = RunHooks[Any]()
         if run_config is None:
             run_config = RunConfig()
 
@@ -732,6 +728,23 @@ class AgentRunner:
         )
         return streamed_result
 
+    @staticmethod
+    def _validate_run_hooks(
+        hooks: RunHooksBase[Any, Agent[Any]] | AgentHooksBase[Any, Agent[Any]] | Any | None,
+    ) -> RunHooks[Any]:
+        if hooks is None:
+            return RunHooks[Any]()
+        input_hook_type = type(hooks).__name__
+        if isinstance(hooks, AgentHooksBase):
+            raise TypeError(
+                "Run hooks must be instances of RunHooks. "
+                f"Received agent-scoped hooks ({input_hook_type}). "
+                "Attach AgentHooks to an Agent via Agent(..., hooks=...)."
+            )
+        if not isinstance(hooks, RunHooksBase):
+            raise TypeError(f"Run hooks must be instances of RunHooks. Received {input_hook_type}.")
+        return hooks
+
     @classmethod
     async def _maybe_filter_model_input(
         cls,

{openai_agents-0.3.1 → openai_agents-0.3.2}/src/agents/tool_context.py

@@ -14,6 +14,10 @@ def _assert_must_pass_tool_name() -> str:
     raise ValueError("tool_name must be passed to ToolContext")
 
 
+def _assert_must_pass_tool_arguments() -> str:
+    raise ValueError("tool_arguments must be passed to ToolContext")
+
+
 @dataclass
 class ToolContext(RunContextWrapper[TContext]):
     """The context of a tool call."""
@@ -24,6 +28,9 @@ class ToolContext(RunContextWrapper[TContext]):
     tool_call_id: str = field(default_factory=_assert_must_pass_tool_call_id)
     """The ID of the tool call."""
 
+    tool_arguments: str = field(default_factory=_assert_must_pass_tool_arguments)
+    """The raw arguments string of the tool call."""
+
     @classmethod
     def from_agent_context(
         cls,
@@ -39,4 +46,10 @@ class ToolContext(RunContextWrapper[TContext]):
             f.name: getattr(context, f.name) for f in fields(RunContextWrapper) if f.init
         }
         tool_name = tool_call.name if tool_call is not None else _assert_must_pass_tool_name()
-        return cls(tool_name=tool_name, tool_call_id=tool_call_id, **base_values)
+        tool_args = (
+            tool_call.arguments if tool_call is not None else _assert_must_pass_tool_arguments()
+        )
+
+        return cls(
+            tool_name=tool_name, tool_call_id=tool_call_id, tool_arguments=tool_args, **base_values
+        )

{openai_agents-0.3.1 → openai_agents-0.3.2}/tests/models/test_litellm_user_agent.py

@@ -5,7 +5,7 @@ from typing import Any
 import pytest
 
 from agents import ModelSettings, ModelTracing, __version__
-from agents.models.chatcmpl_helpers import USER_AGENT_OVERRIDE
+from agents.models.chatcmpl_helpers import HEADERS_OVERRIDE
 
 
 @pytest.mark.allow_call_model_methods
@@ -65,7 +65,7 @@ async def test_user_agent_header_litellm(override_ua: str | None, monkeypatch):
     model = LitellmModel(model="gpt-4")
 
     if override_ua is not None:
-        token = USER_AGENT_OVERRIDE.set(override_ua)
+        token = HEADERS_OVERRIDE.set({"User-Agent": override_ua})
     else:
         token = None
     try:
@@ -83,7 +83,7 @@ async def test_user_agent_header_litellm(override_ua: str | None, monkeypatch):
         )
     finally:
         if token is not None:
-            USER_AGENT_OVERRIDE.reset(token)
+            HEADERS_OVERRIDE.reset(token)
 
     assert "extra_headers" in called_kwargs
     assert called_kwargs["extra_headers"]["User-Agent"] == expected_ua