Merge branch 'main' into patch-1

Author: vincentkoc

.github/ISSUE_TEMPLATE/model_provider.md

@@ -0,0 +1,26 @@
+---
+name: Custom model providers
+about: Questions or bugs about using non-OpenAI models
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+### Please read this first
+
+- **Have you read the custom model provider docs, including the 'Common issues' section?** [Model provider docs](https://openai.github.io/openai-agents-python/models/#using-other-llm-providers)
+- **Have you searched for related issues?** Others may have faced similar issues.
+
+### Describe the question
+A clear and concise description of what the question or bug is.
+
+### Debug information
+- Agents SDK version: (e.g. `v0.0.3`)
+- Python version (e.g. Python 3.10)
+
+### Repro steps
+Ideally provide a minimal python script that can be run to reproduce the issue.
+
+### Expected behavior
+A clear and concise description of what you expected to happen.

.github/workflows/tests.yml

@@ -50,8 +50,8 @@ jobs:
           enable-cache: true
       - name: Install dependencies
         run: make sync
-      - name: Run tests
-        run: make tests
+      - name: Run tests with coverage
+        run: make coverage
 
   build-docs:
     runs-on: ubuntu-latest

Makefile

@@ -18,6 +18,21 @@ mypy:
 tests: 
 	uv run pytest 
 
+.PHONY: coverage
+coverage:
+	
+	uv run coverage run -m pytest
+	uv run coverage xml -o coverage.xml
+	uv run coverage report -m --fail-under=95
+
+.PHONY: snapshots-fix
+snapshots-fix: 
+	uv run pytest --inline-snapshot=fix 
+
+.PHONY: snapshots-create 
+snapshots-create: 
+	uv run pytest --inline-snapshot=create 
+
 .PHONY: old_version_tests
 old_version_tests: 
 	UV_PROJECT_ENVIRONMENT=.venv_39 uv run --python 3.9 -m pytest
@@ -34,4 +49,6 @@ serve-docs:
 .PHONY: deploy-docs
 deploy-docs:
 	uv run mkdocs gh-deploy --force --verbose
+
+	
 

README.md

@@ -7,7 +7,7 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 ### Core concepts:
 
 1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs
-2. [**Handoffs**](https://openai.github.io/openai-agents-python/handoffs/): Allow agents to transfer control to other agents for specific tasks
+2. [**Handoffs**](https://openai.github.io/openai-agents-python/handoffs/): A specialized tool call used by the Agents SDK for transferring control between agents
 3. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): Configurable safety checks for input and output validation
 4. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
 
@@ -142,15 +142,7 @@ The Agents SDK is designed to be highly flexible, allowing you to model a wide r
 
 ## Tracing
 
-The Agents SDK automatically traces your agent runs, making it easy to track and debug the behavior of your agents. Tracing is extensible by design, supporting custom spans and a wide variety of external destinations, including:
-- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)
-- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)
-- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
-- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent)
-- [Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents)
-- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration)
-
-For more details about how to customize or disable tracing, see [Tracing](http://openai.github.io/openai-agents-python/tracing).
+The Agents SDK automatically traces your agent runs, making it easy to track and debug the behavior of your agents. Tracing is extensible by design, supporting custom spans and a wide variety of external destinations, including [Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents), [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk), [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk), [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration), and [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent). For more details about how to customize or disable tracing, see [Tracing](http://openai.github.io/openai-agents-python/tracing), which also includes a larger list of [external tracing processors](http://openai.github.io/openai-agents-python/tracing/#external-tracing-processors-list).
 
 ## Development (only needed if you need to edit the SDK/examples)
 

docs/guardrails.md

@@ -111,8 +111,8 @@ class MessageOutput(BaseModel): # (1)!
     response: str
 
 class MathOutput(BaseModel): # (2)!
-    is_math: bool
     reasoning: str
+    is_math: bool
 
 guardrail_agent = Agent(
     name="Guardrail check",

docs/tracing.md

@@ -9,6 +9,8 @@ The Agents SDK includes built-in tracing, collecting a comprehensive record of e
     1. You can globally disable tracing by setting the env var `OPENAI_AGENTS_DISABLE_TRACING=1`
     2. You can disable tracing for a single run by setting [`agents.run.RunConfig.tracing_disabled`][] to `True`
 
+***For organizations operating under a Zero Data Retention (ZDR) policy using OpenAI's APIs, tracing is unavailable.***
+
 ## Traces and spans
 
 -   **Traces** represent a single end-to-end operation of a "workflow". They're composed of Spans. Traces have the following properties:
@@ -88,11 +90,15 @@ To customize this default setup, to send traces to alternative or additional bac
 1. [`add_trace_processor()`][agents.tracing.add_trace_processor] lets you add an **additional** trace processor that will receive traces and spans as they are ready. This lets you do your own processing in addition to sending traces to OpenAI's backend.
 2. [`set_trace_processors()`][agents.tracing.set_trace_processors] lets you **replace** the default processors with your own trace processors. This means traces will not be sent to the OpenAI backend unless you include a `TracingProcessor` that does so.
 
-External trace processors include:
+## External tracing processors list
 
--   [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)
+-   [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)
--   [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
--   [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration))
--   [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent)
 -   [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents)
+-   [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)
+-   [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration)
+-   [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent)
+-   [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)

examples/agent_patterns/input_guardrails.py

@@ -30,8 +30,8 @@
 
 ### 1. An agent-based guardrail that is triggered if the user is asking to do math homework
 class MathHomeworkOutput(BaseModel):
-    is_math_homework: bool
     reasoning: str
+    is_math_homework: bool
 
 
 guardrail_agent = Agent(

examples/agent_patterns/llm_as_a_judge.py

@@ -23,8 +23,8 @@
 
 @dataclass
 class EvaluationFeedback:
-    score: Literal["pass", "needs_improvement", "fail"]
     feedback: str
+    score: Literal["pass", "needs_improvement", "fail"]
 
 
 evaluator = Agent[None](

examples/basic/agent_lifecycle_example.py

@@ -74,7 +74,7 @@ class FinalResult(BaseModel):
 
 start_agent = Agent(
     name="Start Agent",
-    instructions="Generate a random number. If it's even, stop. If it's odd, hand off to the multipler agent.",
+    instructions="Generate a random number. If it's even, stop. If it's odd, hand off to the multiply agent.",
     tools=[random_number],
     output_type=FinalResult,
     handoffs=[multiply_agent],

examples/basic/hello_world_jupyter.py

@@ -3,7 +3,7 @@
 agent = Agent(name="Assistant", instructions="You are a helpful assistant")
 
 # Intended for Jupyter notebooks where there's an existing event loop
-result = await Runner.run(agent, "Write a haiku about recursion in programming.") # type: ignore[top-level-await]  # noqa: F704
+result = await Runner.run(agent, "Write a haiku about recursion in programming.")  # type: ignore[top-level-await]  # noqa: F704
 print(result.final_output)
 
 # Code within code loops,

examples/handoffs/message_filter.py

@@ -60,9 +60,9 @@ async def main():
 
         print("Step 1 done")
 
-        # 2. Ask it to square a number
+        # 2. Ask it to generate a number
         result = await Runner.run(
-            second_agent,
+            first_agent,
             input=result.to_input_list()
             + [{"content": "Can you generate a random number between 0 and 100?", "role": "user"}],
         )

examples/handoffs/message_filter_streaming.py

@@ -60,9 +60,9 @@ async def main():
 
         print("Step 1 done")
 
-        # 2. Ask it to square a number
+        # 2. Ask it to generate a number
         result = await Runner.run(
-            second_agent,
+            first_agent,
             input=result.to_input_list()
             + [{"content": "Can you generate a random number between 0 and 100?", "role": "user"}],
         )

pyproject.toml

@@ -47,6 +47,7 @@ dev = [
     "mkdocstrings[python]>=0.28.0",
     "coverage>=7.6.12",
     "playwright==1.50.0",
+    "inline-snapshot>=0.20.7",
 ]
 [tool.uv.workspace]
 members = ["agents"]
@@ -116,4 +117,7 @@ filterwarnings = [
 ]
 markers = [
     "allow_call_model_methods: mark test as allowing calls to real model implementations",
-]
+]
+
+[tool.inline-snapshot]
+format-command="ruff format --stdin-filename {filename}"

src/agents/__init__.py

@@ -73,6 +73,7 @@
     SpanData,
     SpanError,
     Trace,
+    TracingProcessor,
     add_trace_processor,
     agent_span,
     custom_span,
@@ -129,10 +130,9 @@ def set_default_openai_api(api: Literal["chat_completions", "responses"]) -> Non
 
 def enable_verbose_stdout_logging():
     """Enables verbose logging to stdout. This is useful for debugging."""
-    for name in ["openai.agents", "openai.agents.tracing"]:
-        logger = logging.getLogger(name)
-        logger.setLevel(logging.DEBUG)
-        logger.addHandler(logging.StreamHandler(sys.stdout))
+    logger = logging.getLogger("openai.agents")
+    logger.setLevel(logging.DEBUG)
+    logger.addHandler(logging.StreamHandler(sys.stdout))
 
 
 __all__ = [
@@ -209,6 +209,7 @@ def enable_verbose_stdout_logging():
     "set_tracing_disabled",
     "trace",
     "Trace",
+    "TracingProcessor",
     "SpanError",
     "Span",
     "SpanData",

src/agents/_run_impl.py

@@ -25,7 +25,6 @@
 from openai.types.responses.response_input_param import ComputerCallOutput
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
 
-from . import _utils
 from .agent import Agent
 from .agent_output import AgentOutputSchema
 from .computer import AsyncComputer, Computer
@@ -59,6 +58,7 @@
     handoff_span,
     trace,
 )
+from .util import _coro, _error_tracing
 
 if TYPE_CHECKING:
     from .run import RunConfig
@@ -293,7 +293,7 @@ def process_model_response(
             elif isinstance(output, ResponseComputerToolCall):
                 items.append(ToolCallItem(raw_item=output, agent=agent))
                 if not computer_tool:
-                    _utils.attach_error_to_current_span(
+                    _error_tracing.attach_error_to_current_span(
                         SpanError(
                             message="Computer tool not found",
                             data={},
@@ -324,7 +324,7 @@ def process_model_response(
             # Regular function tool call
             else:
                 if output.name not in function_map:
-                    _utils.attach_error_to_current_span(
+                    _error_tracing.attach_error_to_current_span(
                         SpanError(
                             message="Tool not found",
                             data={"tool_name": output.name},
@@ -368,7 +368,7 @@ async def run_single_tool(
                         (
                             agent.hooks.on_tool_start(context_wrapper, agent, func_tool)
                             if agent.hooks
-                            else _utils.noop_coroutine()
+                            else _coro.noop_coroutine()
                         ),
                         func_tool.on_invoke_tool(context_wrapper, tool_call.arguments),
                     )
@@ -378,11 +378,11 @@ async def run_single_tool(
                         (
                             agent.hooks.on_tool_end(context_wrapper, agent, func_tool, result)
                             if agent.hooks
-                            else _utils.noop_coroutine()
+                            else _coro.noop_coroutine()
                         ),
                     )
                 except Exception as e:
-                    _utils.attach_error_to_current_span(
+                    _error_tracing.attach_error_to_current_span(
                         SpanError(
                             message="Error running tool",
                             data={"tool_name": func_tool.name, "error": str(e)},
@@ -502,7 +502,7 @@ async def execute_handoffs(
                         source=agent,
                     )
                     if agent.hooks
-                    else _utils.noop_coroutine()
+                    else _coro.noop_coroutine()
                 ),
             )
 
@@ -520,7 +520,7 @@ async def execute_handoffs(
                     new_items=tuple(new_step_items),
                 )
                 if not callable(input_filter):
-                    _utils.attach_error_to_span(
+                    _error_tracing.attach_error_to_span(
                         span_handoff,
                         SpanError(
                             message="Invalid input filter",
@@ -530,7 +530,7 @@ async def execute_handoffs(
                     raise UserError(f"Invalid input filter: {input_filter}")
                 filtered = input_filter(handoff_input_data)
                 if not isinstance(filtered, HandoffInputData):
-                    _utils.attach_error_to_span(
+                    _error_tracing.attach_error_to_span(
                         span_handoff,
                         SpanError(
                             message="Invalid input filter result",
@@ -591,7 +591,7 @@ async def run_final_output_hooks(
             hooks.on_agent_end(context_wrapper, agent, final_output),
             agent.hooks.on_end(context_wrapper, agent, final_output)
             if agent.hooks
-            else _utils.noop_coroutine(),
+            else _coro.noop_coroutine(),
         )
 
     @classmethod
@@ -706,7 +706,7 @@ async def execute(
             (
                 agent.hooks.on_tool_start(context_wrapper, agent, action.computer_tool)
                 if agent.hooks
-                else _utils.noop_coroutine()
+                else _coro.noop_coroutine()
             ),
             output_func,
         )
@@ -716,7 +716,7 @@ async def execute(
             (
                 agent.hooks.on_tool_end(context_wrapper, agent, action.computer_tool, output)
                 if agent.hooks
-                else _utils.noop_coroutine()
+                else _coro.noop_coroutine()
             ),
         )