From 88ee0a87ff1ee7851158ccb2c3336f3d709e73b1 Mon Sep 17 00:00:00 2001 From: Rohan Mehta Date: Tue, 11 Mar 2025 13:12:32 -0700 Subject: [PATCH 1/3] Remove duplicated files in tests --- tests/LICENSE | 21 - tests/Makefile | 37 - tests/README.md | 174 ---- tests/docs/agents.md | 131 --- tests/docs/assets/images/favicon-platform.svg | 16 - tests/docs/assets/images/orchestration.png | Bin 432783 -> 0 bytes tests/docs/assets/logo.svg | 15 - tests/docs/config.md | 94 -- tests/docs/context.md | 76 -- tests/docs/guardrails.md | 154 --- tests/docs/handoffs.md | 113 --- tests/docs/index.md | 52 - tests/docs/models.md | 73 -- tests/docs/multi_agent.md | 37 - tests/docs/quickstart.md | 186 ---- tests/docs/ref/agent.md | 3 - tests/docs/ref/agent_output.md | 3 - tests/docs/ref/exceptions.md | 3 - tests/docs/ref/extensions/handoff_filters.md | 3 - tests/docs/ref/extensions/handoff_prompt.md | 8 - tests/docs/ref/function_schema.md | 3 - tests/docs/ref/guardrail.md | 3 - tests/docs/ref/handoffs.md | 3 - tests/docs/ref/index.md | 13 - tests/docs/ref/items.md | 3 - tests/docs/ref/lifecycle.md | 6 - tests/docs/ref/model_settings.md | 3 - tests/docs/ref/models/interface.md | 3 - .../docs/ref/models/openai_chatcompletions.md | 3 - tests/docs/ref/models/openai_responses.md | 3 - tests/docs/ref/result.md | 3 - tests/docs/ref/run.md | 8 - tests/docs/ref/run_context.md | 3 - tests/docs/ref/stream_events.md | 3 - tests/docs/ref/tool.md | 3 - tests/docs/ref/tracing/create.md | 3 - tests/docs/ref/tracing/index.md | 3 - tests/docs/ref/tracing/processor_interface.md | 3 - tests/docs/ref/tracing/processors.md | 3 - tests/docs/ref/tracing/scope.md | 3 - tests/docs/ref/tracing/setup.md | 3 - tests/docs/ref/tracing/span_data.md | 3 - tests/docs/ref/tracing/spans.md | 9 - tests/docs/ref/tracing/traces.md | 3 - tests/docs/ref/tracing/util.md | 3 - tests/docs/ref/usage.md | 3 - tests/docs/results.md | 52 - tests/docs/running_agents.md | 95 -- tests/docs/streaming.md | 87 -- tests/docs/stylesheets/extra.css | 194 ---- tests/docs/tools.md | 270 ----- tests/docs/tracing.md | 95 -- tests/examples/__init__.py | 3 - tests/examples/agent_patterns/README.md | 54 - .../agent_patterns/agents_as_tools.py | 79 -- .../examples/agent_patterns/deterministic.py | 80 -- .../agent_patterns/input_guardrails.py | 105 -- .../examples/agent_patterns/llm_as_a_judge.py | 76 -- .../agent_patterns/output_guardrails.py | 80 -- .../agent_patterns/parallelization.py | 61 -- tests/examples/agent_patterns/routing.py | 70 -- .../examples/basic/agent_lifecycle_example.py | 112 --- tests/examples/basic/dynamic_system_prompt.py | 69 -- tests/examples/basic/hello_world.py | 20 - tests/examples/basic/lifecycle_example.py | 118 --- tests/examples/basic/stream_items.py | 65 -- tests/examples/basic/stream_text.py | 21 - tests/examples/customer_service/main.py | 169 ---- tests/examples/handoffs/message_filter.py | 176 ---- .../handoffs/message_filter_streaming.py | 176 ---- tests/examples/research_bot/README.md | 25 - tests/examples/research_bot/__init__.py | 1 - .../examples/research_bot/agents/__init__.py | 0 .../research_bot/agents/planner_agent.py | 29 - .../research_bot/agents/search_agent.py | 18 - .../research_bot/agents/writer_agent.py | 33 - tests/examples/research_bot/main.py | 12 - tests/examples/research_bot/manager.py | 119 --- tests/examples/research_bot/printer.py | 41 - .../sample_outputs/product_recs.md | 180 ---- .../sample_outputs/product_recs.txt | 212 ---- .../research_bot/sample_outputs/vacation.md | 177 ---- .../research_bot/sample_outputs/vacation.txt | 206 ---- tests/examples/tools/computer_use.py | 165 --- tests/examples/tools/file_search.py | 36 - tests/examples/tools/web_search.py | 23 - tests/mkdocs.yml | 121 --- tests/pyproject.toml | 119 --- tests/src/agents/__init__.py | 223 ---- tests/src/agents/_config.py | 23 - tests/src/agents/_debug.py | 17 - tests/src/agents/_run_impl.py | 792 --------------- tests/src/agents/_utils.py | 61 -- tests/src/agents/agent.py | 159 --- tests/src/agents/agent_output.py | 144 --- tests/src/agents/computer.py | 107 -- tests/src/agents/exceptions.py | 63 -- tests/src/agents/extensions/__init__.py | 0 .../src/agents/extensions/handoff_filters.py | 67 -- tests/src/agents/extensions/handoff_prompt.py | 19 - tests/src/agents/function_schema.py | 340 ------- tests/src/agents/guardrail.py | 320 ------ tests/src/agents/handoffs.py | 236 ----- tests/src/agents/items.py | 246 ----- tests/src/agents/lifecycle.py | 105 -- tests/src/agents/logger.py | 3 - tests/src/agents/model_settings.py | 35 - tests/src/agents/models/__init__.py | 0 tests/src/agents/models/_openai_shared.py | 34 - tests/src/agents/models/fake_id.py | 5 - tests/src/agents/models/interface.py | 107 -- .../agents/models/openai_chatcompletions.py | 952 ------------------ tests/src/agents/models/openai_provider.py | 65 -- tests/src/agents/models/openai_responses.py | 384 ------- tests/src/agents/result.py | 220 ---- tests/src/agents/run.py | 904 ----------------- tests/src/agents/run_context.py | 26 - tests/src/agents/stream_events.py | 58 -- tests/src/agents/strict_schema.py | 167 --- tests/src/agents/tool.py | 286 ------ tests/src/agents/tracing/__init__.py | 97 -- tests/src/agents/tracing/create.py | 306 ------ tests/src/agents/tracing/logger.py | 3 - .../src/agents/tracing/processor_interface.py | 69 -- tests/src/agents/tracing/processors.py | 261 ----- tests/src/agents/tracing/scope.py | 45 - tests/src/agents/tracing/setup.py | 211 ---- tests/src/agents/tracing/span_data.py | 188 ---- tests/src/agents/tracing/spans.py | 264 ----- tests/src/agents/tracing/traces.py | 195 ---- tests/src/agents/tracing/util.py | 17 - tests/src/agents/usage.py | 22 - tests/src/agents/version.py | 7 - tests/src/openai_agents.egg-info/PKG-INFO | 217 ---- tests/src/openai_agents.egg-info/SOURCES.txt | 81 -- .../dependency_links.txt | 1 - tests/src/openai_agents.egg-info/requires.txt | 6 - .../src/openai_agents.egg-info/top_level.txt | 1 - 138 files changed, 13304 deletions(-) delete mode 100644 tests/LICENSE delete mode 100644 tests/Makefile delete mode 100644 tests/README.md delete mode 100644 tests/docs/agents.md delete mode 100644 tests/docs/assets/images/favicon-platform.svg delete mode 100644 tests/docs/assets/images/orchestration.png delete mode 100644 tests/docs/assets/logo.svg delete mode 100644 tests/docs/config.md delete mode 100644 tests/docs/context.md delete mode 100644 tests/docs/guardrails.md delete mode 100644 tests/docs/handoffs.md delete mode 100644 tests/docs/index.md delete mode 100644 tests/docs/models.md delete mode 100644 tests/docs/multi_agent.md delete mode 100644 tests/docs/quickstart.md delete mode 100644 tests/docs/ref/agent.md delete mode 100644 tests/docs/ref/agent_output.md delete mode 100644 tests/docs/ref/exceptions.md delete mode 100644 tests/docs/ref/extensions/handoff_filters.md delete mode 100644 tests/docs/ref/extensions/handoff_prompt.md delete mode 100644 tests/docs/ref/function_schema.md delete mode 100644 tests/docs/ref/guardrail.md delete mode 100644 tests/docs/ref/handoffs.md delete mode 100644 tests/docs/ref/index.md delete mode 100644 tests/docs/ref/items.md delete mode 100644 tests/docs/ref/lifecycle.md delete mode 100644 tests/docs/ref/model_settings.md delete mode 100644 tests/docs/ref/models/interface.md delete mode 100644 tests/docs/ref/models/openai_chatcompletions.md delete mode 100644 tests/docs/ref/models/openai_responses.md delete mode 100644 tests/docs/ref/result.md delete mode 100644 tests/docs/ref/run.md delete mode 100644 tests/docs/ref/run_context.md delete mode 100644 tests/docs/ref/stream_events.md delete mode 100644 tests/docs/ref/tool.md delete mode 100644 tests/docs/ref/tracing/create.md delete mode 100644 tests/docs/ref/tracing/index.md delete mode 100644 tests/docs/ref/tracing/processor_interface.md delete mode 100644 tests/docs/ref/tracing/processors.md delete mode 100644 tests/docs/ref/tracing/scope.md delete mode 100644 tests/docs/ref/tracing/setup.md delete mode 100644 tests/docs/ref/tracing/span_data.md delete mode 100644 tests/docs/ref/tracing/spans.md delete mode 100644 tests/docs/ref/tracing/traces.md delete mode 100644 tests/docs/ref/tracing/util.md delete mode 100644 tests/docs/ref/usage.md delete mode 100644 tests/docs/results.md delete mode 100644 tests/docs/running_agents.md delete mode 100644 tests/docs/streaming.md delete mode 100644 tests/docs/stylesheets/extra.css delete mode 100644 tests/docs/tools.md delete mode 100644 tests/docs/tracing.md delete mode 100644 tests/examples/__init__.py delete mode 100644 tests/examples/agent_patterns/README.md delete mode 100644 tests/examples/agent_patterns/agents_as_tools.py delete mode 100644 tests/examples/agent_patterns/deterministic.py delete mode 100644 tests/examples/agent_patterns/input_guardrails.py delete mode 100644 tests/examples/agent_patterns/llm_as_a_judge.py delete mode 100644 tests/examples/agent_patterns/output_guardrails.py delete mode 100644 tests/examples/agent_patterns/parallelization.py delete mode 100644 tests/examples/agent_patterns/routing.py delete mode 100644 tests/examples/basic/agent_lifecycle_example.py delete mode 100644 tests/examples/basic/dynamic_system_prompt.py delete mode 100644 tests/examples/basic/hello_world.py delete mode 100644 tests/examples/basic/lifecycle_example.py delete mode 100644 tests/examples/basic/stream_items.py delete mode 100644 tests/examples/basic/stream_text.py delete mode 100644 tests/examples/customer_service/main.py delete mode 100644 tests/examples/handoffs/message_filter.py delete mode 100644 tests/examples/handoffs/message_filter_streaming.py delete mode 100644 tests/examples/research_bot/README.md delete mode 100644 tests/examples/research_bot/__init__.py delete mode 100644 tests/examples/research_bot/agents/__init__.py delete mode 100644 tests/examples/research_bot/agents/planner_agent.py delete mode 100644 tests/examples/research_bot/agents/search_agent.py delete mode 100644 tests/examples/research_bot/agents/writer_agent.py delete mode 100644 tests/examples/research_bot/main.py delete mode 100644 tests/examples/research_bot/manager.py delete mode 100644 tests/examples/research_bot/printer.py delete mode 100644 tests/examples/research_bot/sample_outputs/product_recs.md delete mode 100644 tests/examples/research_bot/sample_outputs/product_recs.txt delete mode 100644 tests/examples/research_bot/sample_outputs/vacation.md delete mode 100644 tests/examples/research_bot/sample_outputs/vacation.txt delete mode 100644 tests/examples/tools/computer_use.py delete mode 100644 tests/examples/tools/file_search.py delete mode 100644 tests/examples/tools/web_search.py delete mode 100644 tests/mkdocs.yml delete mode 100644 tests/pyproject.toml delete mode 100644 tests/src/agents/__init__.py delete mode 100644 tests/src/agents/_config.py delete mode 100644 tests/src/agents/_debug.py delete mode 100644 tests/src/agents/_run_impl.py delete mode 100644 tests/src/agents/_utils.py delete mode 100644 tests/src/agents/agent.py delete mode 100644 tests/src/agents/agent_output.py delete mode 100644 tests/src/agents/computer.py delete mode 100644 tests/src/agents/exceptions.py delete mode 100644 tests/src/agents/extensions/__init__.py delete mode 100644 tests/src/agents/extensions/handoff_filters.py delete mode 100644 tests/src/agents/extensions/handoff_prompt.py delete mode 100644 tests/src/agents/function_schema.py delete mode 100644 tests/src/agents/guardrail.py delete mode 100644 tests/src/agents/handoffs.py delete mode 100644 tests/src/agents/items.py delete mode 100644 tests/src/agents/lifecycle.py delete mode 100644 tests/src/agents/logger.py delete mode 100644 tests/src/agents/model_settings.py delete mode 100644 tests/src/agents/models/__init__.py delete mode 100644 tests/src/agents/models/_openai_shared.py delete mode 100644 tests/src/agents/models/fake_id.py delete mode 100644 tests/src/agents/models/interface.py delete mode 100644 tests/src/agents/models/openai_chatcompletions.py delete mode 100644 tests/src/agents/models/openai_provider.py delete mode 100644 tests/src/agents/models/openai_responses.py delete mode 100644 tests/src/agents/result.py delete mode 100644 tests/src/agents/run.py delete mode 100644 tests/src/agents/run_context.py delete mode 100644 tests/src/agents/stream_events.py delete mode 100644 tests/src/agents/strict_schema.py delete mode 100644 tests/src/agents/tool.py delete mode 100644 tests/src/agents/tracing/__init__.py delete mode 100644 tests/src/agents/tracing/create.py delete mode 100644 tests/src/agents/tracing/logger.py delete mode 100644 tests/src/agents/tracing/processor_interface.py delete mode 100644 tests/src/agents/tracing/processors.py delete mode 100644 tests/src/agents/tracing/scope.py delete mode 100644 tests/src/agents/tracing/setup.py delete mode 100644 tests/src/agents/tracing/span_data.py delete mode 100644 tests/src/agents/tracing/spans.py delete mode 100644 tests/src/agents/tracing/traces.py delete mode 100644 tests/src/agents/tracing/util.py delete mode 100644 tests/src/agents/usage.py delete mode 100644 tests/src/agents/version.py delete mode 100644 tests/src/openai_agents.egg-info/PKG-INFO delete mode 100644 tests/src/openai_agents.egg-info/SOURCES.txt delete mode 100644 tests/src/openai_agents.egg-info/dependency_links.txt delete mode 100644 tests/src/openai_agents.egg-info/requires.txt delete mode 100644 tests/src/openai_agents.egg-info/top_level.txt diff --git a/tests/LICENSE b/tests/LICENSE deleted file mode 100644 index e5ad2c5a..00000000 --- a/tests/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2025 OpenAI - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/tests/Makefile b/tests/Makefile deleted file mode 100644 index 7dd9bbdf..00000000 --- a/tests/Makefile +++ /dev/null @@ -1,37 +0,0 @@ -.PHONY: sync -sync: - uv sync --all-extras --all-packages --group dev - -.PHONY: format -format: - uv run ruff format - -.PHONY: lint -lint: - uv run ruff check - -.PHONY: mypy -mypy: - uv run mypy . - -.PHONY: tests -tests: - uv run pytest - -.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: - uv run mkdocs build - -.PHONY: serve-docs -serve-docs: - uv run mkdocs serve - -.PHONY: deploy-docs -deploy-docs: - uv run mkdocs gh-deploy --force --verbose - diff --git a/tests/README.md b/tests/README.md deleted file mode 100644 index 8acd13cb..00000000 --- a/tests/README.md +++ /dev/null @@ -1,174 +0,0 @@ -# OpenAI Agents SDK - -The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. - -Image of the Agents Tracing UI - -### Core concepts: - -1. [**Agents**](docs/agents.md): LLMs configured with instructions, tools, guardrails, and handoffs -2. [**Handoffs**](docs/handoffs.md): Allow agents to transfer control to other agents for specific tasks -3. [**Guardrails**](docs/guardrails.md): Configurable safety checks for input and output validation -4. [**Tracing**](docs/tracing.md): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows - -Explore the [examples](examples) directory to see the SDK in action. - -## Get started - -1. Set up your Python environment - -``` -python -m venv env -source env/bin/activate -``` - -2. Install Agents SDK - -``` -pip install openai-agents -``` - -## Hello world example - -```python -from agents import Agent, Runner - -agent = Agent(name="Assistant", instructions="You are a helpful assistant") - -result = Runner.run_sync(agent, "Write a haiku about recursion in programming.") -print(result.final_output) - -# Code within the code, -# Functions calling themselves, -# Infinite loop's dance. -``` - -(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_) - -## Handoffs example - -```py -from agents import Agent, Runner -import asyncio - -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], -) - - -async def main(): - result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?") - print(result.final_output) - # ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás? - - -if __name__ == "__main__": - asyncio.run(main()) -``` - -## Functions example - -```python -import asyncio - -from agents import Agent, Runner, function_tool - - -@function_tool -def get_weather(city: str) -> str: - return f"The weather in {city} is sunny." - - -agent = Agent( - name="Hello world", - instructions="You are a helpful agent.", - tools=[get_weather], -) - - -async def main(): - result = await Runner.run(agent, input="What's the weather in Tokyo?") - print(result.final_output) - # The weather in Tokyo is sunny. - - -if __name__ == "__main__": - asyncio.run(main()) -``` - -## The agent loop - -When you call `Runner.run()`, we run a loop until we get a final output. - -1. We call the LLM, using the model and settings on the agent, and the message history. -2. The LLM returns a response, which may include tool calls. -3. If the response has a final output (see below for the more on this), we return it and end the loop. -4. If the response has a handoff, we set the agent to the new agent and go back to step 1. -5. We process the tool calls (if any) and append the tool responses messsages. Then we go to step 1. - -There is a `max_turns` parameter that you can use to limit the number of times the loop executes. - -### Final output - -Final output is the last thing the agent produces in the loop. - -1. If you set an `output_type` on the agent, the final output is when the LLM returns something of that type. We use [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) for this. -2. If there's no `output_type` (i.e. plain text responses), then the first LLM response without any tool calls or handoffs is considered as the final output. - -As a result, the mental model for the agent loop is: - -1. If the current agent has an `output_type`, the loop runs until the agent produces structured output matching that type. -2. If the current agent does not have an `output_type`, the loop runs until the current agent produces a message without any tool calls/handoffs. - -## Common agent patterns - -The Agents SDK is designed to be highly flexible, allowing you to model a wide range of LLM workflows including deterministic flows, iterative loops, and more. See examples in [`examples/agent_patterns`](examples/agent_patterns). - -## Tracing - -The Agents SDK includes built-in tracing, 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), and [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk). See [Tracing](http://openai.github.io/openai-agents-python/tracing.md) for more details. - -## Development (only needed if you need to edit the SDK/examples) - -0. Ensure you have [`uv`](https://docs.astral.sh/uv/) installed. - -```bash -uv --version -``` - -1. Install dependencies - -```bash -make sync -``` - -2. (After making changes) lint/test - -``` -make tests # run tests -make mypy # run typechecker -make lint # run linter -``` - -## Acknowledgements - -We'd like to acknowledge the excellent work of the open-source community, especially: - -- [Pydantic](https://docs.pydantic.dev/latest/) (data validation) and [PydanticAI](https://ai.pydantic.dev/) (advanced agent framework) -- [MkDocs](https://github.com/squidfunk/mkdocs-material) -- [Griffe](https://github.com/mkdocstrings/griffe) -- [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff) - -We're committed to continuing to build the Agents SDK as an open source framework so others in the community can expand on our approach. diff --git a/tests/docs/agents.md b/tests/docs/agents.md deleted file mode 100644 index 9b6264b5..00000000 --- a/tests/docs/agents.md +++ /dev/null @@ -1,131 +0,0 @@ -# Agents - -Agents are the core building block in your apps. An agent is a large language model (LLM), configured with instructions and tools. - -## Basic configuration - -The most common properties of an agent you'll configure are: - -- `instructions`: also known as a developer message or system prompt. -- `model`: which LLM to use, and optional `model_settings` to configure model tuning parameters like temperature, top_p, etc. -- `tools`: Tools that the agent can use to achieve its tasks. - -```python -from agents import Agent, ModelSettings, function_tool - -def get_weather(city: str) -> str: - return f"The weather in {city} is sunny" - -agent = Agent( - name="Haiku agent", - instructions="Always respond in haiku form", - model="o3-mini", - tools=[function_tool(get_weather)], -) -``` - -## Context - -Agents are generic on their `context` type. Context is a dependency-injection tool: it's an object you create and pass to `Runner.run()`, that is passed to every agent, tool, handoff etc, and it serves as a grab bag of dependencies and state for the agent run. You can provide any Python object as the context. - -```python -@dataclass -class UserContext: - uid: str - is_pro_user: bool - - async def fetch_purchases() -> list[Purchase]: - return ... - -agent = Agent[UserContext]( - ..., -) -``` - -## Output types - -By default, agents produce plain text (i.e. `str`) outputs. If you want the agent to produce a particular type of output, you can use the `output_type` parameter. A common choice is to use [Pydantic](https://docs.pydantic.dev/) objects, but we support any type that can be wrapped in a Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) - dataclasses, lists, TypedDict, etc. - -```python -from pydantic import BaseModel -from agents import Agent - - -class CalendarEvent(BaseModel): - name: str - date: str - participants: list[str] - -agent = Agent( - name="Calendar extractor", - instructions="Extract calendar events from text", - output_type=CalendarEvent, -) -``` - -!!! note - - When you pass an `output_type`, that tells the model to use [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) instead of regular plain text responses. - -## Handoffs - -Handoffs are sub-agents that the agent can delegate to. You provide a list of handoffs, and the agent can choose to delegate to them if relevant. This is a powerful pattern that allows orchestrating modular, specialized agents that excel at a single task. Read more in the [handoffs](handoffs.md) documentation. - -```python -from agents import Agent - -booking_agent = Agent(...) -refund_agent = Agent(...) - -triage_agent = Agent( - name="Triage agent", - instructions=( - "Help the user with their questions." - "If they ask about booking, handoff to the booking agent." - "If they ask about refunds, handoff to the refund agent." - ), - handoffs=[booking_agent, refund_agent], -) -``` - -## Dynamic instructions - -In most cases, you can provide instructions when you create the agent. However, you can also provide dynamic instructions via a function. The function will receive the agent and context, and must return the prompt. Both regular and `async` functions are accepted. - -```python -def dynamic_instructions( - context: RunContextWrapper[UserContext], agent: Agent[UserContext] -) -> str: - return f"The user's name is {context.context.name}. Help them with their questions." - - -agent = Agent[UserContext]( - name="Triage agent", - instructions=dynamic_instructions, -) -``` - -## Lifecycle events (hooks) - -Sometimes, you want to observe the lifecycle of an agent. For example, you may want to log events, or pre-fetch data when certain events occur. You can hook into the agent lifecycle with the `hooks` property. Subclass the [`AgentHooks`][agents.lifecycle.AgentHooks] class, and override the methods you're interested in. - -## Guardrails - -Guardrails allow you to run checks/validations on user input, in parallel to the agent running. For example, you could screen the user's input for relevance. Read more in the [guardrails](guardrails.md) documentation. - -## Cloning/copying agents - -By using the `clone()` method on an agent, you can duplicate an Agent, and optionally change any properties you like. - -```python -pirate_agent = Agent( - name="Pirate", - instructions="Write like a pirate", - model="o3-mini", -) - -robot_agent = pirate_agent.clone( - name="Robot", - instructions="Write like a robot", -) -``` diff --git a/tests/docs/assets/images/favicon-platform.svg b/tests/docs/assets/images/favicon-platform.svg deleted file mode 100644 index 91ef0aea..00000000 --- a/tests/docs/assets/images/favicon-platform.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - - - - - - - - diff --git a/tests/docs/assets/images/orchestration.png b/tests/docs/assets/images/orchestration.png deleted file mode 100644 index 621a833b52bfa9c5e863bca18f5866ee9fbe2586..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 432783 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 z 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%0AVW6d*4@Y` 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 z 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 Ui-AeWwrxL~AN{G^>}2wP0j+0BPXGV_ diff --git a/tests/docs/assets/logo.svg b/tests/docs/assets/logo.svg deleted file mode 100644 index ba36fc2a..00000000 --- a/tests/docs/assets/logo.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - - - - - - - - diff --git a/tests/docs/config.md b/tests/docs/config.md deleted file mode 100644 index 198d7b7e..00000000 --- a/tests/docs/config.md +++ /dev/null @@ -1,94 +0,0 @@ -# Configuring the SDK - -## API keys and clients - -By default, the SDK looks for the `OPENAI_API_KEY` environment variable for LLM requests and tracing, as soon as it is imported. If you are unable to set that environment variable before your app starts, you can use the [set_default_openai_key()][agents.set_default_openai_key] function to set the key. - -```python -from agents import set_default_openai_key - -set_default_openai_key("sk-...") -``` - -Alternatively, you can also configure an OpenAI client to be used. By default, the SDK creates an `AsyncOpenAI` instance, using the API key from the environment variable or the default key set above. You can chnage this by using the [set_default_openai_client()][agents.set_default_openai_client] function. - -```python -from openai import AsyncOpenAI -from agents import set_default_openai_client - -custom_client = AsyncOpenAI(base_url="...", api_key="...") -set_default_openai_client(client) -``` - -Finally, you can also customize the OpenAI API that is used. By default, we use the OpenAI Responses API. You can override this to use the Chat Completions API by using the [set_default_openai_api()][agents.set_default_openai_api] function. - -```python -from agents import set_default_openai_api - -set_default_openai_api("chat_completions") -``` - -## Tracing - -Tracing is enabled by default. It uses the OpenAI API keys from the section above by default (i.e. the environment variable or the default key you set). You can specifically set the API key used for tracing by using the [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] function. - -```python -from agents import set_tracing_export_api_key - -set_tracing_export_api_key("sk-...") -``` - -You can also disable tracing entirely by using the [`set_tracing_disabled()`][agents.set_tracing_disabled] function. - -```python -from agents import set_tracing_disabled - -set_tracing_disabled(True) -``` - -## Debug logging - -The SDK has two Python loggers without any handlers set. By default, this means that warnings and errors are sent to `stdout`, but other logs are suppressed. - -To enable verbose logging, use the [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] function. - -```python -from agents import enable_verbose_stdout_logging - -enable_verbose_stdout_logging() -``` - -Alternatively, you can customize the logs by adding handlers, filters, formatters, etc. You can read more in the [Python logging guide](https://docs.python.org/3/howto/logging.html). - -```python -import logging - -logger = logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger - -# To make all logs show up -logger.setLevel(logging.DEBUG) -# To make info and above show up -logger.setLevel(logging.INFO) -# To make warning and above show up -logger.setLevel(logging.WARNING) -# etc - -# You can customize this as needed, but this will output to `stderr` by default -logger.addHandler(logging.StreamHandler()) -``` - -### Sensitive data in logs - -Certain logs may contain sensitive data (for example, user data). If you want to disable this data from being logged, set the following environment variables. - -To disable logging LLM inputs and outputs: - -```bash -export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 -``` - -To disable logging tool inputs and outputs: - -```bash -export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 -``` diff --git a/tests/docs/context.md b/tests/docs/context.md deleted file mode 100644 index 5dcacebe..00000000 --- a/tests/docs/context.md +++ /dev/null @@ -1,76 +0,0 @@ -# Context management - -Context is an overloaded term. There are two main classes of context you might care about: - -1. Context available locally to your code: this is data and dependencies you might need when tool functions run, during callbacks like `on_handoff`, in lifecycle hooks, etc. -2. Context available to LLMs: this is data the LLM sees when generating a response. - -## Local context - -This is represented via the [`RunContextWrapper`][agents.run_context.RunContextWrapper] class and the [`context`][agents.run_context.RunContextWrapper.context] property within it. The way this works is: - -1. You create any Python object you want. A common pattern is to use a dataclass or a Pydantic object. -2. You pass that object to the various run methods (e.g. `Runner.run(..., **context=whatever**))`. -3. All your tool calls, lifecycle hooks etc will be passed a wrapper object, `RunContextWrapper[T]`, where `T` represents your context object type which you can access via `wrapper.context`. - -The **most important** thing to be aware of: every agent, tool function, lifecycle etc for a given agent run must use the same _type_ of context. - -You can use the context for things like: - -- Contextual data for your run (e.g. things like a username/uid or other information about the user) -- Dependencies (e.g. logger objects, data fetchers, etc) -- Helper functions - -!!! danger "Note" - - The context object is **not** sent to the LLM. It is purely a local object that you can read from, write to and call methods on it. - -```python -import asyncio -from dataclasses import dataclass - -from agents import Agent, RunContextWrapper, Runner, function_tool - -@dataclass -class UserInfo: # (1)! - name: str - uid: int - -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)! - - agent = Agent[UserInfo]( # (4)! - name="Assistant", - tools=[function_tool(fetch_user_age)], - ) - - result = await Runner.run( - starting_agent=agent, - input="What is the age of the user?", - context=user_info, - ) - - print(result.final_output) # (5)! - # The user John is 47 years old. - -if __name__ == "__main__": - asyncio.run(main()) -``` - -1. This is the context object. We've used a dataclass here, but you can use any type. -2. This is a tool. You can see it takes a `RunContextWrapper[UserInfo]`. The tool implementation reads from the context. -3. We mark the agent with the generic `UserInfo`, so that the typechecker can catch errors (for example, if we tried to pass a tool that took a different context type). -4. The context is passed to the `run` function. -5. The agent correctly calls the tool and gets the age. - -## Agent/LLM context - -When an LLM is called, the **only** data it can see is from the conversation history. This means that if you want to make some new data available to the LLM, you must do it in a way that makes it available in that history. There are a few ways to do this: - -1. You can add it to the Agent `instructions`. This is also known as a "system prompt" or "developer message". System prompts can be static strings, or they can be dynamic functions that receive the context and output a string. This is a common tactic for information that is always useful (for example, the user's name or the current date). -2. Add it to the `input` when calling the `Runner.run` functions. This is similar to the `instructions` tactic, but allows you to have messages that are lower in the [chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command). -3. Expose it via function tools. This is useful for _on-demand_ context - the LLM decides when it needs some data, and can call the tool to fetch that data. -4. Use retrieval or web search. These are special tools that are able to fetch relevant data from files or databases (retrieval), or from the web (web search). This is useful for "grounding" the response in relevant contextual data. diff --git a/tests/docs/guardrails.md b/tests/docs/guardrails.md deleted file mode 100644 index 2b7369c3..00000000 --- a/tests/docs/guardrails.md +++ /dev/null @@ -1,154 +0,0 @@ -# Guardrails - -Guardrails run _in parallel_ to your agents, enabling you to do checks and validations of user input. For example, imagine you have an agent that uses a very smart (and hence slow/expensive) model to help with customer requests. You wouldn't want malicious users to ask the model to help them with their math homework. So, you can run a guardrail with a fast/cheap model. If the guardrail detects malicious usage, it can immediately raise an error, which stops the expensive model from running and saves you time/money. - -There are two kinds of guardrails: - -1. Input guardrails run on the initial user input -2. Output guardrails run on the final agent output - -## Input guardrails - -Input guardrails run in 3 steps: - -1. First, the guardrail receives the same input passed to the agent. -2. Next, the guardrail function runs to produce a [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] -3. Finally, we check if [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception. - -!!! Note - - Input guardrails are intended to run on user input, so an agent's guardrails only run if the agent is the *first* agent. You might wonder, why is the `guardrails` property on the agent instead of passed to `Runner.run`? It's 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 - -Output guardrailas run in 3 steps: - -1. First, the guardrail receives the same input passed to the agent. -2. Next, the guardrail function runs to produce a [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] -3. Finally, we check if [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception. - -!!! 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. - -## Tripwires - -If the input or output fails the guardrail, the Guardrail can signal this with a tripwire. As soon as we see a guardail that has triggered the tripwires, we immediately raise a `{Input,Output}GuardrailTripwireTriggered` exception and halt the Agent execution. - -## Implementing a guardrail - -You need to provide a function that receives input, and returns a [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]. In this example, we'll do this by running an Agent under the hood. - -```python -from pydantic import BaseModel -from agents import ( - Agent, - GuardrailFunctionOutput, - InputGuardrailTripwireTriggered, - RunContextWrapper, - Runner, - TResponseInputItem, - input_guardrail, -) - -class MathHomeworkOutput(BaseModel): - is_math_homework: bool - reasoning: str - -guardrail_agent = Agent( # (1)! - name="Guardrail check", - instructions="Check if the user is asking you to do their math homework.", - output_type=MathHomeworkOutput, -) - - -@input_guardrail -async def math_guardrail( # (2)! - ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem] -) -> GuardrailFunctionOutput: - result = await Runner.run(guardrail_agent, input, context=ctx.context) - - return GuardrailFunctionOutput( - output_info=result.final_output, # (3)! - tripwire_triggered=result.final_output.is_math_homework, - ) - - -agent = Agent( # (4)! - name="Customer support agent", - instructions="You are a customer support agent. You help customers with their questions.", - input_guardrails=[math_guardrail], -) - -async def main(): - # This should trip the guardrail - try: - await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?") - print("Guardrail didn't trip - this is unexpected") - - except InputGuardrailTripwireTriggered: - print("Math homework guardrail tripped") -``` - -1. We'll use this agent in our guardrail function. -2. This is the guardrail function that receives the agent's input/context, and returns the result. -3. We can include extra information in the guardrail result. -4. This is the actual agent that defines the workflow. - -Output guardrails are similar. - -```python -from pydantic import BaseModel -from agents import ( - Agent, - GuardrailFunctionOutput, - OutputGuardrailTripwireTriggered, - RunContextWrapper, - Runner, - output_guardrail, -) -class MessageOutput(BaseModel): # (1)! - response: str - -class MathOutput(BaseModel): # (2)! - is_math: bool - reasoning: str - -guardrail_agent = Agent( - name="Guardrail check", - instructions="Check if the output includes any math.", - output_type=MathOutput, -) - -@output_guardrail -async def math_guardrail( # (3)! - ctx: RunContextWrapper, agent: Agent, output: MessageOutput -) -> GuardrailFunctionOutput: - result = await Runner.run(guardrail_agent, output.response, context=ctx.context) - - return GuardrailFunctionOutput( - output_info=result.final_output, - tripwire_triggered=result.final_output.is_math, - ) - -agent = Agent( # (4)! - name="Customer support agent", - instructions="You are a customer support agent. You help customers with their questions.", - output_guardrails=[math_guardrail], - output_type=MessageOutput, -) - -async def main(): - # This should trip the guardrail - try: - await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?") - print("Guardrail didn't trip - this is unexpected") - - except OutputGuardrailTripwireTriggered: - print("Math output guardrail tripped") -``` - -1. This is the actual agent's output type. -2. This is the guardrail's output type. -3. This is the guardrail function that receives the agent's output, and returns the result. -4. This is the actual agent that defines the workflow. diff --git a/tests/docs/handoffs.md b/tests/docs/handoffs.md deleted file mode 100644 index 0b868c4a..00000000 --- a/tests/docs/handoffs.md +++ /dev/null @@ -1,113 +0,0 @@ -# Handoffs - -Handoffs allow an agent to delegate tasks to another agent. This is particularly useful in scenarios where different agents specialize in distinct areas. For example, a customer support app might have agents that each specifically handle tasks like order status, refunds, FAQs, etc. - -Handoffs are represented as tools to the LLM. So if there's a handoff to an agent named `Refund Agent`, the tool would be called `transfer_to_refund_agent`. - -## Creating a handoff - -All agents have a [`handoffs`][agents.agent.Agent.handoffs] param, which can either take an `Agent` directly, or a `Handoff` object that customizes the Handoff. - -You can create a handoff using the [`handoff()`][agents.handoffs.handoff] function provided by the Agents SDK. This function allows you to specify the agent to hand off to, along with optional overrides and input filters. - -### Basic Usage - -Here's how you can create a simple handoff: - -```python -from agents import Agent, handoff - -billing_agent = Agent(name="Billing agent") -refund_agent = Agent(name="Refund agent") - -# (1)! -triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) -``` - -1. You can use the agent directly (as in `billing_agent`), or you can use the `handoff()` function. - -### Customizing handoffs via the `handoff()` function - -The [`handoff()`][agents.handoffs.handoff] function lets you customize things. - -- `agent`: This is the agent to which things will be handed off. -- `tool_name_override`: By default, the `Handoff.default_tool_name()` function is used, which resolves to `transfer_to_`. You can override this. -- `tool_description_override`: Override the default tool description from `Handoff.default_tool_description()` -- `on_handoff`: A callback function executed when the handoff is invoked. This is useful for things like kicking off some data fetching as soon as you know a handoff is being invoked. This function receives the agent context, and can optionally also receive LLM generated input. The input data is controlled by the `input_type` param. -- `input_type`: The type of input expected by the handoff (optional). -- `input_filter`: This lets you filter the input received by the next agent. See below for more. - -```python -from agents import Agent, handoff, RunContextWrapper - -def on_handoff(ctx: RunContextWrapper[None]): - print("Handoff called") - -agent = Agent(name="My agent") - -handoff_obj = handoff( - agent=agent, - on_handoff=on_handoff, - tool_name_override="custom_handoff_tool", - tool_description_override="Custom description", -) -``` - -## Handoff inputs - -In certain situations, you want the LLM to provide some data when it calls a handoff. For example, imagine a handoff to an "Escalation agent". You might want a reason to be provided, so you can log it. - -```python -from pydantic import BaseModel - -from agents import Agent, handoff, RunContextWrapper - -class EscalationData(BaseModel): - reason: str - -async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData): - print(f"Escalation agent called with reason: {input_data.reason}") - -agent = Agent(name="Escalation agent") - -handoff_obj = handoff( - agent=agent, - on_handoff=on_handoff, - input_type=EscalationData, -) -``` - -## Input filters - -When a handoff occurs, it's as though the new agent takes over the conversation, and gets to see the entire previous conversation history. If you want to change this, you can set an [`input_filter`][agents.handoffs.Handoff.input_filter]. An input filter is a function that receives the existing input via a [`HandoffInputData`][agents.handoffs.HandoffInputData], and must return a new `HandoffInputData`. - -There are some common patterns (for example removing all tool calls from the history), which are implemented for you in [`agents.extensions.handoff_filters`][] - -```python -from agents import Agent, handoff -from agents.extensions import handoff_filters - -agent = Agent(name="FAQ agent") - -handoff_obj = handoff( - agent=agent, - input_filter=handoff_filters.remove_all_tools, # (1)! -) -``` - -1. This will automatically remove all tools from the history when `FAQ agent` is called. - -## Recommended prompts - -To make sure that LLMs understand handoffs properly, we recommend including information about handoffs in your agents. We have a suggested prefix in [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][], or you can call [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] to automatically add recommended data to your prompts. - -```python -from agents import Agent -from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX - -billing_agent = Agent( - name="Billing agent", - instructions=f"""{RECOMMENDED_PROMPT_PREFIX} - .""", -) -``` diff --git a/tests/docs/index.md b/tests/docs/index.md deleted file mode 100644 index 28c68708..00000000 --- a/tests/docs/index.md +++ /dev/null @@ -1,52 +0,0 @@ -# OpenAI Agents SDK - -The OpenAI Agents SDK enables you to build agentic AI apps in a lightweight, easy to use package with very few abstractions. It's a production-ready upgrade of our previous experimentation for agents, [Swarm](https://github.com/openai/swarm/tree/main). The Agents SDK has a very small set of primitives: - -- **Agents**, which are LLMs equipped with instructions and tools -- **Handoffs**, which allow agents to delegate to other agents for specific tasks -- **Guardrails**, which enable the inputs to agents to be validated - -In combination with Python, these primitives are powerful enough to express complex relationships between tools and agents, and allow you to build real world applications without a steep learning curve. In addition, the SDK comes with built-in **tracing** that lets you visualize and debug your agentic flows, as well as evaluate them and even fine-tune models for your application. - -## Why use the Agents SDK - -The SDK has two driving design principles: - -1. Enough features to be worth using, but few enough primitives to make it quick to learn. -2. Works great out of the box, but you can customize exactly what happens. - -Here are the main features of the SDK: - -- Agent loop: Built-in agent loop that handles calling tools, sending results to the LLM, and looping until the LLM is done. -- Python-first: Use built-in language features to orchestrate and chain agents, rather than needing to learn new abstractions. -- Handoffs: A powerful feature to coordinate and delegate between multiple agents. -- Guardrails: Run input validations and checks in parallel to your agents, breaking early if the checks fail. -- Function tools: Turn any Python function into a tool, with automatic schema generation and Pydantic-powered validation. -- Tracing: Built-in tracing that lets you visualize, debug and monitor your workflows, as well as use the OpenAI suite of evaluation, fine-tuning and distillation tools. - -## Installation - -```bash -pip install openai-agents -``` - -## Hello world example - -```python -from agents import Agent, Runner - -agent = Agent(name="Assistant", instructions="You are a helpful assistant") - -result = Runner.run_sync(agent, "Write a haiku about recursion in programming.") -print(result.final_output) - -# Code within the code, -# Functions calling themselves, -# Infinite loop's dance. -``` - -(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_) - -```bash -export OPENAI_API_KEY=sk-... -``` diff --git a/tests/docs/models.md b/tests/docs/models.md deleted file mode 100644 index 7d2ff1ff..00000000 --- a/tests/docs/models.md +++ /dev/null @@ -1,73 +0,0 @@ -# Models - -The Agents SDK comes with out of the box support for OpenAI models in two flavors: - -- **Recommended**: the [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel], which calls OpenAI APIs using the new [Responses API](https://platform.openai.com/docs/api-reference/responses). -- The [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel], which calls OpenAI APIs using the [Chat Completions API](https://platform.openai.com/docs/api-reference/chat). - -## Mixing and matching models - -Within a single workflow, you may want to use different models for each agent. For example, you could use a smaller, faster model for triage, while using a larger, more capable model for complex tasks. When configuring an [`Agent`][agents.Agent], you can select a specific model by either: - -1. Passing the name of an OpenAI model. -2. Passing any model name + a [`ModelProvider`][agents.models.interface.ModelProvider] that can map that name to a Model instance. -3. Directly providing a [`Model`][agents.models.interface.Model] implementation. - -!!!note - - While our SDK supports both the [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] and the[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] shapes, we recommend using a single model shape for each workflow because the two shapes support a different set of features and tools. If your workflow requires mixing and matching model shapes, make sure that all the features you're using are available on both. - -```python -from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel -import asyncio - -spanish_agent = Agent( - name="Spanish agent", - instructions="You only speak Spanish.", - model="o3-mini", # (1)! -) - -english_agent = Agent( - name="English agent", - instructions="You only speak English", - model=OpenAIChatCompletionsModel( # (2)! - model="gpt-4o", - openai_client=AsyncOpenAI() - ), -) - -triage_agent = Agent( - name="Triage agent", - instructions="Handoff to the appropriate agent based on the language of the request.", - handoffs=[spanish_agent, english_agent], - model="gpt-3.5-turbo", -) - -async def main(): - result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?") - print(result.final_output) -``` - -1. Sets the the name of an OpenAI model directly. -2. Provides a [`Model`][agents.models.interface.Model] implementation. - -## Using other LLM providers - -Many providers also support the OpenAI API format, which means you can pass a `base_url` to the existing OpenAI model implementations and use them easily. `ModelSettings` is used to configure tuning parameters (e.g., temperature, top_p) for the model you select. - -```python -external_client = AsyncOpenAI( - api_key="EXTERNAL_API_KEY", - base_url="https://api.external.com/v1/", -) - -spanish_agent = Agent( - name="Spanish agent", - instructions="You only speak Spanish.", - model=OpenAIChatCompletionsModel( - model="EXTERNAL_MODEL_NAME", - openai_client=external_client, - ), - model_settings=ModelSettings(temperature=0.5), -) -``` diff --git a/tests/docs/multi_agent.md b/tests/docs/multi_agent.md deleted file mode 100644 index c1182492..00000000 --- a/tests/docs/multi_agent.md +++ /dev/null @@ -1,37 +0,0 @@ -# Orchestrating multiple agents - -Orchestration refers to the flow of agents in your app. Which agents run, in what order, and how do they decide what happens next? There are two main ways to orchestrate agents: - -1. Allowing the LLM to make decisions: this uses the intelligence of an LLM to plan, reason, and decide on what steps to take based on that. -2. Orchestrating via code: determining the flow of agents via your code. - -You can mix and match these patterns. Each has their own tradeoffs, described below. - -## Orchestrating via LLM - -An agent is an LLM equipped with instructions, tools and handoffs. This means that given an open-ended task, the LLM can autonomously plan how it will tackle the task, using tools to take actions and acquire data, and using handoffs to delegate tasks to sub-agents. For example, a research agent could be equipped with tools like: - -- Web search to find information online -- File search and retrieval to search through proprietary data and connections -- Computer use to take actions on a computer -- Code execution to do data analysis -- Handoffs to specialized agents that are great at planning, report writing and more. - -This pattern is great when the task is open-ended and you want to rely on the intelligence of an LLM. The most important tactics here are: - -1. Invest in good prompts. Make it clear what tools are available, how to use them, and what parameters it must operate within. -2. Monitor your app and iterate on it. See where things go wrong, and iterate on your prompts. -3. Allow the agent to introspect and improve. For example, run it in a loop, and let it critique itself; or, provide error messages and let it improve. -4. Have specialized agents that excel in one task, rather than having a general purpose agent that is expected to be good at anything. -5. Invest in [evals](https://platform.openai.com/docs/guides/evals). This lets you train your agents to improve and get better at tasks. - -## Orchestrating via code - -While orchestrating via LLM is powerful, orchestrating via LLM makes tasks more deterministic and predictable, in terms of speed, cost and performance. Common patterns here are: - -- Using [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) to generate well formed data that you can inspect with your code. For example, you might ask an agent to classify the task into a few categories, and then pick the next agent based on the category. -- Chaining multiple agents by transforming the output of one into the input of the next. You can decompose a task like writing a blog post into a series of steps - do research, write an outline, write the blog post, critique it, and then improve it. -- Running the agent that performs the task in a `while` loop with an agent that evaluates and provides feedback, until the evaluator says the output passes certain criteria. -- Running multiple agents in parallel, e.g. via Python primitives like `asyncio.gather`. This is useful for speed when you have multiple tasks that don't depend on each other. - -We have a number of examples in [`examples/agent_patterns`](https://github.com/openai/openai-agents-python/examples/agent_patterns). diff --git a/tests/docs/quickstart.md b/tests/docs/quickstart.md deleted file mode 100644 index 19051f49..00000000 --- a/tests/docs/quickstart.md +++ /dev/null @@ -1,186 +0,0 @@ -# Quickstart - -## Create a project and virtual environment - -You'll only need to do this once. - -```bash -mkdir my_project -cd my_project -python -m venv .venv -``` - -### Activate the virtual environment - -Do this every time you start a new terminal session. - -```bash -source .venv/bin/activate -``` - -### Install the Agents SDK - -```bash -pip install openai-agents # or `uv add openai-agents`, etc -``` - -### Set an OpenAI API key - -If you don't have one, follow [these instructions](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) to create an OpenAI API key. - -```bash -export OPENAI_API_KEY=sk-... -``` - -## Create your first agent - -Agents are defined with instructions, a name, and optional config (such as `model_config`) - -```python -from agents import Agent - -agent = Agent( - name="Math Tutor", - instructions="You provide help with math problems. Explain your reasoning at each step and include examples", -) -``` - -## Add a few more agents - -Additional agents can be defined in the same way. `handoff_descriptions` provide additional context for determining handoff routing - -```python -from agents import Agent - -history_tutor_agent = Agent( - name="History Tutor", - handoff_description="Specialist agent for historical questions", - instructions="You provide assistance with historical queries. Explain important events and context clearly.", -) - -math_tutor_agent = Agent( - name="Math Tutor", - handoff_description="Specialist agent for math questions", - instructions="You provide help with math problems. Explain your reasoning at each step and include examples", -) -``` - -## Define your handoffs - -On each agent, you can define an inventory of outgoing handoff options that the agent can choose from to decide how to make progress on their task. - -```python -triage_agent = Agent( - name="Triage Agent", - instructions="You determine which agent to use based on the user's homework question", - handoffs=[history_tutor_agent, math_tutor_agent] -) -``` - -## Run the agent orchestration - -Let's check that the workflow runs and the triage agent correctly routes between the two specialist agents. - -```python -from agents import Runner - -async def main(): - result = await Runner.run(triage_agent, "What is the capital of France?") - print(result.final_output) -``` - -## Add a guardrail - -You can define custom guardrails to run on the input or output. - -```python -from agents import GuardrailFunctionOutput, Agent, Runner -from pydantic import BaseModel - -class HomeworkOutput(BaseModel): - is_homework: bool - reasoning: str - -guardrail_agent = Agent( - name="Guardrail check", - instructions="Check if the user is asking about homework.", - output_type=HomeworkOutput, -) - -async def homework_guardrail(ctx, agent, input_data): - result = await Runner.run(guardrail_agent, input_data, context=ctx.context) - final_output = result.final_output_as(HomeworkOutput) - return GuardrailFunctionOutput( - output_info=final_output, - tripwire_triggered=not final_output.is_homework, - ) -``` - -## Put it all together - -Let's put it all together and run the entire workflow, using handoffs and the input guardrail. - -```python -from agents import Agent, InputGuardrail,GuardrailFunctionOutput, Runner -from pydantic import BaseModel -import asyncio - -class HomeworkOutput(BaseModel): - is_homework: bool - reasoning: str - -guardrail_agent = Agent( - name="Guardrail check", - instructions="Check if the user is asking about homework.", - output_type=HomeworkOutput, -) - -math_tutor_agent = Agent( - name="Math Tutor", - handoff_description="Specialist agent for math questions", - instructions="You provide help with math problems. Explain your reasoning at each step and include examples", -) - -history_tutor_agent = Agent( - name="History Tutor", - handoff_description="Specialist agent for historical questions", - instructions="You provide assistance with historical queries. Explain important events and context clearly.", -) - - -async def homework_guardrail(ctx, agent, input_data): - result = await Runner.run(guardrail_agent, input_data, context=ctx.context) - final_output = result.final_output_as(HomeworkOutput) - return GuardrailFunctionOutput( - output_info=final_output, - tripwire_triggered=not final_output.is_homework, - ) - -triage_agent = Agent( - name="Triage Agent", - instructions="You determine which agent to use based on the user's homework question", - handoffs=[history_tutor_agent, math_tutor_agent], - input_guardrails=[ - InputGuardrail(guardrail_function=homework_guardrail), - ], -) - -async def main(): - result = await Runner.run(triage_agent, "what is life") - print(result.final_output) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -## View your traces - -To review what happened during your agent run, navigate to the [Trace viewer in the OpenAI Dashboard](https://platform.openai.com/traces) to view traces of your agent runs. - -## Next steps - -Learn how to build more complex agentic flows: - -- Learn about how to configure [Agents](agents.md). -- Learn about [running agents](running_agents.md). -- Learn about [tools](tools.md), [guardrails](guardrails.md) and [models](models.md). diff --git a/tests/docs/ref/agent.md b/tests/docs/ref/agent.md deleted file mode 100644 index 9f8b10d2..00000000 --- a/tests/docs/ref/agent.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Agents` - -::: agents.agent diff --git a/tests/docs/ref/agent_output.md b/tests/docs/ref/agent_output.md deleted file mode 100644 index e453de03..00000000 --- a/tests/docs/ref/agent_output.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Agent output` - -::: agents.agent_output diff --git a/tests/docs/ref/exceptions.md b/tests/docs/ref/exceptions.md deleted file mode 100644 index 7c1a2547..00000000 --- a/tests/docs/ref/exceptions.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Exceptions` - -::: agents.exceptions diff --git a/tests/docs/ref/extensions/handoff_filters.md b/tests/docs/ref/extensions/handoff_filters.md deleted file mode 100644 index 0ffcb13c..00000000 --- a/tests/docs/ref/extensions/handoff_filters.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Handoff filters` - -::: agents.extensions.handoff_filters diff --git a/tests/docs/ref/extensions/handoff_prompt.md b/tests/docs/ref/extensions/handoff_prompt.md deleted file mode 100644 index ca800765..00000000 --- a/tests/docs/ref/extensions/handoff_prompt.md +++ /dev/null @@ -1,8 +0,0 @@ -# `Handoff prompt` - -::: agents.extensions.handoff_prompt - - options: - members: - - RECOMMENDED_PROMPT_PREFIX - - prompt_with_handoff_instructions diff --git a/tests/docs/ref/function_schema.md b/tests/docs/ref/function_schema.md deleted file mode 100644 index 06aac2a6..00000000 --- a/tests/docs/ref/function_schema.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Function schema` - -::: agents.function_schema diff --git a/tests/docs/ref/guardrail.md b/tests/docs/ref/guardrail.md deleted file mode 100644 index 17ec929c..00000000 --- a/tests/docs/ref/guardrail.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Guardrails` - -::: agents.guardrail diff --git a/tests/docs/ref/handoffs.md b/tests/docs/ref/handoffs.md deleted file mode 100644 index 717a9181..00000000 --- a/tests/docs/ref/handoffs.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Handoffs` - -::: agents.handoffs diff --git a/tests/docs/ref/index.md b/tests/docs/ref/index.md deleted file mode 100644 index 1b8439fa..00000000 --- a/tests/docs/ref/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Agents module - -::: agents - - options: - members: - - set_default_openai_key - - set_default_openai_client - - set_default_openai_api - - set_tracing_export_api_key - - set_tracing_disabled - - set_trace_processors - - enable_verbose_stdout_logging diff --git a/tests/docs/ref/items.md b/tests/docs/ref/items.md deleted file mode 100644 index 29279e15..00000000 --- a/tests/docs/ref/items.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Items` - -::: agents.items diff --git a/tests/docs/ref/lifecycle.md b/tests/docs/ref/lifecycle.md deleted file mode 100644 index 432af147..00000000 --- a/tests/docs/ref/lifecycle.md +++ /dev/null @@ -1,6 +0,0 @@ -# `Lifecycle` - -::: agents.lifecycle - - options: - show_source: false diff --git a/tests/docs/ref/model_settings.md b/tests/docs/ref/model_settings.md deleted file mode 100644 index f7f411f0..00000000 --- a/tests/docs/ref/model_settings.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Model settings` - -::: agents.model_settings diff --git a/tests/docs/ref/models/interface.md b/tests/docs/ref/models/interface.md deleted file mode 100644 index e7bd89a8..00000000 --- a/tests/docs/ref/models/interface.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Model interface` - -::: agents.models.interface diff --git a/tests/docs/ref/models/openai_chatcompletions.md b/tests/docs/ref/models/openai_chatcompletions.md deleted file mode 100644 index 76cf5633..00000000 --- a/tests/docs/ref/models/openai_chatcompletions.md +++ /dev/null @@ -1,3 +0,0 @@ -# `OpenAI Chat Completions model` - -::: agents.models.openai_chatcompletions diff --git a/tests/docs/ref/models/openai_responses.md b/tests/docs/ref/models/openai_responses.md deleted file mode 100644 index e1794bae..00000000 --- a/tests/docs/ref/models/openai_responses.md +++ /dev/null @@ -1,3 +0,0 @@ -# `OpenAI Responses model` - -::: agents.models.openai_responses diff --git a/tests/docs/ref/result.md b/tests/docs/ref/result.md deleted file mode 100644 index 3a9e4a9b..00000000 --- a/tests/docs/ref/result.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Results` - -::: agents.result diff --git a/tests/docs/ref/run.md b/tests/docs/ref/run.md deleted file mode 100644 index ddf4475f..00000000 --- a/tests/docs/ref/run.md +++ /dev/null @@ -1,8 +0,0 @@ -# `Runner` - -::: agents.run - - options: - members: - - Runner - - RunConfig diff --git a/tests/docs/ref/run_context.md b/tests/docs/ref/run_context.md deleted file mode 100644 index 49e87305..00000000 --- a/tests/docs/ref/run_context.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Run context` - -::: agents.run_context diff --git a/tests/docs/ref/stream_events.md b/tests/docs/ref/stream_events.md deleted file mode 100644 index ea484317..00000000 --- a/tests/docs/ref/stream_events.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Streaming events` - -::: agents.stream_events diff --git a/tests/docs/ref/tool.md b/tests/docs/ref/tool.md deleted file mode 100644 index 887bef75..00000000 --- a/tests/docs/ref/tool.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Tools` - -::: agents.tool diff --git a/tests/docs/ref/tracing/create.md b/tests/docs/ref/tracing/create.md deleted file mode 100644 index c983e336..00000000 --- a/tests/docs/ref/tracing/create.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Creating traces/spans` - -::: agents.tracing.create diff --git a/tests/docs/ref/tracing/index.md b/tests/docs/ref/tracing/index.md deleted file mode 100644 index 88a0fe61..00000000 --- a/tests/docs/ref/tracing/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tracing module - -::: agents.tracing diff --git a/tests/docs/ref/tracing/processor_interface.md b/tests/docs/ref/tracing/processor_interface.md deleted file mode 100644 index 9fb04e86..00000000 --- a/tests/docs/ref/tracing/processor_interface.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Processor interface` - -::: agents.tracing.processor_interface diff --git a/tests/docs/ref/tracing/processors.md b/tests/docs/ref/tracing/processors.md deleted file mode 100644 index d7ac4af1..00000000 --- a/tests/docs/ref/tracing/processors.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Processors` - -::: agents.tracing.processors diff --git a/tests/docs/ref/tracing/scope.md b/tests/docs/ref/tracing/scope.md deleted file mode 100644 index 7b5b9fdf..00000000 --- a/tests/docs/ref/tracing/scope.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Scope` - -::: agents.tracing.scope diff --git a/tests/docs/ref/tracing/setup.md b/tests/docs/ref/tracing/setup.md deleted file mode 100644 index 1dc6a0fe..00000000 --- a/tests/docs/ref/tracing/setup.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Setup` - -::: agents.tracing.setup diff --git a/tests/docs/ref/tracing/span_data.md b/tests/docs/ref/tracing/span_data.md deleted file mode 100644 index 6ace7a88..00000000 --- a/tests/docs/ref/tracing/span_data.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Span data` - -::: agents.tracing.span_data diff --git a/tests/docs/ref/tracing/spans.md b/tests/docs/ref/tracing/spans.md deleted file mode 100644 index 9071707c..00000000 --- a/tests/docs/ref/tracing/spans.md +++ /dev/null @@ -1,9 +0,0 @@ -# `Spans` - -::: agents.tracing.spans - - options: - members: - - Span - - NoOpSpan - - SpanImpl diff --git a/tests/docs/ref/tracing/traces.md b/tests/docs/ref/tracing/traces.md deleted file mode 100644 index 0b7377f9..00000000 --- a/tests/docs/ref/tracing/traces.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Traces` - -::: agents.tracing.traces diff --git a/tests/docs/ref/tracing/util.md b/tests/docs/ref/tracing/util.md deleted file mode 100644 index 2be3d58c..00000000 --- a/tests/docs/ref/tracing/util.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Util` - -::: agents.tracing.util diff --git a/tests/docs/ref/usage.md b/tests/docs/ref/usage.md deleted file mode 100644 index b8b29db5..00000000 --- a/tests/docs/ref/usage.md +++ /dev/null @@ -1,3 +0,0 @@ -# `Usage` - -::: agents.usage diff --git a/tests/docs/results.md b/tests/docs/results.md deleted file mode 100644 index d1864fa8..00000000 --- a/tests/docs/results.md +++ /dev/null @@ -1,52 +0,0 @@ -# Results - -When you call the `Runner.run` methods, you either get a: - -- [`RunResult`][agents.result.RunResult] if you call `run` or `run_sync` -- [`RunResultStreaming`][agents.result.RunResultStreaming] if you call `run_streamed` - -Both of these inherit from [`RunResultBase`][agents.result.RunResultBase], which is where most useful information is present. - -## Final output - -The [`final_output`][agents.result.RunResultBase.final_output] property contains the final output of the last agent that ran. This is either: - -- a `str`, if the last agent didn't have an `output_type` defined -- an object of type `last_agent.output_type`, if the agent had an output type defined. - -!!! note - - `final_output` is of type `Any`. We can't statically type this, because of handoffs. If handoffs occur, that means any Agent might be the last agent, so we don't statically know the set of possible output types. - -## Inputs for the next turn - -You can use [`result.to_input_list()`][agents.result.RunResultBase.to_input_list] to turn the result into an input list that concatenates the original input you provided, to the items generated during the agent run. This makes it convenient to take the outputs of one agent run and pass them into another run, or to run it in a loop and append new user inputs each time. - -## Last agent - -The [`last_agent`][agents.result.RunResultBase.last_agent] property contains the last agent that ran. Depending on your application, this is often useful for the next time the user inputs something. For example, if you have a frontline triage agent that hands off to a language-specific agent, you can store the last agent, and re-use it the next time the user messages the agent. - -## New items - -The [`new_items`][agents.result.RunResultBase.new_items] property contains the new items generated during the run. The items are [`RunItem`][agents.items.RunItem]s. A run item wraps the raw item generated by the LLM. - -- [`MessageOutputItem`][agents.items.MessageOutputItem] indicates a message from the LLM. The raw item is the message generated. -- [`HandoffCallItem`][agents.items.HandoffCallItem] indicates that the LLM called the handoff tool. The raw item is the tool call item from the LLM. -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] indicates that a handoff occured. The raw item is the tool response to the handoff tool call. You can also access the source/target agents from the item. -- [`ToolCallItem`][agents.items.ToolCallItem] indicates that the LLM invoked a tool. -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] indicates that a tool was called. The raw item is the tool response. You can also access the tool output from the item. -- [`ReasoningItem`][agents.items.ReasoningItem] indicates a reasoning item from the LLM. The raw item is the reasoning generated. - -## Other information - -### Guardrail results - -The [`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] and [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] properties contain the results of the guardrails, if any. Guardrail results can sometimes contain useful information you want to log or store, so we make these available to you. - -### Raw responses - -The [`raw_responses`][agents.result.RunResultBase.raw_responses] property contains the [`ModelResponse`][agents.items.ModelResponse]s generated by the LLM. - -### Original input - -The [`input`][agents.result.RunResultBase.input] property contains the original input you provided to the `run` method. In most cases you won't need this, but it's available in case you do. diff --git a/tests/docs/running_agents.md b/tests/docs/running_agents.md deleted file mode 100644 index a2f137cf..00000000 --- a/tests/docs/running_agents.md +++ /dev/null @@ -1,95 +0,0 @@ -# Running agents - -You can run agents via the [`Runner`][agents.run.Runner] class. You have 3 options: - -1. [`Runner.run()`][agents.run.Runner.run], which runs async and returns a [`RunResult`][agents.result.RunResult]. -2. [`Runner.run_sync()`][agents.run.Runner.run_sync], which is a sync method and just runs `.run()` under the hood. -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed], which runs async and returns a [`RunResultStreaming`][agents.result.RunResultStreaming]. It calls the LLM in streaming mode, and streams those events to you as they are received. - -```python -from agents import Agent, Runner - -async def main(): - agent = Agent(name="Assistant", instructions="You are a helpful assistant") - - result = await Runner.run(agent, "Write a haiku about recursion in programming.") - print(result.final_output) - # Code within the code, - # Functions calling themselves, - # Infinite loop's dance. -``` - -Read more in the [results guide](results.md). - -## The agent loop - -When you use the run method in `Runner`, you pass in a starting agent and input. The input can either be a string (which is considered a user message), or a list of input items, which are the items in the OpenAI Responses API. - -The runner then runs a loop: - -1. We call the LLM for the current agent, with the current input. -2. The LLM produces its output. - 1. If the LLM returns a `final_output`, the loop ends and we return the result. - 2. If the LLM does a handoff, we update the current agent and input, and re-run the loop. - 3. If the LLM produces tool calls, we run those tool calls, append the results, and re-run the loop. -3. If we exceed the `max_turns` passed, we raise a [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] exception. - -!!! note - - The rule for whether the LLM output is considered as a "final output" is that it produces text output with the desired type, and there are no tool calls. - -## Streaming - -Streaming allows you to additionally receive streaming events as the LLM runs. Once the stream is done, the [`RunResultStreaming`][agents.result.RunResultStreaming] will contain the complete information about the run, including all the new outputs produces. You can call `.stream_events()` for the streaming events. Read more in the [streaming guide](streaming.md). - -## Run config - -The `run_config` parameter lets you configure some global settings for the agent run: - -- [`model`][agents.run.RunConfig.model]: Allows setting a global LLM model to use, irrespective of what `model` each Agent has. -- [`model_provider`][agents.run.RunConfig.model_provider]: A model provider for looking up model names, which defaults to OpenAI. -- [`model_settings`][agents.run.RunConfig.model_settings]: Overrides agent-specific settings. For example, you can set a global `temperature` or `top_p`. -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: A list of input or output guardrails to include on all runs. -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: A global input filter to apply to all handoffs, if the handoff doesn't already have one. The input filter allows you to edit the inputs that are sent to the new agent. See the documentation in [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] for more details. -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: Allows you to disable [tracing](tracing.md) for the entire run. -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: Configures whether traces will include potentially sensitive data, such as LLM and tool call inputs/outputs. -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: Sets the tracing workflow name, trace ID and trace group ID for the run. We recommend at least setting `workflow_name`. The session ID is an optional field that lets you link traces across multiple runs. -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: Metadata to include on all traces. - -## Conversations/chat threads - -Calling any of the run methods can result in one or more agents running (and hence one or more LLM calls), but it represents a single logical turn in a chat conversation. For example: - -1. User turn: user enter text -2. Runner run: first agent calls LLM, runs tools, does a handoff to a second agent, second agent runs more tools, and then produces an output. - -At the end of the agent run, you can choose what to show to the user. For example, you might show the user every new item generated by the agents, or just the final output. Either way, the user might then ask a followup question, in which case you can call the run method again. - -You can use the base [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] method to get the inputs for the next turn. - -```python -async def main(): - agent = Agent(name="Assistant", instructions="Reply very concisely.") - - with trace(workflow_name="Conversation", group_id=thread_id): - # First turn - result = await Runner.run(agent, "What city is the Golden Gate Bridge in?") - print(result.final_output) - # San Francisco - - # Second turn - new_input = output.to_input_list() + [{"role": "user", "content": "What state is it in?"}] - result = await Runner.run(agent, new_input) - print(result.final_output) - # California -``` - -## Exceptions - -The SDK raises exceptions in certain cases. The full list is in [`agents.exceptions`][]. As an overview: - -- [`AgentsException`][agents.exceptions.AgentsException] is the base class for all exceptions raised in the SDK. -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] is raised when the run exceeds the `max_turns` passed to the run methods. -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError] is raised when the model produces invalid outputs, e.g. malformed JSON or using non-existent tools. -- [`UserError`][agents.exceptions.UserError] is raised when you (the person writing code using the SDK) make an error using the SDK. -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] is raised when a [guardrail](guardrails.md) is tripped. diff --git a/tests/docs/streaming.md b/tests/docs/streaming.md deleted file mode 100644 index b2c7c095..00000000 --- a/tests/docs/streaming.md +++ /dev/null @@ -1,87 +0,0 @@ -# Streaming - -Streaming lets you subscribe to updates of the agent run as it proceeds. This can be useful for showing the end-user progress updates and partial responses. - -To stream, you can call [`Runner.run_streamed()`][agents.run.Runner.run_streamed], which will give you a [`RunResultStreaming`][agents.result.RunResultStreaming]. Calling `result.stream_events()` gives you an async stream of [`StreamEvent`][agents.stream_events.StreamEvent] objects, which are described below. - -## Raw response events - -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] are raw events passed directly from the LLM. They are in OpenAI Responses API format, which means each event has a type (like `response.created`, `response.output_text.delta`, etc) and data. These events are useful if you want to stream response messages to the user as soon as they are generated. - -For example, this will output the text generated by the LLM token-by-token. - -```python -import asyncio -from openai.types.responses import ResponseTextDeltaEvent -from agents import Agent, Runner - -async def main(): - agent = Agent( - name="Joker", - instructions="You are a helpful assistant.", - ) - - result = Runner.run_streamed(agent, input="Please tell me 5 jokes.") - async for event in result.stream_events(): - if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent): - print(event.data.delta, end="", flush=True) - - -if __name__ == "__main__": - asyncio.run(main()) -``` - -## Run item events and agent events - -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]s are higher level events. They inform you when an item has been fully generated. This allows you to push progress updates at the level of "message generated", "tool ran", etc, instead of each token. Similarly, [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] gives you updates when the current agent changes (e.g. as the result of a handoff). - -For example, this will ignore raw events and stream updates to the user. - -```python -import asyncio -import random -from agents import Agent, ItemHelpers, Runner, function_tool - -@function_tool -def how_many_jokes() -> int: - return random.randint(1, 10) - - -async def main(): - agent = Agent( - name="Joker", - instructions="First call the `how_many_jokes` tool, then tell that many jokes.", - tools=[how_many_jokes], - ) - - result = Runner.run_streamed( - agent, - input="Hello", - ) - print("=== Run starting ===") - - async for event in result.stream_events(): - # We'll ignore the raw responses event deltas - if event.type == "raw_response_event": - continue - # When the agent updates, print that - elif event.type == "agent_updated_stream_event": - print(f"Agent updated: {event.new_agent.name}") - continue - # When items are generated, print them - elif event.type == "run_item_stream_event": - if event.item.type == "tool_call_item": - print("-- Tool was called") - elif event.item.type == "tool_call_output_item": - print(f"-- Tool output: {event.item.output}") - elif event.item.type == "message_output_item": - print(f"-- Message output:\n {ItemHelpers.text_message_output(event.item)}") - else: - pass # Ignore other event types - - print("=== Run complete ===") - - -if __name__ == "__main__": - asyncio.run(main()) -``` diff --git a/tests/docs/stylesheets/extra.css b/tests/docs/stylesheets/extra.css deleted file mode 100644 index 89cf164b..00000000 --- a/tests/docs/stylesheets/extra.css +++ /dev/null @@ -1,194 +0,0 @@ -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: normal; - font-weight: 400; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-Regular.woff2") - format("woff2"); -} - -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: italic; - font-weight: 400; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-RegularItalic.woff2") - format("woff2"); -} - -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: normal; - font-weight: 500; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-Medium.woff2") - format("woff2"); -} - -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: italic; - font-weight: 500; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-MediumItalic.woff2") - format("woff2"); -} - -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: normal; - font-weight: 600; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-Semibold.woff2") - format("woff2"); -} - -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: italic; - font-weight: 600; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-SemiboldItalic.woff2") - format("woff2"); -} - -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: normal; - font-weight: 700; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-Bold.woff2") - format("woff2"); -} - -@font-face { - font-display: swap; - font-family: "OpenAI Sans"; - font-style: italic; - font-weight: 700; - src: url("https://cdn.openai.com/common/fonts/openai-sans/OpenAISans-BoldItalic.woff2") - format("woff2"); -} - -/* - Root variables that apply to all color schemes. - Material for MkDocs automatically switches data-md-color-scheme - between "default" (light) and "slate" (dark) when you use the toggles. -*/ -:root { - /* Font families */ - --md-text-font: "OpenAI Sans", -apple-system, system-ui, Helvetica, Arial, - sans-serif; - --md-typeface-heading: "OpenAI Sans", -apple-system, system-ui, Helvetica, - Arial, sans-serif; - - /* Global color variables */ - --md-default-fg-color: #212121; - --md-default-bg-color: #ffffff; - --md-primary-fg-color: #000; - --md-accent-fg-color: #000; - - /* Code block theming */ - --md-code-fg-color: red; - --md-code-bg-color: #f5f5f5; - - /* Tables, blockquotes, etc. */ - --md-table-row-border-color: #e0e0e0; - --md-admonition-bg-color: #f8f8f8; - --md-admonition-title-fg-color: #373737; - --md-default-fg-color--light: #000; - - --md-typeset-a-color: #000; - --md-accent-fg-color: #000; - - --md-code-fg-color: #000; -} - -/* Header styling */ -.md-header { - background-color: #000; -} - -.md-header--shadow { - box-shadow: none; -} - -.md-content .md-typeset h1 { - color: #000; -} - -.md-typeset p, -.md-typeset li { - font-size: 16px; -} - -.md-typeset__table p { - line-height: 1em; -} - -.md-nav { - font-size: 14px; -} -.md-nav__title { - color: #000; - font-weight: 600; -} - -.md-typeset h1, -.md-typeset h2, -.md-typeset h3, -.md-typeset h4 { - font-weight: 600; -} - -.md-typeset h1 code { - color: #000; - padding: 0; - background-color: transparent; -} -.md-footer { - display: none; -} - -.md-header__title { - margin-left: 0 !important; -} - -.md-typeset .admonition, -.md-typeset details { - border: none; - outline: none; - border-radius: 8px; - overflow: hidden; -} - -.md-typeset pre > code { - font-size: 14px; -} - -.md-typeset__table code { - font-size: 14px; -} - -/* Custom link styling */ -.md-content a { - text-decoration: none; -} - -.md-content a:hover { - text-decoration: underline; -} - -/* Code block styling */ -.md-content .md-code__content { - border-radius: 8px; -} - -.md-clipboard.md-icon { - color: #9e9e9e; -} - -/* Reset scrollbar styling to browser default with high priority */ -.md-sidebar__scrollwrap { - scrollbar-color: auto !important; -} diff --git a/tests/docs/tools.md b/tests/docs/tools.md deleted file mode 100644 index f7a88691..00000000 --- a/tests/docs/tools.md +++ /dev/null @@ -1,270 +0,0 @@ -# Tools - -Tools let agents take actions: things like fetching data, running code, calling external APIs, and even using a computer. There are three classes of tools in the Agent SDK: - -- Hosted tools: these run on LLM servers alongside the AI models. OpenAI offers retrieval, web search and computer use as hosted tools. -- Function calling: these allow you to use any Python function as a tool. -- Agents as tools: this allows you to use an agent as a tool, allowing Agents to call other agents without handing off to them. - -## Hosted tools - -OpenAI offers a few built-in tools when using the [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]: - -- The [`WebSearchTool`][agents.tool.WebSearchTool] lets an agent search the web. -- The [`FileSearchTool`][agents.tool.FileSearchTool] allows retrieving information from your OpenAI Vector Stores. -- The [`ComputerTool`][agents.tool.ComputerTool] allows automating computer use tasks. - -```python -from agents import Agent, FileSearchTool, Runner, WebSearchTool - -agent = Agent( - name="Assistant", - tools=[ - WebSearchTool(), - FileSearchTool( - max_num_results=3, - vector_store_ids=["VECTOR_STORE_ID"], - ), - ], -) - -async def main(): - result = await Runner.run(agent, "Which coffee shop should I go to, taking into account my preferences and the weather today in SF?") - print(result.final_output) -``` - -## Function tools - -You can use any Python function as a tool. The Agents SDK will setup the tool automatically: - -- The name of the tool will be the name of the Python function (or you can provide a name) -- Tool description will be taken from the docstring of the function (or you can provide a description) -- The schema for the function inputs is automatically created from the function's arguments -- Descriptions for each input are taken from the docstring of the function, unless disabled - -We use Python's `inspect` module to extract the function signature, along with [`griffe`](https://mkdocstrings.github.io/griffe/) to parse docstrings and `pydantic` for schema creation. - -```python -import json - -from typing_extensions import TypedDict, Any - -from agents import Agent, FunctionTool, RunContextWrapper, function_tool - - -class Location(TypedDict): - lat: float - long: float - -@function_tool # (1)! -async def fetch_weather(location: Location) -> str: - # (2)! - """Fetch the weather for a given location. - - Args: - location: The location to fetch the weather for. - """ - # In real life, we'd fetch the weather from a weather API - return "sunny" - - -@function_tool(name_override="fetch_data") # (3)! -def read_file(ctx: RunContextWrapper[Any], path: str, directory: str | None = None) -> str: - """Read the contents of a file. - - Args: - path: The path to the file to read. - directory: The directory to read the file from. - """ - # In real life, we'd read the file from the file system - return "" - - -agent = Agent( - name="Assistant", - tools=[fetch_weather, read_file], # (4)! -) - -for tool in agent.tools: - if isinstance(tool, FunctionTool): - print(tool.name) - print(tool.description) - print(json.dumps(tool.params_json_schema, indent=2)) - print() - -``` - -1. You can use any Python types as arguments to your functions, and the function can be sync or async. -2. Docstrings, if present, are used to capture descriptions and argument descriptions -3. Functions can optionally take the `context` (must be the first argument). You can also set overrides, like the name of the tool, description, which docstring style to use, etc. -4. You can pass the decorated functions to the list of tools. - -??? note "Expand to see output" - - ``` - fetch_weather - Fetch the weather for a given location. - { - "$defs": { - "Location": { - "properties": { - "lat": { - "title": "Lat", - "type": "number" - }, - "long": { - "title": "Long", - "type": "number" - } - }, - "required": [ - "lat", - "long" - ], - "title": "Location", - "type": "object" - } - }, - "properties": { - "location": { - "$ref": "#/$defs/Location", - "description": "The location to fetch the weather for." - } - }, - "required": [ - "location" - ], - "title": "fetch_weather_args", - "type": "object" - } - - fetch_data - Read the contents of a file. - { - "properties": { - "path": { - "description": "The path to the file to read.", - "title": "Path", - "type": "string" - }, - "directory": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "description": "The directory to read the file from.", - "title": "Directory" - } - }, - "required": [ - "path" - ], - "title": "fetch_data_args", - "type": "object" - } - ``` - -### Custom function tools - -Sometimes, you don't want to use a Python function as a tool. You can directly create a [`FunctionTool`][agents.tool.FunctionTool] if you prefer. You'll need to provide: - -- `name` -- `description` -- `params_json_schema`, which is the JSON schema for the arguments -- `on_invoke_tool`, which is an async function that receives the context and the arguments as a JSON string, and must return the tool output as a string. - -```python -from typing import Any - -from pydantic import BaseModel - -from agents import RunContextWrapper, FunctionTool - - - -def do_some_work(data: str) -> str: - return "done" - - -class FunctionArgs(BaseModel): - username: str - age: int - - -async def run_function(ctx: RunContextWrapper[Any], args: str) -> str: - parsed = FunctionArgs.model_validate_json(args) - return do_some_work(data=f"{parsed.username} is {parsed.age} years old") - - -tool = FunctionTool( - name="process_user", - description="Processes extracted user data", - params_json_schema=FunctionArgs.model_json_schema(), - on_invoke_tool=run_function, -) -``` - -### Automatic argument and docstring parsing - -As mentioned before, we automatically parse the function signature to extract the schema for the tool, and we parse the docstring to extract descriptions for the tool and for individual arguments. Some notes on that: - -1. The signature parsing is done via the `inspect` module. We use type annotations to understand the types for the arguments, and dynamically build a Pydantic model to represent the overall schema. It supports most types, including Python primitives, Pydantic models, TypedDicts, and more. -2. We use `griffe` to parse docstrings. Supported docstring formats are `google`, `sphinx` and `numpy`. We attempt to automatically detect the docstring format, but this is best-effort and you can explicitly set it when calling `function_tool`. You can also disable docstring parsing by setting `use_docstring_info` to `False`. - -The code for the schema extraction lives in [`agents.function_schema`][]. - -## Agents as tools - -In some workflows, you may want a central agent to orchestrate a network of specialized agents, instead of handing off control. You can do this by modeling agents as tools. - -```python -from agents import Agent, Runner -import asyncio - -spanish_agent = Agent( - name="Spanish agent", - instructions="You translate the user's message to Spanish", -) - -french_agent = Agent( - name="French agent", - instructions="You translate the user's message to French", -) - -orchestrator_agent = Agent( - name="orchestrator_agent", - instructions=( - "You are a translation agent. You use the tools given to you to translate." - "If asked for multiple translations, you call the relevant tools." - ), - tools=[ - spanish_agent.as_tool( - tool_name="translate_to_spanish", - tool_description="Translate the user's message to Spanish", - ), - french_agent.as_tool( - tool_name="translate_to_french", - tool_description="Translate the user's message to French", - ), - ], -) - -async def main(): - result = await Runner.run(orchestrator_agent, input="Say 'Hello, how are you?' in Spanish.") - print(result.final_output) -``` - -## Handling errors in function tools - -When you create a function tool via `@function_tool`, you can pass a `failure_error_function`. This is a function that provides an error response to the LLM in case the tool call crashes. - -- By default (i.e. if you don't pass anything), it runs a `default_tool_error_function` which tells the LLM an error occurred. -- If you pass your own error function, it runs that instead, and sends the response to the LLM. -- If you explicitly pass `None`, then any tool call errors will be re-raised for you to handle. This could be a `ModelBehaviorError` if the model produced invalid JSON, or a `UserError` if your code crashed, etc. - -If you are manually creating a `FunctionTool` object, then you must handle errors inside the `on_invoke_tool` function. diff --git a/tests/docs/tracing.md b/tests/docs/tracing.md deleted file mode 100644 index fbf2ae41..00000000 --- a/tests/docs/tracing.md +++ /dev/null @@ -1,95 +0,0 @@ -# Tracing - -The Agents SDK includes built-in tracing, collecting a comprehensive record of events during an agent run: LLM generations, tool calls, handoffs, guardrails, and even custom events that occur. Using the [Traces dashboard](https://platform.openai.com/traces), you can debug, visualize, and monitor your workflows during development and in production. - -!!!note - - Tracing is enabled by default. There are two ways to disable tracing: - - 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` - -## Traces and spans - -- **Traces** represent a single end-to-end operation of a "workflow". They're composed of Spans. Traces have the following properties: - - `workflow_name`: This is the logical workflow or app. For example "Code generation" or "Customer service". - - `trace_id`: A unique ID for the trace. Automatically generated if you don't pass one. Must have the format `trace_<32_alphanumeric>`. - - `group_id`: Optional group ID, to link multiple traces from the same conversation. For example, you might use a chat thread ID. - - `disabled`: If True, the trace will not be recorded. - - `metadata`: Optiona metadata for the trace. -- **Spans** represent operations that have a start and end time. Spans have: - - `started_at` and `ended_at` timestamps. - - `trace_id`, to represent the trace they belong to - - `parent_id`, which points to the parent Span of this Span (if any) - - `span_data`, which is information about the Span. For example, `AgentSpanData` contains information about the Agent, `GenerationSpanData` contains information about the LLM generation, etc. - -## Default tracing - -By default, the SDK traces the following: - -- The entire `Runner.{run, run_sync, run_streamed}()` is wrapped in a `trace()`. -- Each time an agent runs, it is wrapped in `agent_span()` -- LLM generations are wrapped in `generation_span()` -- Function tool calls are each wrapped in `function_span()` -- Guardrails are wrapped in `guardrail_span()` -- Handoffs are wrapped in `handoff_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]. - -In addition, you can set up [custom trace processors](#custom-tracing-processors) to push traces to other destinations (as a replacement, or secondary destination). - -## Higher level traces - -Sometimes, you might want multiple calls to `run()` to be part of a single trace. You can do this by wrapping the entire code in a `trace()`. - -```python -from agents import Agent, Runner, trace - -async def main(): - agent = Agent(name="Joke generator", instructions="Tell funny jokes.") - - with trace("Joke workflow"): # (1)! - first_result = await Runner.run(agent, "Tell me a joke") - second_result = await Runner.run(agent, f"Rate this joke: {first_output.final_output}") - print(f"Joke: {first_result.final_output}") - print(f"Rating: {second_result.final_output}") -``` - -1. Because the two calls to `Runner.run` are wrapped in a `with trace()`, the individual runs will be part of the overall trace rather than creating two traces. - -## Creating traces - -You can use the [`trace()`][agents.tracing.trace] function to create a trace. Traces need to be started and finished. You have two options to do so: - -1. **Recommended**: use the trace as a context manager, i.e. `with trace(...) as my_trace`. This will automatically start and end the trace at the right time. -2. You can also manually call [`trace.start()`][agents.tracing.Trace.start] and [`trace.finish()`][agents.tracing.Trace.finish]. - -The current trace is tracked via a Python [`contextvar`](https://docs.python.org/3/library/contextvars.html). This means that it works with concurrency automatically. If you manually start/end a trace, you'll need to pass `mark_as_current` and `reset_current` to `start()`/`finish()` to update the current trace. - -## Creating spans - -You can use the various [`*_span()`][agents.tracing.create] methods to create a span. In general, you don't need to manually create spans. A [`custom_span()`][agents.tracing.custom_span] function is available for tracking custom span information. - -Spans are automatically part of the current trace, and are nested under the nearest current span, which is tracked via a Python [`contextvar`](https://docs.python.org/3/library/contextvars.html). - -## 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]. - -## Custom tracing processors - -The high level architecture for tracing is: - -- At initialization, we create a global [`TraceProvider`][agents.tracing.setup.TraceProvider], which is responsible for creating traces. -- We configure the `TraceProvider` with a [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] that sends traces/spans in batches to a [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter], which exports the spans and traces to the OpenAI backend in batches. - -To customize this default setup, to send traces to alternative or additional backends or modifying exporter behavior, you have two options: - -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: - -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) diff --git a/tests/examples/__init__.py b/tests/examples/__init__.py deleted file mode 100644 index e333a2e3..00000000 --- a/tests/examples/__init__.py +++ /dev/null @@ -1,3 +0,0 @@ -# Make the examples directory into a package to avoid top-level module name collisions. -# This is needed so that mypy treats files like examples/customer_service/main.py and -# examples/researcher_app/main.py as distinct modules rather than both named "main". diff --git a/tests/examples/agent_patterns/README.md b/tests/examples/agent_patterns/README.md deleted file mode 100644 index 4599b001..00000000 --- a/tests/examples/agent_patterns/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# Common agentic patterns - -This folder contains examples of different common patterns for agents. - -## Deterministic flows - -A common tactic is to break down a task into a series of smaller steps. Each task can be performed by an agent, and the output of one agent is used as input to the next. For example, if your task was to generate a story, you could break it down into the following steps: - -1. Generate an outline -2. Generate the story -3. Generate the ending - -Each of these steps can be performed by an agent. The output of one agent is used as input to the next. - -See the [`deterministic.py`](./deterministic.py) file for an example of this. - -## Handoffs and routing - -In many situations, you have specialized sub-agents that handle specific tasks. You can use handoffs to route the task to the right agent. - -For example, you might have a frontline agent that receives a request, and then hands off to a specialized agent based on the language of the request. -See the [`routing.py`](./routing.py) file for an example of this. - -## Agents as tools - -The mental model for handoffs is that the new agent "takes over". It sees the previous conversation history, and owns the conversation from that point onwards. However, this is not the only way to use agents. You can also use agents as a tool - the tool agent goes off and runs on its own, and then returns the result to the original agent. - -For example, you could model the translation task above as tool calls instead: rather than handing over to the language-specific agent, you could call the agent as a tool, and then use the result in the next step. This enables things like translating multiple languages at once. - -See the [`agents_as_tools.py`](./agents_as_tools.py) file for an example of this. - -## LLM-as-a-judge - -LLMs can often improve the quality of their output if given feedback. A common pattern is to generate a response using a model, and then use a second model to provide feedback. You can even use a small model for the initial generation and a larger model for the feedback, to optimize cost. - -For example, you could use an LLM to generate an outline for a story, and then use a second LLM to evaluate the outline and provide feedback. You can then use the feedback to improve the outline, and repeat until the LLM is satisfied with the outline. - -See the [`llm_as_a_judge.py`](./llm_as_a_judge.py) file for an example of this. - -## Parallelization - -Running multiple agents in parallel is a common pattern. This can be useful for both latency (e.g. if you have multiple steps that don't depend on each other) and also for other reasons e.g. generating multiple responses and picking the best one. - -See the [`parallelization.py`](./parallelization.py) file for an example of this. It runs a translation agent multiple times in parallel, and then picks the best translation. - -## Guardrails - -Related to parallelization, you often want to run input guardrails to make sure the inputs to your agents are valid. For example, if you have a customer support agent, you might want to make sure that the user isn't trying to ask for help with a math problem. - -You can definitely do this without any special Agents SDK features by using parallelization, but we support a special guardrail primitive. Guardrails can have a "tripwire" - if the tripwire is triggered, the agent execution will immediately stop and a `GuardrailTripwireTriggered` exception will be raised. - -This is really useful for latency: for example, you might have a very fast model that runs the guardrail and a slow model that runs the actual agent. You wouldn't want to wait for the slow model to finish, so guardrails let you quickly reject invalid inputs. - -See the [`guardrails.py`](./guardrails.py) file for an example of this. diff --git a/tests/examples/agent_patterns/agents_as_tools.py b/tests/examples/agent_patterns/agents_as_tools.py deleted file mode 100644 index 9fd118ef..00000000 --- a/tests/examples/agent_patterns/agents_as_tools.py +++ /dev/null @@ -1,79 +0,0 @@ -import asyncio - -from agents import Agent, ItemHelpers, MessageOutputItem, Runner, trace - -""" -This example shows the agents-as-tools pattern. The frontline agent receives a user message and -then picks which agents to call, as tools. In this case, it picks from a set of translation -agents. -""" - -spanish_agent = Agent( - name="spanish_agent", - instructions="You translate the user's message to Spanish", - handoff_description="An english to spanish translator", -) - -french_agent = Agent( - name="french_agent", - instructions="You translate the user's message to French", - handoff_description="An english to french translator", -) - -italian_agent = Agent( - name="italian_agent", - instructions="You translate the user's message to Italian", - handoff_description="An english to italian translator", -) - -orchestrator_agent = Agent( - name="orchestrator_agent", - instructions=( - "You are a translation agent. You use the tools given to you to translate." - "If asked for multiple translations, you call the relevant tools in order." - "You never translate on your own, you always use the provided tools." - ), - tools=[ - spanish_agent.as_tool( - tool_name="translate_to_spanish", - tool_description="Translate the user's message to Spanish", - ), - french_agent.as_tool( - tool_name="translate_to_french", - tool_description="Translate the user's message to French", - ), - italian_agent.as_tool( - tool_name="translate_to_italian", - tool_description="Translate the user's message to Italian", - ), - ], -) - -synthesizer_agent = Agent( - name="synthesizer_agent", - instructions="You inspect translations, correct them if needed, and produce a final concatenated response.", -) - - -async def main(): - msg = input("Hi! What would you like translated, and to which languages? ") - - # Run the entire orchestration in a single trace - with trace("Orchestrator evaluator"): - orchestrator_result = await Runner.run(orchestrator_agent, msg) - - for item in orchestrator_result.new_items: - if isinstance(item, MessageOutputItem): - text = ItemHelpers.text_message_output(item) - if text: - print(f" - Translation step: {text}") - - synthesizer_result = await Runner.run( - synthesizer_agent, orchestrator_result.to_input_list() - ) - - print(f"\n\nFinal response:\n{synthesizer_result.final_output}") - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/agent_patterns/deterministic.py b/tests/examples/agent_patterns/deterministic.py deleted file mode 100644 index 0c163afe..00000000 --- a/tests/examples/agent_patterns/deterministic.py +++ /dev/null @@ -1,80 +0,0 @@ -import asyncio - -from pydantic import BaseModel - -from agents import Agent, Runner, trace - -""" -This example demonstrates a deterministic flow, where each step is performed by an agent. -1. The first agent generates a story outline -2. We feed the outline into the second agent -3. The second agent checks if the outline is good quality and if it is a scifi story -4. If the outline is not good quality or not a scifi story, we stop here -5. If the outline is good quality and a scifi story, we feed the outline into the third agent -6. The third agent writes the story -""" - -story_outline_agent = Agent( - name="story_outline_agent", - instructions="Generate a very short story outline based on the user's input.", -) - - -class OutlineCheckerOutput(BaseModel): - good_quality: bool - is_scifi: bool - - -outline_checker_agent = Agent( - name="outline_checker_agent", - instructions="Read the given story outline, and judge the quality. Also, determine if it is a scifi story.", - output_type=OutlineCheckerOutput, -) - -story_agent = Agent( - name="story_agent", - instructions="Write a short story based on the given outline.", - output_type=str, -) - - -async def main(): - input_prompt = input("What kind of story do you want? ") - - # Ensure the entire workflow is a single trace - with trace("Deterministic story flow"): - # 1. Generate an outline - outline_result = await Runner.run( - story_outline_agent, - input_prompt, - ) - print("Outline generated") - - # 2. Check the outline - outline_checker_result = await Runner.run( - outline_checker_agent, - outline_result.final_output, - ) - - # 3. Add a gate to stop if the outline is not good quality or not a scifi story - assert isinstance(outline_checker_result.final_output, OutlineCheckerOutput) - if not outline_checker_result.final_output.good_quality: - print("Outline is not good quality, so we stop here.") - exit(0) - - if not outline_checker_result.final_output.is_scifi: - print("Outline is not a scifi story, so we stop here.") - exit(0) - - print("Outline is good quality and a scifi story, so we continue to write the story.") - - # 4. Write the story - story_result = await Runner.run( - story_agent, - outline_result.final_output, - ) - print(f"Story: {story_result.final_output}") - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/agent_patterns/input_guardrails.py b/tests/examples/agent_patterns/input_guardrails.py deleted file mode 100644 index 62591886..00000000 --- a/tests/examples/agent_patterns/input_guardrails.py +++ /dev/null @@ -1,105 +0,0 @@ -from __future__ import annotations - -import asyncio - -from pydantic import BaseModel - -from agents import ( - Agent, - GuardrailFunctionOutput, - InputGuardrailTripwireTriggered, - RunContextWrapper, - Runner, - TResponseInputItem, - input_guardrail, -) - -""" -This example shows how to use guardrails. - -Guardrails are checks that run in parallel to the agent's execution. -They can be used to do things like: -- Check if input messages are off-topic -- Check that output messages don't violate any policies -- Take over control of the agent's execution if an unexpected input is detected - -In this example, we'll setup an input guardrail that trips if the user is asking to do math homework. -If the guardrail trips, we'll respond with a refusal message. -""" - - -### 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 - - -guardrail_agent = Agent( - name="Guardrail check", - instructions="Check if the user is asking you to do their math homework.", - output_type=MathHomeworkOutput, -) - - -@input_guardrail -async def math_guardrail( - context: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem] -) -> GuardrailFunctionOutput: - """This is an input guardrail function, which happens to call an agent to check if the input - is a math homework question. - """ - result = await Runner.run(guardrail_agent, input, context=context.context) - final_output = result.final_output_as(MathHomeworkOutput) - - return GuardrailFunctionOutput( - output_info=final_output, - tripwire_triggered=not final_output.is_math_homework, - ) - - -### 2. The run loop - - -async def main(): - agent = Agent( - name="Customer support agent", - instructions="You are a customer support agent. You help customers with their questions.", - input_guardrails=[math_guardrail], - ) - - input_data: list[TResponseInputItem] = [] - - while True: - user_input = input("Enter a message: ") - input_data.append( - { - "role": "user", - "content": user_input, - } - ) - - try: - result = await Runner.run(agent, input_data) - print(result.final_output) - # If the guardrail didn't trigger, we use the result as the input for the next run - input_data = result.to_input_list() - except InputGuardrailTripwireTriggered: - # If the guardrail triggered, we instead add a refusal message to the input - message = "Sorry, I can't help you with your math homework." - print(message) - input_data.append( - { - "role": "assistant", - "content": message, - } - ) - - # Sample run: - # Enter a message: What's the capital of California? - # The capital of California is Sacramento. - # Enter a message: Can you help me solve for x: 2x + 5 = 11 - # Sorry, I can't help you with your math homework. - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/agent_patterns/llm_as_a_judge.py b/tests/examples/agent_patterns/llm_as_a_judge.py deleted file mode 100644 index d13a67cb..00000000 --- a/tests/examples/agent_patterns/llm_as_a_judge.py +++ /dev/null @@ -1,76 +0,0 @@ -from __future__ import annotations - -import asyncio -from dataclasses import dataclass -from typing import Literal - -from agents import Agent, ItemHelpers, Runner, TResponseInputItem, trace - -""" -This example shows the LLM as a judge pattern. The first agent generates an outline for a story. -The second agent judges the outline and provides feedback. We loop until the judge is satisfied -with the outline. -""" - -story_outline_generator = Agent( - name="story_outline_generator", - instructions=( - "You generate a very short story outline based on the user's input." - "If there is any feedback provided, use it to improve the outline." - ), -) - - -@dataclass -class EvaluationFeedback: - score: Literal["pass", "needs_improvement", "fail"] - feedback: str - - -evaluator = Agent[None]( - name="evaluator", - instructions=( - "You evaluate a story outline and decide if it's good enough." - "If it's not good enough, you provide feedback on what needs to be improved." - "Never give it a pass on the first try." - ), - output_type=EvaluationFeedback, -) - - -async def main() -> None: - msg = input("What kind of story would you like to hear? ") - input_items: list[TResponseInputItem] = [{"content": msg, "role": "user"}] - - latest_outline: str | None = None - - # We'll run the entire workflow in a single trace - with trace("LLM as a judge"): - while True: - story_outline_result = await Runner.run( - story_outline_generator, - input_items, - ) - - input_items = story_outline_result.to_input_list() - latest_outline = ItemHelpers.text_message_outputs(story_outline_result.new_items) - print("Story outline generated") - - evaluator_result = await Runner.run(evaluator, input_items) - result: EvaluationFeedback = evaluator_result.final_output - - print(f"Evaluator score: {result.score}") - - if result.score == "pass": - print("Story outline is good enough, exiting.") - break - - print("Re-running with feedback") - - input_items.append({"content": f"Feedback: {result.feedback}", "role": "user"}) - - print(f"Final story outline: {latest_outline}") - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/agent_patterns/output_guardrails.py b/tests/examples/agent_patterns/output_guardrails.py deleted file mode 100644 index 526a0852..00000000 --- a/tests/examples/agent_patterns/output_guardrails.py +++ /dev/null @@ -1,80 +0,0 @@ -from __future__ import annotations - -import asyncio -import json - -from pydantic import BaseModel, Field - -from agents import ( - Agent, - GuardrailFunctionOutput, - OutputGuardrailTripwireTriggered, - RunContextWrapper, - Runner, - output_guardrail, -) - -""" -This example shows how to use output guardrails. - -Output guardrails are checks that run on the final output of an agent. -They can be used to do things like: -- Check if the output contains sensitive data -- Check if the output is a valid response to the user's message - -In this example, we'll use a (contrived) example where we check if the agent's response contains -a phone number. -""" - - -# The agent's output type -class MessageOutput(BaseModel): - reasoning: str = Field(description="Thoughts on how to respond to the user's message") - response: str = Field(description="The response to the user's message") - user_name: str | None = Field(description="The name of the user who sent the message, if known") - - -@output_guardrail -async def sensitive_data_check( - context: RunContextWrapper, agent: Agent, output: MessageOutput -) -> GuardrailFunctionOutput: - phone_number_in_response = "650" in output.response - phone_number_in_reasoning = "650" in output.reasoning - - return GuardrailFunctionOutput( - output_info={ - "phone_number_in_response": phone_number_in_response, - "phone_number_in_reasoning": phone_number_in_reasoning, - }, - tripwire_triggered=phone_number_in_response or phone_number_in_reasoning, - ) - - -agent = Agent( - name="Assistant", - instructions="You are a helpful assistant.", - output_type=MessageOutput, - output_guardrails=[sensitive_data_check], -) - - -async def main(): - # This should be ok - await Runner.run(agent, "What's the capital of California?") - print("First message passed") - - # This should trip the guardrail - try: - result = await Runner.run( - agent, "My phone number is 650-123-4567. Where do you think I live?" - ) - print( - f"Guardrail didn't trip - this is unexpected. Output: {json.dumps(result.final_output.model_dump(), indent=2)}" - ) - - except OutputGuardrailTripwireTriggered as e: - print(f"Guardrail tripped. Info: {e.guardrail_result.output.output_info}") - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/agent_patterns/parallelization.py b/tests/examples/agent_patterns/parallelization.py deleted file mode 100644 index fe2a8ecd..00000000 --- a/tests/examples/agent_patterns/parallelization.py +++ /dev/null @@ -1,61 +0,0 @@ -import asyncio - -from agents import Agent, ItemHelpers, Runner, trace - -""" -This example shows the parallelization pattern. We run the agent three times in parallel, and pick -the best result. -""" - -spanish_agent = Agent( - name="spanish_agent", - instructions="You translate the user's message to Spanish", -) - -translation_picker = Agent( - name="translation_picker", - instructions="You pick the best Spanish translation from the given options.", -) - - -async def main(): - msg = input("Hi! Enter a message, and we'll translate it to Spanish.\n\n") - - # Ensure the entire workflow is a single trace - with trace("Parallel translation"): - res_1, res_2, res_3 = await asyncio.gather( - Runner.run( - spanish_agent, - msg, - ), - Runner.run( - spanish_agent, - msg, - ), - Runner.run( - spanish_agent, - msg, - ), - ) - - outputs = [ - ItemHelpers.text_message_outputs(res_1.new_items), - ItemHelpers.text_message_outputs(res_2.new_items), - ItemHelpers.text_message_outputs(res_3.new_items), - ] - - translations = "\n\n".join(outputs) - print(f"\n\nTranslations:\n\n{translations}") - - best_translation = await Runner.run( - translation_picker, - f"Input: {msg}\n\nTranslations:\n{translations}", - ) - - print("\n\n-----") - - print(f"Best translation: {best_translation.final_output}") - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/agent_patterns/routing.py b/tests/examples/agent_patterns/routing.py deleted file mode 100644 index 3dcaefa9..00000000 --- a/tests/examples/agent_patterns/routing.py +++ /dev/null @@ -1,70 +0,0 @@ -import asyncio -import uuid - -from openai.types.responses import ResponseContentPartDoneEvent, ResponseTextDeltaEvent - -from agents import Agent, RawResponsesStreamEvent, Runner, TResponseInputItem, trace - -""" -This example shows the handoffs/routing pattern. The triage agent receives the first message, and -then hands off to the appropriate agent based on the language of the request. Responses are -streamed to the user. -""" - -french_agent = Agent( - name="french_agent", - instructions="You only speak French", -) - -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=[french_agent, spanish_agent, english_agent], -) - - -async def main(): - # We'll create an ID for this conversation, so we can link each trace - conversation_id = str(uuid.uuid4().hex[:16]) - - msg = input("Hi! We speak French, Spanish and English. How can I help? ") - agent = triage_agent - inputs: list[TResponseInputItem] = [{"content": msg, "role": "user"}] - - while True: - # Each conversation turn is a single trace. Normally, each input from the user would be an - # API request to your app, and you can wrap the request in a trace() - with trace("Routing example", group_id=conversation_id): - result = Runner.run_streamed( - agent, - input=inputs, - ) - async for event in result.stream_events(): - if not isinstance(event, RawResponsesStreamEvent): - continue - data = event.data - if isinstance(data, ResponseTextDeltaEvent): - print(data.delta, end="", flush=True) - elif isinstance(data, ResponseContentPartDoneEvent): - print("\n") - - inputs = result.to_input_list() - print("\n") - - user_msg = input("Enter a message: ") - inputs.append({"content": user_msg, "role": "user"}) - agent = result.current_agent - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/basic/agent_lifecycle_example.py b/tests/examples/basic/agent_lifecycle_example.py deleted file mode 100644 index bc0bbe43..00000000 --- a/tests/examples/basic/agent_lifecycle_example.py +++ /dev/null @@ -1,112 +0,0 @@ -import asyncio -import random -from typing import Any - -from pydantic import BaseModel - -from agents import Agent, AgentHooks, RunContextWrapper, Runner, Tool, function_tool - - -class CustomAgentHooks(AgentHooks): - def __init__(self, display_name: str): - self.event_counter = 0 - self.display_name = display_name - - async def on_start(self, context: RunContextWrapper, agent: Agent) -> None: - self.event_counter += 1 - print(f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} started") - - async def on_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None: - self.event_counter += 1 - print( - f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} ended with output {output}" - ) - - async def on_handoff(self, context: RunContextWrapper, agent: Agent, source: Agent) -> None: - self.event_counter += 1 - print( - f"### ({self.display_name}) {self.event_counter}: Agent {source.name} handed off to {agent.name}" - ) - - async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None: - self.event_counter += 1 - print( - f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} started tool {tool.name}" - ) - - async def on_tool_end( - self, context: RunContextWrapper, agent: Agent, tool: Tool, result: str - ) -> None: - self.event_counter += 1 - print( - f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} ended tool {tool.name} with result {result}" - ) - - -### - - -@function_tool -def random_number(max: int) -> int: - """ - Generate a random number up to the provided maximum. - """ - return random.randint(0, max) - - -@function_tool -def multiply_by_two(x: int) -> int: - """Simple multiplication by two.""" - return x * 2 - - -class FinalResult(BaseModel): - number: int - - -multiply_agent = Agent( - name="Multiply Agent", - instructions="Multiply the number by 2 and then return the final result.", - tools=[multiply_by_two], - output_type=FinalResult, - hooks=CustomAgentHooks(display_name="Multiply Agent"), -) - -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.", - tools=[random_number], - output_type=FinalResult, - handoffs=[multiply_agent], - hooks=CustomAgentHooks(display_name="Start Agent"), -) - - -async def main() -> None: - user_input = input("Enter a max number: ") - await Runner.run( - start_agent, - input=f"Generate a random number between 0 and {user_input}.", - ) - - print("Done!") - - -if __name__ == "__main__": - asyncio.run(main()) -""" -$ python examples/basic/agent_lifecycle_example.py - -Enter a max number: 250 -### (Start Agent) 1: Agent Start Agent started -### (Start Agent) 2: Agent Start Agent started tool random_number -### (Start Agent) 3: Agent Start Agent ended tool random_number with result 37 -### (Start Agent) 4: Agent Start Agent started -### (Start Agent) 5: Agent Start Agent handed off to Multiply Agent -### (Multiply Agent) 1: Agent Multiply Agent started -### (Multiply Agent) 2: Agent Multiply Agent started tool multiply_by_two -### (Multiply Agent) 3: Agent Multiply Agent ended tool multiply_by_two with result 74 -### (Multiply Agent) 4: Agent Multiply Agent started -### (Multiply Agent) 5: Agent Multiply Agent ended with output number=74 -Done! -""" diff --git a/tests/examples/basic/dynamic_system_prompt.py b/tests/examples/basic/dynamic_system_prompt.py deleted file mode 100644 index 7bcf90c0..00000000 --- a/tests/examples/basic/dynamic_system_prompt.py +++ /dev/null @@ -1,69 +0,0 @@ -import asyncio -import random -from typing import Literal - -from agents import Agent, RunContextWrapper, Runner - - -class CustomContext: - def __init__(self, style: Literal["haiku", "pirate", "robot"]): - self.style = style - - -def custom_instructions( - run_context: RunContextWrapper[CustomContext], agent: Agent[CustomContext] -) -> str: - context = run_context.context - if context.style == "haiku": - return "Only respond in haikus." - elif context.style == "pirate": - return "Respond as a pirate." - else: - return "Respond as a robot and say 'beep boop' a lot." - - -agent = Agent( - name="Chat 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") - - user_message = "Tell me a joke." - print(f"User: {user_message}") - result = await Runner.run(agent, user_message, context=context) - - print(f"Assistant: {result.final_output}") - - -if __name__ == "__main__": - asyncio.run(main()) - -""" -$ python examples/basic/dynamic_system_prompt.py - -Using style: haiku - -User: Tell me a joke. -Assistant: Why don't eggs tell jokes? -They might crack each other's shells, -leaving yolk on face. - -$ python examples/basic/dynamic_system_prompt.py -Using style: robot - -User: Tell me a joke. -Assistant: Beep boop! Why was the robot so bad at soccer? Beep boop... because it kept kicking up a debug! Beep boop! - -$ python examples/basic/dynamic_system_prompt.py -Using style: pirate - -User: Tell me a joke. -Assistant: Why did the pirate go to school? - -To improve his arrr-ticulation! Har har har! 🏴‍☠️ -""" diff --git a/tests/examples/basic/hello_world.py b/tests/examples/basic/hello_world.py deleted file mode 100644 index 169290d6..00000000 --- a/tests/examples/basic/hello_world.py +++ /dev/null @@ -1,20 +0,0 @@ -import asyncio - -from agents import Agent, Runner - - -async def main(): - agent = Agent( - name="Assistant", - instructions="You only respond in haikus.", - ) - - result = await Runner.run(agent, "Tell me about recursion in programming.") - print(result.final_output) - # Function calls itself, - # Looping in smaller pieces, - # Endless by design. - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/basic/lifecycle_example.py b/tests/examples/basic/lifecycle_example.py deleted file mode 100644 index 9b365106..00000000 --- a/tests/examples/basic/lifecycle_example.py +++ /dev/null @@ -1,118 +0,0 @@ -import asyncio -import random -from typing import Any - -from pydantic import BaseModel - -from agents import Agent, RunContextWrapper, RunHooks, Runner, Tool, Usage, function_tool - - -class ExampleHooks(RunHooks): - def __init__(self): - self.event_counter = 0 - - def _usage_to_str(self, usage: Usage) -> str: - return f"{usage.requests} requests, {usage.input_tokens} input tokens, {usage.output_tokens} output tokens, {usage.total_tokens} total tokens" - - async def on_agent_start(self, context: RunContextWrapper, agent: Agent) -> None: - self.event_counter += 1 - print( - f"### {self.event_counter}: Agent {agent.name} started. Usage: {self._usage_to_str(context.usage)}" - ) - - async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None: - self.event_counter += 1 - print( - f"### {self.event_counter}: Agent {agent.name} ended with output {output}. Usage: {self._usage_to_str(context.usage)}" - ) - - 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)}" - ) - - async def on_tool_end( - self, context: RunContextWrapper, agent: Agent, tool: Tool, result: str - ) -> None: - self.event_counter += 1 - print( - f"### {self.event_counter}: Tool {tool.name} ended with result {result}. Usage: {self._usage_to_str(context.usage)}" - ) - - async def on_handoff( - self, context: RunContextWrapper, from_agent: Agent, to_agent: Agent - ) -> None: - self.event_counter += 1 - print( - f"### {self.event_counter}: Handoff from {from_agent.name} to {to_agent.name}. Usage: {self._usage_to_str(context.usage)}" - ) - - -hooks = ExampleHooks() - -### - - -@function_tool -def random_number(max: int) -> int: - """Generate a random number up to the provided max.""" - return random.randint(0, max) - - -@function_tool -def multiply_by_two(x: int) -> int: - """Return x times two.""" - return x * 2 - - -class FinalResult(BaseModel): - number: int - - -multiply_agent = Agent( - name="Multiply Agent", - instructions="Multiply the number by 2 and then return the final result.", - tools=[multiply_by_two], - output_type=FinalResult, -) - -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.", - tools=[random_number], - output_type=FinalResult, - handoffs=[multiply_agent], -) - - -async def main() -> None: - user_input = input("Enter a max number: ") - await Runner.run( - start_agent, - hooks=hooks, - input=f"Generate a random number between 0 and {user_input}.", - ) - - print("Done!") - - -if __name__ == "__main__": - asyncio.run(main()) -""" -$ python examples/basic/lifecycle_example.py - -Enter a max number: 250 -### 1: Agent Start Agent started. Usage: 0 requests, 0 input tokens, 0 output tokens, 0 total tokens -### 2: Tool random_number started. Usage: 1 requests, 148 input tokens, 15 output tokens, 163 total tokens -### 3: Tool random_number ended with result 101. Usage: 1 requests, 148 input tokens, 15 output tokens, 163 total tokens -### 4: Agent Start Agent started. Usage: 1 requests, 148 input tokens, 15 output tokens, 163 total tokens -### 5: Handoff from Start Agent to Multiply Agent. Usage: 2 requests, 323 input tokens, 30 output tokens, 353 total tokens -### 6: Agent Multiply Agent started. Usage: 2 requests, 323 input tokens, 30 output tokens, 353 total tokens -### 7: Tool multiply_by_two started. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens -### 8: Tool multiply_by_two ended with result 202. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens -### 9: Agent Multiply Agent started. Usage: 3 requests, 504 input tokens, 46 output tokens, 550 total tokens -### 10: Agent Multiply Agent ended with output number=202. Usage: 4 requests, 714 input tokens, 63 output tokens, 777 total tokens -Done! - -""" diff --git a/tests/examples/basic/stream_items.py b/tests/examples/basic/stream_items.py deleted file mode 100644 index c1f2257a..00000000 --- a/tests/examples/basic/stream_items.py +++ /dev/null @@ -1,65 +0,0 @@ -import asyncio -import random - -from agents import Agent, ItemHelpers, Runner, function_tool - - -@function_tool -def how_many_jokes() -> int: - return random.randint(1, 10) - - -async def main(): - agent = Agent( - name="Joker", - instructions="First call the `how_many_jokes` tool, then tell that many jokes.", - tools=[how_many_jokes], - ) - - result = Runner.run_streamed( - agent, - input="Hello", - ) - print("=== Run starting ===") - async for event in result.stream_events(): - # We'll ignore the raw responses event deltas - if event.type == "raw_response_event": - continue - elif event.type == "agent_updated_stream_event": - print(f"Agent updated: {event.new_agent.name}") - continue - elif event.type == "run_item_stream_event": - if event.item.type == "tool_call_item": - print("-- Tool was called") - elif event.item.type == "tool_call_output_item": - print(f"-- Tool output: {event.item.output}") - elif event.item.type == "message_output_item": - print(f"-- Message output:\n {ItemHelpers.text_message_output(event.item)}") - else: - pass # Ignore other event types - - print("=== Run complete ===") - - -if __name__ == "__main__": - asyncio.run(main()) - - # === Run starting === - # Agent updated: Joker - # -- Tool was called - # -- Tool output: 4 - # -- Message output: - # Sure, here are four jokes for you: - - # 1. **Why don't skeletons fight each other?** - # They don't have the guts! - - # 2. **What do you call fake spaghetti?** - # An impasta! - - # 3. **Why did the scarecrow win an award?** - # Because he was outstanding in his field! - - # 4. **Why did the bicycle fall over?** - # Because it was two-tired! - # === Run complete === diff --git a/tests/examples/basic/stream_text.py b/tests/examples/basic/stream_text.py deleted file mode 100644 index a73c1fee..00000000 --- a/tests/examples/basic/stream_text.py +++ /dev/null @@ -1,21 +0,0 @@ -import asyncio - -from openai.types.responses import ResponseTextDeltaEvent - -from agents import Agent, Runner - - -async def main(): - agent = Agent( - name="Joker", - instructions="You are a helpful assistant.", - ) - - result = Runner.run_streamed(agent, input="Please tell me 5 jokes.") - async for event in result.stream_events(): - if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent): - print(event.data.delta, end="", flush=True) - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/customer_service/main.py b/tests/examples/customer_service/main.py deleted file mode 100644 index bd802e22..00000000 --- a/tests/examples/customer_service/main.py +++ /dev/null @@ -1,169 +0,0 @@ -from __future__ import annotations as _annotations - -import asyncio -import random -import uuid - -from pydantic import BaseModel - -from agents import ( - Agent, - HandoffOutputItem, - ItemHelpers, - MessageOutputItem, - RunContextWrapper, - Runner, - ToolCallItem, - ToolCallOutputItem, - TResponseInputItem, - function_tool, - handoff, - trace, -) -from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX - -### CONTEXT - - -class AirlineAgentContext(BaseModel): - passenger_name: str | None = None - confirmation_number: str | None = None - seat_number: str | None = None - flight_number: str | None = None - - -### TOOLS - - -@function_tool( - name_override="faq_lookup_tool", description_override="Lookup frequently asked questions." -) -async def faq_lookup_tool(question: str) -> str: - if "bag" in question or "baggage" in question: - return ( - "You are allowed to bring one bag on the plane. " - "It must be under 50 pounds and 22 inches x 14 inches x 9 inches." - ) - elif "seats" in question or "plane" in question: - return ( - "There are 120 seats on the plane. " - "There are 22 business class seats and 98 economy seats. " - "Exit rows are rows 4 and 16. " - "Rows 5-8 are Economy Plus, with extra legroom. " - ) - elif "wifi" in question: - return "We have free wifi on the plane, join Airline-Wifi" - return "I'm sorry, I don't know the answer to that question." - - -@function_tool -async def update_seat( - context: RunContextWrapper[AirlineAgentContext], confirmation_number: str, new_seat: str -) -> str: - """ - Update the seat for a given confirmation number. - - Args: - confirmation_number: The confirmation number for the flight. - new_seat: The new seat to update to. - """ - # Update the context based on the customer's input - context.context.confirmation_number = confirmation_number - context.context.seat_number = new_seat - # Ensure that the flight number has been set by the incoming handoff - assert context.context.flight_number is not None, "Flight number is required" - return f"Updated seat to {new_seat} for confirmation number {confirmation_number}" - - -### HOOKS - - -async def on_seat_booking_handoff(context: RunContextWrapper[AirlineAgentContext]) -> None: - flight_number = f"FLT-{random.randint(100, 999)}" - context.context.flight_number = flight_number - - -### AGENTS - -faq_agent = Agent[AirlineAgentContext]( - name="FAQ Agent", - handoff_description="A helpful agent that can answer questions about the airline.", - instructions=f"""{RECOMMENDED_PROMPT_PREFIX} - You are an FAQ agent. If you are speaking to a customer, you probably were transferred to from the triage agent. - Use the following routine to support the customer. - # Routine - 1. Identify the last question asked by the customer. - 2. Use the faq lookup tool to answer the question. Do not rely on your own knowledge. - 3. If you cannot answer the question, transfer back to the triage agent.""", - tools=[faq_lookup_tool], -) - -seat_booking_agent = Agent[AirlineAgentContext]( - name="Seat Booking Agent", - handoff_description="A helpful agent that can update a seat on a flight.", - instructions=f"""{RECOMMENDED_PROMPT_PREFIX} - You are a seat booking agent. If you are speaking to a customer, you probably were transferred to from the triage agent. - Use the following routine to support the customer. - # Routine - 1. Ask for their confirmation number. - 2. Ask the customer what their desired seat number is. - 3. Use the update seat tool to update the seat on the flight. - If the customer asks a question that is not related to the routine, transfer back to the triage agent. """, - tools=[update_seat], -) - -triage_agent = Agent[AirlineAgentContext]( - name="Triage Agent", - handoff_description="A triage agent that can delegate a customer's request to the appropriate agent.", - instructions=( - f"{RECOMMENDED_PROMPT_PREFIX} " - "You are a helpful triaging agent. You can use your tools to delegate questions to other appropriate agents." - ), - handoffs=[ - faq_agent, - handoff(agent=seat_booking_agent, on_handoff=on_seat_booking_handoff), - ], -) - -faq_agent.handoffs.append(triage_agent) -seat_booking_agent.handoffs.append(triage_agent) - - -### RUN - - -async def main(): - current_agent: Agent[AirlineAgentContext] = triage_agent - input_items: list[TResponseInputItem] = [] - context = AirlineAgentContext() - - # Normally, each input from the user would be an API request to your app, and you can wrap the request in a trace() - # Here, we'll just use a random UUID for the conversation ID - conversation_id = uuid.uuid4().hex[:16] - - while True: - user_input = input("Enter your message: ") - with trace("Customer service", group_id=conversation_id): - input_items.append({"content": user_input, "role": "user"}) - result = await Runner.run(current_agent, input_items, context=context) - - for new_item in result.new_items: - agent_name = new_item.agent.name - if isinstance(new_item, MessageOutputItem): - print(f"{agent_name}: {ItemHelpers.text_message_output(new_item)}") - elif isinstance(new_item, HandoffOutputItem): - print( - f"Handed off from {new_item.source_agent.name} to {new_item.target_agent.name}" - ) - elif isinstance(new_item, ToolCallItem): - print(f"{agent_name}: Calling a tool") - elif isinstance(new_item, ToolCallOutputItem): - print(f"{agent_name}: Tool call output: {new_item.output}") - else: - print(f"{agent_name}: Skipping item: {new_item.__class__.__name__}") - input_items = result.to_input_list() - current_agent = result.last_agent - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/handoffs/message_filter.py b/tests/examples/handoffs/message_filter.py deleted file mode 100644 index 9dd56ef7..00000000 --- a/tests/examples/handoffs/message_filter.py +++ /dev/null @@ -1,176 +0,0 @@ -from __future__ import annotations - -import json -import random - -from agents import Agent, HandoffInputData, Runner, function_tool, handoff, trace -from agents.extensions import handoff_filters - - -@function_tool -def random_number_tool(max: int) -> int: - """Return a random integer between 0 and the given maximum.""" - return random.randint(0, max) - - -def spanish_handoff_message_filter(handoff_message_data: HandoffInputData) -> HandoffInputData: - # First, we'll remove any tool-related messages from the message history - handoff_message_data = handoff_filters.remove_all_tools(handoff_message_data) - - # Second, we'll also remove the first two items from the history, just for demonstration - history = ( - tuple(handoff_message_data.input_history[2:]) - if isinstance(handoff_message_data.input_history, tuple) - else handoff_message_data.input_history - ) - - return HandoffInputData( - input_history=history, - pre_handoff_items=tuple(handoff_message_data.pre_handoff_items), - new_items=tuple(handoff_message_data.new_items), - ) - - -first_agent = Agent( - name="Assistant", - instructions="Be extremely concise.", - tools=[random_number_tool], -) - -spanish_agent = Agent( - name="Spanish Assistant", - instructions="You only speak Spanish and are extremely concise.", - handoff_description="A Spanish-speaking assistant.", -) - -second_agent = Agent( - name="Assistant", - instructions=( - "Be a helpful assistant. If the user speaks Spanish, handoff to the Spanish assistant." - ), - handoffs=[handoff(spanish_agent, input_filter=spanish_handoff_message_filter)], -) - - -async def main(): - # Trace the entire run as a single workflow - with trace(workflow_name="Message filtering"): - # 1. Send a regular message to the first agent - result = await Runner.run(first_agent, input="Hi, my name is Sora.") - - print("Step 1 done") - - # 2. Ask it to square a number - result = await Runner.run( - second_agent, - input=result.to_input_list() - + [{"content": "Can you generate a random number between 0 and 100?", "role": "user"}], - ) - - print("Step 2 done") - - # 3. Call the second agent - result = await Runner.run( - second_agent, - input=result.to_input_list() - + [ - { - "content": "I live in New York City. Whats the population of the city?", - "role": "user", - } - ], - ) - - print("Step 3 done") - - # 4. Cause a handoff to occur - result = await Runner.run( - second_agent, - input=result.to_input_list() - + [ - { - "content": "Por favor habla en español. ¿Cuál es mi nombre y dónde vivo?", - "role": "user", - } - ], - ) - - print("Step 4 done") - - print("\n===Final messages===\n") - - # 5. That should have caused spanish_handoff_message_filter to be called, which means the - # output should be missing the first two messages, and have no tool calls. - # Let's print the messages to see what happened - for message in result.to_input_list(): - print(json.dumps(message, indent=2)) - # tool_calls = message.tool_calls if isinstance(message, AssistantMessage) else None - - # print(f"{message.role}: {message.content}\n - Tool calls: {tool_calls or 'None'}") - """ - $python examples/handoffs/message_filter.py - Step 1 done - Step 2 done - Step 3 done - Step 4 done - - ===Final messages=== - - { - "content": "Can you generate a random number between 0 and 100?", - "role": "user" - } - { - "id": "...", - "content": [ - { - "annotations": [], - "text": "Sure! Here's a random number between 0 and 100: **42**.", - "type": "output_text" - } - ], - "role": "assistant", - "status": "completed", - "type": "message" - } - { - "content": "I live in New York City. Whats the population of the city?", - "role": "user" - } - { - "id": "...", - "content": [ - { - "annotations": [], - "text": "As of the most recent estimates, the population of New York City is approximately 8.6 million people. However, this number is constantly changing due to various factors such as migration and birth rates. For the latest and most accurate information, it's always a good idea to check the official data from sources like the U.S. Census Bureau.", - "type": "output_text" - } - ], - "role": "assistant", - "status": "completed", - "type": "message" - } - { - "content": "Por favor habla en espa\u00f1ol. \u00bfCu\u00e1l es mi nombre y d\u00f3nde vivo?", - "role": "user" - } - { - "id": "...", - "content": [ - { - "annotations": [], - "text": "No tengo acceso a esa informaci\u00f3n personal, solo s\u00e9 lo que me has contado: vives en Nueva York.", - "type": "output_text" - } - ], - "role": "assistant", - "status": "completed", - "type": "message" - } - """ - - -if __name__ == "__main__": - import asyncio - - asyncio.run(main()) diff --git a/tests/examples/handoffs/message_filter_streaming.py b/tests/examples/handoffs/message_filter_streaming.py deleted file mode 100644 index 8d1b4208..00000000 --- a/tests/examples/handoffs/message_filter_streaming.py +++ /dev/null @@ -1,176 +0,0 @@ -from __future__ import annotations - -import json -import random - -from agents import Agent, HandoffInputData, Runner, function_tool, handoff, trace -from agents.extensions import handoff_filters - - -@function_tool -def random_number_tool(max: int) -> int: - """Return a random integer between 0 and the given maximum.""" - return random.randint(0, max) - - -def spanish_handoff_message_filter(handoff_message_data: HandoffInputData) -> HandoffInputData: - # First, we'll remove any tool-related messages from the message history - handoff_message_data = handoff_filters.remove_all_tools(handoff_message_data) - - # Second, we'll also remove the first two items from the history, just for demonstration - history = ( - tuple(handoff_message_data.input_history[2:]) - if isinstance(handoff_message_data.input_history, tuple) - else handoff_message_data.input_history - ) - - return HandoffInputData( - input_history=history, - pre_handoff_items=tuple(handoff_message_data.pre_handoff_items), - new_items=tuple(handoff_message_data.new_items), - ) - - -first_agent = Agent( - name="Assistant", - instructions="Be extremely concise.", - tools=[random_number_tool], -) - -spanish_agent = Agent( - name="Spanish Assistant", - instructions="You only speak Spanish and are extremely concise.", - handoff_description="A Spanish-speaking assistant.", -) - -second_agent = Agent( - name="Assistant", - instructions=( - "Be a helpful assistant. If the user speaks Spanish, handoff to the Spanish assistant." - ), - handoffs=[handoff(spanish_agent, input_filter=spanish_handoff_message_filter)], -) - - -async def main(): - # Trace the entire run as a single workflow - with trace(workflow_name="Streaming message filter"): - # 1. Send a regular message to the first agent - result = await Runner.run(first_agent, input="Hi, my name is Sora.") - - print("Step 1 done") - - # 2. Ask it to square a number - result = await Runner.run( - second_agent, - input=result.to_input_list() - + [{"content": "Can you generate a random number between 0 and 100?", "role": "user"}], - ) - - print("Step 2 done") - - # 3. Call the second agent - result = await Runner.run( - second_agent, - input=result.to_input_list() - + [ - { - "content": "I live in New York City. Whats the population of the city?", - "role": "user", - } - ], - ) - - print("Step 3 done") - - # 4. Cause a handoff to occur - stream_result = Runner.run_streamed( - second_agent, - input=result.to_input_list() - + [ - { - "content": "Por favor habla en español. ¿Cuál es mi nombre y dónde vivo?", - "role": "user", - } - ], - ) - async for _ in stream_result.stream_events(): - pass - - print("Step 4 done") - - print("\n===Final messages===\n") - - # 5. That should have caused spanish_handoff_message_filter to be called, which means the - # output should be missing the first two messages, and have no tool calls. - # Let's print the messages to see what happened - for item in stream_result.to_input_list(): - print(json.dumps(item, indent=2)) - """ - $python examples/handoffs/message_filter_streaming.py - Step 1 done - Step 2 done - Step 3 done - Tu nombre y lugar de residencia no los tengo disponibles. Solo sé que mencionaste vivir en la ciudad de Nueva York. - Step 4 done - - ===Final messages=== - - { - "content": "Can you generate a random number between 0 and 100?", - "role": "user" - } - { - "id": "...", - "content": [ - { - "annotations": [], - "text": "Sure! Here's a random number between 0 and 100: **37**.", - "type": "output_text" - } - ], - "role": "assistant", - "status": "completed", - "type": "message" - } - { - "content": "I live in New York City. Whats the population of the city?", - "role": "user" - } - { - "id": "...", - "content": [ - { - "annotations": [], - "text": "As of the latest estimates, New York City's population is approximately 8.5 million people. Would you like more information about the city?", - "type": "output_text" - } - ], - "role": "assistant", - "status": "completed", - "type": "message" - } - { - "content": "Por favor habla en espa\u00f1ol. \u00bfCu\u00e1l es mi nombre y d\u00f3nde vivo?", - "role": "user" - } - { - "id": "...", - "content": [ - { - "annotations": [], - "text": "No s\u00e9 tu nombre, pero me dijiste que vives en Nueva York.", - "type": "output_text" - } - ], - "role": "assistant", - "status": "completed", - "type": "message" - } - """ - - -if __name__ == "__main__": - import asyncio - - asyncio.run(main()) diff --git a/tests/examples/research_bot/README.md b/tests/examples/research_bot/README.md deleted file mode 100644 index 4060983c..00000000 --- a/tests/examples/research_bot/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Research bot - -This is a simple example of a multi-agent research bot. To run it: - -```bash -python -m examples.research_bot.main -``` - -## Architecture - -The flow is: - -1. User enters their research topic -2. `planner_agent` comes up with a plan to search the web for information. The plan is a list of search queries, with a search term and a reason for each query. -3. For each search item, we run a `search_agent`, which uses the Web Search tool to search for that term and summarize the results. These all run in parallel. -4. Finally, the `writer_agent` receives the search summaries, and creates a written report. - -## Suggested improvements - -If you're building your own research bot, some ideas to add to this are: - -1. Retrieval: Add support for fetching relevant information from a vector store. You could use the File Search tool for this. -2. Image and file upload: Allow users to attach PDFs or other files, as baseline context for the research. -3. More planning and thinking: Models often produce better results given more time to think. Improve the planning process to come up with a better plan, and add an evaluation step so that the model can choose to improve it's results, search for more stuff, etc. -4. Code execution: Allow running code, which is useful for data analysis. diff --git a/tests/examples/research_bot/__init__.py b/tests/examples/research_bot/__init__.py deleted file mode 100644 index 8b137891..00000000 --- a/tests/examples/research_bot/__init__.py +++ /dev/null @@ -1 +0,0 @@ - diff --git a/tests/examples/research_bot/agents/__init__.py b/tests/examples/research_bot/agents/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/tests/examples/research_bot/agents/planner_agent.py b/tests/examples/research_bot/agents/planner_agent.py deleted file mode 100644 index e80a8e65..00000000 --- a/tests/examples/research_bot/agents/planner_agent.py +++ /dev/null @@ -1,29 +0,0 @@ -from pydantic import BaseModel - -from agents import Agent - -PROMPT = ( - "You are a helpful research assistant. Given a query, come up with a set of web searches " - "to perform to best answer the query. Output between 5 and 20 terms to query for." -) - - -class WebSearchItem(BaseModel): - reason: str - "Your reasoning for why this search is important to the query." - - query: str - "The search term to use for the web search." - - -class WebSearchPlan(BaseModel): - searches: list[WebSearchItem] - """A list of web searches to perform to best answer the query.""" - - -planner_agent = Agent( - name="PlannerAgent", - instructions=PROMPT, - model="gpt-4o", - output_type=WebSearchPlan, -) diff --git a/tests/examples/research_bot/agents/search_agent.py b/tests/examples/research_bot/agents/search_agent.py deleted file mode 100644 index 72cbc8e1..00000000 --- a/tests/examples/research_bot/agents/search_agent.py +++ /dev/null @@ -1,18 +0,0 @@ -from agents import Agent, WebSearchTool -from agents.model_settings import ModelSettings - -INSTRUCTIONS = ( - "You are a research assistant. Given a search term, you search the web for that term and" - "produce a concise summary of the results. The summary must 2-3 paragraphs and less than 300" - "words. Capture the main points. Write succintly, no need to have complete sentences or good" - "grammar. This will be consumed by someone synthesizing a report, so its vital you capture the" - "essence and ignore any fluff. Do not include any additional commentary other than the summary" - "itself." -) - -search_agent = Agent( - name="Search agent", - instructions=INSTRUCTIONS, - tools=[WebSearchTool()], - model_settings=ModelSettings(tool_choice="required"), -) diff --git a/tests/examples/research_bot/agents/writer_agent.py b/tests/examples/research_bot/agents/writer_agent.py deleted file mode 100644 index 7b7d01a2..00000000 --- a/tests/examples/research_bot/agents/writer_agent.py +++ /dev/null @@ -1,33 +0,0 @@ -# Agent used to synthesize a final report from the individual summaries. -from pydantic import BaseModel - -from agents import Agent - -PROMPT = ( - "You are a senior researcher tasked with writing a cohesive report for a research query. " - "You will be provided with the original query, and some initial research done by a research " - "assistant.\n" - "You should first come up with an outline for the report that describes the structure and " - "flow of the report. Then, generate the report and return that as your final output.\n" - "The final output should be in markdown format, and it should be lengthy and detailed. Aim " - "for 5-10 pages of content, at least 1000 words." -) - - -class ReportData(BaseModel): - short_summary: str - """A short 2-3 sentence summary of the findings.""" - - markdown_report: str - """The final report""" - - follow_up_questions: list[str] - """Suggested topics to research further""" - - -writer_agent = Agent( - name="WriterAgent", - instructions=PROMPT, - model="o3-mini", - output_type=ReportData, -) diff --git a/tests/examples/research_bot/main.py b/tests/examples/research_bot/main.py deleted file mode 100644 index a0fd43dc..00000000 --- a/tests/examples/research_bot/main.py +++ /dev/null @@ -1,12 +0,0 @@ -import asyncio - -from .manager import ResearchManager - - -async def main() -> None: - query = input("What would you like to research? ") - await ResearchManager().run(query) - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/research_bot/manager.py b/tests/examples/research_bot/manager.py deleted file mode 100644 index 47306f14..00000000 --- a/tests/examples/research_bot/manager.py +++ /dev/null @@ -1,119 +0,0 @@ -from __future__ import annotations - -import asyncio -import time - -from rich.console import Console - -from agents import Runner, custom_span, gen_trace_id, trace - -from .agents.planner_agent import WebSearchItem, WebSearchPlan, planner_agent -from .agents.search_agent import search_agent -from .agents.writer_agent import ReportData, writer_agent -from .printer import Printer - - -class ResearchManager: - def __init__(self): - self.console = Console() - self.printer = Printer(self.console) - - async def run(self, query: str) -> None: - trace_id = gen_trace_id() - with trace("Research trace", trace_id=trace_id): - self.printer.update_item( - "trace_id", - f"View trace: https://platform.openai.com/traces/{trace_id}", - is_done=True, - hide_checkmark=True, - ) - - self.printer.update_item( - "starting", - "Starting research...", - is_done=True, - hide_checkmark=True, - ) - search_plan = await self._plan_searches(query) - search_results = await self._perform_searches(search_plan) - report = await self._write_report(query, search_results) - - final_report = f"Report summary\n\n{report.short_summary}" - self.printer.update_item("final_report", final_report, is_done=True) - - self.printer.end() - - print("\n\n=====REPORT=====\n\n") - print(f"Report: {report.markdown_report}") - print("\n\n=====FOLLOW UP QUESTIONS=====\n\n") - follow_up_questions = "\n".join(report.follow_up_questions) - print(f"Follow up questions: {follow_up_questions}") - - async def _plan_searches(self, query: str) -> WebSearchPlan: - self.printer.update_item("planning", "Planning searches...") - result = await Runner.run( - planner_agent, - f"Query: {query}", - ) - self.printer.update_item( - "planning", - f"Will perform {len(result.final_output.searches)} searches", - is_done=True, - ) - return result.final_output_as(WebSearchPlan) - - async def _perform_searches(self, search_plan: WebSearchPlan) -> list[str]: - with custom_span("Search the web"): - self.printer.update_item("searching", "Searching...") - num_completed = 0 - tasks = [asyncio.create_task(self._search(item)) for item in search_plan.searches] - results = [] - for task in asyncio.as_completed(tasks): - result = await task - if result is not None: - results.append(result) - num_completed += 1 - self.printer.update_item( - "searching", f"Searching... {num_completed}/{len(tasks)} completed" - ) - self.printer.mark_item_done("searching") - return results - - async def _search(self, item: WebSearchItem) -> str | None: - input = f"Search term: {item.query}\nReason for searching: {item.reason}" - try: - result = await Runner.run( - search_agent, - input, - ) - return str(result.final_output) - except Exception: - return None - - async def _write_report(self, query: str, search_results: list[str]) -> ReportData: - self.printer.update_item("writing", "Thinking about report...") - input = f"Original query: {query}\nSummarized search results: {search_results}" - result = Runner.run_streamed( - writer_agent, - input, - ) - update_messages = [ - "Thinking about report...", - "Planning report structure...", - "Writing outline...", - "Creating sections...", - "Cleaning up formatting...", - "Finalizing report...", - "Finishing report...", - ] - - last_update = time.time() - next_message = 0 - async for _ in result.stream_events(): - if time.time() - last_update > 5 and next_message < len(update_messages): - self.printer.update_item("writing", update_messages[next_message]) - next_message += 1 - last_update = time.time() - - self.printer.mark_item_done("writing") - return result.final_output_as(ReportData) diff --git a/tests/examples/research_bot/printer.py b/tests/examples/research_bot/printer.py deleted file mode 100644 index e820c753..00000000 --- a/tests/examples/research_bot/printer.py +++ /dev/null @@ -1,41 +0,0 @@ -from typing import Any - -from rich.console import Console, Group -from rich.live import Live -from rich.spinner import Spinner - - -class Printer: - def __init__(self, console: Console): - self.live = Live(console=console) - self.items: dict[str, tuple[str, bool]] = {} - self.hide_done_ids: set[str] = set() - self.live.start() - - def end(self) -> None: - self.live.stop() - - def hide_done_checkmark(self, item_id: str) -> None: - self.hide_done_ids.add(item_id) - - def update_item( - self, item_id: str, content: str, is_done: bool = False, hide_checkmark: bool = False - ) -> None: - self.items[item_id] = (content, is_done) - if hide_checkmark: - self.hide_done_ids.add(item_id) - self.flush() - - def mark_item_done(self, item_id: str) -> None: - self.items[item_id] = (self.items[item_id][0], True) - self.flush() - - def flush(self) -> None: - renderables: list[Any] = [] - for item_id, (content, is_done) in self.items.items(): - if is_done: - prefix = "✅ " if item_id not in self.hide_done_ids else "" - renderables.append(prefix + content) - else: - renderables.append(Spinner("dots", text=content)) - self.live.update(Group(*renderables)) diff --git a/tests/examples/research_bot/sample_outputs/product_recs.md b/tests/examples/research_bot/sample_outputs/product_recs.md deleted file mode 100644 index 70789eb3..00000000 --- a/tests/examples/research_bot/sample_outputs/product_recs.md +++ /dev/null @@ -1,180 +0,0 @@ -# Comprehensive Guide on Best Surfboards for Beginners: Transitioning, Features, and Budget Options - -Surfing is not only a sport but a lifestyle that hooks its enthusiasts with the allure of riding waves and connecting with nature. For beginners, selecting the right surfboard is critical to safety, learning, and performance. This comprehensive guide has been crafted to walk through the essential aspects of choosing the ideal surfboard for beginners, especially those looking to transition from an 11-foot longboard to a shorter, more dynamic board. We discuss various board types, materials, design elements, and budget ranges, providing a detailed road map for both new surfers and those in the process of progression. - ---- - -## Table of Contents - -1. [Introduction](#introduction) -2. [Board Types and Design Considerations](#board-types-and-design-considerations) -3. [Key Board Dimensions and Features](#key-board-dimensions-and-features) -4. [Materials: Soft-Top vs. Hard-Top Boards](#materials-soft-top-vs-hard-top-boards) -5. [Tips for Transitioning from Longboards to Shorter Boards](#tips-for-transitioning-from-longboards-to-shorter-boards) -6. [Budget and Pricing Options](#budget-and-pricing-options) -7. [Recommended Models and Buying Options](#recommended-models-and-buying-options) -8. [Conclusion](#conclusion) -9. [Follow-up Questions](#follow-up-questions) - ---- - -## Introduction - -Surfing is a dynamic sport that requires not only skill and technique but also the proper equipment. For beginners, the right surfboard can make the difference between a frustrating experience and one that builds confidence and enthusiasm. Many newcomers start with longboards due to their stability and ease of paddling; however, as skills develop, transitioning to a shorter board might be desirable for enhancing maneuverability and performance. This guide is designed for surfers who can already catch waves on an 11-foot board and are now considering stepping down to a more versatile option. - -The overarching goal of this document is to help beginners identify which surfboard characteristics are most important, including board length, width, thickness, volume, and materials, while also considering factors like weight distribution, buoyancy, and control. We will also take a look at board types that are particularly welcoming for beginners and discuss gradual transitioning strategies. - ---- - -## Board Types and Design Considerations - -Choosing a board involves understanding the variety of designs available. Below are the main types of surfboards that cater to beginners and transitional surfers: - -### Longboards and Mini-Mals - -Longboards, typically 8 to 11 feet in length, provide ample stability, smoother paddling, and are well-suited for wave-catching. Their generous volume and width allow beginners to build confidence when standing up and riding waves. Mini-mal or mini-malibus (often around 8 to 9 feet) are a popular bridge between the longboard and the more agile shortboard, offering both stability and moderate maneuverability, which makes them excellent for gradual progress. - -### Funboards and Hybrids - -Funboards and hybrid boards blend the benefits of longboards and shortboards. They typically range from 6’6" to 8’0" in length, with extra volume and width that help preserve stability while introducing elements of sharper turning and improved agility. Hybrids are particularly helpful for surfers transitioning from longboards, as they maintain some of the buoyancy and ease of catching waves, yet offer a taste of the performance found in smaller boards. - -### Shortboards - -Shortboards emphasize performance, maneuverability, and a more responsive ride. However, they have less volume and require stronger paddling, quicker pop-up techniques, and more refined balance. For beginners, moving to a traditional shortboard immediately can be challenging. It is generally advised to make a gradual transition, potentially starting with a funboard or hybrid before making a direct leap to a performance shortboard. - ---- - -## Key Board Dimensions and Features - -When selecting a beginner surfboard, several key dimensions and features drastically affect performance, ease of learning, and safety: - -### Length and Width - -- **Length**: Starting with an 8 to 9-foot board is ideal. Longer boards offer enhanced stability and improved paddling capabilities. Gradual downsizing is recommended if you plan to move from an 11-foot board. -- **Width**: A board with a width over 20 inches provides greater stability and facilitates balance, especially vital for beginners. - -### Thickness and Volume - -- **Thickness**: Typically around 2.5 to 3 inches. Thicker decks increase buoyancy, allowing the surfer to paddle easier while catching waves. -- **Volume**: Measured in liters, volume is critical in understanding a board's flotation capacity. Higher volumes (e.g., 60-100 liters) are essential for beginners as they make the board more forgiving and stable. Suitable volumes might vary according to the surfer’s weight and experience level. - -### Nose and Tail Shape - -- **Nose Shape**: A wide, rounded nose expands the board’s planing surface, which can help in catching waves sooner and maintaining stability as you ride. -- **Tail Design**: Square or rounded tails are generally recommended as they enhance stability and allow for controlled turns, essential during the learning phase. - -### Rocker - -- **Rocker**: This is the curvature of the board from nose to tail. For beginners, a minimal or relaxed rocker provides better stability and ease during paddling. A steeper rocker might be introduced progressively as the surfer’s skills improve. - ---- - -## Materials: Soft-Top vs. Hard-Top Boards - -The material composition of a surfboard is a crucial factor in determining its performance, durability, and safety. Beginners have two primary choices: - -### Soft-Top (Foam) Boards - -Soft-top boards are constructed almost entirely from foam. Their attributes include: - -- **Safety and Forgiveness**: The foam construction minimizes injury upon impact which is advantageous for beginners who might fall frequently. -- **Stability and Buoyancy**: These boards typically offer greater buoyancy due to their softer material and thicker construction, easing the initial learning process. -- **Maintenance**: They often require less maintenance—there is typically no need for waxing and they are more resistant to dings and scratches. - -However, as a surfer’s skills progress, a soft-top might limit maneuverability and overall performance. - -### Hard-Top Boards - -Hard-tops, in contrast, offer a more traditional surfboard feel. They generally rely on a foam core encased in resin, with two prevalent combinations: - -- **PU (Polyurethane) Core with Polyester Resin**: This combination gives a classic feel and is relatively economical; however, these boards can be heavier and, as they age, more prone to damage. -- **EPS (Expanded Polystyrene) Core with Epoxy Resin**: Lightweight and durable, EPS boards are often more buoyant and resistant to damage, although they usually carry a higher price tag and may be less forgiving. - -Deciding between soft-top and hard-top boards often depends on a beginner’s progression goals, overall comfort, and budget constraints. - ---- - -## Tips for Transitioning from Longboards to Shorter Boards - -For surfers who have mastered the basics on an 11-foot board, the transition to a shorter board requires careful consideration, patience, and incremental changes. Here are some key tips: - -### Gradual Downsizing - -Experts recommend reducing the board length gradually—by about a foot at a time—to allow the body to adjust slowly to a board with less buoyancy and more responsiveness. This process helps maintain wave-catching ability and reduces the shock of transitioning to a very different board feel. - -### Strengthening Core Skills - -Before transitioning, make sure your surfing fundamentals are solid. Focus on practicing: - -- **Steep Take-offs**: Ensure that your pop-up is swift and robust to keep pace with shorter boards that demand a rapid transition from paddling to standing. -- **Angling and Paddling Techniques**: Learn to angle your takeoffs properly to compensate for the lower buoyancy and increased maneuverability of shorter boards. - -### Experimenting with Rentals or Borrowed Boards - -If possible, try out a friend’s shorter board or rent one for a day to experience firsthand the differences in performance. This practical trial can provide valuable insights and inform your decision before making a purchase. - ---- - -## Budget and Pricing Options - -Surfboards are available across a range of prices to match different budgets. Whether you are looking for an affordable beginner board or a more expensive model that grows with your skills, it’s important to understand what features you can expect at different price points. - -### Budget-Friendly Options - -For those on a tight budget, several entry-level models offer excellent value. Examples include: - -- **Wavestorm 8' Classic Pinline Surfboard**: Priced affordably, this board is popular for its ease of use, ample volume, and forgiving nature. Despite its low cost, it delivers the stability needed to get started. -- **Liquid Shredder EZ Slider Foamie**: A smaller board catering to younger or lighter surfers, this budget option provides easy paddling and a minimal risk of injury due to its soft construction. - -### Moderate Price Range - -As you move into the intermediate range, boards typically become slightly more specialized in their design, offering features such as improved stringer systems or versatile fin setups. These are excellent for surfers who wish to continue progressing their skills without compromising stability. Many surfboard packages from retailers also bundle a board with essential accessories like board bags, leashes, and wax for additional savings. - -### Higher-End Models and Transitional Packages - -For surfers looking for durability, performance, and advanced design features, investing in an EPS/epoxy board might be ideal. Although they come at a premium, these boards are lightweight, strong, and customizable with various fin configurations. Some options include boards from brands like South Bay Board Co. and ISLE, which combine high-quality construction with beginner-friendly features that help mediate the transition from longboard to shortboard performance. - ---- - -## Recommended Models and Buying Options - -Based on extensive research and community recommendations, here are some standout models and tips on where to buy: - -### Recommended Models - -- **South Bay Board Co. 8'8" Heritage**: Combining foam and resin construction, this board is ideal for beginners who need stability and a forgiving surface. Its 86-liter volume suits both lightweight and somewhat heavier surfers. -- **Rock-It 8' Big Softy**: With a high volume and an easy paddling profile, this board is designed for beginners, offering ample buoyancy to smooth out the learning curve. -- **Wave Bandit EZ Rider Series**: Available in multiple lengths (7', 8', 9'), these boards offer versatility, with construction features that balance the stability of longboards and the agility required for shorter boards. -- **Hybrid/Funboards Like the Poacher Funboard**: Perfect for transitioning surfers, these boards blend the ease of catching waves with the capability for more dynamic maneuvers. - -### Buying Options - -- **Surf Shops and Local Retailers**: Traditional surf shops allow you to test different boards, which is ideal for assessing the board feel and condition—especially if you are considering a used board. -- **Online Retailers and Marketplaces**: Websites like Evo, Surfboards Direct, and even local online marketplaces like Craigslist and Facebook Marketplace provide options that range from new to gently used boards. Always inspect reviews and verify seller policies before purchase. -- **Package Deals and Bundles**: Many retailers offer bundled packages that include not just the board, but also essentials like a leash, wax, fins, and board bags. These packages can be more cost-effective and are great for beginners who need a complete surf kit. - ---- - -## Conclusion - -Selecting the right surfboard as a beginner is about balancing various factors: stability, buoyancy, maneuverability, and budget. - -For those who have honed the basics using an 11-foot longboard, the transition to a shorter board should be gradual. Start by focusing on boards that preserve stability—such as funboards and hybrids—before moving to the more performance-oriented shortboards. Key characteristics like board length, width, thickness, volume, and material profoundly influence your surfing experience. Soft-top boards provide a forgiving entry point, while hard-top boards, especially those with EPS cores and epoxy resin, offer benefits for more advanced progression despite the increased learning curve. - -Emphasizing fundamentals like proper pop-up technique and effective paddle work will ease the transition and ensure that the new board complements your evolving skills. Additionally, understanding the pricing spectrum—from budget-friendly models to premium options—allows you to make an informed purchase that suits both your financial and performance needs. - -With a thoughtful approach to board selection, you can enhance your learning curve, enjoy safer sessions in the water, and ultimately develop the skills necessary to master the diverse challenges surfing presents. Whether your goal is to ride gentle waves or eventually experiment with sharper turns and dynamic maneuvers, choosing the right board is your first step towards a rewarding and sustainable surfing journey. - ---- - -## Follow-up Questions - -1. What is your current budget range for a new surfboard, or are you considering buying used? -2. How frequently do you plan to surf, and in what type of wave conditions? -3. Are you interested in a board that you can grow into as your skills progress, or do you prefer one that is more specialized for certain conditions? -4. Would you be interested in additional equipment bundles (like fins, leashes, boards bags) offered by local retailers or online shops? -5. Have you had the opportunity to test ride any boards before, and what feedback did you gather from that experience? - ---- - -With this detailed guide, beginners should now have a comprehensive understanding of the surfboard market and the key factors influencing board performance, safety, and ease of progression. Happy surfing, and may you find the perfect board that rides the waves as beautifully as your passion for the sport! diff --git a/tests/examples/research_bot/sample_outputs/product_recs.txt b/tests/examples/research_bot/sample_outputs/product_recs.txt deleted file mode 100644 index 78865f23..00000000 --- a/tests/examples/research_bot/sample_outputs/product_recs.txt +++ /dev/null @@ -1,212 +0,0 @@ -# Terminal output for a product recommendation related query. See product_recs.md for final report. - -$ uv run python -m examples.research_bot.main - -What would you like to research? Best surfboards for beginners. I can catch my own waves, but previously used an 11ft board. What should I look for, what are my options? Various budget ranges. -View trace: https://platform.openai.com/traces/trace_... -Starting research... -✅ Will perform 15 searches -✅ Searching... 15/15 completed -✅ Finishing report... -✅ Report summary - -This report provides a detailed guide on selecting the best surfboards for beginners, especially for those transitioning from an 11-foot longboard to a -shorter board. It covers design considerations such as board dimensions, shape, materials, and volume, while comparing soft-top and hard-top boards. In -addition, the report discusses various budget ranges, recommended board models, buying options (both new and used), and techniques to ease the transition to -more maneuverable boards. By understanding these factors, beginner surfers can select a board that not only enhances their skills but also suits their -individual needs. - - -=====REPORT===== - - -Report: # Comprehensive Guide on Best Surfboards for Beginners: Transitioning, Features, and Budget Options - -Surfing is not only a sport but a lifestyle that hooks its enthusiasts with the allure of riding waves and connecting with nature. For beginners, selecting the right surfboard is critical to safety, learning, and performance. This comprehensive guide has been crafted to walk through the essential aspects of choosing the ideal surfboard for beginners, especially those looking to transition from an 11-foot longboard to a shorter, more dynamic board. We discuss various board types, materials, design elements, and budget ranges, providing a detailed road map for both new surfers and those in the process of progression. - ---- - -## Table of Contents - -1. [Introduction](#introduction) -2. [Board Types and Design Considerations](#board-types-and-design-considerations) -3. [Key Board Dimensions and Features](#key-board-dimensions-and-features) -4. [Materials: Soft-Top vs. Hard-Top Boards](#materials-soft-top-vs-hard-top-boards) -5. [Tips for Transitioning from Longboards to Shorter Boards](#tips-for-transitioning-from-longboards-to-shorter-boards) -6. [Budget and Pricing Options](#budget-and-pricing-options) -7. [Recommended Models and Buying Options](#recommended-models-and-buying-options) -8. [Conclusion](#conclusion) -9. [Follow-up Questions](#follow-up-questions) - ---- - -## Introduction - -Surfing is a dynamic sport that requires not only skill and technique but also the proper equipment. For beginners, the right surfboard can make the difference between a frustrating experience and one that builds confidence and enthusiasm. Many newcomers start with longboards due to their stability and ease of paddling; however, as skills develop, transitioning to a shorter board might be desirable for enhancing maneuverability and performance. This guide is designed for surfers who can already catch waves on an 11-foot board and are now considering stepping down to a more versatile option. - -The overarching goal of this document is to help beginners identify which surfboard characteristics are most important, including board length, width, thickness, volume, and materials, while also considering factors like weight distribution, buoyancy, and control. We will also take a look at board types that are particularly welcoming for beginners and discuss gradual transitioning strategies. - ---- - -## Board Types and Design Considerations - -Choosing a board involves understanding the variety of designs available. Below are the main types of surfboards that cater to beginners and transitional surfers: - -### Longboards and Mini-Mals - -Longboards, typically 8 to 11 feet in length, provide ample stability, smoother paddling, and are well-suited for wave-catching. Their generous volume and width allow beginners to build confidence when standing up and riding waves. Mini-mal or mini-malibus (often around 8 to 9 feet) are a popular bridge between the longboard and the more agile shortboard, offering both stability and moderate maneuverability, which makes them excellent for gradual progress. - -### Funboards and Hybrids - -Funboards and hybrid boards blend the benefits of longboards and shortboards. They typically range from 6’6" to 8’0" in length, with extra volume and width that help preserve stability while introducing elements of sharper turning and improved agility. Hybrids are particularly helpful for surfers transitioning from longboards, as they maintain some of the buoyancy and ease of catching waves, yet offer a taste of the performance found in smaller boards. - -### Shortboards - -Shortboards emphasize performance, maneuverability, and a more responsive ride. However, they have less volume and require stronger paddling, quicker pop-up techniques, and more refined balance. For beginners, moving to a traditional shortboard immediately can be challenging. It is generally advised to make a gradual transition, potentially starting with a funboard or hybrid before making a direct leap to a performance shortboard. - ---- - -## Key Board Dimensions and Features - -When selecting a beginner surfboard, several key dimensions and features drastically affect performance, ease of learning, and safety: - -### Length and Width - -- **Length**: Starting with an 8 to 9-foot board is ideal. Longer boards offer enhanced stability and improved paddling capabilities. Gradual downsizing is recommended if you plan to move from an 11-foot board. -- **Width**: A board with a width over 20 inches provides greater stability and facilitates balance, especially vital for beginners. - -### Thickness and Volume - -- **Thickness**: Typically around 2.5 to 3 inches. Thicker decks increase buoyancy, allowing the surfer to paddle easier while catching waves. -- **Volume**: Measured in liters, volume is critical in understanding a board's flotation capacity. Higher volumes (e.g., 60-100 liters) are essential for beginners as they make the board more forgiving and stable. Suitable volumes might vary according to the surfer’s weight and experience level. - -### Nose and Tail Shape - -- **Nose Shape**: A wide, rounded nose expands the board’s planing surface, which can help in catching waves sooner and maintaining stability as you ride. -- **Tail Design**: Square or rounded tails are generally recommended as they enhance stability and allow for controlled turns, essential during the learning phase. - -### Rocker - -- **Rocker**: This is the curvature of the board from nose to tail. For beginners, a minimal or relaxed rocker provides better stability and ease during paddling. A steeper rocker might be introduced progressively as the surfer’s skills improve. - ---- - -## Materials: Soft-Top vs. Hard-Top Boards - -The material composition of a surfboard is a crucial factor in determining its performance, durability, and safety. Beginners have two primary choices: - -### Soft-Top (Foam) Boards - -Soft-top boards are constructed almost entirely from foam. Their attributes include: - -- **Safety and Forgiveness**: The foam construction minimizes injury upon impact which is advantageous for beginners who might fall frequently. -- **Stability and Buoyancy**: These boards typically offer greater buoyancy due to their softer material and thicker construction, easing the initial learning process. -- **Maintenance**: They often require less maintenance—there is typically no need for waxing and they are more resistant to dings and scratches. - -However, as a surfer’s skills progress, a soft-top might limit maneuverability and overall performance. - -### Hard-Top Boards - -Hard-tops, in contrast, offer a more traditional surfboard feel. They generally rely on a foam core encased in resin, with two prevalent combinations: - -- **PU (Polyurethane) Core with Polyester Resin**: This combination gives a classic feel and is relatively economical; however, these boards can be heavier and, as they age, more prone to damage. -- **EPS (Expanded Polystyrene) Core with Epoxy Resin**: Lightweight and durable, EPS boards are often more buoyant and resistant to damage, although they usually carry a higher price tag and may be less forgiving. - -Deciding between soft-top and hard-top boards often depends on a beginner’s progression goals, overall comfort, and budget constraints. - ---- - -## Tips for Transitioning from Longboards to Shorter Boards - -For surfers who have mastered the basics on an 11-foot board, the transition to a shorter board requires careful consideration, patience, and incremental changes. Here are some key tips: - -### Gradual Downsizing - -Experts recommend reducing the board length gradually—by about a foot at a time—to allow the body to adjust slowly to a board with less buoyancy and more responsiveness. This process helps maintain wave-catching ability and reduces the shock of transitioning to a very different board feel. - -### Strengthening Core Skills - -Before transitioning, make sure your surfing fundamentals are solid. Focus on practicing: - -- **Steep Take-offs**: Ensure that your pop-up is swift and robust to keep pace with shorter boards that demand a rapid transition from paddling to standing. -- **Angling and Paddling Techniques**: Learn to angle your takeoffs properly to compensate for the lower buoyancy and increased maneuverability of shorter boards. - -### Experimenting with Rentals or Borrowed Boards - -If possible, try out a friend’s shorter board or rent one for a day to experience firsthand the differences in performance. This practical trial can provide valuable insights and inform your decision before making a purchase. - ---- - -## Budget and Pricing Options - -Surfboards are available across a range of prices to match different budgets. Whether you are looking for an affordable beginner board or a more expensive model that grows with your skills, it’s important to understand what features you can expect at different price points. - -### Budget-Friendly Options - -For those on a tight budget, several entry-level models offer excellent value. Examples include: - -- **Wavestorm 8' Classic Pinline Surfboard**: Priced affordably, this board is popular for its ease of use, ample volume, and forgiving nature. Despite its low cost, it delivers the stability needed to get started. -- **Liquid Shredder EZ Slider Foamie**: A smaller board catering to younger or lighter surfers, this budget option provides easy paddling and a minimal risk of injury due to its soft construction. - -### Moderate Price Range - -As you move into the intermediate range, boards typically become slightly more specialized in their design, offering features such as improved stringer systems or versatile fin setups. These are excellent for surfers who wish to continue progressing their skills without compromising stability. Many surfboard packages from retailers also bundle a board with essential accessories like board bags, leashes, and wax for additional savings. - -### Higher-End Models and Transitional Packages - -For surfers looking for durability, performance, and advanced design features, investing in an EPS/epoxy board might be ideal. Although they come at a premium, these boards are lightweight, strong, and customizable with various fin configurations. Some options include boards from brands like South Bay Board Co. and ISLE, which combine high-quality construction with beginner-friendly features that help mediate the transition from longboard to shortboard performance. - ---- - -## Recommended Models and Buying Options - -Based on extensive research and community recommendations, here are some standout models and tips on where to buy: - -### Recommended Models - -- **South Bay Board Co. 8'8" Heritage**: Combining foam and resin construction, this board is ideal for beginners who need stability and a forgiving surface. Its 86-liter volume suits both lightweight and somewhat heavier surfers. -- **Rock-It 8' Big Softy**: With a high volume and an easy paddling profile, this board is designed for beginners, offering ample buoyancy to smooth out the learning curve. -- **Wave Bandit EZ Rider Series**: Available in multiple lengths (7', 8', 9'), these boards offer versatility, with construction features that balance the stability of longboards and the agility required for shorter boards. -- **Hybrid/Funboards Like the Poacher Funboard**: Perfect for transitioning surfers, these boards blend the ease of catching waves with the capability for more dynamic maneuvers. - -### Buying Options - -- **Surf Shops and Local Retailers**: Traditional surf shops allow you to test different boards, which is ideal for assessing the board feel and condition—especially if you are considering a used board. -- **Online Retailers and Marketplaces**: Websites like Evo, Surfboards Direct, and even local online marketplaces like Craigslist and Facebook Marketplace provide options that range from new to gently used boards. Always inspect reviews and verify seller policies before purchase. -- **Package Deals and Bundles**: Many retailers offer bundled packages that include not just the board, but also essentials like a leash, wax, fins, and board bags. These packages can be more cost-effective and are great for beginners who need a complete surf kit. - ---- - -## Conclusion - -Selecting the right surfboard as a beginner is about balancing various factors: stability, buoyancy, maneuverability, and budget. - -For those who have honed the basics using an 11-foot longboard, the transition to a shorter board should be gradual. Start by focusing on boards that preserve stability—such as funboards and hybrids—before moving to the more performance-oriented shortboards. Key characteristics like board length, width, thickness, volume, and material profoundly influence your surfing experience. Soft-top boards provide a forgiving entry point, while hard-top boards, especially those with EPS cores and epoxy resin, offer benefits for more advanced progression despite the increased learning curve. - -Emphasizing fundamentals like proper pop-up technique and effective paddle work will ease the transition and ensure that the new board complements your evolving skills. Additionally, understanding the pricing spectrum—from budget-friendly models to premium options—allows you to make an informed purchase that suits both your financial and performance needs. - -With a thoughtful approach to board selection, you can enhance your learning curve, enjoy safer sessions in the water, and ultimately develop the skills necessary to master the diverse challenges surfing presents. Whether your goal is to ride gentle waves or eventually experiment with sharper turns and dynamic maneuvers, choosing the right board is your first step towards a rewarding and sustainable surfing journey. - ---- - -## Follow-up Questions - -1. What is your current budget range for a new surfboard, or are you considering buying used? -2. How frequently do you plan to surf, and in what type of wave conditions? -3. Are you interested in a board that you can grow into as your skills progress, or do you prefer one that is more specialized for certain conditions? -4. Would you be interested in additional equipment bundles (like fins, leashes, boards bags) offered by local retailers or online shops? -5. Have you had the opportunity to test ride any boards before, and what feedback did you gather from that experience? - ---- - -With this detailed guide, beginners should now have a comprehensive understanding of the surfboard market and the key factors influencing board performance, safety, and ease of progression. Happy surfing, and may you find the perfect board that rides the waves as beautifully as your passion for the sport! - - -=====FOLLOW UP QUESTIONS===== - - -Follow up questions: What is your current budget range for a new surfboard, or are you considering a used board? -What types of waves do you typically surf, and how might that affect your board choice? -Would you be interested in a transitional board that grows with your skills, or are you looking for a more specialized design? -Have you had experience with renting or borrowing boards to try different sizes before making a purchase? -Do you require additional equipment bundles (like fins, leash, or wax), or do you already have those? diff --git a/tests/examples/research_bot/sample_outputs/vacation.md b/tests/examples/research_bot/sample_outputs/vacation.md deleted file mode 100644 index 82c137af..00000000 --- a/tests/examples/research_bot/sample_outputs/vacation.md +++ /dev/null @@ -1,177 +0,0 @@ -Report: # Caribbean Adventure in April: Surfing, Hiking, and Water Sports Exploration - -The Caribbean is renowned for its crystal-clear waters, vibrant culture, and diverse outdoor activities. April is an especially attractive month for visitors: warm temperatures, clear skies, and the promise of abundant activities. This report explores the best Caribbean destinations in April, with a focus on optimizing your vacation for surfing, hiking, and water sports. - ---- - -## Table of Contents - -1. [Introduction](#introduction) -2. [Why April is the Perfect Time in the Caribbean](#why-april-is-the-perfect-time-in-the-caribbean) -3. [Surfing in the Caribbean](#surfing-in-the-caribbean) - - 3.1 [Barbados: The Tale of Two Coasts](#barbados-the-tale-of-two-coasts) - - 3.2 [Puerto Rico: Rincón and Beyond](#puerto-rico-rinc%C3%B3n-and-beyond) - - 3.3 [Dominican Republic and Other Hotspots](#dominican-republic-and-other-hotspots) -4. [Hiking Adventures Across the Caribbean](#hiking-adventures-across-the-caribbean) - - 4.1 [Trekking Through Tropical Rainforests](#trekking-through-tropical-rainforests) - - 4.2 [Volcanic Peaks and Rugged Landscapes](#volcanic-peaks-and-rugged-landscapes) -5. [Diverse Water Sports Experiences](#diverse-water-sports-experiences) - - 5.1 [Snorkeling, Diving, and Jet Skiing](#snorkeling-diving-and-jet-skiing) - - 5.2 [Kiteboarding and Windsurfing](#kiteboarding-and-windsurfing) -6. [Combining Adventures: Multi-Activity Destinations](#combining-adventures-multi-activity-destinations) -7. [Practical Advice and Travel Tips](#practical-advice-and-travel-tips) -8. [Conclusion](#conclusion) - ---- - -## Introduction - -Caribbean vacations are much more than just beach relaxation; they offer adventure, exploration, and a lively cultural tapestry waiting to be discovered. For travelers seeking an adrenaline-filled getaway, April provides optimal conditions. This report synthesizes diverse research findings and travel insights to help you create an itinerary that combines the thrill of surfing, the challenge of hiking, and the excitement of water sports. - -Whether you're standing on the edge of a powerful reef break or trekking through lush tropical landscapes, the Caribbean in April invites you to dive into nature, adventure, and culture. The following sections break down the best destinations and activities, ensuring that every aspect of your trip is meticulously planned for an unforgettable experience. - ---- - -## Why April is the Perfect Time in the Caribbean - -April stands at the crossroads of seasons in many Caribbean destinations. It marks the tail end of the dry season, ensuring: - -- **Consistent Warm Temperatures:** Average daytime highs around 29°C (84°F) foster comfortable conditions for both land and water activities. -- **Pleasant Sea Temperatures:** With sea temperatures near 26°C (79°F), swimmers, surfers, and divers are treated to inviting waters. -- **Clear Skies and Minimal Rainfall:** Crisp, blue skies make for excellent visibility during snorkeling and diving, as well as clear panoramic views while hiking. -- **Festivals and Cultural Events:** Many islands host seasonal festivals such as Barbados' Fish Festival and Antigua's Sailing Week, adding a cultural layer to your vacation. - -These factors create an ideal backdrop for balancing your outdoor pursuits, whether you’re catching epic waves, trekking rugged trails, or partaking in water sports. - ---- - -## Surfing in the Caribbean - -Surfing in the Caribbean offers diverse wave experiences, ranging from gentle, beginner-friendly rollers to powerful reef breaks that challenge even seasoned surfers. April, in particular, provides excellent conditions for those looking to ride its picturesque waves. - -### Barbados: The Tale of Two Coasts - -Barbados is a prime destination: - -- **Soup Bowl in Bathsheba:** On the east coast, the Soup Bowl is famous for its consistent, powerful waves. This spot attracts experienced surfers who appreciate its challenging right-hand reef break with steep drops, providing the kind of performance wave rarely found elsewhere. -- **Freights Bay:** On the south coast, visitors find more forgiving, gentle wave conditions. Ideal for beginners and longboarders, this spot offers the perfect balance for those still mastering their craft. - -Barbados not only excels in its surfing credentials but also complements the experience with a rich local culture and events in April, making it a well-rounded destination. - -### Puerto Rico: Rincón and Beyond - -Rincón in Puerto Rico is hailed as the Caribbean’s surfing capital: - -- **Diverse Breaks:** With spots ranging from challenging reef breaks such as Tres Palmas and Dogman's to more inviting waves at Domes and Maria's, Puerto Rico offers a spectrum for all surfing skill levels. -- **Local Culture:** Aside from its surf culture, the island boasts vibrant local food scenes, historic sites, and exciting nightlife, enriching your overall travel experience. - -In addition, Puerto Rico’s coasts often feature opportunities for hiking and other outdoor adventures, making it an attractive option for multi-activity travelers. - -### Dominican Republic and Other Hotspots - -Other islands such as the Dominican Republic, with Playa Encuentro on its north coast, provide consistent surf year-round. Highlights include: - -- **Playa Encuentro:** A hotspot known for its dependable breaks, ideal for both intermediate and advanced surfers during the cooler months of October to April. -- **Jamaica and The Bahamas:** Jamaica’s Boston Bay offers a mix of beginner and intermediate waves, and The Bahamas’ Surfer’s Beach on Eleuthera draws parallels to the legendary surf spots of Hawaii, especially during the winter months. - -These destinations not only spotlight surfing but also serve as gateways to additional outdoor activities, ensuring there's never a dull moment whether you're balancing waves with hikes or cultural exploration. - ---- - -## Hiking Adventures Across the Caribbean - -The Caribbean's topography is as varied as it is beautiful. Its network of hiking trails traverses volcanic peaks, ancient rainforests, and dramatic coastal cliffs, offering breathtaking vistas to intrepid explorers. - -### Trekking Through Tropical Rainforests - -For nature enthusiasts, the lush forests of the Caribbean present an immersive encounter with biodiversity: - -- **El Yunque National Forest, Puerto Rico:** The only tropical rainforest within the U.S. National Forest System, El Yunque is rich in endemic species such as the Puerto Rican parrot and the famous coquí frog. Trails like the El Yunque Peak Trail and La Mina Falls Trail provide both challenging hikes and scenic rewards. -- **Virgin Islands National Park, St. John:** With over 20 well-defined trails, this park offers hikes that reveal historical petroglyphs, colonial ruins, and stunning coastal views along the Reef Bay Trail. - -### Volcanic Peaks and Rugged Landscapes - -For those seeking more rugged challenges, several destinations offer unforgettable adventures: - -- **Morne Trois Pitons National Park, Dominica:** A UNESCO World Heritage Site showcasing volcanic landscapes, hot springs, the famed Boiling Lake, and lush trails that lead to hidden waterfalls. -- **Gros Piton, Saint Lucia:** The iconic hike up Gros Piton provides a moderately challenging trek that ends with panoramic views of the Caribbean Sea, a truly rewarding experience for hikers. -- **La Soufrière, St. Vincent:** This active volcano not only offers a dynamic hiking environment but also the opportunity to observe the ongoing geological transformations up close. - -Other noteworthy hiking spots include the Blue Mountains in Jamaica for coffee plantation tours and expansive views, as well as trails in Martinique around Montagne Pelée, which combine historical context with natural beauty. - ---- - -## Diverse Water Sports Experiences - -While surfing and hiking attract a broad range of adventurers, the Caribbean also scores high on other water sports. Whether you're drawn to snorkeling, jet skiing, or wind- and kiteboarding, the islands offer a plethora of aquatic activities. - -### Snorkeling, Diving, and Jet Skiing - -Caribbean waters teem with life and color, making them ideal for underwater exploration: - -- **Bonaire:** Its protected marine parks serve as a magnet for divers and snorkelers. With vibrant coral reefs and diverse marine species, Bonaire is a top destination for those who appreciate the underwater world. -- **Cayman Islands:** Unique attractions such as Stingray City provide opportunities to interact with friendly stingrays in clear, calm waters. Additionally, the Underwater Sculpture Park is an innovative blend of art and nature. -- **The Bahamas:** In places like Eleuthera, excursions often cater to families and thrill-seekers alike. Options include jet ski rentals, where groups can explore hidden beaches and pristine coves while enjoying the vibrant marine life. - -### Kiteboarding and Windsurfing - -Harnessing the steady trade winds and warm Caribbean waters, several islands have become hubs for kiteboarding and windsurfing: - -- **Aruba:** Known as "One Happy Island," Aruba’s Fisherman's Huts area provides consistent winds, perfect for enthusiasts of windsurfing and kiteboarding alike. -- **Cabarete, Dominican Republic and Silver Rock, Barbados:** Both destinations benefit from reliable trade winds, making them popular among kitesurfers. These spots often combine water sports with a lively beach culture, ensuring that the fun continues on land as well. - -Local operators provide equipment rental and lessons, ensuring that even first-time adventurers can safely and confidently enjoy these exciting sports. - ---- - -## Combining Adventures: Multi-Activity Destinations - -For travelers seeking a comprehensive vacation where surfing, hiking, and water sports converge, several Caribbean destinations offer the best of all worlds. - -- **Puerto Rico:** With its robust surf scene in Rincón, world-class hiking in El Yunque, and opportunities for snorkeling and jet skiing in San Juan Bay, Puerto Rico is a true multi-adventure destination. -- **Barbados:** In addition to the surf breaks along its coasts, Barbados offers a mix of cultural events, local cuisine, and even hiking excursions to scenic rural areas, making for a well-rounded experience. -- **Dominican Republic and Jamaica:** Both are renowned not only for their consistent surf conditions but also for expansive hiking trails and water sports. From the rugged landscapes of the Dominican Republic to Jamaica’s blend of cultural history and natural exploration, these islands allow travelers to mix and match activities seamlessly. - -Group tours and local guides further enhance these experiences, providing insider tips, safe excursions, and personalized itineraries that cater to multiple interests within one trip. - ---- - -## Practical Advice and Travel Tips - -### Weather and Timing - -- **Optimal Climate:** April offers ideal weather conditions across the Caribbean. With minimal rainfall and warm temperatures, it is a great time to schedule outdoor activities. -- **Surfing Seasons:** While April marks the end of the prime surf season in some areas (like Rincón in Puerto Rico), many destinations maintain consistent conditions during this month. - -### Booking and Costs - -- **Surfing Lessons:** Expect to pay between $40 and $110 per session depending on the location. For instance, Puerto Rico typically charges around $75 for beginner lessons, while group lessons in the Dominican Republic average approximately $95. -- **Equipment Rentals:** Pricing for jet ski, surfboard, and snorkeling equipment may vary. In the Bahamas, an hour-long jet ski tour might cost about $120 per group, whereas a similar experience might be available at a lower cost in other regions. -- **Accommodations:** Prices also vary by island. Many travelers find that even affordable stays do not skimp on amenities, allowing you to invest more in guided excursions and local experiences. - -### Cultural Considerations - -- **Festivals and Events:** Check local event calendars. Destinations like Barbados and Antigua host festivals in April that combine cultural heritage with festive outdoor activities. -- **Local Cuisine:** Incorporate food tours into your itinerary. Caribbean cuisine—with its fusion of flavors—can be as adventurous as the outdoor activities. - -### Health and Safety - -- **Staying Hydrated:** The warm temperatures demand that you stay properly hydrated. Always carry water, especially during long hikes. -- **Sun Protection:** Use sunscreen, hats, and sunglasses to protect yourself during extended periods outdoors on both land and water. -- **Local Guides:** Utilize local tour operators for both hiking and water sports. Their expertise not only enriches your experience but also ensures safety in unfamiliar terrain or water bodies. - ---- - -## Conclusion - -The Caribbean in April is a haven for adventure seekers. With its pristine beaches, diverse ecosystems, and rich cultural tapestry, it offers something for every type of traveler. Whether you're chasing the perfect wave along the shores of Barbados and Puerto Rico, trekking through the lush landscapes of El Yunque or Morne Trois Pitons, or engaging in an array of water sports from snorkeling to kiteboarding, your ideal vacation is only a booking away. - -This report has outlined the best destinations and provided practical advice to optimize your vacation for surfing, hiking, and water sports. By considering the diverse offerings—from epic surf breaks and challenging hiking trails to vibrant water sports—the Caribbean stands out as a multi-adventure destination where every day brings a new experience. - -Plan carefully, pack wisely, and get ready to explore the vibrant mosaic of landscapes and activities that make the Caribbean in April a truly unforgettable adventure. - -Happy travels! - ---- - -_References available upon request. Many insights were drawn from trusted sources including Lonely Planet, TravelPug, and various Caribbean-centric exploration sites, ensuring a well-rounded and practical guide for your vacation planning._ diff --git a/tests/examples/research_bot/sample_outputs/vacation.txt b/tests/examples/research_bot/sample_outputs/vacation.txt deleted file mode 100644 index b2649981..00000000 --- a/tests/examples/research_bot/sample_outputs/vacation.txt +++ /dev/null @@ -1,206 +0,0 @@ -# Terminal output for a vacation related query. See vacation.md for final report. - -$ uv run python -m examples.research_bot.main -What would you like to research? Caribbean vacation spots in April, optimizing for surfing, hiking and water sports -View trace: https://platform.openai.com/traces/trace_.... -Starting research... -✅ Will perform 15 searches -✅ Searching... 15/15 completed -✅ Finishing report... -✅ Report summary - -This report provides an in-depth exploration of selected Caribbean vacation spots in April that are ideal for surfing, hiking, and water sports. Covering -destinations from Barbados and Puerto Rico to the Bahamas and Jamaica, it examines favorable weather conditions, recommended surf breaks, scenic hiking -trails, and various water sports activities. Detailed destination profiles, activity highlights, and travel tips are integrated to help travelers design a -multi-adventure itinerary in the Caribbean during April. - - -=====REPORT===== - - -Report: # Caribbean Adventure in April: Surfing, Hiking, and Water Sports Exploration - -The Caribbean is renowned for its crystal-clear waters, vibrant culture, and diverse outdoor activities. April is an especially attractive month for visitors: warm temperatures, clear skies, and the promise of abundant activities. This report explores the best Caribbean destinations in April, with a focus on optimizing your vacation for surfing, hiking, and water sports. - ---- - -## Table of Contents - -1. [Introduction](#introduction) -2. [Why April is the Perfect Time in the Caribbean](#why-april-is-the-perfect-time-in-the-caribbean) -3. [Surfing in the Caribbean](#surfing-in-the-caribbean) - - 3.1 [Barbados: The Tale of Two Coasts](#barbados-the-tale-of-two-coasts) - - 3.2 [Puerto Rico: Rincón and Beyond](#puerto-rico-rinc%C3%B3n-and-beyond) - - 3.3 [Dominican Republic and Other Hotspots](#dominican-republic-and-other-hotspots) -4. [Hiking Adventures Across the Caribbean](#hiking-adventures-across-the-caribbean) - - 4.1 [Trekking Through Tropical Rainforests](#trekking-through-tropical-rainforests) - - 4.2 [Volcanic Peaks and Rugged Landscapes](#volcanic-peaks-and-rugged-landscapes) -5. [Diverse Water Sports Experiences](#diverse-water-sports-experiences) - - 5.1 [Snorkeling, Diving, and Jet Skiing](#snorkeling-diving-and-jet-skiing) - - 5.2 [Kiteboarding and Windsurfing](#kiteboarding-and-windsurfing) -6. [Combining Adventures: Multi-Activity Destinations](#combining-adventures-multi-activity-destinations) -7. [Practical Advice and Travel Tips](#practical-advice-and-travel-tips) -8. [Conclusion](#conclusion) - ---- - -## Introduction - -Caribbean vacations are much more than just beach relaxation; they offer adventure, exploration, and a lively cultural tapestry waiting to be discovered. For travelers seeking an adrenaline-filled getaway, April provides optimal conditions. This report synthesizes diverse research findings and travel insights to help you create an itinerary that combines the thrill of surfing, the challenge of hiking, and the excitement of water sports. - -Whether you're standing on the edge of a powerful reef break or trekking through lush tropical landscapes, the Caribbean in April invites you to dive into nature, adventure, and culture. The following sections break down the best destinations and activities, ensuring that every aspect of your trip is meticulously planned for an unforgettable experience. - ---- - -## Why April is the Perfect Time in the Caribbean - -April stands at the crossroads of seasons in many Caribbean destinations. It marks the tail end of the dry season, ensuring: - -- **Consistent Warm Temperatures:** Average daytime highs around 29°C (84°F) foster comfortable conditions for both land and water activities. -- **Pleasant Sea Temperatures:** With sea temperatures near 26°C (79°F), swimmers, surfers, and divers are treated to inviting waters. -- **Clear Skies and Minimal Rainfall:** Crisp, blue skies make for excellent visibility during snorkeling and diving, as well as clear panoramic views while hiking. -- **Festivals and Cultural Events:** Many islands host seasonal festivals such as Barbados' Fish Festival and Antigua's Sailing Week, adding a cultural layer to your vacation. - -These factors create an ideal backdrop for balancing your outdoor pursuits, whether you’re catching epic waves, trekking rugged trails, or partaking in water sports. - ---- - -## Surfing in the Caribbean - -Surfing in the Caribbean offers diverse wave experiences, ranging from gentle, beginner-friendly rollers to powerful reef breaks that challenge even seasoned surfers. April, in particular, provides excellent conditions for those looking to ride its picturesque waves. - -### Barbados: The Tale of Two Coasts - -Barbados is a prime destination: - -- **Soup Bowl in Bathsheba:** On the east coast, the Soup Bowl is famous for its consistent, powerful waves. This spot attracts experienced surfers who appreciate its challenging right-hand reef break with steep drops, providing the kind of performance wave rarely found elsewhere. -- **Freights Bay:** On the south coast, visitors find more forgiving, gentle wave conditions. Ideal for beginners and longboarders, this spot offers the perfect balance for those still mastering their craft. - -Barbados not only excels in its surfing credentials but also complements the experience with a rich local culture and events in April, making it a well-rounded destination. - -### Puerto Rico: Rincón and Beyond - -Rincón in Puerto Rico is hailed as the Caribbean’s surfing capital: - -- **Diverse Breaks:** With spots ranging from challenging reef breaks such as Tres Palmas and Dogman's to more inviting waves at Domes and Maria's, Puerto Rico offers a spectrum for all surfing skill levels. -- **Local Culture:** Aside from its surf culture, the island boasts vibrant local food scenes, historic sites, and exciting nightlife, enriching your overall travel experience. - -In addition, Puerto Rico’s coasts often feature opportunities for hiking and other outdoor adventures, making it an attractive option for multi-activity travelers. - -### Dominican Republic and Other Hotspots - -Other islands such as the Dominican Republic, with Playa Encuentro on its north coast, provide consistent surf year-round. Highlights include: - -- **Playa Encuentro:** A hotspot known for its dependable breaks, ideal for both intermediate and advanced surfers during the cooler months of October to April. -- **Jamaica and The Bahamas:** Jamaica’s Boston Bay offers a mix of beginner and intermediate waves, and The Bahamas’ Surfer’s Beach on Eleuthera draws parallels to the legendary surf spots of Hawaii, especially during the winter months. - -These destinations not only spotlight surfing but also serve as gateways to additional outdoor activities, ensuring there's never a dull moment whether you're balancing waves with hikes or cultural exploration. - ---- - -## Hiking Adventures Across the Caribbean - -The Caribbean's topography is as varied as it is beautiful. Its network of hiking trails traverses volcanic peaks, ancient rainforests, and dramatic coastal cliffs, offering breathtaking vistas to intrepid explorers. - -### Trekking Through Tropical Rainforests - -For nature enthusiasts, the lush forests of the Caribbean present an immersive encounter with biodiversity: - -- **El Yunque National Forest, Puerto Rico:** The only tropical rainforest within the U.S. National Forest System, El Yunque is rich in endemic species such as the Puerto Rican parrot and the famous coquí frog. Trails like the El Yunque Peak Trail and La Mina Falls Trail provide both challenging hikes and scenic rewards. -- **Virgin Islands National Park, St. John:** With over 20 well-defined trails, this park offers hikes that reveal historical petroglyphs, colonial ruins, and stunning coastal views along the Reef Bay Trail. - -### Volcanic Peaks and Rugged Landscapes - -For those seeking more rugged challenges, several destinations offer unforgettable adventures: - -- **Morne Trois Pitons National Park, Dominica:** A UNESCO World Heritage Site showcasing volcanic landscapes, hot springs, the famed Boiling Lake, and lush trails that lead to hidden waterfalls. -- **Gros Piton, Saint Lucia:** The iconic hike up Gros Piton provides a moderately challenging trek that ends with panoramic views of the Caribbean Sea, a truly rewarding experience for hikers. -- **La Soufrière, St. Vincent:** This active volcano not only offers a dynamic hiking environment but also the opportunity to observe the ongoing geological transformations up close. - -Other noteworthy hiking spots include the Blue Mountains in Jamaica for coffee plantation tours and expansive views, as well as trails in Martinique around Montagne Pelée, which combine historical context with natural beauty. - ---- - -## Diverse Water Sports Experiences - -While surfing and hiking attract a broad range of adventurers, the Caribbean also scores high on other water sports. Whether you're drawn to snorkeling, jet skiing, or wind- and kiteboarding, the islands offer a plethora of aquatic activities. - -### Snorkeling, Diving, and Jet Skiing - -Caribbean waters teem with life and color, making them ideal for underwater exploration: - -- **Bonaire:** Its protected marine parks serve as a magnet for divers and snorkelers. With vibrant coral reefs and diverse marine species, Bonaire is a top destination for those who appreciate the underwater world. -- **Cayman Islands:** Unique attractions such as Stingray City provide opportunities to interact with friendly stingrays in clear, calm waters. Additionally, the Underwater Sculpture Park is an innovative blend of art and nature. -- **The Bahamas:** In places like Eleuthera, excursions often cater to families and thrill-seekers alike. Options include jet ski rentals, where groups can explore hidden beaches and pristine coves while enjoying the vibrant marine life. - -### Kiteboarding and Windsurfing - -Harnessing the steady trade winds and warm Caribbean waters, several islands have become hubs for kiteboarding and windsurfing: - -- **Aruba:** Known as "One Happy Island," Aruba’s Fisherman's Huts area provides consistent winds, perfect for enthusiasts of windsurfing and kiteboarding alike. -- **Cabarete, Dominican Republic and Silver Rock, Barbados:** Both destinations benefit from reliable trade winds, making them popular among kitesurfers. These spots often combine water sports with a lively beach culture, ensuring that the fun continues on land as well. - -Local operators provide equipment rental and lessons, ensuring that even first-time adventurers can safely and confidently enjoy these exciting sports. - ---- - -## Combining Adventures: Multi-Activity Destinations - -For travelers seeking a comprehensive vacation where surfing, hiking, and water sports converge, several Caribbean destinations offer the best of all worlds. - -- **Puerto Rico:** With its robust surf scene in Rincón, world-class hiking in El Yunque, and opportunities for snorkeling and jet skiing in San Juan Bay, Puerto Rico is a true multi-adventure destination. -- **Barbados:** In addition to the surf breaks along its coasts, Barbados offers a mix of cultural events, local cuisine, and even hiking excursions to scenic rural areas, making for a well-rounded experience. -- **Dominican Republic and Jamaica:** Both are renowned not only for their consistent surf conditions but also for expansive hiking trails and water sports. From the rugged landscapes of the Dominican Republic to Jamaica’s blend of cultural history and natural exploration, these islands allow travelers to mix and match activities seamlessly. - -Group tours and local guides further enhance these experiences, providing insider tips, safe excursions, and personalized itineraries that cater to multiple interests within one trip. - ---- - -## Practical Advice and Travel Tips - -### Weather and Timing - -- **Optimal Climate:** April offers ideal weather conditions across the Caribbean. With minimal rainfall and warm temperatures, it is a great time to schedule outdoor activities. -- **Surfing Seasons:** While April marks the end of the prime surf season in some areas (like Rincón in Puerto Rico), many destinations maintain consistent conditions during this month. - -### Booking and Costs - -- **Surfing Lessons:** Expect to pay between $40 and $110 per session depending on the location. For instance, Puerto Rico typically charges around $75 for beginner lessons, while group lessons in the Dominican Republic average approximately $95. -- **Equipment Rentals:** Pricing for jet ski, surfboard, and snorkeling equipment may vary. In the Bahamas, an hour-long jet ski tour might cost about $120 per group, whereas a similar experience might be available at a lower cost in other regions. -- **Accommodations:** Prices also vary by island. Many travelers find that even affordable stays do not skimp on amenities, allowing you to invest more in guided excursions and local experiences. - -### Cultural Considerations - -- **Festivals and Events:** Check local event calendars. Destinations like Barbados and Antigua host festivals in April that combine cultural heritage with festive outdoor activities. -- **Local Cuisine:** Incorporate food tours into your itinerary. Caribbean cuisine—with its fusion of flavors—can be as adventurous as the outdoor activities. - -### Health and Safety - -- **Staying Hydrated:** The warm temperatures demand that you stay properly hydrated. Always carry water, especially during long hikes. -- **Sun Protection:** Use sunscreen, hats, and sunglasses to protect yourself during extended periods outdoors on both land and water. -- **Local Guides:** Utilize local tour operators for both hiking and water sports. Their expertise not only enriches your experience but also ensures safety in unfamiliar terrain or water bodies. - ---- - -## Conclusion - -The Caribbean in April is a haven for adventure seekers. With its pristine beaches, diverse ecosystems, and rich cultural tapestry, it offers something for every type of traveler. Whether you're chasing the perfect wave along the shores of Barbados and Puerto Rico, trekking through the lush landscapes of El Yunque or Morne Trois Pitons, or engaging in an array of water sports from snorkeling to kiteboarding, your ideal vacation is only a booking away. - -This report has outlined the best destinations and provided practical advice to optimize your vacation for surfing, hiking, and water sports. By considering the diverse offerings—from epic surf breaks and challenging hiking trails to vibrant water sports—the Caribbean stands out as a multi-adventure destination where every day brings a new experience. - -Plan carefully, pack wisely, and get ready to explore the vibrant mosaic of landscapes and activities that make the Caribbean in April a truly unforgettable adventure. - -Happy travels! - ---- - -*References available upon request. Many insights were drawn from trusted sources including Lonely Planet, TravelPug, and various Caribbean-centric exploration sites, ensuring a well-rounded and practical guide for your vacation planning.* - - - -=====FOLLOW UP QUESTIONS===== - - -Follow up questions: Would you like detailed profiles for any of the highlighted destinations (e.g., Puerto Rico or Barbados)? -Are you interested in more information about booking details and local tour operators in specific islands? -Do you need guidance on combining cultural events with outdoor adventures during your Caribbean vacation? \ No newline at end of file diff --git a/tests/examples/tools/computer_use.py b/tests/examples/tools/computer_use.py deleted file mode 100644 index ae339552..00000000 --- a/tests/examples/tools/computer_use.py +++ /dev/null @@ -1,165 +0,0 @@ -import asyncio -import base64 -import logging -from typing import Literal, Union - -from playwright.async_api import Browser, Page, Playwright, async_playwright - -from agents import ( - Agent, - AsyncComputer, - Button, - ComputerTool, - Environment, - ModelSettings, - Runner, - trace, -) - -logging.getLogger("openai.agents").setLevel(logging.DEBUG) -logging.getLogger("openai.agents").addHandler(logging.StreamHandler()) - - -async def main(): - async with LocalPlaywrightComputer() as computer: - with trace("Computer use example"): - agent = Agent( - name="Browser user", - instructions="You are a helpful agent.", - tools=[ComputerTool(computer)], - # Use the computer using model, and set truncation to auto because its required - model="computer-use-preview", - model_settings=ModelSettings(truncation="auto"), - ) - result = await Runner.run(agent, "Search for SF sports news and summarize.") - print(result.final_output) - - -CUA_KEY_TO_PLAYWRIGHT_KEY = { - "/": "Divide", - "\\": "Backslash", - "alt": "Alt", - "arrowdown": "ArrowDown", - "arrowleft": "ArrowLeft", - "arrowright": "ArrowRight", - "arrowup": "ArrowUp", - "backspace": "Backspace", - "capslock": "CapsLock", - "cmd": "Meta", - "ctrl": "Control", - "delete": "Delete", - "end": "End", - "enter": "Enter", - "esc": "Escape", - "home": "Home", - "insert": "Insert", - "option": "Alt", - "pagedown": "PageDown", - "pageup": "PageUp", - "shift": "Shift", - "space": " ", - "super": "Meta", - "tab": "Tab", - "win": "Meta", -} - - -class LocalPlaywrightComputer(AsyncComputer): - """A computer, implemented using a local Playwright browser.""" - - def __init__(self): - self._playwright: Union[Playwright, None] = None - self._browser: Union[Browser, None] = None - self._page: Union[Page, None] = None - - async def _get_browser_and_page(self) -> tuple[Browser, Page]: - width, height = self.dimensions - launch_args = [f"--window-size={width},{height}"] - browser = await self.playwright.chromium.launch(headless=False, args=launch_args) - page = await browser.new_page() - await page.set_viewport_size({"width": width, "height": height}) - await page.goto("https://www.bing.com") - return browser, page - - async def __aenter__(self): - # Start Playwright and call the subclass hook for getting browser/page - self._playwright = await async_playwright().start() - self._browser, self._page = await self._get_browser_and_page() - return self - - async def __aexit__(self, exc_type, exc_val, exc_tb): - if self._browser: - await self._browser.close() - if self._playwright: - await self._playwright.stop() - - @property - def playwright(self) -> Playwright: - assert self._playwright is not None - return self._playwright - - @property - def browser(self) -> Browser: - assert self._browser is not None - return self._browser - - @property - def page(self) -> Page: - assert self._page is not None - return self._page - - @property - def environment(self) -> Environment: - return "browser" - - @property - def dimensions(self) -> tuple[int, int]: - return (1024, 768) - - async def screenshot(self) -> str: - """Capture only the viewport (not full_page).""" - png_bytes = await self.page.screenshot(full_page=False) - return base64.b64encode(png_bytes).decode("utf-8") - - async def click(self, x: int, y: int, button: Button = "left") -> None: - playwright_button: Literal["left", "middle", "right"] = "left" - - # Playwright only supports left, middle, right buttons - if button in ("left", "right", "middle"): - playwright_button = button # type: ignore - - await self.page.mouse.click(x, y, button=playwright_button) - - async def double_click(self, x: int, y: int) -> None: - await self.page.mouse.dblclick(x, y) - - async def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None: - await self.page.mouse.move(x, y) - await self.page.evaluate(f"window.scrollBy({scroll_x}, {scroll_y})") - - async def type(self, text: str) -> None: - await self.page.keyboard.type(text) - - async def wait(self) -> None: - await asyncio.sleep(1) - - async def move(self, x: int, y: int) -> None: - await self.page.mouse.move(x, y) - - async def keypress(self, keys: list[str]) -> None: - for key in keys: - mapped_key = CUA_KEY_TO_PLAYWRIGHT_KEY.get(key.lower(), key) - await self.page.keyboard.press(mapped_key) - - async def drag(self, path: list[tuple[int, int]]) -> None: - if not path: - return - await self.page.mouse.move(path[0][0], path[0][1]) - await self.page.mouse.down() - for px, py in path[1:]: - await self.page.mouse.move(px, py) - await self.page.mouse.up() - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/tools/file_search.py b/tests/examples/tools/file_search.py deleted file mode 100644 index 2a3d4cf1..00000000 --- a/tests/examples/tools/file_search.py +++ /dev/null @@ -1,36 +0,0 @@ -import asyncio - -from agents import Agent, FileSearchTool, Runner, trace - - -async def main(): - agent = Agent( - name="File searcher", - instructions="You are a helpful agent.", - tools=[ - FileSearchTool( - max_num_results=3, - vector_store_ids=["vs_67bf88953f748191be42b462090e53e7"], - include_search_results=True, - ) - ], - ) - - with trace("File search example"): - result = await Runner.run( - agent, "Be concise, and tell me 1 sentence about Arrakis I might not know." - ) - print(result.final_output) - """ - Arrakis, the desert planet in Frank Herbert's "Dune," was inspired by the scarcity of water - as a metaphor for oil and other finite resources. - """ - - print("\n".join([str(out) for out in result.new_items])) - """ - {"id":"...", "queries":["Arrakis"], "results":[...]} - """ - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/examples/tools/web_search.py b/tests/examples/tools/web_search.py deleted file mode 100644 index 35eeb680..00000000 --- a/tests/examples/tools/web_search.py +++ /dev/null @@ -1,23 +0,0 @@ -import asyncio - -from agents import Agent, Runner, WebSearchTool, trace - - -async def main(): - agent = Agent( - name="Web searcher", - instructions="You are a helpful agent.", - tools=[WebSearchTool(user_location={"type": "approximate", "city": "New York"})], - ) - - with trace("Web search example"): - result = await Runner.run( - agent, - "search the web for 'local sports news' and give me 1 interesting update in a sentence.", - ) - print(result.final_output) - # The New York Giants are reportedly pursuing quarterback Aaron Rodgers after his ... - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tests/mkdocs.yml b/tests/mkdocs.yml deleted file mode 100644 index 398fb74a..00000000 --- a/tests/mkdocs.yml +++ /dev/null @@ -1,121 +0,0 @@ -site_name: OpenAI Agents SDK -theme: - name: material - features: - # Allows copying code blocks - - content.code.copy - # Allows selecting code blocks - - content.code.select - # Shows the current path in the sidebar - - navigation.path - # Shows sections in the sidebar - - navigation.sections - # Shows sections expanded by default - - navigation.expand - # Enables annotations in code blocks - - content.code.annotate - palette: - primary: black - logo: assets/logo.svg - favicon: images/favicon-platform.svg -nav: - - Intro: index.md - - Quickstart: quickstart.md - - Documentation: - - agents.md - - running_agents.md - - results.md - - streaming.md - - tools.md - - handoffs.md - - tracing.md - - context.md - - guardrails.md - - multi_agent.md - - models.md - - config.md - - API Reference: - - Agents: - - ref/index.md - - ref/agent.md - - ref/run.md - - ref/tool.md - - ref/result.md - - ref/stream_events.md - - ref/handoffs.md - - ref/lifecycle.md - - ref/items.md - - ref/run_context.md - - ref/usage.md - - ref/exceptions.md - - ref/guardrail.md - - ref/model_settings.md - - ref/agent_output.md - - ref/function_schema.md - - ref/models/interface.md - - ref/models/openai_chatcompletions.md - - ref/models/openai_responses.md - - Tracing: - - ref/tracing/index.md - - ref/tracing/create.md - - ref/tracing/traces.md - - ref/tracing/spans.md - - ref/tracing/processor_interface.md - - ref/tracing/processors.md - - ref/tracing/scope.md - - ref/tracing/setup.md - - ref/tracing/span_data.md - - ref/tracing/util.md - - Extensions: - - ref/extensions/handoff_filters.md - - ref/extensions/handoff_prompt.md - -plugins: - - search - - mkdocstrings: - handlers: - python: - paths: ["src/agents"] - selection: - docstring_style: google - options: - # Shows links to other members in signatures - signature_crossrefs: true - # Orders members by source order, rather than alphabetical - members_order: source - # Puts the signature on a separate line from the member name - separate_signature: true - # Shows type annotations in signatures - show_signature_annotations: true - # Makes the font sizes nicer - heading_level: 3 - -extra: - # Remove material generation message in footer - generator: false - -markdown_extensions: - - admonition - - pymdownx.details - - pymdownx.superfences - - attr_list - - md_in_html - - pymdownx.highlight: - anchor_linenums: true - line_spans: __span - pygments_lang_class: true - - pymdownx.inlinehilite - - pymdownx.snippets - - pymdownx.superfences - -validation: - omitted_files: warn - absolute_links: warn - unrecognized_links: warn - anchors: warn - -extra_css: - - stylesheets/extra.css - -watch: - - "src/agents" diff --git a/tests/pyproject.toml b/tests/pyproject.toml deleted file mode 100644 index 24e08eb7..00000000 --- a/tests/pyproject.toml +++ /dev/null @@ -1,119 +0,0 @@ -[project] -name = "openai-agents" -version = "0.0.1" -description = "OpenAI Agents SDK" -readme = "README.md" -requires-python = ">=3.9" -license = "MIT" -authors = [ - { name = "OpenAI", email = "support@openai.com" }, -] -dependencies = [ - "openai>=1.66.0", - "pydantic>=2.10, <3", - "griffe>=1.5.6, <2", - "typing-extensions>=4.12.2, <5", - "requests>=2.0, <3", - "types-requests>=2.0, <3", -] -classifiers = [ - "Typing :: Typed", - "Intended Audience :: Developers", - "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Intended Audience :: Developers", - "Operating System :: OS Independent", - "Topic :: Software Development :: Libraries :: Python Modules", - "License :: OSI Approved :: MIT License" -] - -[project.urls] -Homepage = "https://github.com/openai/openai-agents-python" -Repository = "https://github.com/openai/openai-agents-python" - -[dependency-groups] -dev = [ - "mypy", - "ruff==0.9.2", - "pytest", - "pytest-asyncio", - "pytest-mock>=3.14.0", - "rich", - "mkdocs>=1.6.0", - "mkdocs-material>=9.6.0", - "mkdocstrings[python]>=0.28.0", - "coverage>=7.6.12", - "playwright==1.50.0", -] -[tool.uv.workspace] -members = ["agents"] - -[tool.uv.sources] -agents = { workspace = true } - -[build-system] -requires = ["hatchling"] -build-backend = "hatchling.build" - -[tool.hatch.build.targets.wheel] -packages = ["src/agents"] - - -[tool.ruff] -line-length = 100 -target-version = "py39" - -[tool.ruff.lint] -select = [ - "E", # pycodestyle errors - "W", # pycodestyle warnings - "F", # pyflakes - "I", # isort - "B", # flake8-bugbear - "C4", # flake8-comprehensions - "UP", # pyupgrade -] -isort = { combine-as-imports = true, known-first-party = ["agents"] } - -[tool.ruff.lint.pydocstyle] -convention = "google" - -[tool.ruff.lint.per-file-ignores] -"examples/**/*.py" = ["E501"] - -[tool.mypy] -strict = true -disallow_incomplete_defs = false -disallow_untyped_defs = false -disallow_untyped_calls = false - -[tool.coverage.run] -source = [ - "tests", - "src/agents", -] - -[tool.coverage.report] -show_missing = true -sort = "-Cover" -exclude_also = [ - # This is only executed while typechecking - "if TYPE_CHECKING:", - "@abc.abstractmethod", - "raise NotImplementedError", - "logger.debug", -] - -[tool.pytest.ini_options] -asyncio_mode = "auto" -asyncio_default_fixture_loop_scope = "session" -filterwarnings = [ - # This is a warning that is expected to happen: we have an async filter that raises an exception - "ignore:coroutine 'test_async_input_filter_fails..invalid_input_filter' was never awaited:RuntimeWarning", -] -markers = [ - "allow_call_model_methods: mark test as allowing calls to real model implementations", -] \ No newline at end of file diff --git a/tests/src/agents/__init__.py b/tests/src/agents/__init__.py deleted file mode 100644 index 69c500ab..00000000 --- a/tests/src/agents/__init__.py +++ /dev/null @@ -1,223 +0,0 @@ -import logging -import sys -from typing import Literal - -from openai import AsyncOpenAI - -from . import _config -from .agent import Agent -from .agent_output import AgentOutputSchema -from .computer import AsyncComputer, Button, Computer, Environment -from .exceptions import ( - AgentsException, - InputGuardrailTripwireTriggered, - MaxTurnsExceeded, - ModelBehaviorError, - OutputGuardrailTripwireTriggered, - UserError, -) -from .guardrail import ( - GuardrailFunctionOutput, - InputGuardrail, - InputGuardrailResult, - OutputGuardrail, - OutputGuardrailResult, - input_guardrail, - output_guardrail, -) -from .handoffs import Handoff, HandoffInputData, HandoffInputFilter, handoff -from .items import ( - HandoffCallItem, - HandoffOutputItem, - ItemHelpers, - MessageOutputItem, - ModelResponse, - ReasoningItem, - RunItem, - ToolCallItem, - ToolCallOutputItem, - TResponseInputItem, -) -from .lifecycle import AgentHooks, RunHooks -from .model_settings import ModelSettings -from .models.interface import Model, ModelProvider, ModelTracing -from .models.openai_chatcompletions import OpenAIChatCompletionsModel -from .models.openai_provider import OpenAIProvider -from .models.openai_responses import OpenAIResponsesModel -from .result import RunResult, RunResultStreaming -from .run import RunConfig, Runner -from .run_context import RunContextWrapper, TContext -from .stream_events import ( - AgentUpdatedStreamEvent, - RawResponsesStreamEvent, - RunItemStreamEvent, - StreamEvent, -) -from .tool import ( - ComputerTool, - FileSearchTool, - FunctionTool, - Tool, - WebSearchTool, - default_tool_error_function, - function_tool, -) -from .tracing import ( - AgentSpanData, - CustomSpanData, - FunctionSpanData, - GenerationSpanData, - GuardrailSpanData, - HandoffSpanData, - Span, - SpanData, - SpanError, - Trace, - add_trace_processor, - agent_span, - custom_span, - function_span, - gen_span_id, - gen_trace_id, - generation_span, - get_current_span, - get_current_trace, - guardrail_span, - handoff_span, - set_trace_processors, - set_tracing_disabled, - set_tracing_export_api_key, - trace, -) -from .usage import Usage - - -def set_default_openai_key(key: str) -> None: - """Set the default OpenAI API key to use for LLM requests and tracing. This is only necessary if - the OPENAI_API_KEY environment variable is not already set. - - If provided, this key will be used instead of the OPENAI_API_KEY environment variable. - """ - _config.set_default_openai_key(key) - - -def set_default_openai_client(client: AsyncOpenAI, use_for_tracing: bool = True) -> None: - """Set the default OpenAI client to use for LLM requests and/or tracing. If provided, this - client will be used instead of the default OpenAI client. - - Args: - client: The OpenAI client to use. - use_for_tracing: Whether to use the API key from this client for uploading traces. If False, - you'll either need to set the OPENAI_API_KEY environment variable or call - set_tracing_export_api_key() with the API key you want to use for tracing. - """ - _config.set_default_openai_client(client, use_for_tracing) - - -def set_default_openai_api(api: Literal["chat_completions", "responses"]) -> None: - """Set the default API to use for OpenAI LLM requests. By default, we will use the responses API - but you can set this to use the chat completions API instead. - """ - _config.set_default_openai_api(api) - - -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)) - - -__all__ = [ - "Agent", - "Runner", - "Model", - "ModelProvider", - "ModelTracing", - "ModelSettings", - "OpenAIChatCompletionsModel", - "OpenAIProvider", - "OpenAIResponsesModel", - "AgentOutputSchema", - "Computer", - "AsyncComputer", - "Environment", - "Button", - "AgentsException", - "InputGuardrailTripwireTriggered", - "OutputGuardrailTripwireTriggered", - "MaxTurnsExceeded", - "ModelBehaviorError", - "UserError", - "InputGuardrail", - "InputGuardrailResult", - "OutputGuardrail", - "OutputGuardrailResult", - "GuardrailFunctionOutput", - "input_guardrail", - "output_guardrail", - "handoff", - "Handoff", - "HandoffInputData", - "HandoffInputFilter", - "TResponseInputItem", - "MessageOutputItem", - "ModelResponse", - "RunItem", - "HandoffCallItem", - "HandoffOutputItem", - "ToolCallItem", - "ToolCallOutputItem", - "ReasoningItem", - "ModelResponse", - "ItemHelpers", - "RunHooks", - "AgentHooks", - "RunContextWrapper", - "TContext", - "RunResult", - "RunResultStreaming", - "RunConfig", - "RawResponsesStreamEvent", - "RunItemStreamEvent", - "AgentUpdatedStreamEvent", - "StreamEvent", - "FunctionTool", - "ComputerTool", - "FileSearchTool", - "Tool", - "WebSearchTool", - "function_tool", - "Usage", - "add_trace_processor", - "agent_span", - "custom_span", - "function_span", - "generation_span", - "get_current_span", - "get_current_trace", - "guardrail_span", - "handoff_span", - "set_trace_processors", - "set_tracing_disabled", - "trace", - "Trace", - "SpanError", - "Span", - "SpanData", - "AgentSpanData", - "CustomSpanData", - "FunctionSpanData", - "GenerationSpanData", - "GuardrailSpanData", - "HandoffSpanData", - "set_default_openai_key", - "set_default_openai_client", - "set_default_openai_api", - "set_tracing_export_api_key", - "enable_verbose_stdout_logging", - "gen_trace_id", - "gen_span_id", - "default_tool_error_function", -] diff --git a/tests/src/agents/_config.py b/tests/src/agents/_config.py deleted file mode 100644 index 55ded64d..00000000 --- a/tests/src/agents/_config.py +++ /dev/null @@ -1,23 +0,0 @@ -from openai import AsyncOpenAI -from typing_extensions import Literal - -from .models import _openai_shared -from .tracing import set_tracing_export_api_key - - -def set_default_openai_key(key: str) -> None: - set_tracing_export_api_key(key) - _openai_shared.set_default_openai_key(key) - - -def set_default_openai_client(client: AsyncOpenAI, use_for_tracing: bool) -> None: - if use_for_tracing: - set_tracing_export_api_key(client.api_key) - _openai_shared.set_default_openai_client(client) - - -def set_default_openai_api(api: Literal["chat_completions", "responses"]) -> None: - if api == "chat_completions": - _openai_shared.set_use_responses_by_default(False) - else: - _openai_shared.set_use_responses_by_default(True) diff --git a/tests/src/agents/_debug.py b/tests/src/agents/_debug.py deleted file mode 100644 index 4da91be4..00000000 --- a/tests/src/agents/_debug.py +++ /dev/null @@ -1,17 +0,0 @@ -import os - - -def _debug_flag_enabled(flag: str) -> bool: - flag_value = os.getenv(flag) - return flag_value is not None and (flag_value == "1" or flag_value.lower() == "true") - - -DONT_LOG_MODEL_DATA = _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_MODEL_DATA") -"""By default we don't log LLM inputs/outputs, to prevent exposing sensitive information. Set this -flag to enable logging them. -""" - -DONT_LOG_TOOL_DATA = _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_TOOL_DATA") -"""By default we don't log tool call inputs/outputs, to prevent exposing sensitive information. Set -this flag to enable logging them. -""" diff --git a/tests/src/agents/_run_impl.py b/tests/src/agents/_run_impl.py deleted file mode 100644 index 112819c8..00000000 --- a/tests/src/agents/_run_impl.py +++ /dev/null @@ -1,792 +0,0 @@ -from __future__ import annotations - -import asyncio -from dataclasses import dataclass -from typing import TYPE_CHECKING, Any - -from openai.types.responses import ( - ResponseComputerToolCall, - ResponseFileSearchToolCall, - ResponseFunctionToolCall, - ResponseFunctionWebSearch, - ResponseOutputMessage, -) -from openai.types.responses.response_computer_tool_call import ( - ActionClick, - ActionDoubleClick, - ActionDrag, - ActionKeypress, - ActionMove, - ActionScreenshot, - ActionScroll, - ActionType, - ActionWait, -) -from openai.types.responses.response_input_param import ComputerCallOutput -from openai.types.responses.response_output_item import Reasoning - -from . import _utils -from .agent import Agent -from .agent_output import AgentOutputSchema -from .computer import AsyncComputer, Computer -from .exceptions import AgentsException, ModelBehaviorError, UserError -from .guardrail import InputGuardrail, InputGuardrailResult, OutputGuardrail, OutputGuardrailResult -from .handoffs import Handoff, HandoffInputData -from .items import ( - HandoffCallItem, - HandoffOutputItem, - ItemHelpers, - MessageOutputItem, - ModelResponse, - ReasoningItem, - RunItem, - ToolCallItem, - ToolCallOutputItem, - TResponseInputItem, -) -from .lifecycle import RunHooks -from .logger import logger -from .models.interface import ModelTracing -from .run_context import RunContextWrapper, TContext -from .stream_events import RunItemStreamEvent, StreamEvent -from .tool import ComputerTool, FunctionTool -from .tracing import ( - SpanError, - Trace, - function_span, - get_current_trace, - guardrail_span, - handoff_span, - trace, -) - -if TYPE_CHECKING: - from .run import RunConfig - - -class QueueCompleteSentinel: - pass - - -QUEUE_COMPLETE_SENTINEL = QueueCompleteSentinel() - - -@dataclass -class ToolRunHandoff: - handoff: Handoff - tool_call: ResponseFunctionToolCall - - -@dataclass -class ToolRunFunction: - tool_call: ResponseFunctionToolCall - function_tool: FunctionTool - - -@dataclass -class ToolRunComputerAction: - tool_call: ResponseComputerToolCall - computer_tool: ComputerTool - - -@dataclass -class ProcessedResponse: - new_items: list[RunItem] - handoffs: list[ToolRunHandoff] - functions: list[ToolRunFunction] - computer_actions: list[ToolRunComputerAction] - - def has_tools_to_run(self) -> bool: - # Handoffs, functions and computer actions need local processing - # Hosted tools have already run, so there's nothing to do. - return any( - [ - self.handoffs, - self.functions, - self.computer_actions, - ] - ) - - -@dataclass -class NextStepHandoff: - new_agent: Agent[Any] - - -@dataclass -class NextStepFinalOutput: - output: Any - - -@dataclass -class NextStepRunAgain: - pass - - -@dataclass -class SingleStepResult: - original_input: str | list[TResponseInputItem] - """The input items i.e. the items before run() was called. May be mutated by handoff input - filters.""" - - model_response: ModelResponse - """The model response for the current step.""" - - pre_step_items: list[RunItem] - """Items generated before the current step.""" - - new_step_items: list[RunItem] - """Items generated during this current step.""" - - next_step: NextStepHandoff | NextStepFinalOutput | NextStepRunAgain - """The next step to take.""" - - @property - def generated_items(self) -> list[RunItem]: - """Items generated during the agent run (i.e. everything generated after - `original_input`).""" - return self.pre_step_items + self.new_step_items - - -def get_model_tracing_impl( - tracing_disabled: bool, trace_include_sensitive_data: bool -) -> ModelTracing: - if tracing_disabled: - return ModelTracing.DISABLED - elif trace_include_sensitive_data: - return ModelTracing.ENABLED - else: - return ModelTracing.ENABLED_WITHOUT_DATA - - -class RunImpl: - @classmethod - async def execute_tools_and_side_effects( - cls, - *, - agent: Agent[TContext], - # The original input to the Runner - original_input: str | list[TResponseInputItem], - # Eveything generated by Runner since the original input, but before the current step - pre_step_items: list[RunItem], - new_response: ModelResponse, - processed_response: ProcessedResponse, - output_schema: AgentOutputSchema | None, - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - run_config: RunConfig, - ) -> SingleStepResult: - # Make a copy of the generated items - pre_step_items = list(pre_step_items) - - new_step_items: list[RunItem] = [] - new_step_items.extend(processed_response.new_items) - - # First, lets run the tool calls - function tools and computer actions - function_results, computer_results = await asyncio.gather( - cls.execute_function_tool_calls( - agent=agent, - tool_runs=processed_response.functions, - hooks=hooks, - context_wrapper=context_wrapper, - config=run_config, - ), - cls.execute_computer_actions( - agent=agent, - actions=processed_response.computer_actions, - hooks=hooks, - context_wrapper=context_wrapper, - config=run_config, - ), - ) - new_step_items.extend(function_results) - new_step_items.extend(computer_results) - - # Second, check if there are any handoffs - if run_handoffs := processed_response.handoffs: - return await cls.execute_handoffs( - agent=agent, - original_input=original_input, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - new_response=new_response, - run_handoffs=run_handoffs, - hooks=hooks, - context_wrapper=context_wrapper, - run_config=run_config, - ) - - # Now we can check if the model also produced a final output - message_items = [item for item in new_step_items if isinstance(item, MessageOutputItem)] - - # We'll use the last content output as the final output - potential_final_output_text = ( - ItemHelpers.extract_last_text(message_items[-1].raw_item) if message_items else None - ) - - # There are two possibilities that lead to a final output: - # 1. Structured output schema => always leads to a final output - # 2. Plain text output schema => only leads to a final output if there are no tool calls - if output_schema and not output_schema.is_plain_text() and potential_final_output_text: - final_output = output_schema.validate_json(potential_final_output_text) - return await cls.execute_final_output( - agent=agent, - original_input=original_input, - new_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - final_output=final_output, - hooks=hooks, - context_wrapper=context_wrapper, - ) - elif ( - not output_schema or output_schema.is_plain_text() - ) and not processed_response.has_tools_to_run(): - return await cls.execute_final_output( - agent=agent, - original_input=original_input, - new_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - final_output=potential_final_output_text or "", - hooks=hooks, - context_wrapper=context_wrapper, - ) - else: - # If there's no final output, we can just run again - return SingleStepResult( - original_input=original_input, - model_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - next_step=NextStepRunAgain(), - ) - - @classmethod - def process_model_response( - cls, - *, - agent: Agent[Any], - response: ModelResponse, - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - ) -> ProcessedResponse: - items: list[RunItem] = [] - - run_handoffs = [] - functions = [] - computer_actions = [] - - handoff_map = {handoff.tool_name: handoff for handoff in handoffs} - function_map = {tool.name: tool for tool in agent.tools if isinstance(tool, FunctionTool)} - computer_tool = next((tool for tool in agent.tools if isinstance(tool, ComputerTool)), None) - - for output in response.output: - if isinstance(output, ResponseOutputMessage): - items.append(MessageOutputItem(raw_item=output, agent=agent)) - elif isinstance(output, ResponseFileSearchToolCall): - items.append(ToolCallItem(raw_item=output, agent=agent)) - elif isinstance(output, ResponseFunctionWebSearch): - items.append(ToolCallItem(raw_item=output, agent=agent)) - elif isinstance(output, Reasoning): - items.append(ReasoningItem(raw_item=output, agent=agent)) - elif isinstance(output, ResponseComputerToolCall): - items.append(ToolCallItem(raw_item=output, agent=agent)) - if not computer_tool: - _utils.attach_error_to_current_span( - SpanError( - message="Computer tool not found", - data={}, - ) - ) - raise ModelBehaviorError( - "Model produced computer action without a computer tool." - ) - computer_actions.append( - ToolRunComputerAction(tool_call=output, computer_tool=computer_tool) - ) - elif not isinstance(output, ResponseFunctionToolCall): - logger.warning(f"Unexpected output type, ignoring: {type(output)}") - continue - - # At this point we know it's a function tool call - if not isinstance(output, ResponseFunctionToolCall): - continue - - # Handoffs - if output.name in handoff_map: - items.append(HandoffCallItem(raw_item=output, agent=agent)) - handoff = ToolRunHandoff( - tool_call=output, - handoff=handoff_map[output.name], - ) - run_handoffs.append(handoff) - # Regular function tool call - else: - if output.name not in function_map: - _utils.attach_error_to_current_span( - SpanError( - message="Tool not found", - data={"tool_name": output.name}, - ) - ) - raise ModelBehaviorError(f"Tool {output.name} not found in agent {agent.name}") - items.append(ToolCallItem(raw_item=output, agent=agent)) - functions.append( - ToolRunFunction( - tool_call=output, - function_tool=function_map[output.name], - ) - ) - - return ProcessedResponse( - new_items=items, - handoffs=run_handoffs, - functions=functions, - computer_actions=computer_actions, - ) - - @classmethod - async def execute_function_tool_calls( - cls, - *, - agent: Agent[TContext], - tool_runs: list[ToolRunFunction], - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - config: RunConfig, - ) -> list[RunItem]: - async def run_single_tool( - func_tool: FunctionTool, tool_call: ResponseFunctionToolCall - ) -> str: - with function_span(func_tool.name) as span_fn: - if config.trace_include_sensitive_data: - span_fn.span_data.input = tool_call.arguments - try: - _, _, result = await asyncio.gather( - hooks.on_tool_start(context_wrapper, agent, func_tool), - ( - agent.hooks.on_tool_start(context_wrapper, agent, func_tool) - if agent.hooks - else _utils.noop_coroutine() - ), - func_tool.on_invoke_tool(context_wrapper, tool_call.arguments), - ) - - await asyncio.gather( - hooks.on_tool_end(context_wrapper, agent, func_tool, result), - ( - agent.hooks.on_tool_end(context_wrapper, agent, func_tool, result) - if agent.hooks - else _utils.noop_coroutine() - ), - ) - except Exception as e: - _utils.attach_error_to_current_span( - SpanError( - message="Error running tool", - data={"tool_name": func_tool.name, "error": str(e)}, - ) - ) - if isinstance(e, AgentsException): - raise e - raise UserError(f"Error running tool {func_tool.name}: {e}") from e - - if config.trace_include_sensitive_data: - span_fn.span_data.output = result - return result - - tasks = [] - for tool_run in tool_runs: - function_tool = tool_run.function_tool - tasks.append(run_single_tool(function_tool, tool_run.tool_call)) - - results = await asyncio.gather(*tasks) - - return [ - ToolCallOutputItem( - output=str(result), - raw_item=ItemHelpers.tool_call_output_item(tool_run.tool_call, str(result)), - agent=agent, - ) - for tool_run, result in zip(tool_runs, results) - ] - - @classmethod - async def execute_computer_actions( - cls, - *, - agent: Agent[TContext], - actions: list[ToolRunComputerAction], - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - config: RunConfig, - ) -> list[RunItem]: - results: list[RunItem] = [] - # Need to run these serially, because each action can affect the computer state - for action in actions: - results.append( - await ComputerAction.execute( - agent=agent, - action=action, - hooks=hooks, - context_wrapper=context_wrapper, - config=config, - ) - ) - - return results - - @classmethod - async def execute_handoffs( - cls, - *, - agent: Agent[TContext], - original_input: str | list[TResponseInputItem], - pre_step_items: list[RunItem], - new_step_items: list[RunItem], - new_response: ModelResponse, - run_handoffs: list[ToolRunHandoff], - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - run_config: RunConfig, - ) -> SingleStepResult: - # If there is more than one handoff, add tool responses that reject those handoffs - if len(run_handoffs) > 1: - output_message = "Multiple handoffs detected, ignoring this one." - new_step_items.extend( - [ - ToolCallOutputItem( - output=output_message, - raw_item=ItemHelpers.tool_call_output_item( - handoff.tool_call, output_message - ), - agent=agent, - ) - for handoff in run_handoffs[1:] - ] - ) - - actual_handoff = run_handoffs[0] - with handoff_span(from_agent=agent.name) as span_handoff: - handoff = actual_handoff.handoff - new_agent: Agent[Any] = await handoff.on_invoke_handoff( - context_wrapper, actual_handoff.tool_call.arguments - ) - span_handoff.span_data.to_agent = new_agent.name - - # Append a tool output item for the handoff - new_step_items.append( - HandoffOutputItem( - agent=agent, - raw_item=ItemHelpers.tool_call_output_item( - actual_handoff.tool_call, - handoff.get_transfer_message(new_agent), - ), - source_agent=agent, - target_agent=new_agent, - ) - ) - - # Execute handoff hooks - await asyncio.gather( - hooks.on_handoff( - context=context_wrapper, - from_agent=agent, - to_agent=new_agent, - ), - ( - agent.hooks.on_handoff( - context_wrapper, - agent=new_agent, - source=agent, - ) - if agent.hooks - else _utils.noop_coroutine() - ), - ) - - # If there's an input filter, filter the input for the next agent - input_filter = handoff.input_filter or ( - run_config.handoff_input_filter if run_config else None - ) - if input_filter: - logger.debug("Filtering inputs for handoff") - handoff_input_data = HandoffInputData( - input_history=tuple(original_input) - if isinstance(original_input, list) - else original_input, - pre_handoff_items=tuple(pre_step_items), - new_items=tuple(new_step_items), - ) - if not callable(input_filter): - _utils.attach_error_to_span( - span_handoff, - SpanError( - message="Invalid input filter", - data={"details": "not callable()"}, - ), - ) - raise UserError(f"Invalid input filter: {input_filter}") - filtered = input_filter(handoff_input_data) - if not isinstance(filtered, HandoffInputData): - _utils.attach_error_to_span( - span_handoff, - SpanError( - message="Invalid input filter result", - data={"details": "not a HandoffInputData"}, - ), - ) - raise UserError(f"Invalid input filter result: {filtered}") - - original_input = ( - filtered.input_history - if isinstance(filtered.input_history, str) - else list(filtered.input_history) - ) - pre_step_items = list(filtered.pre_handoff_items) - new_step_items = list(filtered.new_items) - - return SingleStepResult( - original_input=original_input, - model_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - next_step=NextStepHandoff(new_agent), - ) - - @classmethod - async def execute_final_output( - cls, - *, - agent: Agent[TContext], - original_input: str | list[TResponseInputItem], - new_response: ModelResponse, - pre_step_items: list[RunItem], - new_step_items: list[RunItem], - final_output: Any, - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - ) -> SingleStepResult: - # Run the on_end hooks - await cls.run_final_output_hooks(agent, hooks, context_wrapper, final_output) - - return SingleStepResult( - original_input=original_input, - model_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - next_step=NextStepFinalOutput(final_output), - ) - - @classmethod - async def run_final_output_hooks( - cls, - agent: Agent[TContext], - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - final_output: Any, - ): - await asyncio.gather( - 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(), - ) - - @classmethod - async def run_single_input_guardrail( - cls, - agent: Agent[Any], - guardrail: InputGuardrail[TContext], - input: str | list[TResponseInputItem], - context: RunContextWrapper[TContext], - ) -> InputGuardrailResult: - with guardrail_span(guardrail.get_name()) as span_guardrail: - result = await guardrail.run(agent, input, context) - span_guardrail.span_data.triggered = result.output.tripwire_triggered - return result - - @classmethod - async def run_single_output_guardrail( - cls, - guardrail: OutputGuardrail[TContext], - agent: Agent[Any], - agent_output: Any, - context: RunContextWrapper[TContext], - ) -> OutputGuardrailResult: - with guardrail_span(guardrail.get_name()) as span_guardrail: - result = await guardrail.run(agent=agent, agent_output=agent_output, context=context) - span_guardrail.span_data.triggered = result.output.tripwire_triggered - return result - - @classmethod - def stream_step_result_to_queue( - cls, - step_result: SingleStepResult, - queue: asyncio.Queue[StreamEvent | QueueCompleteSentinel], - ): - for item in step_result.new_step_items: - if isinstance(item, MessageOutputItem): - event = RunItemStreamEvent(item=item, name="message_output_created") - elif isinstance(item, HandoffCallItem): - event = RunItemStreamEvent(item=item, name="handoff_requested") - elif isinstance(item, HandoffOutputItem): - event = RunItemStreamEvent(item=item, name="handoff_occured") - elif isinstance(item, ToolCallItem): - event = RunItemStreamEvent(item=item, name="tool_called") - elif isinstance(item, ToolCallOutputItem): - event = RunItemStreamEvent(item=item, name="tool_output") - elif isinstance(item, ReasoningItem): - event = RunItemStreamEvent(item=item, name="reasoning_item_created") - else: - logger.warning(f"Unexpected item type: {type(item)}") - event = None - - if event: - queue.put_nowait(event) - - -class TraceCtxManager: - """Creates a trace only if there is no current trace, and manages the trace lifecycle.""" - - def __init__( - self, - workflow_name: str, - trace_id: str | None, - group_id: str | None, - metadata: dict[str, Any] | None, - disabled: bool, - ): - self.trace: Trace | None = None - self.workflow_name = workflow_name - self.trace_id = trace_id - self.group_id = group_id - self.metadata = metadata - self.disabled = disabled - - def __enter__(self) -> TraceCtxManager: - current_trace = get_current_trace() - if not current_trace: - self.trace = trace( - workflow_name=self.workflow_name, - trace_id=self.trace_id, - group_id=self.group_id, - metadata=self.metadata, - disabled=self.disabled, - ) - self.trace.start(mark_as_current=True) - - return self - - def __exit__(self, exc_type, exc_val, exc_tb): - if self.trace: - self.trace.finish(reset_current=True) - - -class ComputerAction: - @classmethod - async def execute( - cls, - *, - agent: Agent[TContext], - action: ToolRunComputerAction, - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - config: RunConfig, - ) -> RunItem: - output_func = ( - cls._get_screenshot_async(action.computer_tool.computer, action.tool_call) - if isinstance(action.computer_tool.computer, AsyncComputer) - else cls._get_screenshot_sync(action.computer_tool.computer, action.tool_call) - ) - - _, _, output = await asyncio.gather( - hooks.on_tool_start(context_wrapper, agent, action.computer_tool), - ( - agent.hooks.on_tool_start(context_wrapper, agent, action.computer_tool) - if agent.hooks - else _utils.noop_coroutine() - ), - output_func, - ) - - await asyncio.gather( - hooks.on_tool_end(context_wrapper, agent, action.computer_tool, output), - ( - agent.hooks.on_tool_end(context_wrapper, agent, action.computer_tool, output) - if agent.hooks - else _utils.noop_coroutine() - ), - ) - - # TODO: don't send a screenshot every single time, use references - image_url = f"data:image/png;base64,{output}" - return ToolCallOutputItem( - agent=agent, - output=image_url, - raw_item=ComputerCallOutput( - call_id=action.tool_call.call_id, - output={ - "type": "computer_screenshot", - "image_url": image_url, - }, - type="computer_call_output", - ), - ) - - @classmethod - async def _get_screenshot_sync( - cls, - computer: Computer, - tool_call: ResponseComputerToolCall, - ) -> str: - action = tool_call.action - if isinstance(action, ActionClick): - computer.click(action.x, action.y, action.button) - elif isinstance(action, ActionDoubleClick): - computer.double_click(action.x, action.y) - elif isinstance(action, ActionDrag): - computer.drag([(p.x, p.y) for p in action.path]) - elif isinstance(action, ActionKeypress): - computer.keypress(action.keys) - elif isinstance(action, ActionMove): - computer.move(action.x, action.y) - elif isinstance(action, ActionScreenshot): - computer.screenshot() - elif isinstance(action, ActionScroll): - computer.scroll(action.x, action.y, action.scroll_x, action.scroll_y) - elif isinstance(action, ActionType): - computer.type(action.text) - elif isinstance(action, ActionWait): - computer.wait() - - return computer.screenshot() - - @classmethod - async def _get_screenshot_async( - cls, - computer: AsyncComputer, - tool_call: ResponseComputerToolCall, - ) -> str: - action = tool_call.action - if isinstance(action, ActionClick): - await computer.click(action.x, action.y, action.button) - elif isinstance(action, ActionDoubleClick): - await computer.double_click(action.x, action.y) - elif isinstance(action, ActionDrag): - await computer.drag([(p.x, p.y) for p in action.path]) - elif isinstance(action, ActionKeypress): - await computer.keypress(action.keys) - elif isinstance(action, ActionMove): - await computer.move(action.x, action.y) - elif isinstance(action, ActionScreenshot): - await computer.screenshot() - elif isinstance(action, ActionScroll): - await computer.scroll(action.x, action.y, action.scroll_x, action.scroll_y) - elif isinstance(action, ActionType): - await computer.type(action.text) - elif isinstance(action, ActionWait): - await computer.wait() - - return await computer.screenshot() diff --git a/tests/src/agents/_utils.py b/tests/src/agents/_utils.py deleted file mode 100644 index 2a0293a6..00000000 --- a/tests/src/agents/_utils.py +++ /dev/null @@ -1,61 +0,0 @@ -from __future__ import annotations - -import re -from collections.abc import Awaitable -from typing import Any, Literal, Union - -from pydantic import TypeAdapter, ValidationError -from typing_extensions import TypeVar - -from .exceptions import ModelBehaviorError -from .logger import logger -from .tracing import Span, SpanError, get_current_span - -T = TypeVar("T") - -MaybeAwaitable = Union[Awaitable[T], T] - - -def transform_string_function_style(name: str) -> str: - # Replace spaces with underscores - name = name.replace(" ", "_") - - # Replace non-alphanumeric characters with underscores - name = re.sub(r"[^a-zA-Z0-9]", "_", name) - - return name.lower() - - -def validate_json(json_str: str, type_adapter: TypeAdapter[T], partial: bool) -> T: - partial_setting: bool | Literal["off", "on", "trailing-strings"] = ( - "trailing-strings" if partial else False - ) - try: - validated = type_adapter.validate_json(json_str, experimental_allow_partial=partial_setting) - return validated - except ValidationError as e: - attach_error_to_current_span( - SpanError( - message="Invalid JSON provided", - data={}, - ) - ) - raise ModelBehaviorError( - f"Invalid JSON when parsing {json_str} for {type_adapter}; {e}" - ) from e - - -def attach_error_to_span(span: Span[Any], error: SpanError) -> None: - span.set_error(error) - - -def attach_error_to_current_span(error: SpanError) -> None: - span = get_current_span() - if span: - attach_error_to_span(span, error) - else: - logger.warning(f"No span to add error {error} to") - - -async def noop_coroutine() -> None: - pass diff --git a/tests/src/agents/agent.py b/tests/src/agents/agent.py deleted file mode 100644 index 61c0a896..00000000 --- a/tests/src/agents/agent.py +++ /dev/null @@ -1,159 +0,0 @@ -from __future__ import annotations - -import dataclasses -import inspect -from collections.abc import Awaitable -from dataclasses import dataclass, field -from typing import TYPE_CHECKING, Any, Callable, Generic, cast - -from . import _utils -from ._utils import MaybeAwaitable -from .guardrail import InputGuardrail, OutputGuardrail -from .handoffs import Handoff -from .items import ItemHelpers -from .logger import logger -from .model_settings import ModelSettings -from .models.interface import Model -from .run_context import RunContextWrapper, TContext -from .tool import Tool, function_tool - -if TYPE_CHECKING: - from .lifecycle import AgentHooks - from .result import RunResult - - -@dataclass -class Agent(Generic[TContext]): - """An agent is an AI model configured with instructions, tools, guardrails, handoffs and more. - - We strongly recommend passing `instructions`, which is the "system prompt" for the agent. In - addition, you can pass `description`, which is a human-readable description of the agent, used - when the agent is used inside tools/handoffs. - - Agents are generic on the context type. The context is a (mutable) object you create. It is - passed to tool functions, handoffs, guardrails, etc. - """ - - name: str - """The name of the agent.""" - - instructions: ( - str - | Callable[ - [RunContextWrapper[TContext], Agent[TContext]], - MaybeAwaitable[str], - ] - | None - ) = None - """The instructions for the agent. Will be used as the "system prompt" when this agent is - invoked. Describes what the agent should do, and how it responds. - - Can either be a string, or a function that dynamically generates instructions for the agent. If - you provide a function, it will be called with the context and the agent instance. It must - return a string. - """ - - handoff_description: str | None = None - """A description of the agent. This is used when the agent is used as a handoff, so that an - LLM knows what it does and when to invoke it. - """ - - handoffs: list[Agent[Any] | Handoff[TContext]] = field(default_factory=list) - """Handoffs are sub-agents that the agent can delegate to. You can provide a list of handoffs, - and the agent can choose to delegate to them if relevant. Allows for separation of concerns and - modularity. - """ - - model: str | Model | None = None - """The model implementation to use when invoking the LLM. - - By default, if not set, the agent will use the default model configured in - `model_settings.DEFAULT_MODEL`. - """ - - model_settings: ModelSettings = field(default_factory=ModelSettings) - """Configures model-specific tuning parameters (e.g. temperature, top_p). - """ - - tools: list[Tool] = field(default_factory=list) - """A list of tools that the agent can use.""" - - input_guardrails: list[InputGuardrail[TContext]] = field(default_factory=list) - """A list of checks that run in parallel to the agent's execution, before generating a - response. Runs only if the agent is the first agent in the chain. - """ - - output_guardrails: list[OutputGuardrail[TContext]] = field(default_factory=list) - """A list of checks that run on the final output of the agent, after generating a response. - Runs only if the agent produces a final output. - """ - - output_type: type[Any] | None = None - """The type of the output object. If not provided, the output will be `str`.""" - - hooks: AgentHooks[TContext] | None = None - """A class that receives callbacks on various lifecycle events for this agent. - """ - - def clone(self, **kwargs: Any) -> Agent[TContext]: - """Make a copy of the agent, with the given arguments changed. For example, you could do: - ``` - new_agent = agent.clone(instructions="New instructions") - ``` - """ - return dataclasses.replace(self, **kwargs) - - def as_tool( - self, - tool_name: str | None, - tool_description: str | None, - custom_output_extractor: Callable[[RunResult], Awaitable[str]] | None = None, - ) -> Tool: - """Transform this agent into a tool, callable by other agents. - - This is different from handoffs in two ways: - 1. In handoffs, the new agent receives the conversation history. In this tool, the new agent - receives generated input. - 2. In handoffs, the new agent takes over the conversation. In this tool, the new agent is - called as a tool, and the conversation is continued by the original agent. - - Args: - tool_name: The name of the tool. If not provided, the agent's name will be used. - tool_description: The description of the tool, which should indicate what it does and - when to use it. - custom_output_extractor: A function that extracts the output from the agent. If not - provided, the last message from the agent will be used. - """ - - @function_tool( - name_override=tool_name or _utils.transform_string_function_style(self.name), - description_override=tool_description or "", - ) - async def run_agent(context: RunContextWrapper, input: str) -> str: - from .run import Runner - - output = await Runner.run( - starting_agent=self, - input=input, - context=context.context, - ) - if custom_output_extractor: - return await custom_output_extractor(output) - - return ItemHelpers.text_message_outputs(output.new_items) - - return run_agent - - async def get_system_prompt(self, run_context: RunContextWrapper[TContext]) -> str | None: - """Get the system prompt for the agent.""" - if isinstance(self.instructions, str): - return self.instructions - elif callable(self.instructions): - if inspect.iscoroutinefunction(self.instructions): - return await cast(Awaitable[str], self.instructions(run_context, self)) - else: - return cast(str, self.instructions(run_context, self)) - elif self.instructions is not None: - logger.error(f"Instructions must be a string or a function, got {self.instructions}") - - return None diff --git a/tests/src/agents/agent_output.py b/tests/src/agents/agent_output.py deleted file mode 100644 index 8140d8c6..00000000 --- a/tests/src/agents/agent_output.py +++ /dev/null @@ -1,144 +0,0 @@ -from dataclasses import dataclass -from typing import Any - -from pydantic import BaseModel, TypeAdapter -from typing_extensions import TypedDict, get_args, get_origin - -from . import _utils -from .exceptions import ModelBehaviorError, UserError -from .strict_schema import ensure_strict_json_schema -from .tracing import SpanError - -_WRAPPER_DICT_KEY = "response" - - -@dataclass(init=False) -class AgentOutputSchema: - """An object that captures the JSON schema of the output, as well as validating/parsing JSON - produced by the LLM into the output type. - """ - - output_type: type[Any] - """The type of the output.""" - - _type_adapter: TypeAdapter[Any] - """A type adapter that wraps the output type, so that we can validate JSON.""" - - _is_wrapped: bool - """Whether the output type is wrapped in a dictionary. This is generally done if the base - output type cannot be represented as a JSON Schema object. - """ - - _output_schema: dict[str, Any] - """The JSON schema of the output.""" - - strict_json_schema: bool - """Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True, - as it increases the likelihood of correct JSON input. - """ - - def __init__(self, output_type: type[Any], strict_json_schema: bool = True): - """ - Args: - output_type: The type of the output. - strict_json_schema: Whether the JSON schema is in strict mode. We **strongly** recommend - setting this to True, as it increases the likelihood of correct JSON input. - """ - self.output_type = output_type - self.strict_json_schema = strict_json_schema - - if output_type is None or output_type is str: - self._is_wrapped = False - self._type_adapter = TypeAdapter(output_type) - self._output_schema = self._type_adapter.json_schema() - return - - # We should wrap for things that are not plain text, and for things that would definitely - # not be a JSON Schema object. - self._is_wrapped = not _is_subclass_of_base_model_or_dict(output_type) - - if self._is_wrapped: - OutputType = TypedDict( - "OutputType", - { - _WRAPPER_DICT_KEY: output_type, # type: ignore - }, - ) - self._type_adapter = TypeAdapter(OutputType) - self._output_schema = self._type_adapter.json_schema() - else: - self._type_adapter = TypeAdapter(output_type) - self._output_schema = self._type_adapter.json_schema() - - if self.strict_json_schema: - self._output_schema = ensure_strict_json_schema(self._output_schema) - - def is_plain_text(self) -> bool: - """Whether the output type is plain text (versus a JSON object).""" - return self.output_type is None or self.output_type is str - - def json_schema(self) -> dict[str, Any]: - """The JSON schema of the output type.""" - if self.is_plain_text(): - raise UserError("Output type is plain text, so no JSON schema is available") - return self._output_schema - - def validate_json(self, json_str: str, partial: bool = False) -> Any: - """Validate a JSON string against the output type. Returns the validated object, or raises - a `ModelBehaviorError` if the JSON is invalid. - """ - validated = _utils.validate_json(json_str, self._type_adapter, partial) - if self._is_wrapped: - if not isinstance(validated, dict): - _utils.attach_error_to_current_span( - SpanError( - message="Invalid JSON", - data={"details": f"Expected a dict, got {type(validated)}"}, - ) - ) - raise ModelBehaviorError( - f"Expected a dict, got {type(validated)} for JSON: {json_str}" - ) - - if _WRAPPER_DICT_KEY not in validated: - _utils.attach_error_to_current_span( - SpanError( - message="Invalid JSON", - data={"details": f"Could not find key {_WRAPPER_DICT_KEY} in JSON"}, - ) - ) - raise ModelBehaviorError( - f"Could not find key {_WRAPPER_DICT_KEY} in JSON: {json_str}" - ) - return validated[_WRAPPER_DICT_KEY] - return validated - - def output_type_name(self) -> str: - """The name of the output type.""" - return _type_to_str(self.output_type) - - -def _is_subclass_of_base_model_or_dict(t: Any) -> bool: - if not isinstance(t, type): - return False - - # If it's a generic alias, 'origin' will be the actual type, e.g. 'list' - origin = get_origin(t) - - allowed_types = (BaseModel, dict) - # If it's a generic alias e.g. list[str], then we should check the origin type i.e. list - return issubclass(origin or t, allowed_types) - - -def _type_to_str(t: type[Any]) -> str: - origin = get_origin(t) - args = get_args(t) - - if origin is None: - # It's a simple type like `str`, `int`, etc. - return t.__name__ - elif args: - args_str = ', '.join(_type_to_str(arg) for arg in args) - return f"{origin.__name__}[{args_str}]" - else: - return str(t) diff --git a/tests/src/agents/computer.py b/tests/src/agents/computer.py deleted file mode 100644 index 1b9224d5..00000000 --- a/tests/src/agents/computer.py +++ /dev/null @@ -1,107 +0,0 @@ -import abc -from typing import Literal - -Environment = Literal["mac", "windows", "ubuntu", "browser"] -Button = Literal["left", "right", "wheel", "back", "forward"] - - -class Computer(abc.ABC): - """A computer implemented with sync operations. The Computer interface abstracts the - operations needed to control a computer or browser.""" - - @property - @abc.abstractmethod - def environment(self) -> Environment: - pass - - @property - @abc.abstractmethod - def dimensions(self) -> tuple[int, int]: - pass - - @abc.abstractmethod - def screenshot(self) -> str: - pass - - @abc.abstractmethod - def click(self, x: int, y: int, button: Button) -> None: - pass - - @abc.abstractmethod - def double_click(self, x: int, y: int) -> None: - pass - - @abc.abstractmethod - def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None: - pass - - @abc.abstractmethod - def type(self, text: str) -> None: - pass - - @abc.abstractmethod - def wait(self) -> None: - pass - - @abc.abstractmethod - def move(self, x: int, y: int) -> None: - pass - - @abc.abstractmethod - def keypress(self, keys: list[str]) -> None: - pass - - @abc.abstractmethod - def drag(self, path: list[tuple[int, int]]) -> None: - pass - - -class AsyncComputer(abc.ABC): - """A computer implemented with async operations. The Computer interface abstracts the - operations needed to control a computer or browser.""" - - @property - @abc.abstractmethod - def environment(self) -> Environment: - pass - - @property - @abc.abstractmethod - def dimensions(self) -> tuple[int, int]: - pass - - @abc.abstractmethod - async def screenshot(self) -> str: - pass - - @abc.abstractmethod - async def click(self, x: int, y: int, button: Button) -> None: - pass - - @abc.abstractmethod - async def double_click(self, x: int, y: int) -> None: - pass - - @abc.abstractmethod - async def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None: - pass - - @abc.abstractmethod - async def type(self, text: str) -> None: - pass - - @abc.abstractmethod - async def wait(self) -> None: - pass - - @abc.abstractmethod - async def move(self, x: int, y: int) -> None: - pass - - @abc.abstractmethod - async def keypress(self, keys: list[str]) -> None: - pass - - @abc.abstractmethod - async def drag(self, path: list[tuple[int, int]]) -> None: - pass diff --git a/tests/src/agents/exceptions.py b/tests/src/agents/exceptions.py deleted file mode 100644 index 78898f01..00000000 --- a/tests/src/agents/exceptions.py +++ /dev/null @@ -1,63 +0,0 @@ -from typing import TYPE_CHECKING - -if TYPE_CHECKING: - from .guardrail import InputGuardrailResult, OutputGuardrailResult - - -class AgentsException(Exception): - """Base class for all exceptions in the Agents SDK.""" - - -class MaxTurnsExceeded(AgentsException): - """Exception raised when the maximum number of turns is exceeded.""" - - message: str - - def __init__(self, message: str): - self.message = message - - -class ModelBehaviorError(AgentsException): - """Exception raised when the model does something unexpected, e.g. calling a tool that doesn't - exist, or providing malformed JSON. - """ - - message: str - - def __init__(self, message: str): - self.message = message - - -class UserError(AgentsException): - """Exception raised when the user makes an error using the SDK.""" - - message: str - - def __init__(self, message: str): - self.message = message - - -class InputGuardrailTripwireTriggered(AgentsException): - """Exception raised when a guardrail tripwire is triggered.""" - - guardrail_result: "InputGuardrailResult" - """The result data of the guardrail that was triggered.""" - - def __init__(self, guardrail_result: "InputGuardrailResult"): - self.guardrail_result = guardrail_result - super().__init__( - f"Guardrail {guardrail_result.guardrail.__class__.__name__} triggered tripwire" - ) - - -class OutputGuardrailTripwireTriggered(AgentsException): - """Exception raised when a guardrail tripwire is triggered.""" - - guardrail_result: "OutputGuardrailResult" - """The result data of the guardrail that was triggered.""" - - def __init__(self, guardrail_result: "OutputGuardrailResult"): - self.guardrail_result = guardrail_result - super().__init__( - f"Guardrail {guardrail_result.guardrail.__class__.__name__} triggered tripwire" - ) diff --git a/tests/src/agents/extensions/__init__.py b/tests/src/agents/extensions/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/tests/src/agents/extensions/handoff_filters.py b/tests/src/agents/extensions/handoff_filters.py deleted file mode 100644 index f4f9b8bf..00000000 --- a/tests/src/agents/extensions/handoff_filters.py +++ /dev/null @@ -1,67 +0,0 @@ -from __future__ import annotations - -from ..handoffs import HandoffInputData -from ..items import ( - HandoffCallItem, - HandoffOutputItem, - RunItem, - ToolCallItem, - ToolCallOutputItem, - TResponseInputItem, -) - -"""Contains common handoff input filters, for convenience. """ - - -def remove_all_tools(handoff_input_data: HandoffInputData) -> HandoffInputData: - """Filters out all tool items: file search, web search and function calls+output.""" - - history = handoff_input_data.input_history - new_items = handoff_input_data.new_items - - filtered_history = ( - _remove_tool_types_from_input(history) if isinstance(history, tuple) else history - ) - filtered_pre_handoff_items = _remove_tools_from_items(handoff_input_data.pre_handoff_items) - filtered_new_items = _remove_tools_from_items(new_items) - - return HandoffInputData( - input_history=filtered_history, - pre_handoff_items=filtered_pre_handoff_items, - new_items=filtered_new_items, - ) - - -def _remove_tools_from_items(items: tuple[RunItem, ...]) -> tuple[RunItem, ...]: - filtered_items = [] - for item in items: - if ( - isinstance(item, HandoffCallItem) - or isinstance(item, HandoffOutputItem) - or isinstance(item, ToolCallItem) - or isinstance(item, ToolCallOutputItem) - ): - continue - filtered_items.append(item) - return tuple(filtered_items) - - -def _remove_tool_types_from_input( - items: tuple[TResponseInputItem, ...], -) -> tuple[TResponseInputItem, ...]: - tool_types = [ - "function_call", - "function_call_output", - "computer_call", - "computer_call_output", - "file_search_call", - "web_search_call", - ] - - filtered_items: list[TResponseInputItem] = [] - for item in items: - itype = item.get("type") - if itype in tool_types: - continue - filtered_items.append(item) - return tuple(filtered_items) diff --git a/tests/src/agents/extensions/handoff_prompt.py b/tests/src/agents/extensions/handoff_prompt.py deleted file mode 100644 index cfb5ca7e..00000000 --- a/tests/src/agents/extensions/handoff_prompt.py +++ /dev/null @@ -1,19 +0,0 @@ -# A recommended prompt prefix for agents that use handoffs. We recommend including this or -# similar instructions in any agents that use handoffs. -RECOMMENDED_PROMPT_PREFIX = ( - "# System context\n" - "You are part of a multi-agent system called the Agents SDK, designed to make agent " - "coordination and execution easy. Agents uses two primary abstraction: **Agents** and " - "**Handoffs**. An agent encompasses instructions and tools and can hand off a " - "conversation to another agent when appropriate. " - "Handoffs are achieved by calling a handoff function, generally named " - "`transfer_to_`. Transfers between agents are handled seamlessly in the background;" - " do not mention or draw attention to these transfers in your conversation with the user.\n" -) - - -def prompt_with_handoff_instructions(prompt: str) -> str: - """ - Add recommended instructions to the prompt for agents that use handoffs. - """ - return f"{RECOMMENDED_PROMPT_PREFIX}\n\n{prompt}" diff --git a/tests/src/agents/function_schema.py b/tests/src/agents/function_schema.py deleted file mode 100644 index a4b57672..00000000 --- a/tests/src/agents/function_schema.py +++ /dev/null @@ -1,340 +0,0 @@ -from __future__ import annotations - -import contextlib -import inspect -import logging -import re -from dataclasses import dataclass -from typing import Any, Callable, Literal, get_args, get_origin, get_type_hints - -from griffe import Docstring, DocstringSectionKind -from pydantic import BaseModel, Field, create_model - -from .exceptions import UserError -from .run_context import RunContextWrapper -from .strict_schema import ensure_strict_json_schema - - -@dataclass -class FuncSchema: - """ - Captures the schema for a python function, in preparation for sending it to an LLM as a tool. - """ - - name: str - """The name of the function.""" - description: str | None - """The description of the function.""" - params_pydantic_model: type[BaseModel] - """A Pydantic model that represents the function's parameters.""" - params_json_schema: dict[str, Any] - """The JSON schema for the function's parameters, derived from the Pydantic model.""" - signature: inspect.Signature - """The signature of the function.""" - takes_context: bool = False - """Whether the function takes a RunContextWrapper argument (must be the first argument).""" - - def to_call_args(self, data: BaseModel) -> tuple[list[Any], dict[str, Any]]: - """ - Converts validated data from the Pydantic model into (args, kwargs), suitable for calling - the original function. - """ - positional_args: list[Any] = [] - keyword_args: dict[str, Any] = {} - seen_var_positional = False - - # Use enumerate() so we can skip the first parameter if it's context. - for idx, (name, param) in enumerate(self.signature.parameters.items()): - # If the function takes a RunContextWrapper and this is the first parameter, skip it. - if self.takes_context and idx == 0: - continue - - value = getattr(data, name, None) - if param.kind == param.VAR_POSITIONAL: - # e.g. *args: extend positional args and mark that *args is now seen - positional_args.extend(value or []) - seen_var_positional = True - elif param.kind == param.VAR_KEYWORD: - # e.g. **kwargs handling - keyword_args.update(value or {}) - elif param.kind in (param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD): - # Before *args, add to positional args. After *args, add to keyword args. - if not seen_var_positional: - positional_args.append(value) - else: - keyword_args[name] = value - else: - # For KEYWORD_ONLY parameters, always use keyword args. - keyword_args[name] = value - return positional_args, keyword_args - - -@dataclass -class FuncDocumentation: - """Contains metadata about a python function, extracted from its docstring.""" - - name: str - """The name of the function, via `__name__`.""" - description: str | None - """The description of the function, derived from the docstring.""" - param_descriptions: dict[str, str] | None - """The parameter descriptions of the function, derived from the docstring.""" - - -DocstringStyle = Literal["google", "numpy", "sphinx"] - - -# As of Feb 2025, the automatic style detection in griffe is an Insiders feature. This -# code approximates it. -def _detect_docstring_style(doc: str) -> DocstringStyle: - scores: dict[DocstringStyle, int] = {"sphinx": 0, "numpy": 0, "google": 0} - - # Sphinx style detection: look for :param, :type, :return:, and :rtype: - sphinx_patterns = [r"^:param\s", r"^:type\s", r"^:return:", r"^:rtype:"] - for pattern in sphinx_patterns: - if re.search(pattern, doc, re.MULTILINE): - scores["sphinx"] += 1 - - # Numpy style detection: look for headers like 'Parameters', 'Returns', or 'Yields' followed by - # a dashed underline - numpy_patterns = [ - r"^Parameters\s*\n\s*-{3,}", - r"^Returns\s*\n\s*-{3,}", - r"^Yields\s*\n\s*-{3,}", - ] - for pattern in numpy_patterns: - if re.search(pattern, doc, re.MULTILINE): - scores["numpy"] += 1 - - # Google style detection: look for section headers with a trailing colon - google_patterns = [r"^(Args|Arguments):", r"^(Returns):", r"^(Raises):"] - for pattern in google_patterns: - if re.search(pattern, doc, re.MULTILINE): - scores["google"] += 1 - - max_score = max(scores.values()) - if max_score == 0: - return "google" - - # Priority order: sphinx > numpy > google in case of tie - styles: list[DocstringStyle] = ["sphinx", "numpy", "google"] - - for style in styles: - if scores[style] == max_score: - return style - - return "google" - - -@contextlib.contextmanager -def _suppress_griffe_logging(): - # Supresses warnings about missing annotations for params - logger = logging.getLogger("griffe") - previous_level = logger.getEffectiveLevel() - logger.setLevel(logging.ERROR) - try: - yield - finally: - logger.setLevel(previous_level) - - -def generate_func_documentation( - func: Callable[..., Any], style: DocstringStyle | None = None -) -> FuncDocumentation: - """ - Extracts metadata from a function docstring, in preparation for sending it to an LLM as a tool. - - Args: - func: The function to extract documentation from. - style: The style of the docstring to use for parsing. If not provided, we will attempt to - auto-detect the style. - - Returns: - A FuncDocumentation object containing the function's name, description, and parameter - descriptions. - """ - name = func.__name__ - doc = inspect.getdoc(func) - if not doc: - return FuncDocumentation(name=name, description=None, param_descriptions=None) - - with _suppress_griffe_logging(): - docstring = Docstring(doc, lineno=1, parser=style or _detect_docstring_style(doc)) - parsed = docstring.parse() - - description: str | None = next( - (section.value for section in parsed if section.kind == DocstringSectionKind.text), None - ) - - param_descriptions: dict[str, str] = { - param.name: param.description - for section in parsed - if section.kind == DocstringSectionKind.parameters - for param in section.value - } - - return FuncDocumentation( - name=func.__name__, - description=description, - param_descriptions=param_descriptions or None, - ) - - -def function_schema( - func: Callable[..., Any], - docstring_style: DocstringStyle | None = None, - name_override: str | None = None, - description_override: str | None = None, - use_docstring_info: bool = True, - strict_json_schema: bool = True, -) -> FuncSchema: - """ - Given a python function, extracts a `FuncSchema` from it, capturing the name, description, - parameter descriptions, and other metadata. - - Args: - func: The function to extract the schema from. - docstring_style: The style of the docstring to use for parsing. If not provided, we will - attempt to auto-detect the style. - name_override: If provided, use this name instead of the function's `__name__`. - description_override: If provided, use this description instead of the one derived from the - docstring. - use_docstring_info: If True, uses the docstring to generate the description and parameter - descriptions. - strict_json_schema: Whether the JSON schema is in strict mode. If True, we'll ensure that - the schema adheres to the "strict" standard the OpenAI API expects. We **strongly** - recommend setting this to True, as it increases the likelihood of the LLM providing - correct JSON input. - - Returns: - A `FuncSchema` object containing the function's name, description, parameter descriptions, - and other metadata. - """ - - # 1. Grab docstring info - if use_docstring_info: - doc_info = generate_func_documentation(func, docstring_style) - param_descs = doc_info.param_descriptions or {} - else: - doc_info = None - param_descs = {} - - func_name = name_override or doc_info.name if doc_info else func.__name__ - - # 2. Inspect function signature and get type hints - sig = inspect.signature(func) - type_hints = get_type_hints(func) - params = list(sig.parameters.items()) - takes_context = False - filtered_params = [] - - if params: - first_name, first_param = params[0] - # Prefer the evaluated type hint if available - ann = type_hints.get(first_name, first_param.annotation) - if ann != inspect._empty: - origin = get_origin(ann) or ann - if origin is RunContextWrapper: - takes_context = True # Mark that the function takes context - else: - filtered_params.append((first_name, first_param)) - else: - filtered_params.append((first_name, first_param)) - - # For parameters other than the first, raise error if any use RunContextWrapper. - for name, param in params[1:]: - ann = type_hints.get(name, param.annotation) - if ann != inspect._empty: - origin = get_origin(ann) or ann - if origin is RunContextWrapper: - raise UserError( - f"RunContextWrapper param found at non-first position in function" - f" {func.__name__}" - ) - filtered_params.append((name, param)) - - # We will collect field definitions for create_model as a dict: - # field_name -> (type_annotation, default_value_or_Field(...)) - fields: dict[str, Any] = {} - - for name, param in filtered_params: - ann = type_hints.get(name, param.annotation) - default = param.default - - # If there's no type hint, assume `Any` - if ann == inspect._empty: - ann = Any - - # If a docstring param description exists, use it - field_description = param_descs.get(name, None) - - # Handle different parameter kinds - if param.kind == param.VAR_POSITIONAL: - # e.g. *args: extend positional args - if get_origin(ann) is tuple: - # e.g. def foo(*args: tuple[int, ...]) -> treat as List[int] - args_of_tuple = get_args(ann) - if len(args_of_tuple) == 2 and args_of_tuple[1] is Ellipsis: - ann = list[args_of_tuple[0]] # type: ignore - else: - ann = list[Any] - else: - # If user wrote *args: int, treat as List[int] - ann = list[ann] # type: ignore - - # Default factory to empty list - fields[name] = ( - ann, - Field(default_factory=list, description=field_description), # type: ignore - ) - - elif param.kind == param.VAR_KEYWORD: - # **kwargs handling - if get_origin(ann) is dict: - # e.g. def foo(**kwargs: dict[str, int]) - dict_args = get_args(ann) - if len(dict_args) == 2: - ann = dict[dict_args[0], dict_args[1]] # type: ignore - else: - ann = dict[str, Any] - else: - # e.g. def foo(**kwargs: int) -> Dict[str, int] - ann = dict[str, ann] # type: ignore - - fields[name] = ( - ann, - Field(default_factory=dict, description=field_description), # type: ignore - ) - - else: - # Normal parameter - if default == inspect._empty: - # Required field - fields[name] = ( - ann, - Field(..., description=field_description), - ) - else: - # Parameter with a default value - fields[name] = ( - ann, - Field(default=default, description=field_description), - ) - - # 3. Dynamically build a Pydantic model - dynamic_model = create_model(f"{func_name}_args", __base__=BaseModel, **fields) - - # 4. Build JSON schema from that model - json_schema = dynamic_model.model_json_schema() - if strict_json_schema: - json_schema = ensure_strict_json_schema(json_schema) - - # 5. Return as a FuncSchema dataclass - return FuncSchema( - name=func_name, - description=description_override or doc_info.description if doc_info else None, - params_pydantic_model=dynamic_model, - params_json_schema=json_schema, - signature=sig, - takes_context=takes_context, - ) diff --git a/tests/src/agents/guardrail.py b/tests/src/agents/guardrail.py deleted file mode 100644 index fcae0b8a..00000000 --- a/tests/src/agents/guardrail.py +++ /dev/null @@ -1,320 +0,0 @@ -from __future__ import annotations - -import inspect -from collections.abc import Awaitable -from dataclasses import dataclass -from typing import TYPE_CHECKING, Any, Callable, Generic, Union, overload - -from typing_extensions import TypeVar - -from ._utils import MaybeAwaitable -from .exceptions import UserError -from .items import TResponseInputItem -from .run_context import RunContextWrapper, TContext - -if TYPE_CHECKING: - from .agent import Agent - - -@dataclass -class GuardrailFunctionOutput: - """The output of a guardrail function.""" - - output_info: Any - """ - Optional information about the guardrail's output. For example, the guardrail could include - information about the checks it performed and granular results. - """ - - tripwire_triggered: bool - """ - Whether the tripwire was triggered. If triggered, the agent's execution will be halted. - """ - - -@dataclass -class InputGuardrailResult: - """The result of a guardrail run.""" - - guardrail: InputGuardrail[Any] - """ - The guardrail that was run. - """ - - output: GuardrailFunctionOutput - """The output of the guardrail function.""" - - -@dataclass -class OutputGuardrailResult: - """The result of a guardrail run.""" - - guardrail: OutputGuardrail[Any] - """ - The guardrail that was run. - """ - - agent_output: Any - """ - The output of the agent that was checked by the guardrail. - """ - - agent: Agent[Any] - """ - The agent that was checked by the guardrail. - """ - - output: GuardrailFunctionOutput - """The output of the guardrail function.""" - - -@dataclass -class InputGuardrail(Generic[TContext]): - """Input guardrails are checks that run in parallel to the agent's execution. - They can be used to do things like: - - Check if input messages are off-topic - - Take over control of the agent's execution if an unexpected input is detected - - You can use the `@input_guardrail()` decorator to turn a function into an `InputGuardrail`, or - create an `InputGuardrail` manually. - - Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, the agent - execution will immediately stop and a `InputGuardrailTripwireTriggered` exception will be raised - """ - - guardrail_function: Callable[ - [RunContextWrapper[TContext], Agent[Any], str | list[TResponseInputItem]], - MaybeAwaitable[GuardrailFunctionOutput], - ] - """A function that receives the the agent input and the context, and returns a - `GuardrailResult`. The result marks whether the tripwire was triggered, and can optionally - include information about the guardrail's output. - """ - - name: str | None = None - """The name of the guardrail, used for tracing. If not provided, we'll use the guardrail - function's name. - """ - - def get_name(self) -> str: - if self.name: - return self.name - - return self.guardrail_function.__name__ - - async def run( - self, - agent: Agent[Any], - input: str | list[TResponseInputItem], - context: RunContextWrapper[TContext], - ) -> InputGuardrailResult: - if not callable(self.guardrail_function): - raise UserError(f"Guardrail function must be callable, got {self.guardrail_function}") - - output = self.guardrail_function(context, agent, input) - if inspect.isawaitable(output): - return InputGuardrailResult( - guardrail=self, - output=await output, - ) - - return InputGuardrailResult( - guardrail=self, - output=output, - ) - - -@dataclass -class OutputGuardrail(Generic[TContext]): - """Output guardrails are checks that run on the final output of an agent. - They can be used to do check if the output passes certain validation criteria - - You can use the `@output_guardrail()` decorator to turn a function into an `OutputGuardrail`, - or create an `OutputGuardrail` manually. - - Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, a - `OutputGuardrailTripwireTriggered` exception will be raised. - """ - - guardrail_function: Callable[ - [RunContextWrapper[TContext], Agent[Any], Any], - MaybeAwaitable[GuardrailFunctionOutput], - ] - """A function that receives the final agent, its output, and the context, and returns a - `GuardrailResult`. The result marks whether the tripwire was triggered, and can optionally - include information about the guardrail's output. - """ - - name: str | None = None - """The name of the guardrail, used for tracing. If not provided, we'll use the guardrail - function's name. - """ - - def get_name(self) -> str: - if self.name: - return self.name - - return self.guardrail_function.__name__ - - async def run( - self, context: RunContextWrapper[TContext], agent: Agent[Any], agent_output: Any - ) -> OutputGuardrailResult: - if not callable(self.guardrail_function): - raise UserError(f"Guardrail function must be callable, got {self.guardrail_function}") - - output = self.guardrail_function(context, agent, agent_output) - if inspect.isawaitable(output): - return OutputGuardrailResult( - guardrail=self, - agent=agent, - agent_output=agent_output, - output=await output, - ) - - return OutputGuardrailResult( - guardrail=self, - agent=agent, - agent_output=agent_output, - output=output, - ) - - -TContext_co = TypeVar("TContext_co", bound=Any, covariant=True) - -# For InputGuardrail -_InputGuardrailFuncSync = Callable[ - [RunContextWrapper[TContext_co], "Agent[Any]", Union[str, list[TResponseInputItem]]], - GuardrailFunctionOutput, -] -_InputGuardrailFuncAsync = Callable[ - [RunContextWrapper[TContext_co], "Agent[Any]", Union[str, list[TResponseInputItem]]], - Awaitable[GuardrailFunctionOutput], -] - - -@overload -def input_guardrail( - func: _InputGuardrailFuncSync[TContext_co], -) -> InputGuardrail[TContext_co]: ... - - -@overload -def input_guardrail( - func: _InputGuardrailFuncAsync[TContext_co], -) -> InputGuardrail[TContext_co]: ... - - -@overload -def input_guardrail( - *, - name: str | None = None, -) -> Callable[ - [_InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co]], - InputGuardrail[TContext_co], -]: ... - - -def input_guardrail( - func: _InputGuardrailFuncSync[TContext_co] - | _InputGuardrailFuncAsync[TContext_co] - | None = None, - *, - name: str | None = None, -) -> ( - InputGuardrail[TContext_co] - | Callable[ - [_InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co]], - InputGuardrail[TContext_co], - ] -): - """ - Decorator that transforms a sync or async function into an `InputGuardrail`. - It can be used directly (no parentheses) or with keyword args, e.g.: - - @input_guardrail - def my_sync_guardrail(...): ... - - @input_guardrail(name="guardrail_name") - async def my_async_guardrail(...): ... - """ - - def decorator( - f: _InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co], - ) -> InputGuardrail[TContext_co]: - return InputGuardrail(guardrail_function=f, name=name) - - if func is not None: - # Decorator was used without parentheses - return decorator(func) - - # Decorator used with keyword arguments - return decorator - - -_OutputGuardrailFuncSync = Callable[ - [RunContextWrapper[TContext_co], "Agent[Any]", Any], - GuardrailFunctionOutput, -] -_OutputGuardrailFuncAsync = Callable[ - [RunContextWrapper[TContext_co], "Agent[Any]", Any], - Awaitable[GuardrailFunctionOutput], -] - - -@overload -def output_guardrail( - func: _OutputGuardrailFuncSync[TContext_co], -) -> OutputGuardrail[TContext_co]: ... - - -@overload -def output_guardrail( - func: _OutputGuardrailFuncAsync[TContext_co], -) -> OutputGuardrail[TContext_co]: ... - - -@overload -def output_guardrail( - *, - name: str | None = None, -) -> Callable[ - [_OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co]], - OutputGuardrail[TContext_co], -]: ... - - -def output_guardrail( - func: _OutputGuardrailFuncSync[TContext_co] - | _OutputGuardrailFuncAsync[TContext_co] - | None = None, - *, - name: str | None = None, -) -> ( - OutputGuardrail[TContext_co] - | Callable[ - [_OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co]], - OutputGuardrail[TContext_co], - ] -): - """ - Decorator that transforms a sync or async function into an `OutputGuardrail`. - It can be used directly (no parentheses) or with keyword args, e.g.: - - @output_guardrail - def my_sync_guardrail(...): ... - - @output_guardrail(name="guardrail_name") - async def my_async_guardrail(...): ... - """ - - def decorator( - f: _OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co], - ) -> OutputGuardrail[TContext_co]: - return OutputGuardrail(guardrail_function=f, name=name) - - if func is not None: - # Decorator was used without parentheses - return decorator(func) - - # Decorator used with keyword arguments - return decorator diff --git a/tests/src/agents/handoffs.py b/tests/src/agents/handoffs.py deleted file mode 100644 index ac157401..00000000 --- a/tests/src/agents/handoffs.py +++ /dev/null @@ -1,236 +0,0 @@ -from __future__ import annotations - -import inspect -from collections.abc import Awaitable -from dataclasses import dataclass -from typing import TYPE_CHECKING, Any, Callable, Generic, cast, overload - -from pydantic import TypeAdapter -from typing_extensions import TypeAlias, TypeVar - -from . import _utils -from .exceptions import ModelBehaviorError, UserError -from .items import RunItem, TResponseInputItem -from .run_context import RunContextWrapper, TContext -from .strict_schema import ensure_strict_json_schema -from .tracing.spans import SpanError - -if TYPE_CHECKING: - from .agent import Agent - - -# The handoff input type is the type of data passed when the agent is called via a handoff. -THandoffInput = TypeVar("THandoffInput", default=Any) - -OnHandoffWithInput = Callable[[RunContextWrapper[Any], THandoffInput], Any] -OnHandoffWithoutInput = Callable[[RunContextWrapper[Any]], Any] - - -@dataclass(frozen=True) -class HandoffInputData: - input_history: str | tuple[TResponseInputItem, ...] - """ - The input history before `Runner.run()` was called. - """ - - pre_handoff_items: tuple[RunItem, ...] - """ - The items generated before the agent turn where the handoff was invoked. - """ - - new_items: tuple[RunItem, ...] - """ - The new items generated during the current agent turn, including the item that triggered the - handoff and the tool output message representing the response from the handoff output. - """ - - -HandoffInputFilter: TypeAlias = Callable[[HandoffInputData], HandoffInputData] -"""A function that filters the input data passed to the next agent.""" - - -@dataclass -class Handoff(Generic[TContext]): - """A handoff is when an agent delegates a task to another agent. - For example, in a customer support scenario you might have a "triage agent" that determines - which agent should handle the user's request, and sub-agents that specialize in different - areas like billing, account management, etc. - """ - - tool_name: str - """The name of the tool that represents the handoff.""" - - tool_description: str - """The description of the tool that represents the handoff.""" - - input_json_schema: dict[str, Any] - """The JSON schema for the handoff input. Can be empty if the handoff does not take an input. - """ - - on_invoke_handoff: Callable[[RunContextWrapper[Any], str], Awaitable[Agent[TContext]]] - """The function that invokes the handoff. The parameters passed are: - 1. The handoff run context - 2. The arguments from the LLM, as a JSON string. Empty string if input_json_schema is empty. - - Must return an agent. - """ - - agent_name: str - """The name of the agent that is being handed off to.""" - - input_filter: HandoffInputFilter | None = None - """A function that filters the inputs that are passed to the next agent. By default, the new - agent sees the entire conversation history. In some cases, you may want to filter inputs e.g. - to remove older inputs, or remove tools from existing inputs. - - The function will receive the entire conversation history so far, including the input item - that triggered the handoff and a tool call output item representing the handoff tool's output. - - You are free to modify the input history or new items as you see fit. The next agent that - runs will receive `handoff_input_data.all_items`. - - IMPORTANT: in streaming mode, we will not stream anything as a result of this function. The - items generated before will already have been streamed. - """ - - strict_json_schema: bool = True - """Whether the input JSON schema is in strict mode. We **strongly** recommend setting this to - True, as it increases the likelihood of correct JSON input. - """ - - def get_transfer_message(self, agent: Agent[Any]) -> str: - base = f"{{'assistant': '{agent.name}'}}" - return base - - @classmethod - def default_tool_name(cls, agent: Agent[Any]) -> str: - return _utils.transform_string_function_style(f"transfer_to_{agent.name}") - - @classmethod - def default_tool_description(cls, agent: Agent[Any]) -> str: - return ( - f"Handoff to the {agent.name} agent to handle the request. " - f"{agent.handoff_description or ''}" - ) - - -@overload -def handoff( - agent: Agent[TContext], - *, - tool_name_override: str | None = None, - tool_description_override: str | None = None, - input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None, -) -> Handoff[TContext]: ... - - -@overload -def handoff( - agent: Agent[TContext], - *, - on_handoff: OnHandoffWithInput[THandoffInput], - input_type: type[THandoffInput], - tool_description_override: str | None = None, - tool_name_override: str | None = None, - input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None, -) -> Handoff[TContext]: ... - - -@overload -def handoff( - agent: Agent[TContext], - *, - on_handoff: OnHandoffWithoutInput, - tool_description_override: str | None = None, - tool_name_override: str | None = None, - input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None, -) -> Handoff[TContext]: ... - - -def handoff( - agent: Agent[TContext], - tool_name_override: str | None = None, - tool_description_override: str | None = None, - on_handoff: OnHandoffWithInput[THandoffInput] | OnHandoffWithoutInput | None = None, - input_type: type[THandoffInput] | None = None, - input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None, -) -> Handoff[TContext]: - """Create a handoff from an agent. - - Args: - agent: The agent to handoff to, or a function that returns an agent. - tool_name_override: Optional override for the name of the tool that represents the handoff. - tool_description_override: Optional override for the description of the tool that - represents the handoff. - on_handoff: A function that runs when the handoff is invoked. - input_type: the type of the input to the handoff. If provided, the input will be validated - against this type. Only relevant if you pass a function that takes an input. - input_filter: a function that filters the inputs that are passed to the next agent. - """ - assert (on_handoff and input_type) or not (on_handoff and input_type), ( - "You must provide either both on_input and input_type, or neither" - ) - type_adapter: TypeAdapter[Any] | None - if input_type is not None: - assert callable(on_handoff), "on_handoff must be callable" - sig = inspect.signature(on_handoff) - if len(sig.parameters) != 2: - raise UserError("on_handoff must take two arguments: context and input") - - type_adapter = TypeAdapter(input_type) - input_json_schema = type_adapter.json_schema() - else: - type_adapter = None - input_json_schema = {} - if on_handoff is not None: - sig = inspect.signature(on_handoff) - if len(sig.parameters) != 1: - raise UserError("on_handoff must take one argument: context") - - async def _invoke_handoff( - ctx: RunContextWrapper[Any], input_json: str | None = None - ) -> Agent[Any]: - if input_type is not None and type_adapter is not None: - if input_json is None: - _utils.attach_error_to_current_span( - SpanError( - message="Handoff function expected non-null input, but got None", - data={"details": "input_json is None"}, - ) - ) - raise ModelBehaviorError("Handoff function expected non-null input, but got None") - - validated_input = _utils.validate_json( - json_str=input_json, - type_adapter=type_adapter, - partial=False, - ) - input_func = cast(OnHandoffWithInput[THandoffInput], on_handoff) - if inspect.iscoroutinefunction(input_func): - await input_func(ctx, validated_input) - else: - input_func(ctx, validated_input) - elif on_handoff is not None: - no_input_func = cast(OnHandoffWithoutInput, on_handoff) - if inspect.iscoroutinefunction(no_input_func): - await no_input_func(ctx) - else: - no_input_func(ctx) - - return agent - - tool_name = tool_name_override or Handoff.default_tool_name(agent) - tool_description = tool_description_override or Handoff.default_tool_description(agent) - - # Always ensure the input JSON schema is in strict mode - # If there is a need, we can make this configurable in the future - input_json_schema = ensure_strict_json_schema(input_json_schema) - - return Handoff( - tool_name=tool_name, - tool_description=tool_description, - input_json_schema=input_json_schema, - on_invoke_handoff=_invoke_handoff, - input_filter=input_filter, - agent_name=agent.name, - ) diff --git a/tests/src/agents/items.py b/tests/src/agents/items.py deleted file mode 100644 index bbaf49d8..00000000 --- a/tests/src/agents/items.py +++ /dev/null @@ -1,246 +0,0 @@ -from __future__ import annotations - -import abc -import copy -from dataclasses import dataclass -from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, Union - -from openai.types.responses import ( - Response, - ResponseComputerToolCall, - ResponseFileSearchToolCall, - ResponseFunctionToolCall, - ResponseFunctionWebSearch, - ResponseInputItemParam, - ResponseOutputItem, - ResponseOutputMessage, - ResponseOutputRefusal, - ResponseOutputText, - ResponseStreamEvent, -) -from openai.types.responses.response_input_item_param import ComputerCallOutput, FunctionCallOutput -from openai.types.responses.response_output_item import Reasoning -from pydantic import BaseModel -from typing_extensions import TypeAlias - -from .exceptions import AgentsException, ModelBehaviorError -from .usage import Usage - -if TYPE_CHECKING: - from .agent import Agent - -TResponse = Response -"""A type alias for the Response type from the OpenAI SDK.""" - -TResponseInputItem = ResponseInputItemParam -"""A type alias for the ResponseInputItemParam type from the OpenAI SDK.""" - -TResponseOutputItem = ResponseOutputItem -"""A type alias for the ResponseOutputItem type from the OpenAI SDK.""" - -TResponseStreamEvent = ResponseStreamEvent -"""A type alias for the ResponseStreamEvent type from the OpenAI SDK.""" - -T = TypeVar("T", bound=Union[TResponseOutputItem, TResponseInputItem]) - - -@dataclass -class RunItemBase(Generic[T], abc.ABC): - agent: Agent[Any] - """The agent whose run caused this item to be generated.""" - - raw_item: T - """The raw Responses item from the run. This will always be a either an output item (i.e. - `openai.types.responses.ResponseOutputItem` or an input item - (i.e. `openai.types.responses.ResponseInputItemParam`). - """ - - def to_input_item(self) -> TResponseInputItem: - """Converts this item into an input item suitable for passing to the model.""" - if isinstance(self.raw_item, dict): - # We know that input items are dicts, so we can ignore the type error - return self.raw_item # type: ignore - elif isinstance(self.raw_item, BaseModel): - # All output items are Pydantic models that can be converted to input items. - return self.raw_item.model_dump(exclude_unset=True) # type: ignore - else: - raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}") - - -@dataclass -class MessageOutputItem(RunItemBase[ResponseOutputMessage]): - """Represents a message from the LLM.""" - - raw_item: ResponseOutputMessage - """The raw response output message.""" - - type: Literal["message_output_item"] = "message_output_item" - - -@dataclass -class HandoffCallItem(RunItemBase[ResponseFunctionToolCall]): - """Represents a tool call for a handoff from one agent to another.""" - - raw_item: ResponseFunctionToolCall - """The raw response function tool call that represents the handoff.""" - - type: Literal["handoff_call_item"] = "handoff_call_item" - - -@dataclass -class HandoffOutputItem(RunItemBase[TResponseInputItem]): - """Represents the output of a handoff.""" - - raw_item: TResponseInputItem - """The raw input item that represents the handoff taking place.""" - - source_agent: Agent[Any] - """The agent that made the handoff.""" - - target_agent: Agent[Any] - """The agent that is being handed off to.""" - - type: Literal["handoff_output_item"] = "handoff_output_item" - - -ToolCallItemTypes: TypeAlias = Union[ - ResponseFunctionToolCall, - ResponseComputerToolCall, - ResponseFileSearchToolCall, - ResponseFunctionWebSearch, -] -"""A type that represents a tool call item.""" - - -@dataclass -class ToolCallItem(RunItemBase[ToolCallItemTypes]): - """Represents a tool call e.g. a function call or computer action call.""" - - raw_item: ToolCallItemTypes - """The raw tool call item.""" - - type: Literal["tool_call_item"] = "tool_call_item" - - -@dataclass -class ToolCallOutputItem(RunItemBase[Union[FunctionCallOutput, ComputerCallOutput]]): - """Represents the output of a tool call.""" - - raw_item: FunctionCallOutput | ComputerCallOutput - """The raw item from the model.""" - - output: str - """The output of the tool call.""" - - type: Literal["tool_call_output_item"] = "tool_call_output_item" - - -@dataclass -class ReasoningItem(RunItemBase[Reasoning]): - """Represents a reasoning item.""" - - raw_item: Reasoning - """The raw reasoning item.""" - - type: Literal["reasoning_item"] = "reasoning_item" - - -RunItem: TypeAlias = Union[ - MessageOutputItem, - HandoffCallItem, - HandoffOutputItem, - ToolCallItem, - ToolCallOutputItem, - ReasoningItem, -] -"""An item generated by an agent.""" - - -@dataclass -class ModelResponse: - output: list[TResponseOutputItem] - """A list of outputs (messages, tool calls, etc) generated by the model""" - - usage: Usage - """The usage information for the response.""" - - referenceable_id: str | None - """An ID for the response which can be used to refer to the response in subsequent calls to the - model. Not supported by all model providers. - """ - - def to_input_items(self) -> list[TResponseInputItem]: - """Convert the output into a list of input items suitable for passing to the model.""" - # We happen to know that the shape of the Pydantic output items are the same as the - # equivalent TypedDict input items, so we can just convert each one. - # This is also tested via unit tests. - return [it.model_dump(exclude_unset=True) for it in self.output] # type: ignore - - -class ItemHelpers: - @classmethod - def extract_last_content(cls, message: TResponseOutputItem) -> str: - """Extracts the last text content or refusal from a message.""" - if not isinstance(message, ResponseOutputMessage): - return "" - - last_content = message.content[-1] - if isinstance(last_content, ResponseOutputText): - return last_content.text - elif isinstance(last_content, ResponseOutputRefusal): - return last_content.refusal - else: - raise ModelBehaviorError(f"Unexpected content type: {type(last_content)}") - - @classmethod - def extract_last_text(cls, message: TResponseOutputItem) -> str | None: - """Extracts the last text content from a message, if any. Ignores refusals.""" - if isinstance(message, ResponseOutputMessage): - last_content = message.content[-1] - if isinstance(last_content, ResponseOutputText): - return last_content.text - - return None - - @classmethod - def input_to_new_input_list( - cls, input: str | list[TResponseInputItem] - ) -> list[TResponseInputItem]: - """Converts a string or list of input items into a list of input items.""" - if isinstance(input, str): - return [ - { - "content": input, - "role": "user", - } - ] - return copy.deepcopy(input) - - @classmethod - def text_message_outputs(cls, items: list[RunItem]) -> str: - """Concatenates all the text content from a list of message output items.""" - text = "" - for item in items: - if isinstance(item, MessageOutputItem): - text += cls.text_message_output(item) - return text - - @classmethod - def text_message_output(cls, message: MessageOutputItem) -> str: - """Extracts all the text content from a single message output item.""" - text = "" - for item in message.raw_item.content: - if isinstance(item, ResponseOutputText): - text += item.text - return text - - @classmethod - def tool_call_output_item( - cls, tool_call: ResponseFunctionToolCall, output: str - ) -> FunctionCallOutput: - """Creates a tool call output item from a tool call and its output.""" - return { - "call_id": tool_call.call_id, - "output": output, - "type": "function_call_output", - } diff --git a/tests/src/agents/lifecycle.py b/tests/src/agents/lifecycle.py deleted file mode 100644 index 8643248b..00000000 --- a/tests/src/agents/lifecycle.py +++ /dev/null @@ -1,105 +0,0 @@ -from typing import Any, Generic - -from .agent import Agent -from .run_context import RunContextWrapper, TContext -from .tool import Tool - - -class RunHooks(Generic[TContext]): - """A class that receives callbacks on various lifecycle events in an agent run. Subclass and - override the methods you need. - """ - - async def on_agent_start( - self, context: RunContextWrapper[TContext], agent: Agent[TContext] - ) -> None: - """Called before the agent is invoked. Called each time the current agent changes.""" - pass - - async def on_agent_end( - self, - context: RunContextWrapper[TContext], - agent: Agent[TContext], - output: Any, - ) -> None: - """Called when the agent produces a final output.""" - pass - - async def on_handoff( - self, - context: RunContextWrapper[TContext], - from_agent: Agent[TContext], - to_agent: Agent[TContext], - ) -> None: - """Called when a handoff occurs.""" - pass - - async def on_tool_start( - self, - context: RunContextWrapper[TContext], - agent: Agent[TContext], - tool: Tool, - ) -> None: - """Called before a tool is invoked.""" - pass - - async def on_tool_end( - self, - context: RunContextWrapper[TContext], - agent: Agent[TContext], - tool: Tool, - result: str, - ) -> None: - """Called after a tool is invoked.""" - pass - - -class AgentHooks(Generic[TContext]): - """A class that receives callbacks on various lifecycle events for a specific agent. You can - set this on `agent.hooks` to receive events for that specific agent. - - Subclass and override the methods you need. - """ - - async def on_start(self, context: RunContextWrapper[TContext], agent: Agent[TContext]) -> None: - """Called before the agent is invoked. Called each time the running agent is changed to this - agent.""" - pass - - async def on_end( - self, - context: RunContextWrapper[TContext], - agent: Agent[TContext], - output: Any, - ) -> None: - """Called when the agent produces a final output.""" - pass - - async def on_handoff( - self, - context: RunContextWrapper[TContext], - agent: Agent[TContext], - source: Agent[TContext], - ) -> None: - """Called when the agent is being handed off to. The `source` is the agent that is handing - off to this agent.""" - pass - - async def on_tool_start( - self, - context: RunContextWrapper[TContext], - agent: Agent[TContext], - tool: Tool, - ) -> None: - """Called before a tool is invoked.""" - pass - - async def on_tool_end( - self, - context: RunContextWrapper[TContext], - agent: Agent[TContext], - tool: Tool, - result: str, - ) -> None: - """Called after a tool is invoked.""" - pass diff --git a/tests/src/agents/logger.py b/tests/src/agents/logger.py deleted file mode 100644 index bd81a827..00000000 --- a/tests/src/agents/logger.py +++ /dev/null @@ -1,3 +0,0 @@ -import logging - -logger = logging.getLogger("openai.agents") diff --git a/tests/src/agents/model_settings.py b/tests/src/agents/model_settings.py deleted file mode 100644 index 78cf9a83..00000000 --- a/tests/src/agents/model_settings.py +++ /dev/null @@ -1,35 +0,0 @@ -from __future__ import annotations - -from dataclasses import dataclass -from typing import Literal - - -@dataclass -class ModelSettings: - """Settings to use when calling an LLM. - - This class holds optional model configuration parameters (e.g. temperature, - top_p, penalties, truncation, etc.). - """ - temperature: float | None = None - top_p: float | None = None - frequency_penalty: float | None = None - presence_penalty: float | None = None - tool_choice: Literal["auto", "required", "none"] | str | None = None - parallel_tool_calls: bool | None = False - truncation: Literal["auto", "disabled"] | None = None - - def resolve(self, override: ModelSettings | None) -> ModelSettings: - """Produce a new ModelSettings by overlaying any non-None values from the - override on top of this instance.""" - if override is None: - return self - return ModelSettings( - temperature=override.temperature or self.temperature, - top_p=override.top_p or self.top_p, - frequency_penalty=override.frequency_penalty or self.frequency_penalty, - presence_penalty=override.presence_penalty or self.presence_penalty, - tool_choice=override.tool_choice or self.tool_choice, - parallel_tool_calls=override.parallel_tool_calls or self.parallel_tool_calls, - truncation=override.truncation or self.truncation, - ) diff --git a/tests/src/agents/models/__init__.py b/tests/src/agents/models/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/tests/src/agents/models/_openai_shared.py b/tests/src/agents/models/_openai_shared.py deleted file mode 100644 index 2e145018..00000000 --- a/tests/src/agents/models/_openai_shared.py +++ /dev/null @@ -1,34 +0,0 @@ -from __future__ import annotations - -from openai import AsyncOpenAI - -_default_openai_key: str | None = None -_default_openai_client: AsyncOpenAI | None = None -_use_responses_by_default: bool = True - - -def set_default_openai_key(key: str) -> None: - global _default_openai_key - _default_openai_key = key - - -def get_default_openai_key() -> str | None: - return _default_openai_key - - -def set_default_openai_client(client: AsyncOpenAI) -> None: - global _default_openai_client - _default_openai_client = client - - -def get_default_openai_client() -> AsyncOpenAI | None: - return _default_openai_client - - -def set_use_responses_by_default(use_responses: bool) -> None: - global _use_responses_by_default - _use_responses_by_default = use_responses - - -def get_use_responses_by_default() -> bool: - return _use_responses_by_default diff --git a/tests/src/agents/models/fake_id.py b/tests/src/agents/models/fake_id.py deleted file mode 100644 index 0565b0a7..00000000 --- a/tests/src/agents/models/fake_id.py +++ /dev/null @@ -1,5 +0,0 @@ -FAKE_RESPONSES_ID = "__fake_id__" -"""This is a placeholder ID used to fill in the `id` field in Responses API related objects. It's -useful when you're creating Responses objects from non-Responses APIs, e.g. the OpenAI Chat -Completions API or other LLM providers. -""" diff --git a/tests/src/agents/models/interface.py b/tests/src/agents/models/interface.py deleted file mode 100644 index e9a8700c..00000000 --- a/tests/src/agents/models/interface.py +++ /dev/null @@ -1,107 +0,0 @@ -from __future__ import annotations - -import abc -import enum -from collections.abc import AsyncIterator -from typing import TYPE_CHECKING - -from ..agent_output import AgentOutputSchema -from ..handoffs import Handoff -from ..items import ModelResponse, TResponseInputItem, TResponseStreamEvent -from ..tool import Tool - -if TYPE_CHECKING: - from ..model_settings import ModelSettings - - -class ModelTracing(enum.Enum): - DISABLED = 0 - """Tracing is disabled entirely.""" - - ENABLED = 1 - """Tracing is enabled, and all data is included.""" - - ENABLED_WITHOUT_DATA = 2 - """Tracing is enabled, but inputs/outputs are not included.""" - - def is_disabled(self) -> bool: - return self == ModelTracing.DISABLED - - def include_data(self) -> bool: - return self == ModelTracing.ENABLED - - -class Model(abc.ABC): - """The base interface for calling an LLM.""" - - @abc.abstractmethod - async def get_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - tracing: ModelTracing, - ) -> ModelResponse: - """Get a response from the model. - - Args: - system_instructions: The system instructions to use. - input: The input items to the model, in OpenAI Responses format. - model_settings: The model settings to use. - tools: The tools available to the model. - output_schema: The output schema to use. - handoffs: The handoffs available to the model. - tracing: Tracing configuration. - - Returns: - The full model response. - """ - pass - - @abc.abstractmethod - def stream_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - tracing: ModelTracing, - ) -> AsyncIterator[TResponseStreamEvent]: - """Stream a response from the model. - - Args: - system_instructions: The system instructions to use. - input: The input items to the model, in OpenAI Responses format. - model_settings: The model settings to use. - tools: The tools available to the model. - output_schema: The output schema to use. - handoffs: The handoffs available to the model. - tracing: Tracing configuration. - - Returns: - An iterator of response stream events, in OpenAI Responses format. - """ - pass - - -class ModelProvider(abc.ABC): - """The base interface for a model provider. - - Model provider is responsible for looking up Models by name. - """ - - @abc.abstractmethod - def get_model(self, model_name: str | None) -> Model: - """Get a model by name. - - Args: - model_name: The name of the model to get. - - Returns: - The model. - """ diff --git a/tests/src/agents/models/openai_chatcompletions.py b/tests/src/agents/models/openai_chatcompletions.py deleted file mode 100644 index a7340d05..00000000 --- a/tests/src/agents/models/openai_chatcompletions.py +++ /dev/null @@ -1,952 +0,0 @@ -from __future__ import annotations - -import dataclasses -import json -import time -from collections.abc import AsyncIterator, Iterable -from dataclasses import dataclass, field -from typing import TYPE_CHECKING, Any, Literal, cast, overload - -from openai import NOT_GIVEN, AsyncOpenAI, AsyncStream, NotGiven -from openai.types import ChatModel -from openai.types.chat import ( - ChatCompletion, - ChatCompletionAssistantMessageParam, - ChatCompletionChunk, - ChatCompletionContentPartImageParam, - ChatCompletionContentPartParam, - ChatCompletionContentPartTextParam, - ChatCompletionDeveloperMessageParam, - ChatCompletionMessage, - ChatCompletionMessageParam, - ChatCompletionMessageToolCallParam, - ChatCompletionSystemMessageParam, - ChatCompletionToolChoiceOptionParam, - ChatCompletionToolMessageParam, - ChatCompletionUserMessageParam, -) -from openai.types.chat.chat_completion_tool_param import ChatCompletionToolParam -from openai.types.chat.completion_create_params import ResponseFormat -from openai.types.completion_usage import CompletionUsage -from openai.types.responses import ( - EasyInputMessageParam, - Response, - ResponseCompletedEvent, - ResponseContentPartAddedEvent, - ResponseContentPartDoneEvent, - ResponseCreatedEvent, - ResponseFileSearchToolCallParam, - ResponseFunctionCallArgumentsDeltaEvent, - ResponseFunctionToolCall, - ResponseFunctionToolCallParam, - ResponseInputContentParam, - ResponseInputImageParam, - ResponseInputTextParam, - ResponseOutputItem, - ResponseOutputItemAddedEvent, - ResponseOutputItemDoneEvent, - ResponseOutputMessage, - ResponseOutputMessageParam, - ResponseOutputRefusal, - ResponseOutputText, - ResponseRefusalDeltaEvent, - ResponseTextDeltaEvent, -) -from openai.types.responses.response_input_param import FunctionCallOutput, ItemReference, Message - -from .. import _debug -from ..agent_output import AgentOutputSchema -from ..exceptions import AgentsException, UserError -from ..handoffs import Handoff -from ..items import ModelResponse, TResponseInputItem, TResponseOutputItem, TResponseStreamEvent -from ..logger import logger -from ..tool import FunctionTool, Tool -from ..tracing import generation_span -from ..tracing.span_data import GenerationSpanData -from ..tracing.spans import Span -from ..usage import Usage -from ..version import __version__ -from .fake_id import FAKE_RESPONSES_ID -from .interface import Model, ModelTracing - -if TYPE_CHECKING: - from ..model_settings import ModelSettings - - -_USER_AGENT = f"Agents/Python {__version__}" -_HEADERS = {"User-Agent": _USER_AGENT} - - -@dataclass -class _StreamingState: - started: bool = False - text_content_index_and_output: tuple[int, ResponseOutputText] | None = None - refusal_content_index_and_output: tuple[int, ResponseOutputRefusal] | None = None - function_calls: dict[int, ResponseFunctionToolCall] = field(default_factory=dict) - - -class OpenAIChatCompletionsModel(Model): - def __init__( - self, - model: str | ChatModel, - openai_client: AsyncOpenAI, - ) -> None: - self.model = model - self._client = openai_client - - def _non_null_or_not_given(self, value: Any) -> Any: - return value if value is not None else NOT_GIVEN - - async def get_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - tracing: ModelTracing, - ) -> ModelResponse: - with generation_span( - model=str(self.model), - model_config=dataclasses.asdict(model_settings) - | {"base_url": str(self._client.base_url)}, - disabled=tracing.is_disabled(), - ) as span_generation: - response = await self._fetch_response( - system_instructions, - input, - model_settings, - tools, - output_schema, - handoffs, - span_generation, - tracing, - stream=False, - ) - - if _debug.DONT_LOG_MODEL_DATA: - logger.debug("Received model response") - else: - logger.debug( - f"LLM resp:\n{json.dumps(response.choices[0].message.model_dump(), indent=2)}\n" - ) - - usage = ( - Usage( - requests=1, - input_tokens=response.usage.prompt_tokens, - output_tokens=response.usage.completion_tokens, - total_tokens=response.usage.total_tokens, - ) - if response.usage - else Usage() - ) - if tracing.include_data(): - span_generation.span_data.output = [response.choices[0].message.model_dump()] - span_generation.span_data.usage = { - "input_tokens": usage.input_tokens, - "output_tokens": usage.output_tokens, - } - - items = _Converter.message_to_output_items(response.choices[0].message) - - return ModelResponse( - output=items, - usage=usage, - referenceable_id=None, - ) - - async def stream_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - tracing: ModelTracing, - ) -> AsyncIterator[TResponseStreamEvent]: - """ - Yields a partial message as it is generated, as well as the usage information. - """ - with generation_span( - model=str(self.model), - model_config=dataclasses.asdict(model_settings) - | {"base_url": str(self._client.base_url)}, - disabled=tracing.is_disabled(), - ) as span_generation: - response, stream = await self._fetch_response( - system_instructions, - input, - model_settings, - tools, - output_schema, - handoffs, - span_generation, - tracing, - stream=True, - ) - - usage: CompletionUsage | None = None - state = _StreamingState() - - async for chunk in stream: - if not state.started: - state.started = True - yield ResponseCreatedEvent( - response=response, - type="response.created", - ) - - # The usage is only available in the last chunk - usage = chunk.usage - - if not chunk.choices or not chunk.choices[0].delta: - continue - - delta = chunk.choices[0].delta - - # Handle text - if delta.content: - if not state.text_content_index_and_output: - # Initialize a content tracker for streaming text - state.text_content_index_and_output = ( - 0 if not state.refusal_content_index_and_output else 1, - ResponseOutputText( - text="", - type="output_text", - annotations=[], - ), - ) - # Start a new assistant message stream - assistant_item = ResponseOutputMessage( - id=FAKE_RESPONSES_ID, - content=[], - role="assistant", - type="message", - status="in_progress", - ) - # Notify consumers of the start of a new output message + first content part - yield ResponseOutputItemAddedEvent( - item=assistant_item, - output_index=0, - type="response.output_item.added", - ) - yield ResponseContentPartAddedEvent( - content_index=state.text_content_index_and_output[0], - item_id=FAKE_RESPONSES_ID, - output_index=0, - part=ResponseOutputText( - text="", - type="output_text", - annotations=[], - ), - type="response.content_part.added", - ) - # Emit the delta for this segment of content - yield ResponseTextDeltaEvent( - content_index=state.text_content_index_and_output[0], - delta=delta.content, - item_id=FAKE_RESPONSES_ID, - output_index=0, - type="response.output_text.delta", - ) - # Accumulate the text into the response part - state.text_content_index_and_output[1].text += delta.content - - # Handle refusals (model declines to answer) - if delta.refusal: - if not state.refusal_content_index_and_output: - # Initialize a content tracker for streaming refusal text - state.refusal_content_index_and_output = ( - 0 if not state.text_content_index_and_output else 1, - ResponseOutputRefusal(refusal="", type="refusal"), - ) - # Start a new assistant message if one doesn't exist yet (in-progress) - assistant_item = ResponseOutputMessage( - id=FAKE_RESPONSES_ID, - content=[], - role="assistant", - type="message", - status="in_progress", - ) - # Notify downstream that assistant message + first content part are starting - yield ResponseOutputItemAddedEvent( - item=assistant_item, - output_index=0, - type="response.output_item.added", - ) - yield ResponseContentPartAddedEvent( - content_index=state.refusal_content_index_and_output[0], - item_id=FAKE_RESPONSES_ID, - output_index=0, - part=ResponseOutputText( - text="", - type="output_text", - annotations=[], - ), - type="response.content_part.added", - ) - # Emit the delta for this segment of refusal - yield ResponseRefusalDeltaEvent( - content_index=state.refusal_content_index_and_output[0], - delta=delta.refusal, - item_id=FAKE_RESPONSES_ID, - output_index=0, - type="response.refusal.delta", - ) - # Accumulate the refusal string in the output part - state.refusal_content_index_and_output[1].refusal += delta.refusal - - # Handle tool calls - # Because we don't know the name of the function until the end of the stream, we'll - # save everything and yield events at the end - if delta.tool_calls: - for tc_delta in delta.tool_calls: - if tc_delta.index not in state.function_calls: - state.function_calls[tc_delta.index] = ResponseFunctionToolCall( - id=FAKE_RESPONSES_ID, - arguments="", - name="", - type="function_call", - call_id="", - ) - tc_function = tc_delta.function - - state.function_calls[tc_delta.index].arguments += ( - tc_function.arguments if tc_function else "" - ) or "" - state.function_calls[tc_delta.index].name += ( - tc_function.name if tc_function else "" - ) or "" - state.function_calls[tc_delta.index].call_id += tc_delta.id or "" - - function_call_starting_index = 0 - if state.text_content_index_and_output: - function_call_starting_index += 1 - # Send end event for this content part - yield ResponseContentPartDoneEvent( - content_index=state.text_content_index_and_output[0], - item_id=FAKE_RESPONSES_ID, - output_index=0, - part=state.text_content_index_and_output[1], - type="response.content_part.done", - ) - - if state.refusal_content_index_and_output: - function_call_starting_index += 1 - # Send end event for this content part - yield ResponseContentPartDoneEvent( - content_index=state.refusal_content_index_and_output[0], - item_id=FAKE_RESPONSES_ID, - output_index=0, - part=state.refusal_content_index_and_output[1], - type="response.content_part.done", - ) - - # Actually send events for the function calls - for function_call in state.function_calls.values(): - # First, a ResponseOutputItemAdded for the function call - yield ResponseOutputItemAddedEvent( - item=ResponseFunctionToolCall( - id=FAKE_RESPONSES_ID, - call_id=function_call.call_id, - arguments=function_call.arguments, - name=function_call.name, - type="function_call", - ), - output_index=function_call_starting_index, - type="response.output_item.added", - ) - # Then, yield the args - yield ResponseFunctionCallArgumentsDeltaEvent( - delta=function_call.arguments, - item_id=FAKE_RESPONSES_ID, - output_index=function_call_starting_index, - type="response.function_call_arguments.delta", - ) - # Finally, the ResponseOutputItemDone - yield ResponseOutputItemDoneEvent( - item=ResponseFunctionToolCall( - id=FAKE_RESPONSES_ID, - call_id=function_call.call_id, - arguments=function_call.arguments, - name=function_call.name, - type="function_call", - ), - output_index=function_call_starting_index, - type="response.output_item.done", - ) - - # Finally, send the Response completed event - outputs: list[ResponseOutputItem] = [] - if state.text_content_index_and_output or state.refusal_content_index_and_output: - assistant_msg = ResponseOutputMessage( - id=FAKE_RESPONSES_ID, - content=[], - role="assistant", - type="message", - status="completed", - ) - if state.text_content_index_and_output: - assistant_msg.content.append(state.text_content_index_and_output[1]) - if state.refusal_content_index_and_output: - assistant_msg.content.append(state.refusal_content_index_and_output[1]) - outputs.append(assistant_msg) - - # send a ResponseOutputItemDone for the assistant message - yield ResponseOutputItemDoneEvent( - item=assistant_msg, - output_index=0, - type="response.output_item.done", - ) - - for function_call in state.function_calls.values(): - outputs.append(function_call) - - final_response = response.model_copy(update={"output": outputs, "usage": usage}) - - yield ResponseCompletedEvent( - response=final_response, - type="response.completed", - ) - if tracing.include_data(): - span_generation.span_data.output = [final_response.model_dump()] - - if usage: - span_generation.span_data.usage = { - "input_tokens": usage.prompt_tokens, - "output_tokens": usage.completion_tokens, - } - - @overload - async def _fetch_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - span: Span[GenerationSpanData], - tracing: ModelTracing, - stream: Literal[True], - ) -> tuple[Response, AsyncStream[ChatCompletionChunk]]: ... - - @overload - async def _fetch_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - span: Span[GenerationSpanData], - tracing: ModelTracing, - stream: Literal[False], - ) -> ChatCompletion: ... - - async def _fetch_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - span: Span[GenerationSpanData], - tracing: ModelTracing, - stream: bool = False, - ) -> ChatCompletion | tuple[Response, AsyncStream[ChatCompletionChunk]]: - converted_messages = _Converter.items_to_messages(input) - - if system_instructions: - converted_messages.insert( - 0, - { - "content": system_instructions, - "role": "system", - }, - ) - if tracing.include_data(): - span.span_data.input = converted_messages - - parallel_tool_calls = ( - True if model_settings.parallel_tool_calls and tools and len(tools) > 0 else NOT_GIVEN - ) - tool_choice = _Converter.convert_tool_choice(model_settings.tool_choice) - response_format = _Converter.convert_response_format(output_schema) - - converted_tools = [ToolConverter.to_openai(tool) for tool in tools] if tools else [] - - for handoff in handoffs: - converted_tools.append(ToolConverter.convert_handoff_tool(handoff)) - - if _debug.DONT_LOG_MODEL_DATA: - logger.debug("Calling LLM") - else: - logger.debug( - f"{json.dumps(converted_messages, indent=2)}\n" - f"Tools:\n{json.dumps(converted_tools, indent=2)}\n" - f"Stream: {stream}\n" - f"Tool choice: {tool_choice}\n" - f"Response format: {response_format}\n" - ) - - ret = await self._get_client().chat.completions.create( - model=self.model, - messages=converted_messages, - tools=converted_tools or NOT_GIVEN, - temperature=self._non_null_or_not_given(model_settings.temperature), - top_p=self._non_null_or_not_given(model_settings.top_p), - frequency_penalty=self._non_null_or_not_given(model_settings.frequency_penalty), - presence_penalty=self._non_null_or_not_given(model_settings.presence_penalty), - tool_choice=tool_choice, - response_format=response_format, - parallel_tool_calls=parallel_tool_calls, - stream=stream, - stream_options={"include_usage": True} if stream else NOT_GIVEN, - extra_headers=_HEADERS, - ) - - if isinstance(ret, ChatCompletion): - return ret - - response = Response( - id=FAKE_RESPONSES_ID, - created_at=time.time(), - model=self.model, - object="response", - output=[], - tool_choice=cast(Literal["auto", "required", "none"], tool_choice) - if tool_choice != NOT_GIVEN - else "auto", - top_p=model_settings.top_p, - temperature=model_settings.temperature, - tools=[], - parallel_tool_calls=parallel_tool_calls or False, - ) - return response, ret - - def _get_client(self) -> AsyncOpenAI: - if self._client is None: - self._client = AsyncOpenAI() - return self._client - - -class _Converter: - @classmethod - def convert_tool_choice( - cls, tool_choice: Literal["auto", "required", "none"] | str | None - ) -> ChatCompletionToolChoiceOptionParam | NotGiven: - if tool_choice is None: - return NOT_GIVEN - elif tool_choice == "auto": - return "auto" - elif tool_choice == "required": - return "required" - elif tool_choice == "none": - return "none" - else: - return { - "type": "function", - "function": { - "name": tool_choice, - }, - } - - @classmethod - def convert_response_format( - cls, final_output_schema: AgentOutputSchema | None - ) -> ResponseFormat | NotGiven: - if not final_output_schema or final_output_schema.is_plain_text(): - return NOT_GIVEN - - return { - "type": "json_schema", - "json_schema": { - "name": "final_output", - "strict": final_output_schema.strict_json_schema, - "schema": final_output_schema.json_schema(), - }, - } - - @classmethod - def message_to_output_items(cls, message: ChatCompletionMessage) -> list[TResponseOutputItem]: - items: list[TResponseOutputItem] = [] - - message_item = ResponseOutputMessage( - id=FAKE_RESPONSES_ID, - content=[], - role="assistant", - type="message", - status="completed", - ) - if message.content: - message_item.content.append( - ResponseOutputText(text=message.content, type="output_text", annotations=[]) - ) - if message.refusal: - message_item.content.append( - ResponseOutputRefusal(refusal=message.refusal, type="refusal") - ) - if message.audio: - raise AgentsException("Audio is not currently supported") - - if message_item.content: - items.append(message_item) - - if message.tool_calls: - for tool_call in message.tool_calls: - items.append( - ResponseFunctionToolCall( - id=FAKE_RESPONSES_ID, - call_id=tool_call.id, - arguments=tool_call.function.arguments, - name=tool_call.function.name, - type="function_call", - ) - ) - - return items - - @classmethod - def maybe_easy_input_message(cls, item: Any) -> EasyInputMessageParam | None: - if not isinstance(item, dict): - return None - - keys = item.keys() - # EasyInputMessageParam only has these two keys - if keys != {"content", "role"}: - return None - - role = item.get("role", None) - if role not in ("user", "assistant", "system", "developer"): - return None - - if "content" not in item: - return None - - return cast(EasyInputMessageParam, item) - - @classmethod - def maybe_input_message(cls, item: Any) -> Message | None: - if ( - isinstance(item, dict) - and item.get("type") == "message" - and item.get("role") - in ( - "user", - "system", - "developer", - ) - ): - return cast(Message, item) - - return None - - @classmethod - def maybe_file_search_call(cls, item: Any) -> ResponseFileSearchToolCallParam | None: - if isinstance(item, dict) and item.get("type") == "file_search_call": - return cast(ResponseFileSearchToolCallParam, item) - return None - - @classmethod - def maybe_function_tool_call(cls, item: Any) -> ResponseFunctionToolCallParam | None: - if isinstance(item, dict) and item.get("type") == "function_call": - return cast(ResponseFunctionToolCallParam, item) - return None - - @classmethod - def maybe_function_tool_call_output( - cls, - item: Any, - ) -> FunctionCallOutput | None: - if isinstance(item, dict) and item.get("type") == "function_call_output": - return cast(FunctionCallOutput, item) - return None - - @classmethod - def maybe_item_reference(cls, item: Any) -> ItemReference | None: - if isinstance(item, dict) and item.get("type") == "item_reference": - return cast(ItemReference, item) - return None - - @classmethod - def maybe_response_output_message(cls, item: Any) -> ResponseOutputMessageParam | None: - # ResponseOutputMessage is only used for messages with role assistant - if ( - isinstance(item, dict) - and item.get("type") == "message" - and item.get("role") == "assistant" - ): - return cast(ResponseOutputMessageParam, item) - return None - - @classmethod - def extract_text_content( - cls, content: str | Iterable[ResponseInputContentParam] - ) -> str | list[ChatCompletionContentPartTextParam]: - all_content = cls.extract_all_content(content) - if isinstance(all_content, str): - return all_content - out: list[ChatCompletionContentPartTextParam] = [] - for c in all_content: - if c.get("type") == "text": - out.append(cast(ChatCompletionContentPartTextParam, c)) - return out - - @classmethod - def extract_all_content( - cls, content: str | Iterable[ResponseInputContentParam] - ) -> str | list[ChatCompletionContentPartParam]: - if isinstance(content, str): - return content - out: list[ChatCompletionContentPartParam] = [] - - for c in content: - if isinstance(c, dict) and c.get("type") == "input_text": - casted_text_param = cast(ResponseInputTextParam, c) - out.append( - ChatCompletionContentPartTextParam( - type="text", - text=casted_text_param["text"], - ) - ) - elif isinstance(c, dict) and c.get("type") == "input_image": - casted_image_param = cast(ResponseInputImageParam, c) - if "image_url" not in casted_image_param or not casted_image_param["image_url"]: - raise UserError( - f"Only image URLs are supported for input_image {casted_image_param}" - ) - out.append( - ChatCompletionContentPartImageParam( - type="image_url", - image_url={ - "url": casted_image_param["image_url"], - "detail": casted_image_param["detail"], - }, - ) - ) - elif isinstance(c, dict) and c.get("type") == "input_file": - raise UserError(f"File uploads are not supported for chat completions {c}") - else: - raise UserError(f"Unknonw content: {c}") - return out - - @classmethod - def items_to_messages( - cls, - items: str | Iterable[TResponseInputItem], - ) -> list[ChatCompletionMessageParam]: - """ - Convert a sequence of 'Item' objects into a list of ChatCompletionMessageParam. - - Rules: - - EasyInputMessage or InputMessage (role=user) => ChatCompletionUserMessageParam - - EasyInputMessage or InputMessage (role=system) => ChatCompletionSystemMessageParam - - EasyInputMessage or InputMessage (role=developer) => ChatCompletionDeveloperMessageParam - - InputMessage (role=assistant) => Start or flush a ChatCompletionAssistantMessageParam - - response_output_message => Also produces/flushes a ChatCompletionAssistantMessageParam - - tool calls get attached to the *current* assistant message, or create one if none. - - tool outputs => ChatCompletionToolMessageParam - """ - - if isinstance(items, str): - return [ - ChatCompletionUserMessageParam( - role="user", - content=items, - ) - ] - - result: list[ChatCompletionMessageParam] = [] - current_assistant_msg: ChatCompletionAssistantMessageParam | None = None - - def flush_assistant_message() -> None: - nonlocal current_assistant_msg - if current_assistant_msg is not None: - # The API doesn't support empty arrays for tool_calls - if not current_assistant_msg.get("tool_calls"): - del current_assistant_msg["tool_calls"] - result.append(current_assistant_msg) - current_assistant_msg = None - - def ensure_assistant_message() -> ChatCompletionAssistantMessageParam: - nonlocal current_assistant_msg - if current_assistant_msg is None: - current_assistant_msg = ChatCompletionAssistantMessageParam(role="assistant") - current_assistant_msg["tool_calls"] = [] - return current_assistant_msg - - for item in items: - # 1) Check easy input message - if easy_msg := cls.maybe_easy_input_message(item): - role = easy_msg["role"] - content = easy_msg["content"] - - if role == "user": - flush_assistant_message() - msg_user: ChatCompletionUserMessageParam = { - "role": "user", - "content": cls.extract_all_content(content), - } - result.append(msg_user) - elif role == "system": - flush_assistant_message() - msg_system: ChatCompletionSystemMessageParam = { - "role": "system", - "content": cls.extract_text_content(content), - } - result.append(msg_system) - elif role == "developer": - flush_assistant_message() - msg_developer: ChatCompletionDeveloperMessageParam = { - "role": "developer", - "content": cls.extract_text_content(content), - } - result.append(msg_developer) - else: - raise UserError(f"Unexpected role in easy_input_message: {role}") - - # 2) Check input message - elif in_msg := cls.maybe_input_message(item): - role = in_msg["role"] - content = in_msg["content"] - flush_assistant_message() - - if role == "user": - msg_user = { - "role": "user", - "content": cls.extract_all_content(content), - } - result.append(msg_user) - elif role == "system": - msg_system = { - "role": "system", - "content": cls.extract_text_content(content), - } - result.append(msg_system) - elif role == "developer": - msg_developer = { - "role": "developer", - "content": cls.extract_text_content(content), - } - result.append(msg_developer) - else: - raise UserError(f"Unexpected role in input_message: {role}") - - # 3) response output message => assistant - elif resp_msg := cls.maybe_response_output_message(item): - flush_assistant_message() - new_asst = ChatCompletionAssistantMessageParam(role="assistant") - contents = resp_msg["content"] - - text_segments = [] - for c in contents: - if c["type"] == "output_text": - text_segments.append(c["text"]) - elif c["type"] == "refusal": - new_asst["refusal"] = c["refusal"] - elif c["type"] == "output_audio": - # Can't handle this, b/c chat completions expects an ID which we dont have - raise UserError( - f"Only audio IDs are supported for chat completions, but got: {c}" - ) - else: - raise UserError(f"Unknown content type in ResponseOutputMessage: {c}") - - if text_segments: - combined = "\n".join(text_segments) - new_asst["content"] = combined - - new_asst["tool_calls"] = [] - current_assistant_msg = new_asst - - # 4) function/file-search calls => attach to assistant - elif file_search := cls.maybe_file_search_call(item): - asst = ensure_assistant_message() - tool_calls = list(asst.get("tool_calls", [])) - new_tool_call = ChatCompletionMessageToolCallParam( - id=file_search["id"], - type="function", - function={ - "name": "file_search_call", - "arguments": json.dumps( - { - "queries": file_search.get("queries", []), - "status": file_search.get("status"), - } - ), - }, - ) - tool_calls.append(new_tool_call) - asst["tool_calls"] = tool_calls - - elif func_call := cls.maybe_function_tool_call(item): - asst = ensure_assistant_message() - tool_calls = list(asst.get("tool_calls", [])) - new_tool_call = ChatCompletionMessageToolCallParam( - id=func_call["call_id"], - type="function", - function={ - "name": func_call["name"], - "arguments": func_call["arguments"], - }, - ) - tool_calls.append(new_tool_call) - asst["tool_calls"] = tool_calls - # 5) function call output => tool message - elif func_output := cls.maybe_function_tool_call_output(item): - flush_assistant_message() - msg: ChatCompletionToolMessageParam = { - "role": "tool", - "tool_call_id": func_output["call_id"], - "content": func_output["output"], - } - result.append(msg) - - # 6) item reference => handle or raise - elif item_ref := cls.maybe_item_reference(item): - raise UserError( - f"Encountered an item_reference, which is not supported: {item_ref}" - ) - - # 7) If we haven't recognized it => fail or ignore - else: - raise UserError(f"Unhandled item type or structure: {item}") - - flush_assistant_message() - return result - - -class ToolConverter: - @classmethod - def to_openai(cls, tool: Tool) -> ChatCompletionToolParam: - if isinstance(tool, FunctionTool): - return { - "type": "function", - "function": { - "name": tool.name, - "description": tool.description or "", - "parameters": tool.params_json_schema, - }, - } - - raise UserError( - f"Hosted tools are not supported with the ChatCompletions API. FGot tool type: " - f"{type(tool)}, tool: {tool}" - ) - - @classmethod - def convert_handoff_tool(cls, handoff: Handoff[Any]) -> ChatCompletionToolParam: - return { - "type": "function", - "function": { - "name": handoff.tool_name, - "description": handoff.tool_description, - "parameters": handoff.input_json_schema, - }, - } diff --git a/tests/src/agents/models/openai_provider.py b/tests/src/agents/models/openai_provider.py deleted file mode 100644 index 51946638..00000000 --- a/tests/src/agents/models/openai_provider.py +++ /dev/null @@ -1,65 +0,0 @@ -from __future__ import annotations - -import httpx -from openai import AsyncOpenAI, DefaultAsyncHttpxClient - -from . import _openai_shared -from .interface import Model, ModelProvider -from .openai_chatcompletions import OpenAIChatCompletionsModel -from .openai_responses import OpenAIResponsesModel - -DEFAULT_MODEL: str = "gpt-4o" - - -_http_client: httpx.AsyncClient | None = None - - -# If we create a new httpx client for each request, that would mean no sharing of connection pools, -# which would mean worse latency and resource usage. So, we share the client across requests. -def shared_http_client() -> httpx.AsyncClient: - global _http_client - if _http_client is None: - _http_client = DefaultAsyncHttpxClient() - return _http_client - - -class OpenAIProvider(ModelProvider): - def __init__( - self, - *, - api_key: str | None = None, - base_url: str | None = None, - openai_client: AsyncOpenAI | None = None, - organization: str | None = None, - project: str | None = None, - use_responses: bool | None = None, - ) -> None: - if openai_client is not None: - assert api_key is None and base_url is None, ( - "Don't provide api_key or base_url if you provide openai_client" - ) - self._client = openai_client - else: - self._client = _openai_shared.get_default_openai_client() or AsyncOpenAI( - api_key=api_key or _openai_shared.get_default_openai_key(), - base_url=base_url, - organization=organization, - project=project, - http_client=shared_http_client(), - ) - - self._is_openai_model = self._client.base_url.host.startswith("api.openai.com") - if use_responses is not None: - self._use_responses = use_responses - else: - self._use_responses = _openai_shared.get_use_responses_by_default() - - def get_model(self, model_name: str | None) -> Model: - if model_name is None: - model_name = DEFAULT_MODEL - - return ( - OpenAIResponsesModel(model=model_name, openai_client=self._client) - if self._use_responses - else OpenAIChatCompletionsModel(model=model_name, openai_client=self._client) - ) diff --git a/tests/src/agents/models/openai_responses.py b/tests/src/agents/models/openai_responses.py deleted file mode 100644 index a10d7b98..00000000 --- a/tests/src/agents/models/openai_responses.py +++ /dev/null @@ -1,384 +0,0 @@ -from __future__ import annotations - -import json -from collections.abc import AsyncIterator -from dataclasses import dataclass -from typing import TYPE_CHECKING, Any, Literal, overload - -from openai import NOT_GIVEN, AsyncOpenAI, AsyncStream, NotGiven -from openai.types import ChatModel -from openai.types.responses import ( - Response, - ResponseCompletedEvent, - ResponseStreamEvent, - ResponseTextConfigParam, - ToolParam, - WebSearchToolParam, - response_create_params, -) - -from .. import _debug -from ..agent_output import AgentOutputSchema -from ..exceptions import UserError -from ..handoffs import Handoff -from ..items import ItemHelpers, ModelResponse, TResponseInputItem -from ..logger import logger -from ..tool import ComputerTool, FileSearchTool, FunctionTool, Tool, WebSearchTool -from ..tracing import SpanError, response_span -from ..usage import Usage -from ..version import __version__ -from .interface import Model, ModelTracing - -if TYPE_CHECKING: - from ..model_settings import ModelSettings - - -_USER_AGENT = f"Agents/Python {__version__}" -_HEADERS = {"User-Agent": _USER_AGENT} - -# From the Responses API -IncludeLiteral = Literal[ - "file_search_call.results", - "message.input_image.image_url", - "computer_call_output.output.image_url", -] - - -class OpenAIResponsesModel(Model): - """ - Implementation of `Model` that uses the OpenAI Responses API. - """ - - def __init__( - self, - model: str | ChatModel, - openai_client: AsyncOpenAI, - ) -> None: - self.model = model - self._client = openai_client - - def _non_null_or_not_given(self, value: Any) -> Any: - return value if value is not None else NOT_GIVEN - - async def get_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - tracing: ModelTracing, - ) -> ModelResponse: - with response_span(disabled=tracing.is_disabled()) as span_response: - try: - response = await self._fetch_response( - system_instructions, - input, - model_settings, - tools, - output_schema, - handoffs, - stream=False, - ) - - if _debug.DONT_LOG_MODEL_DATA: - logger.debug("LLM responsed") - else: - logger.debug( - "LLM resp:\n" - f"{json.dumps([x.model_dump() for x in response.output], indent=2)}\n" - ) - - usage = ( - Usage( - requests=1, - input_tokens=response.usage.input_tokens, - output_tokens=response.usage.output_tokens, - total_tokens=response.usage.total_tokens, - ) - if response.usage - else Usage() - ) - - if tracing.include_data(): - span_response.span_data.response = response - span_response.span_data.input = input - except Exception as e: - span_response.set_error( - SpanError( - message="Error getting response", - data={ - "error": str(e) if tracing.include_data() else e.__class__.__name__, - }, - ) - ) - logger.error(f"Error getting response: {e}") - raise - - return ModelResponse( - output=response.output, - usage=usage, - referenceable_id=response.id, - ) - - async def stream_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - tracing: ModelTracing, - ) -> AsyncIterator[ResponseStreamEvent]: - """ - Yields a partial message as it is generated, as well as the usage information. - """ - with response_span(disabled=tracing.is_disabled()) as span_response: - try: - stream = await self._fetch_response( - system_instructions, - input, - model_settings, - tools, - output_schema, - handoffs, - stream=True, - ) - - final_response: Response | None = None - - async for chunk in stream: - if isinstance(chunk, ResponseCompletedEvent): - final_response = chunk.response - yield chunk - - if final_response and tracing.include_data(): - span_response.span_data.response = final_response - span_response.span_data.input = input - - except Exception as e: - span_response.set_error( - SpanError( - message="Error streaming response", - data={ - "error": str(e) if tracing.include_data() else e.__class__.__name__, - }, - ) - ) - logger.error(f"Error streaming response: {e}") - raise - - @overload - async def _fetch_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - stream: Literal[True], - ) -> AsyncStream[ResponseStreamEvent]: ... - - @overload - async def _fetch_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - stream: Literal[False], - ) -> Response: ... - - async def _fetch_response( - self, - system_instructions: str | None, - input: str | list[TResponseInputItem], - model_settings: ModelSettings, - tools: list[Tool], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - stream: Literal[True] | Literal[False] = False, - ) -> Response | AsyncStream[ResponseStreamEvent]: - list_input = ItemHelpers.input_to_new_input_list(input) - - parallel_tool_calls = ( - True if model_settings.parallel_tool_calls and tools and len(tools) > 0 else NOT_GIVEN - ) - - tool_choice = Converter.convert_tool_choice(model_settings.tool_choice) - converted_tools = Converter.convert_tools(tools, handoffs) - response_format = Converter.get_response_format(output_schema) - - if _debug.DONT_LOG_MODEL_DATA: - logger.debug("Calling LLM") - else: - logger.debug( - f"Calling LLM {self.model} with input:\n" - f"{json.dumps(list_input, indent=2)}\n" - f"Tools:\n{json.dumps(converted_tools.tools, indent=2)}\n" - f"Stream: {stream}\n" - f"Tool choice: {tool_choice}\n" - f"Response format: {response_format}\n" - ) - - return await self._client.responses.create( - instructions=self._non_null_or_not_given(system_instructions), - model=self.model, - input=list_input, - include=converted_tools.includes, - tools=converted_tools.tools, - temperature=self._non_null_or_not_given(model_settings.temperature), - top_p=self._non_null_or_not_given(model_settings.top_p), - truncation=self._non_null_or_not_given(model_settings.truncation), - tool_choice=tool_choice, - parallel_tool_calls=parallel_tool_calls, - stream=stream, - extra_headers=_HEADERS, - text=response_format, - ) - - def _get_client(self) -> AsyncOpenAI: - if self._client is None: - self._client = AsyncOpenAI() - return self._client - - -@dataclass -class ConvertedTools: - tools: list[ToolParam] - includes: list[IncludeLiteral] - - -class Converter: - @classmethod - def convert_tool_choice( - cls, tool_choice: Literal["auto", "required", "none"] | str | None - ) -> response_create_params.ToolChoice | NotGiven: - if tool_choice is None: - return NOT_GIVEN - elif tool_choice == "required": - return "required" - elif tool_choice == "auto": - return "auto" - elif tool_choice == "none": - return "none" - elif tool_choice == "file_search": - return { - "type": "file_search", - } - elif tool_choice == "web_search_preview": - return { - "type": "web_search_preview", - } - elif tool_choice == "computer_use_preview": - return { - "type": "computer_use_preview", - } - else: - return { - "type": "function", - "name": tool_choice, - } - - @classmethod - def get_response_format( - cls, output_schema: AgentOutputSchema | None - ) -> ResponseTextConfigParam | NotGiven: - if output_schema is None or output_schema.is_plain_text(): - return NOT_GIVEN - else: - return { - "format": { - "type": "json_schema", - "name": "final_output", - "schema": output_schema.json_schema(), - "strict": output_schema.strict_json_schema, - } - } - - @classmethod - def convert_tools( - cls, - tools: list[Tool], - handoffs: list[Handoff[Any]], - ) -> ConvertedTools: - converted_tools: list[ToolParam] = [] - includes: list[IncludeLiteral] = [] - - computer_tools = [tool for tool in tools if isinstance(tool, ComputerTool)] - if len(computer_tools) > 1: - raise UserError(f"You can only provide one computer tool. Got {len(computer_tools)}") - - for tool in tools: - converted_tool, include = cls._convert_tool(tool) - converted_tools.append(converted_tool) - if include: - includes.append(include) - - for handoff in handoffs: - converted_tools.append(cls._convert_handoff_tool(handoff)) - - return ConvertedTools(tools=converted_tools, includes=includes) - - @classmethod - def _convert_tool(cls, tool: Tool) -> tuple[ToolParam, IncludeLiteral | None]: - """Returns converted tool and includes""" - - if isinstance(tool, FunctionTool): - converted_tool: ToolParam = { - "name": tool.name, - "parameters": tool.params_json_schema, - "strict": tool.strict_json_schema, - "type": "function", - "description": tool.description, - } - includes: IncludeLiteral | None = None - elif isinstance(tool, WebSearchTool): - ws: WebSearchToolParam = { - "type": "web_search_preview", - "user_location": tool.user_location, - "search_context_size": tool.search_context_size, - } - converted_tool = ws - includes = None - elif isinstance(tool, FileSearchTool): - converted_tool = { - "type": "file_search", - "vector_store_ids": tool.vector_store_ids, - } - if tool.max_num_results: - converted_tool["max_num_results"] = tool.max_num_results - if tool.ranking_options: - converted_tool["ranking_options"] = tool.ranking_options - if tool.filters: - converted_tool["filters"] = tool.filters - - includes = "file_search_call.results" if tool.include_search_results else None - elif isinstance(tool, ComputerTool): - converted_tool = { - "type": "computer-preview", - "environment": tool.computer.environment, - "display_width": tool.computer.dimensions[0], - "display_height": tool.computer.dimensions[1], - } - includes = None - - else: - raise UserError(f"Unknown tool type: {type(tool)}, tool") - - return converted_tool, includes - - @classmethod - def _convert_handoff_tool(cls, handoff: Handoff) -> ToolParam: - return { - "name": handoff.tool_name, - "parameters": handoff.input_json_schema, - "strict": handoff.strict_json_schema, - "type": "function", - "description": handoff.tool_description, - } diff --git a/tests/src/agents/result.py b/tests/src/agents/result.py deleted file mode 100644 index 56838273..00000000 --- a/tests/src/agents/result.py +++ /dev/null @@ -1,220 +0,0 @@ -from __future__ import annotations - -import abc -import asyncio -from collections.abc import AsyncIterator -from dataclasses import dataclass, field -from typing import TYPE_CHECKING, Any, cast - -from typing_extensions import TypeVar - -from ._run_impl import QueueCompleteSentinel -from .agent import Agent -from .agent_output import AgentOutputSchema -from .exceptions import InputGuardrailTripwireTriggered, MaxTurnsExceeded -from .guardrail import InputGuardrailResult, OutputGuardrailResult -from .items import ItemHelpers, ModelResponse, RunItem, TResponseInputItem -from .logger import logger -from .stream_events import StreamEvent -from .tracing import Trace - -if TYPE_CHECKING: - from ._run_impl import QueueCompleteSentinel - from .agent import Agent - -T = TypeVar("T") - - -@dataclass -class RunResultBase(abc.ABC): - input: str | list[TResponseInputItem] - """The original input items i.e. the items before run() was called. This may be a mutated - version of the input, if there are handoff input filters that mutate the input. - """ - - new_items: list[RunItem] - """The new items generated during the agent run. These include things like new messages, tool - calls and their outputs, etc. - """ - - raw_responses: list[ModelResponse] - """The raw LLM responses generated by the model during the agent run.""" - - final_output: Any - """The output of the last agent.""" - - input_guardrail_results: list[InputGuardrailResult] - """Guardrail results for the input messages.""" - - output_guardrail_results: list[OutputGuardrailResult] - """Guardrail results for the final output of the agent.""" - - @property - @abc.abstractmethod - def last_agent(self) -> Agent[Any]: - """The last agent that was run.""" - - def final_output_as(self, cls: type[T], raise_if_incorrect_type: bool = False) -> T: - """A convenience method to cast the final output to a specific type. By default, the cast - is only for the typechecker. If you set `raise_if_incorrect_type` to True, we'll raise a - TypeError if the final output is not of the given type. - - Args: - cls: The type to cast the final output to. - raise_if_incorrect_type: If True, we'll raise a TypeError if the final output is not of - the given type. - - Returns: - The final output casted to the given type. - """ - if raise_if_incorrect_type and not isinstance(self.final_output, cls): - raise TypeError(f"Final output is not of type {cls.__name__}") - - return cast(T, self.final_output) - - def to_input_list(self) -> list[TResponseInputItem]: - """Creates a new input list, merging the original input with all the new items generated.""" - original_items: list[TResponseInputItem] = ItemHelpers.input_to_new_input_list(self.input) - new_items = [item.to_input_item() for item in self.new_items] - - return original_items + new_items - - -@dataclass -class RunResult(RunResultBase): - _last_agent: Agent[Any] - - @property - def last_agent(self) -> Agent[Any]: - """The last agent that was run.""" - return self._last_agent - - -@dataclass -class RunResultStreaming(RunResultBase): - """The result of an agent run in streaming mode. You can use the `stream_events` method to - receive semantic events as they are generated. - - The streaming method will raise: - - A MaxTurnsExceeded exception if the agent exceeds the max_turns limit. - - A GuardrailTripwireTriggered exception if a guardrail is tripped. - """ - - current_agent: Agent[Any] - """The current agent that is running.""" - - current_turn: int - """The current turn number.""" - - max_turns: int - """The maximum number of turns the agent can run for.""" - - final_output: Any - """The final output of the agent. This is None until the agent has finished running.""" - - _current_agent_output_schema: AgentOutputSchema | None = field(repr=False) - - _trace: Trace | None = field(repr=False) - - is_complete: bool = False - """Whether the agent has finished running.""" - - # Queues that the background run_loop writes to - _event_queue: asyncio.Queue[StreamEvent | QueueCompleteSentinel] = field( - default_factory=asyncio.Queue, repr=False - ) - _input_guardrail_queue: asyncio.Queue[InputGuardrailResult] = field( - default_factory=asyncio.Queue, repr=False - ) - - # Store the asyncio tasks that we're waiting on - _run_impl_task: asyncio.Task[Any] | None = field(default=None, repr=False) - _input_guardrails_task: asyncio.Task[Any] | None = field(default=None, repr=False) - _output_guardrails_task: asyncio.Task[Any] | None = field(default=None, repr=False) - _stored_exception: Exception | None = field(default=None, repr=False) - - @property - def last_agent(self) -> Agent[Any]: - """The last agent that was run. Updates as the agent run progresses, so the true last agent - is only available after the agent run is complete. - """ - return self.current_agent - - async def stream_events(self) -> AsyncIterator[StreamEvent]: - """Stream deltas for new items as they are generated. We're using the types from the - OpenAI Responses API, so these are semantic events: each event has a `type` field that - describes the type of the event, along with the data for that event. - - This will raise: - - A MaxTurnsExceeded exception if the agent exceeds the max_turns limit. - - A GuardrailTripwireTriggered exception if a guardrail is tripped. - """ - while True: - self._check_errors() - if self._stored_exception: - logger.debug("Breaking due to stored exception") - self.is_complete = True - break - - if self.is_complete and self._event_queue.empty(): - break - - try: - item = await self._event_queue.get() - except asyncio.CancelledError: - break - - if isinstance(item, QueueCompleteSentinel): - self._event_queue.task_done() - # Check for errors, in case the queue was completed due to an exception - self._check_errors() - break - - yield item - self._event_queue.task_done() - - if self._trace: - self._trace.finish(reset_current=True) - - self._cleanup_tasks() - - if self._stored_exception: - raise self._stored_exception - - def _check_errors(self): - if self.current_turn > self.max_turns: - self._stored_exception = MaxTurnsExceeded(f"Max turns ({self.max_turns}) exceeded") - - # Fetch all the completed guardrail results from the queue and raise if needed - while not self._input_guardrail_queue.empty(): - guardrail_result = self._input_guardrail_queue.get_nowait() - if guardrail_result.output.tripwire_triggered: - self._stored_exception = InputGuardrailTripwireTriggered(guardrail_result) - - # Check the tasks for any exceptions - if self._run_impl_task and self._run_impl_task.done(): - exc = self._run_impl_task.exception() - if exc and isinstance(exc, Exception): - self._stored_exception = exc - - if self._input_guardrails_task and self._input_guardrails_task.done(): - exc = self._input_guardrails_task.exception() - if exc and isinstance(exc, Exception): - self._stored_exception = exc - - if self._output_guardrails_task and self._output_guardrails_task.done(): - exc = self._output_guardrails_task.exception() - if exc and isinstance(exc, Exception): - self._stored_exception = exc - - def _cleanup_tasks(self): - if self._run_impl_task and not self._run_impl_task.done(): - self._run_impl_task.cancel() - - if self._input_guardrails_task and not self._input_guardrails_task.done(): - self._input_guardrails_task.cancel() - - if self._output_guardrails_task and not self._output_guardrails_task.done(): - self._output_guardrails_task.cancel() - self._output_guardrails_task.cancel() - self._output_guardrails_task.cancel() diff --git a/tests/src/agents/run.py b/tests/src/agents/run.py deleted file mode 100644 index dfff7e38..00000000 --- a/tests/src/agents/run.py +++ /dev/null @@ -1,904 +0,0 @@ -from __future__ import annotations - -import asyncio -import copy -from dataclasses import dataclass, field -from typing import Any, cast - -from openai.types.responses import ResponseCompletedEvent - -from . import Model, _utils -from ._run_impl import ( - NextStepFinalOutput, - NextStepHandoff, - NextStepRunAgain, - QueueCompleteSentinel, - RunImpl, - SingleStepResult, - TraceCtxManager, - get_model_tracing_impl, -) -from .agent import Agent -from .agent_output import AgentOutputSchema -from .exceptions import ( - AgentsException, - InputGuardrailTripwireTriggered, - MaxTurnsExceeded, - ModelBehaviorError, - OutputGuardrailTripwireTriggered, -) -from .guardrail import InputGuardrail, InputGuardrailResult, OutputGuardrail, OutputGuardrailResult -from .handoffs import Handoff, HandoffInputFilter, handoff -from .items import ItemHelpers, ModelResponse, RunItem, TResponseInputItem -from .lifecycle import RunHooks -from .logger import logger -from .model_settings import ModelSettings -from .models.interface import ModelProvider -from .models.openai_provider import OpenAIProvider -from .result import RunResult, RunResultStreaming -from .run_context import RunContextWrapper, TContext -from .stream_events import AgentUpdatedStreamEvent, RawResponsesStreamEvent -from .tracing import Span, SpanError, agent_span, get_current_trace, trace -from .tracing.span_data import AgentSpanData -from .usage import Usage - -DEFAULT_MAX_TURNS = 10 - - -@dataclass -class RunConfig: - """Configures settings for the entire agent run.""" - - model: str | Model | None = None - """The model to use for the entire agent run. If set, will override the model set on every - agent. The model_provider passed in below must be able to resolve this model name. - """ - - model_provider: ModelProvider = field(default_factory=OpenAIProvider) - """The model provider to use when looking up string model names. Defaults to OpenAI.""" - - model_settings: ModelSettings | None = None - """Configure global model settings. Any non-null values will override the agent-specific model - settings. - """ - - handoff_input_filter: HandoffInputFilter | None = None - """A global input filter to apply to all handoffs. If `Handoff.input_filter` is set, then that - will take precedence. The input filter allows you to edit the inputs that are sent to the new - agent. See the documentation in `Handoff.input_filter` for more details. - """ - - input_guardrails: list[InputGuardrail[Any]] | None = None - """A list of input guardrails to run on the initial run input.""" - - output_guardrails: list[OutputGuardrail[Any]] | None = None - """A list of output guardrails to run on the final output of the run.""" - - tracing_disabled: bool = False - """Whether tracing is disabled for the agent run. If disabled, we will not trace the agent run. - """ - - trace_include_sensitive_data: bool = True - """Whether we include potentially sensitive data (for example: inputs/outputs of tool calls or - LLM generations) in traces. If False, we'll still create spans for these events, but the - sensitive data will not be included. - """ - - workflow_name: str = "Agent workflow" - """The name of the run, used for tracing. Should be a logical name for the run, like - "Code generation workflow" or "Customer support agent". - """ - - trace_id: str | None = None - """A custom trace ID to use for tracing. If not provided, we will generate a new trace ID.""" - - group_id: str | None = None - """ - A grouping identifier to use for tracing, to link multiple traces from the same conversation - or process. For example, you might use a chat thread ID. - """ - - trace_metadata: dict[str, Any] | None = None - """ - An optional dictionary of additional metadata to include with the trace. - """ - - -class Runner: - @classmethod - async def run( - cls, - starting_agent: Agent[TContext], - input: str | list[TResponseInputItem], - *, - context: TContext | None = None, - max_turns: int = DEFAULT_MAX_TURNS, - hooks: RunHooks[TContext] | None = None, - run_config: RunConfig | None = None, - ) -> RunResult: - """Run a workflow starting at the given agent. The agent will run in a loop until a final - output is generated. The loop runs like so: - 1. The agent is invoked with the given input. - 2. If there is a final output (i.e. the agent produces something of type - `agent.output_type`, the loop terminates. - 3. If there's a handoff, we run the loop again, with the new agent. - 4. Else, we run tool calls (if any), and re-run the loop. - - In two cases, the agent may raise an exception: - 1. If the max_turns is exceeded, a MaxTurnsExceeded exception is raised. - 2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised. - - Note that only the first agent's input guardrails are run. - - Args: - starting_agent: The starting agent to run. - input: The initial input to the agent. You can pass a single string for a user message, - or a list of input items. - context: The context to run the agent with. - max_turns: The maximum number of turns to run the agent for. A turn is defined as one - AI invocation (including any tool calls that might occur). - hooks: An object that receives callbacks on various lifecycle events. - run_config: Global settings for the entire agent run. - - Returns: - A run result containing all the inputs, guardrail results and the output of the last - agent. Agents may perform handoffs, so we don't know the specific type of the output. - """ - if hooks is None: - hooks = RunHooks[Any]() - if run_config is None: - run_config = RunConfig() - - with TraceCtxManager( - workflow_name=run_config.workflow_name, - trace_id=run_config.trace_id, - group_id=run_config.group_id, - metadata=run_config.trace_metadata, - disabled=run_config.tracing_disabled, - ): - current_turn = 0 - original_input: str | list[TResponseInputItem] = copy.deepcopy(input) - generated_items: list[RunItem] = [] - model_responses: list[ModelResponse] = [] - - context_wrapper: RunContextWrapper[TContext] = RunContextWrapper( - context=context, # type: ignore - ) - - input_guardrail_results: list[InputGuardrailResult] = [] - - current_span: Span[AgentSpanData] | None = None - current_agent = starting_agent - should_run_agent_start_hooks = True - - try: - while True: - # Start an agent span if we don't have one. This span is ended if the current - # agent changes, or if the agent loop ends. - if current_span is None: - handoff_names = [h.agent_name for h in cls._get_handoffs(current_agent)] - tool_names = [t.name for t in current_agent.tools] - if output_schema := cls._get_output_schema(current_agent): - output_type_name = output_schema.output_type_name() - else: - output_type_name = "str" - - current_span = agent_span( - name=current_agent.name, - handoffs=handoff_names, - tools=tool_names, - output_type=output_type_name, - ) - current_span.start(mark_as_current=True) - - current_turn += 1 - if current_turn > max_turns: - _utils.attach_error_to_span( - current_span, - SpanError( - message="Max turns exceeded", - data={"max_turns": max_turns}, - ), - ) - raise MaxTurnsExceeded(f"Max turns ({max_turns}) exceeded") - - logger.debug( - f"Running agent {current_agent.name} (turn {current_turn})", - ) - - if current_turn == 1: - input_guardrail_results, turn_result = await asyncio.gather( - cls._run_input_guardrails( - starting_agent, - starting_agent.input_guardrails - + (run_config.input_guardrails or []), - copy.deepcopy(input), - context_wrapper, - ), - cls._run_single_turn( - agent=current_agent, - original_input=original_input, - generated_items=generated_items, - hooks=hooks, - context_wrapper=context_wrapper, - run_config=run_config, - should_run_agent_start_hooks=should_run_agent_start_hooks, - ), - ) - else: - turn_result = await cls._run_single_turn( - agent=current_agent, - original_input=original_input, - generated_items=generated_items, - hooks=hooks, - context_wrapper=context_wrapper, - run_config=run_config, - should_run_agent_start_hooks=should_run_agent_start_hooks, - ) - should_run_agent_start_hooks = False - - model_responses.append(turn_result.model_response) - original_input = turn_result.original_input - generated_items = turn_result.generated_items - - if isinstance(turn_result.next_step, NextStepFinalOutput): - output_guardrail_results = await cls._run_output_guardrails( - current_agent.output_guardrails + (run_config.output_guardrails or []), - current_agent, - turn_result.next_step.output, - context_wrapper, - ) - return RunResult( - input=original_input, - new_items=generated_items, - raw_responses=model_responses, - final_output=turn_result.next_step.output, - _last_agent=current_agent, - input_guardrail_results=input_guardrail_results, - output_guardrail_results=output_guardrail_results, - ) - elif isinstance(turn_result.next_step, NextStepHandoff): - current_agent = cast(Agent[TContext], turn_result.next_step.new_agent) - current_span.finish(reset_current=True) - current_span = None - should_run_agent_start_hooks = True - elif isinstance(turn_result.next_step, NextStepRunAgain): - pass - else: - raise AgentsException( - f"Unknown next step type: {type(turn_result.next_step)}" - ) - finally: - if current_span: - current_span.finish(reset_current=True) - - @classmethod - def run_sync( - cls, - starting_agent: Agent[TContext], - input: str | list[TResponseInputItem], - *, - context: TContext | None = None, - max_turns: int = DEFAULT_MAX_TURNS, - hooks: RunHooks[TContext] | None = None, - run_config: RunConfig | None = None, - ) -> RunResult: - """Run a workflow synchronously, starting at the given agent. Note that this just wraps the - `run` method, so it will not work if there's already an event loop (e.g. inside an async - function, or in a Jupyter notebook or async context like FastAPI). For those cases, use - the `run` method instead. - - The agent will run in a loop until a final output is generated. The loop runs like so: - 1. The agent is invoked with the given input. - 2. If there is a final output (i.e. the agent produces something of type - `agent.output_type`, the loop terminates. - 3. If there's a handoff, we run the loop again, with the new agent. - 4. Else, we run tool calls (if any), and re-run the loop. - - In two cases, the agent may raise an exception: - 1. If the max_turns is exceeded, a MaxTurnsExceeded exception is raised. - 2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised. - - Note that only the first agent's input guardrails are run. - - Args: - starting_agent: The starting agent to run. - input: The initial input to the agent. You can pass a single string for a user message, - or a list of input items. - context: The context to run the agent with. - max_turns: The maximum number of turns to run the agent for. A turn is defined as one - AI invocation (including any tool calls that might occur). - hooks: An object that receives callbacks on various lifecycle events. - run_config: Global settings for the entire agent run. - - Returns: - A run result containing all the inputs, guardrail results and the output of the last - agent. Agents may perform handoffs, so we don't know the specific type of the output. - """ - return asyncio.get_event_loop().run_until_complete( - cls.run( - starting_agent, - input, - context=context, - max_turns=max_turns, - hooks=hooks, - run_config=run_config, - ) - ) - - @classmethod - def run_streamed( - cls, - starting_agent: Agent[TContext], - input: str | list[TResponseInputItem], - context: TContext | None = None, - max_turns: int = DEFAULT_MAX_TURNS, - hooks: RunHooks[TContext] | None = None, - run_config: RunConfig | None = None, - ) -> RunResultStreaming: - """Run a workflow starting at the given agent in streaming mode. The returned result object - contains a method you can use to stream semantic events as they are generated. - - The agent will run in a loop until a final output is generated. The loop runs like so: - 1. The agent is invoked with the given input. - 2. If there is a final output (i.e. the agent produces something of type - `agent.output_type`, the loop terminates. - 3. If there's a handoff, we run the loop again, with the new agent. - 4. Else, we run tool calls (if any), and re-run the loop. - - In two cases, the agent may raise an exception: - 1. If the max_turns is exceeded, a MaxTurnsExceeded exception is raised. - 2. If a guardrail tripwire is triggered, a GuardrailTripwireTriggered exception is raised. - - Note that only the first agent's input guardrails are run. - - Args: - starting_agent: The starting agent to run. - input: The initial input to the agent. You can pass a single string for a user message, - or a list of input items. - context: The context to run the agent with. - max_turns: The maximum number of turns to run the agent for. A turn is defined as one - AI invocation (including any tool calls that might occur). - hooks: An object that receives callbacks on various lifecycle events. - run_config: Global settings for the entire agent run. - - Returns: - A result object that contains data about the run, as well as a method to stream events. - """ - if hooks is None: - hooks = RunHooks[Any]() - if run_config is None: - run_config = RunConfig() - - # If there's already a trace, we don't create a new one. In addition, we can't end the - # trace here, because the actual work is done in `stream_events` and this method ends - # before that. - new_trace = ( - None - if get_current_trace() - else trace( - workflow_name=run_config.workflow_name, - trace_id=run_config.trace_id, - group_id=run_config.group_id, - metadata=run_config.trace_metadata, - disabled=run_config.tracing_disabled, - ) - ) - # Need to start the trace here, because the current trace contextvar is captured at - # asyncio.create_task time - if new_trace: - new_trace.start(mark_as_current=True) - - output_schema = cls._get_output_schema(starting_agent) - context_wrapper: RunContextWrapper[TContext] = RunContextWrapper( - context=context # type: ignore - ) - - streamed_result = RunResultStreaming( - input=copy.deepcopy(input), - new_items=[], - current_agent=starting_agent, - raw_responses=[], - final_output=None, - is_complete=False, - current_turn=0, - max_turns=max_turns, - input_guardrail_results=[], - output_guardrail_results=[], - _current_agent_output_schema=output_schema, - _trace=new_trace, - ) - - # Kick off the actual agent loop in the background and return the streamed result object. - streamed_result._run_impl_task = asyncio.create_task( - cls._run_streamed_impl( - starting_input=input, - streamed_result=streamed_result, - starting_agent=starting_agent, - max_turns=max_turns, - hooks=hooks, - context_wrapper=context_wrapper, - run_config=run_config, - ) - ) - return streamed_result - - @classmethod - async def _run_input_guardrails_with_queue( - cls, - agent: Agent[Any], - guardrails: list[InputGuardrail[TContext]], - input: str | list[TResponseInputItem], - context: RunContextWrapper[TContext], - streamed_result: RunResultStreaming, - parent_span: Span[Any], - ): - queue = streamed_result._input_guardrail_queue - - # We'll run the guardrails and push them onto the queue as they complete - guardrail_tasks = [ - asyncio.create_task( - RunImpl.run_single_input_guardrail(agent, guardrail, input, context) - ) - for guardrail in guardrails - ] - guardrail_results = [] - try: - for done in asyncio.as_completed(guardrail_tasks): - result = await done - if result.output.tripwire_triggered: - _utils.attach_error_to_span( - parent_span, - SpanError( - message="Guardrail tripwire triggered", - data={ - "guardrail": result.guardrail.get_name(), - "type": "input_guardrail", - }, - ), - ) - queue.put_nowait(result) - guardrail_results.append(result) - except Exception: - for t in guardrail_tasks: - t.cancel() - raise - - streamed_result.input_guardrail_results = guardrail_results - - @classmethod - async def _run_streamed_impl( - cls, - starting_input: str | list[TResponseInputItem], - streamed_result: RunResultStreaming, - starting_agent: Agent[TContext], - max_turns: int, - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - run_config: RunConfig, - ): - current_span: Span[AgentSpanData] | None = None - current_agent = starting_agent - current_turn = 0 - should_run_agent_start_hooks = True - - streamed_result._event_queue.put_nowait(AgentUpdatedStreamEvent(new_agent=current_agent)) - - try: - while True: - if streamed_result.is_complete: - break - - # Start an agent span if we don't have one. This span is ended if the current - # agent changes, or if the agent loop ends. - if current_span is None: - handoff_names = [h.agent_name for h in cls._get_handoffs(current_agent)] - tool_names = [t.name for t in current_agent.tools] - if output_schema := cls._get_output_schema(current_agent): - output_type_name = output_schema.output_type_name() - else: - output_type_name = "str" - - current_span = agent_span( - name=current_agent.name, - handoffs=handoff_names, - tools=tool_names, - output_type=output_type_name, - ) - current_span.start(mark_as_current=True) - - current_turn += 1 - streamed_result.current_turn = current_turn - - if current_turn > max_turns: - _utils.attach_error_to_span( - current_span, - SpanError( - message="Max turns exceeded", - data={"max_turns": max_turns}, - ), - ) - streamed_result._event_queue.put_nowait(QueueCompleteSentinel()) - break - - if current_turn == 1: - # Run the input guardrails in the background and put the results on the queue - streamed_result._input_guardrails_task = asyncio.create_task( - cls._run_input_guardrails_with_queue( - starting_agent, - starting_agent.input_guardrails + (run_config.input_guardrails or []), - copy.deepcopy(ItemHelpers.input_to_new_input_list(starting_input)), - context_wrapper, - streamed_result, - current_span, - ) - ) - try: - turn_result = await cls._run_single_turn_streamed( - streamed_result, - current_agent, - hooks, - context_wrapper, - run_config, - should_run_agent_start_hooks, - ) - should_run_agent_start_hooks = False - - streamed_result.raw_responses = streamed_result.raw_responses + [ - turn_result.model_response - ] - streamed_result.input = turn_result.original_input - streamed_result.new_items = turn_result.generated_items - - if isinstance(turn_result.next_step, NextStepHandoff): - current_agent = turn_result.next_step.new_agent - current_span.finish(reset_current=True) - current_span = None - should_run_agent_start_hooks = True - streamed_result._event_queue.put_nowait( - AgentUpdatedStreamEvent(new_agent=current_agent) - ) - elif isinstance(turn_result.next_step, NextStepFinalOutput): - streamed_result._output_guardrails_task = asyncio.create_task( - cls._run_output_guardrails( - current_agent.output_guardrails - + (run_config.output_guardrails or []), - current_agent, - turn_result.next_step.output, - context_wrapper, - ) - ) - - try: - output_guardrail_results = await streamed_result._output_guardrails_task - except Exception: - # Exceptions will be checked in the stream_events loop - output_guardrail_results = [] - - streamed_result.output_guardrail_results = output_guardrail_results - streamed_result.final_output = turn_result.next_step.output - streamed_result.is_complete = True - streamed_result._event_queue.put_nowait(QueueCompleteSentinel()) - elif isinstance(turn_result.next_step, NextStepRunAgain): - pass - except Exception as e: - if current_span: - _utils.attach_error_to_span( - current_span, - SpanError( - message="Error in agent run", - data={"error": str(e)}, - ), - ) - streamed_result.is_complete = True - streamed_result._event_queue.put_nowait(QueueCompleteSentinel()) - raise - - streamed_result.is_complete = True - finally: - if current_span: - current_span.finish(reset_current=True) - - @classmethod - async def _run_single_turn_streamed( - cls, - streamed_result: RunResultStreaming, - agent: Agent[TContext], - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - run_config: RunConfig, - should_run_agent_start_hooks: bool, - ) -> SingleStepResult: - if should_run_agent_start_hooks: - await asyncio.gather( - hooks.on_agent_start(context_wrapper, agent), - ( - agent.hooks.on_start(context_wrapper, agent) - if agent.hooks - else _utils.noop_coroutine() - ), - ) - - output_schema = cls._get_output_schema(agent) - - streamed_result.current_agent = agent - streamed_result._current_agent_output_schema = output_schema - - system_prompt = await agent.get_system_prompt(context_wrapper) - - handoffs = cls._get_handoffs(agent) - - model = cls._get_model(agent, run_config) - model_settings = agent.model_settings.resolve(run_config.model_settings) - final_response: ModelResponse | None = None - - input = ItemHelpers.input_to_new_input_list(streamed_result.input) - input.extend([item.to_input_item() for item in streamed_result.new_items]) - - # 1. Stream the output events - async for event in model.stream_response( - system_prompt, - input, - model_settings, - agent.tools, - output_schema, - handoffs, - get_model_tracing_impl( - run_config.tracing_disabled, run_config.trace_include_sensitive_data - ), - ): - if isinstance(event, ResponseCompletedEvent): - usage = ( - Usage( - requests=1, - input_tokens=event.response.usage.input_tokens, - output_tokens=event.response.usage.output_tokens, - total_tokens=event.response.usage.total_tokens, - ) - if event.response.usage - else Usage() - ) - final_response = ModelResponse( - output=event.response.output, - usage=usage, - referenceable_id=event.response.id, - ) - - streamed_result._event_queue.put_nowait(RawResponsesStreamEvent(data=event)) - - # 2. At this point, the streaming is complete for this turn of the agent loop. - if not final_response: - raise ModelBehaviorError("Model did not produce a final response!") - - # 3. Now, we can process the turn as we do in the non-streaming case - single_step_result = await cls._get_single_step_result_from_response( - agent=agent, - original_input=streamed_result.input, - pre_step_items=streamed_result.new_items, - new_response=final_response, - output_schema=output_schema, - handoffs=handoffs, - hooks=hooks, - context_wrapper=context_wrapper, - run_config=run_config, - ) - - RunImpl.stream_step_result_to_queue(single_step_result, streamed_result._event_queue) - return single_step_result - - @classmethod - async def _run_single_turn( - cls, - *, - agent: Agent[TContext], - original_input: str | list[TResponseInputItem], - generated_items: list[RunItem], - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - run_config: RunConfig, - should_run_agent_start_hooks: bool, - ) -> SingleStepResult: - # Ensure we run the hooks before anything else - if should_run_agent_start_hooks: - await asyncio.gather( - hooks.on_agent_start(context_wrapper, agent), - ( - agent.hooks.on_start(context_wrapper, agent) - if agent.hooks - else _utils.noop_coroutine() - ), - ) - - system_prompt = await agent.get_system_prompt(context_wrapper) - - output_schema = cls._get_output_schema(agent) - handoffs = cls._get_handoffs(agent) - input = ItemHelpers.input_to_new_input_list(original_input) - input.extend([generated_item.to_input_item() for generated_item in generated_items]) - - new_response = await cls._get_new_response( - agent, - system_prompt, - input, - output_schema, - handoffs, - context_wrapper, - run_config, - ) - - return await cls._get_single_step_result_from_response( - agent=agent, - original_input=original_input, - pre_step_items=generated_items, - new_response=new_response, - output_schema=output_schema, - handoffs=handoffs, - hooks=hooks, - context_wrapper=context_wrapper, - run_config=run_config, - ) - - @classmethod - async def _get_single_step_result_from_response( - cls, - *, - agent: Agent[TContext], - original_input: str | list[TResponseInputItem], - pre_step_items: list[RunItem], - new_response: ModelResponse, - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - hooks: RunHooks[TContext], - context_wrapper: RunContextWrapper[TContext], - run_config: RunConfig, - ) -> SingleStepResult: - processed_response = RunImpl.process_model_response( - agent=agent, - response=new_response, - output_schema=output_schema, - handoffs=handoffs, - ) - return await RunImpl.execute_tools_and_side_effects( - agent=agent, - original_input=original_input, - pre_step_items=pre_step_items, - new_response=new_response, - processed_response=processed_response, - output_schema=output_schema, - hooks=hooks, - context_wrapper=context_wrapper, - run_config=run_config, - ) - - @classmethod - async def _run_input_guardrails( - cls, - agent: Agent[Any], - guardrails: list[InputGuardrail[TContext]], - input: str | list[TResponseInputItem], - context: RunContextWrapper[TContext], - ) -> list[InputGuardrailResult]: - if not guardrails: - return [] - - guardrail_tasks = [ - asyncio.create_task( - RunImpl.run_single_input_guardrail(agent, guardrail, input, context) - ) - for guardrail in guardrails - ] - - guardrail_results = [] - - for done in asyncio.as_completed(guardrail_tasks): - result = await done - if result.output.tripwire_triggered: - # Cancel all guardrail tasks if a tripwire is triggered. - for t in guardrail_tasks: - t.cancel() - _utils.attach_error_to_current_span( - SpanError( - message="Guardrail tripwire triggered", - data={"guardrail": result.guardrail.get_name()}, - ) - ) - raise InputGuardrailTripwireTriggered(result) - else: - guardrail_results.append(result) - - return guardrail_results - - @classmethod - async def _run_output_guardrails( - cls, - guardrails: list[OutputGuardrail[TContext]], - agent: Agent[TContext], - agent_output: Any, - context: RunContextWrapper[TContext], - ) -> list[OutputGuardrailResult]: - if not guardrails: - return [] - - guardrail_tasks = [ - asyncio.create_task( - RunImpl.run_single_output_guardrail(guardrail, agent, agent_output, context) - ) - for guardrail in guardrails - ] - - guardrail_results = [] - - for done in asyncio.as_completed(guardrail_tasks): - result = await done - if result.output.tripwire_triggered: - # Cancel all guardrail tasks if a tripwire is triggered. - for t in guardrail_tasks: - t.cancel() - _utils.attach_error_to_current_span( - SpanError( - message="Guardrail tripwire triggered", - data={"guardrail": result.guardrail.get_name()}, - ) - ) - raise OutputGuardrailTripwireTriggered(result) - else: - guardrail_results.append(result) - - return guardrail_results - - @classmethod - async def _get_new_response( - cls, - agent: Agent[TContext], - system_prompt: str | None, - input: list[TResponseInputItem], - output_schema: AgentOutputSchema | None, - handoffs: list[Handoff], - context_wrapper: RunContextWrapper[TContext], - run_config: RunConfig, - ) -> ModelResponse: - model = cls._get_model(agent, run_config) - model_settings = agent.model_settings.resolve(run_config.model_settings) - new_response = await model.get_response( - system_instructions=system_prompt, - input=input, - model_settings=model_settings, - tools=agent.tools, - output_schema=output_schema, - handoffs=handoffs, - tracing=get_model_tracing_impl( - run_config.tracing_disabled, run_config.trace_include_sensitive_data - ), - ) - - context_wrapper.usage.add(new_response.usage) - - return new_response - - @classmethod - def _get_output_schema(cls, agent: Agent[Any]) -> AgentOutputSchema | None: - if agent.output_type is None or agent.output_type is str: - return None - - return AgentOutputSchema(agent.output_type) - - @classmethod - def _get_handoffs(cls, agent: Agent[Any]) -> list[Handoff]: - handoffs = [] - for handoff_item in agent.handoffs: - if isinstance(handoff_item, Handoff): - handoffs.append(handoff_item) - elif isinstance(handoff_item, Agent): - handoffs.append(handoff(handoff_item)) - return handoffs - - @classmethod - def _get_model(cls, agent: Agent[Any], run_config: RunConfig) -> Model: - if isinstance(run_config.model, Model): - return run_config.model - elif isinstance(run_config.model, str): - return run_config.model_provider.get_model(run_config.model) - elif isinstance(agent.model, Model): - return agent.model - - return run_config.model_provider.get_model(agent.model) diff --git a/tests/src/agents/run_context.py b/tests/src/agents/run_context.py deleted file mode 100644 index 579a215f..00000000 --- a/tests/src/agents/run_context.py +++ /dev/null @@ -1,26 +0,0 @@ -from dataclasses import dataclass, field -from typing import Any, Generic - -from typing_extensions import TypeVar - -from .usage import Usage - -TContext = TypeVar("TContext", default=Any) - - -@dataclass -class RunContextWrapper(Generic[TContext]): - """This wraps the context object that you passed to `Runner.run()`. It also contains - information about the usage of the agent run so far. - - NOTE: Contexts are not passed to the LLM. They're a way to pass dependencies and data to code - you implement, like tool functions, callbacks, hooks, etc. - """ - - context: TContext - """The context object (or None), passed by you to `Runner.run()`""" - - usage: Usage = field(default_factory=Usage) - """The usage of the agent run so far. For streamed responses, the usage will be stale until the - last chunk of the stream is processed. - """ diff --git a/tests/src/agents/stream_events.py b/tests/src/agents/stream_events.py deleted file mode 100644 index bd37d11f..00000000 --- a/tests/src/agents/stream_events.py +++ /dev/null @@ -1,58 +0,0 @@ -from __future__ import annotations - -from dataclasses import dataclass -from typing import Any, Literal, Union - -from typing_extensions import TypeAlias - -from .agent import Agent -from .items import RunItem, TResponseStreamEvent - - -@dataclass -class RawResponsesStreamEvent: - """Streaming event from the LLM. These are 'raw' events, i.e. they are directly passed through - from the LLM. - """ - - data: TResponseStreamEvent - """The raw responses streaming event from the LLM.""" - - type: Literal["raw_response_event"] = "raw_response_event" - """The type of the event.""" - - -@dataclass -class RunItemStreamEvent: - """Streaming events that wrap a `RunItem`. As the agent processes the LLM response, it will - generate these events for new messages, tool calls, tool outputs, handoffs, etc. - """ - - name: Literal[ - "message_output_created", - "handoff_requested", - "handoff_occured", - "tool_called", - "tool_output", - "reasoning_item_created", - ] - """The name of the event.""" - - item: RunItem - """The item that was created.""" - - type: Literal["run_item_stream_event"] = "run_item_stream_event" - - -@dataclass -class AgentUpdatedStreamEvent: - """Event that notifies that there is a new agent running.""" - - new_agent: Agent[Any] - """The new agent.""" - - type: Literal["agent_updated_stream_event"] = "agent_updated_stream_event" - - -StreamEvent: TypeAlias = Union[RawResponsesStreamEvent, RunItemStreamEvent, AgentUpdatedStreamEvent] -"""A streaming event from an agent.""" diff --git a/tests/src/agents/strict_schema.py b/tests/src/agents/strict_schema.py deleted file mode 100644 index 910ad85f..00000000 --- a/tests/src/agents/strict_schema.py +++ /dev/null @@ -1,167 +0,0 @@ -from __future__ import annotations - -from typing import Any - -from openai import NOT_GIVEN -from typing_extensions import TypeGuard - -from .exceptions import UserError - -_EMPTY_SCHEMA = { - "additionalProperties": False, - "type": "object", - "properties": {}, - "required": [], -} - - -def ensure_strict_json_schema( - schema: dict[str, Any], -) -> dict[str, Any]: - """Mutates the given JSON schema to ensure it conforms to the `strict` standard - that the OpenAI API expects. - """ - if schema == {}: - return _EMPTY_SCHEMA - return _ensure_strict_json_schema(schema, path=(), root=schema) - - -# Adapted from https://github.com/openai/openai-python/blob/main/src/openai/lib/_pydantic.py -def _ensure_strict_json_schema( - json_schema: object, - *, - path: tuple[str, ...], - root: dict[str, object], -) -> dict[str, Any]: - if not is_dict(json_schema): - raise TypeError(f"Expected {json_schema} to be a dictionary; path={path}") - - defs = json_schema.get("$defs") - if is_dict(defs): - for def_name, def_schema in defs.items(): - _ensure_strict_json_schema(def_schema, path=(*path, "$defs", def_name), root=root) - - definitions = json_schema.get("definitions") - if is_dict(definitions): - for definition_name, definition_schema in definitions.items(): - _ensure_strict_json_schema( - definition_schema, path=(*path, "definitions", definition_name), root=root - ) - - typ = json_schema.get("type") - if typ == "object" and "additionalProperties" not in json_schema: - json_schema["additionalProperties"] = False - elif ( - typ == "object" - and "additionalProperties" in json_schema - and json_schema["additionalProperties"] is True - ): - raise UserError( - "additionalProperties should not be set for object types. This could be because " - "you're using an older version of Pydantic, or because you configured additional " - "properties to be allowed. If you really need this, update the function or output tool " - "to not use a strict schema." - ) - - # object types - # { 'type': 'object', 'properties': { 'a': {...} } } - properties = json_schema.get("properties") - if is_dict(properties): - json_schema["required"] = list(properties.keys()) - json_schema["properties"] = { - key: _ensure_strict_json_schema(prop_schema, path=(*path, "properties", key), root=root) - for key, prop_schema in properties.items() - } - - # arrays - # { 'type': 'array', 'items': {...} } - items = json_schema.get("items") - if is_dict(items): - json_schema["items"] = _ensure_strict_json_schema(items, path=(*path, "items"), root=root) - - # unions - any_of = json_schema.get("anyOf") - if is_list(any_of): - json_schema["anyOf"] = [ - _ensure_strict_json_schema(variant, path=(*path, "anyOf", str(i)), root=root) - for i, variant in enumerate(any_of) - ] - - # intersections - all_of = json_schema.get("allOf") - if is_list(all_of): - if len(all_of) == 1: - json_schema.update( - _ensure_strict_json_schema(all_of[0], path=(*path, "allOf", "0"), root=root) - ) - json_schema.pop("allOf") - else: - json_schema["allOf"] = [ - _ensure_strict_json_schema(entry, path=(*path, "allOf", str(i)), root=root) - for i, entry in enumerate(all_of) - ] - - # strip `None` defaults as there's no meaningful distinction here - # the schema will still be `nullable` and the model will default - # to using `None` anyway - if json_schema.get("default", NOT_GIVEN) is None: - json_schema.pop("default") - - # we can't use `$ref`s if there are also other properties defined, e.g. - # `{"$ref": "...", "description": "my description"}` - # - # so we unravel the ref - # `{"type": "string", "description": "my description"}` - ref = json_schema.get("$ref") - if ref and has_more_than_n_keys(json_schema, 1): - assert isinstance(ref, str), f"Received non-string $ref - {ref}" - - resolved = resolve_ref(root=root, ref=ref) - if not is_dict(resolved): - raise ValueError( - f"Expected `$ref: {ref}` to resolved to a dictionary but got {resolved}" - ) - - # properties from the json schema take priority over the ones on the `$ref` - json_schema.update({**resolved, **json_schema}) - json_schema.pop("$ref") - # Since the schema expanded from `$ref` might not have `additionalProperties: false` applied - # we call `_ensure_strict_json_schema` again to fix the inlined schema and ensure it's valid - return _ensure_strict_json_schema(json_schema, path=path, root=root) - - return json_schema - - -def resolve_ref(*, root: dict[str, object], ref: str) -> object: - if not ref.startswith("#/"): - raise ValueError(f"Unexpected $ref format {ref!r}; Does not start with #/") - - path = ref[2:].split("/") - resolved = root - for key in path: - value = resolved[key] - assert is_dict(value), ( - f"encountered non-dictionary entry while resolving {ref} - {resolved}" - ) - resolved = value - - return resolved - - -def is_dict(obj: object) -> TypeGuard[dict[str, object]]: - # just pretend that we know there are only `str` keys - # as that check is not worth the performance cost - return isinstance(obj, dict) - - -def is_list(obj: object) -> TypeGuard[list[object]]: - return isinstance(obj, list) - - -def has_more_than_n_keys(obj: dict[str, object], n: int) -> bool: - i = 0 - for _ in obj.keys(): - i += 1 - if i > n: - return True - return False diff --git a/tests/src/agents/tool.py b/tests/src/agents/tool.py deleted file mode 100644 index 75872680..00000000 --- a/tests/src/agents/tool.py +++ /dev/null @@ -1,286 +0,0 @@ -from __future__ import annotations - -import inspect -import json -from collections.abc import Awaitable -from dataclasses import dataclass -from typing import Any, Callable, Literal, Union, overload - -from openai.types.responses.file_search_tool_param import Filters, RankingOptions -from openai.types.responses.web_search_tool_param import UserLocation -from pydantic import ValidationError -from typing_extensions import Concatenate, ParamSpec - -from . import _debug, _utils -from ._utils import MaybeAwaitable -from .computer import AsyncComputer, Computer -from .exceptions import ModelBehaviorError -from .function_schema import DocstringStyle, function_schema -from .logger import logger -from .run_context import RunContextWrapper -from .tracing import SpanError - -ToolParams = ParamSpec("ToolParams") - -ToolFunctionWithoutContext = Callable[ToolParams, Any] -ToolFunctionWithContext = Callable[Concatenate[RunContextWrapper[Any], ToolParams], Any] - -ToolFunction = Union[ToolFunctionWithoutContext[ToolParams], ToolFunctionWithContext[ToolParams]] - - -@dataclass -class FunctionTool: - """A tool that wraps a function. In most cases, you should use the `function_tool` helpers to - create a FunctionTool, as they let you easily wrap a Python function. - """ - - name: str - """The name of the tool, as shown to the LLM. Generally the name of the function.""" - - description: str - """A description of the tool, as shown to the LLM.""" - - params_json_schema: dict[str, Any] - """The JSON schema for the tool's parameters.""" - - on_invoke_tool: Callable[[RunContextWrapper[Any], str], Awaitable[str]] - """A function that invokes the tool with the given context and parameters. The params passed - are: - 1. The tool run context. - 2. The arguments from the LLM, as a JSON string. - - You must return a string representation of the tool output. In case of errors, you can either - raise an Exception (which will cause the run to fail) or return a string error message (which - will be sent back to the LLM). - """ - - strict_json_schema: bool = True - """Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True, - as it increases the likelihood of correct JSON input.""" - - -@dataclass -class FileSearchTool: - """A hosted tool that lets the LLM search through a vector store. Currently only supported with - OpenAI models, using the Responses API. - """ - - vector_store_ids: list[str] - """The IDs of the vector stores to search.""" - - max_num_results: int | None = None - """The maximum number of results to return.""" - - include_search_results: bool = False - """Whether to include the search results in the output produced by the LLM.""" - - ranking_options: RankingOptions | None = None - """Ranking options for search.""" - - filters: Filters | None = None - """A filter to apply based on file attributes.""" - - @property - def name(self): - return "file_search" - - -@dataclass -class WebSearchTool: - """A hosted tool that lets the LLM search the web. Currently only supported with OpenAI models, - using the Responses API. - """ - - user_location: UserLocation | None = None - """Optional location for the search. Lets you customize results to be relevant to a location.""" - - search_context_size: Literal["low", "medium", "high"] = "medium" - """The amount of context to use for the search.""" - - @property - def name(self): - return "web_search_preview" - - -@dataclass -class ComputerTool: - """A hosted tool that lets the LLM control a computer.""" - - computer: Computer | AsyncComputer - """The computer implementation, which describes the environment and dimensions of the computer, - as well as implements the computer actions like click, screenshot, etc. - """ - - @property - def name(self): - return "computer_use_preview" - - -Tool = Union[FunctionTool, FileSearchTool, WebSearchTool, ComputerTool] -"""A tool that can be used in an agent.""" - - -def default_tool_error_function(ctx: RunContextWrapper[Any], error: Exception) -> str: - """The default tool error function, which just returns a generic error message.""" - return f"An error occurred while running the tool. Please try again. Error: {str(error)}" - - -ToolErrorFunction = Callable[[RunContextWrapper[Any], Exception], MaybeAwaitable[str]] - - -@overload -def function_tool( - func: ToolFunction[...], - *, - name_override: str | None = None, - description_override: str | None = None, - docstring_style: DocstringStyle | None = None, - use_docstring_info: bool = True, - failure_error_function: ToolErrorFunction | None = None, -) -> FunctionTool: - """Overload for usage as @function_tool (no parentheses).""" - ... - - -@overload -def function_tool( - *, - name_override: str | None = None, - description_override: str | None = None, - docstring_style: DocstringStyle | None = None, - use_docstring_info: bool = True, - failure_error_function: ToolErrorFunction | None = None, -) -> Callable[[ToolFunction[...]], FunctionTool]: - """Overload for usage as @function_tool(...).""" - ... - - -def function_tool( - func: ToolFunction[...] | None = None, - *, - name_override: str | None = None, - description_override: str | None = None, - docstring_style: DocstringStyle | None = None, - use_docstring_info: bool = True, - failure_error_function: ToolErrorFunction | None = default_tool_error_function, -) -> FunctionTool | Callable[[ToolFunction[...]], FunctionTool]: - """ - Decorator to create a FunctionTool from a function. By default, we will: - 1. Parse the function signature to create a JSON schema for the tool's parameters. - 2. Use the function's docstring to populate the tool's description. - 3. Use the function's docstring to populate argument descriptions. - The docstring style is detected automatically, but you can override it. - - If the function takes a `RunContextWrapper` as the first argument, it *must* match the - context type of the agent that uses the tool. - - Args: - func: The function to wrap. - name_override: If provided, use this name for the tool instead of the function's name. - description_override: If provided, use this description for the tool instead of the - function's docstring. - docstring_style: If provided, use this style for the tool's docstring. If not provided, - we will attempt to auto-detect the style. - use_docstring_info: If True, use the function's docstring to populate the tool's - description and argument descriptions. - failure_error_function: If provided, use this function to generate an error message when - the tool call fails. The error message is sent to the LLM. If you pass None, then no - error message will be sent and instead an Exception will be raised. - """ - - def _create_function_tool(the_func: ToolFunction[...]) -> FunctionTool: - schema = function_schema( - func=the_func, - name_override=name_override, - description_override=description_override, - docstring_style=docstring_style, - use_docstring_info=use_docstring_info, - ) - - async def _on_invoke_tool_impl(ctx: RunContextWrapper[Any], input: str) -> str: - try: - json_data: dict[str, Any] = json.loads(input) if input else {} - except Exception as e: - if _debug.DONT_LOG_TOOL_DATA: - logger.debug(f"Invalid JSON input for tool {schema.name}") - else: - logger.debug(f"Invalid JSON input for tool {schema.name}: {input}") - raise ModelBehaviorError( - f"Invalid JSON input for tool {schema.name}: {input}" - ) from e - - if _debug.DONT_LOG_TOOL_DATA: - logger.debug(f"Invoking tool {schema.name}") - else: - logger.debug(f"Invoking tool {schema.name} with input {input}") - - try: - parsed = ( - schema.params_pydantic_model(**json_data) - if json_data - else schema.params_pydantic_model() - ) - except ValidationError as e: - raise ModelBehaviorError(f"Invalid JSON input for tool {schema.name}: {e}") from e - - args, kwargs_dict = schema.to_call_args(parsed) - - if not _debug.DONT_LOG_TOOL_DATA: - logger.debug(f"Tool call args: {args}, kwargs: {kwargs_dict}") - - if inspect.iscoroutinefunction(the_func): - if schema.takes_context: - result = await the_func(ctx, *args, **kwargs_dict) - else: - result = await the_func(*args, **kwargs_dict) - else: - if schema.takes_context: - result = the_func(ctx, *args, **kwargs_dict) - else: - result = the_func(*args, **kwargs_dict) - - if _debug.DONT_LOG_TOOL_DATA: - logger.debug(f"Tool {schema.name} completed.") - else: - logger.debug(f"Tool {schema.name} returned {result}") - - return str(result) - - async def _on_invoke_tool(ctx: RunContextWrapper[Any], input: str) -> str: - try: - return await _on_invoke_tool_impl(ctx, input) - except Exception as e: - if failure_error_function is None: - raise - - result = failure_error_function(ctx, e) - if inspect.isawaitable(result): - return await result - - _utils.attach_error_to_current_span( - SpanError( - message="Error running tool (non-fatal)", - data={ - "tool_name": schema.name, - "error": str(e), - }, - ) - ) - return result - - return FunctionTool( - name=schema.name, - description=schema.description or "", - params_json_schema=schema.params_json_schema, - on_invoke_tool=_on_invoke_tool, - ) - - # If func is actually a callable, we were used as @function_tool with no parentheses - if callable(func): - return _create_function_tool(func) - - # Otherwise, we were used as @function_tool(...), so return a decorator - def decorator(real_func: ToolFunction[...]) -> FunctionTool: - return _create_function_tool(real_func) - - return decorator diff --git a/tests/src/agents/tracing/__init__.py b/tests/src/agents/tracing/__init__.py deleted file mode 100644 index 8e802018..00000000 --- a/tests/src/agents/tracing/__init__.py +++ /dev/null @@ -1,97 +0,0 @@ -import atexit - -from .create import ( - agent_span, - custom_span, - function_span, - generation_span, - get_current_span, - get_current_trace, - guardrail_span, - handoff_span, - response_span, - trace, -) -from .processor_interface import TracingProcessor -from .processors import default_exporter, default_processor -from .setup import GLOBAL_TRACE_PROVIDER -from .span_data import ( - AgentSpanData, - CustomSpanData, - FunctionSpanData, - GenerationSpanData, - GuardrailSpanData, - HandoffSpanData, - ResponseSpanData, - SpanData, -) -from .spans import Span, SpanError -from .traces import Trace -from .util import gen_span_id, gen_trace_id - -__all__ = [ - "add_trace_processor", - "agent_span", - "custom_span", - "function_span", - "generation_span", - "get_current_span", - "get_current_trace", - "guardrail_span", - "handoff_span", - "response_span", - "set_trace_processors", - "set_tracing_disabled", - "trace", - "Trace", - "SpanError", - "Span", - "SpanData", - "AgentSpanData", - "CustomSpanData", - "FunctionSpanData", - "GenerationSpanData", - "GuardrailSpanData", - "HandoffSpanData", - "ResponseSpanData", - "TracingProcessor", - "gen_trace_id", - "gen_span_id", -] - - -def add_trace_processor(span_processor: TracingProcessor) -> None: - """ - Adds a new trace processor. This processor will receive all traces/spans. - """ - GLOBAL_TRACE_PROVIDER.register_processor(span_processor) - - -def set_trace_processors(processors: list[TracingProcessor]) -> None: - """ - Set the list of trace processors. This will replace the current list of processors. - """ - GLOBAL_TRACE_PROVIDER.set_processors(processors) - - -def set_tracing_disabled(disabled: bool) -> None: - """ - Set whether tracing is globally disabled. - """ - GLOBAL_TRACE_PROVIDER.set_disabled(disabled) - - -def set_tracing_export_api_key(api_key: str) -> None: - """ - Set the OpenAI API key for the backend exporter. - """ - default_exporter().set_api_key(api_key) - - -# Add the default processor, which exports traces and spans to the backend in batches. You can -# change the default behavior by either: -# 1. calling add_trace_processor(), which adds additional processors, or -# 2. calling set_trace_processors(), which replaces the default processor. -add_trace_processor(default_processor()) - -atexit.register(GLOBAL_TRACE_PROVIDER.shutdown) diff --git a/tests/src/agents/tracing/create.py b/tests/src/agents/tracing/create.py deleted file mode 100644 index 8d7fc493..00000000 --- a/tests/src/agents/tracing/create.py +++ /dev/null @@ -1,306 +0,0 @@ -from __future__ import annotations - -from collections.abc import Mapping, Sequence -from typing import TYPE_CHECKING, Any - -from .logger import logger -from .setup import GLOBAL_TRACE_PROVIDER -from .span_data import ( - AgentSpanData, - CustomSpanData, - FunctionSpanData, - GenerationSpanData, - GuardrailSpanData, - HandoffSpanData, - ResponseSpanData, -) -from .spans import Span -from .traces import Trace - -if TYPE_CHECKING: - from openai.types.responses import Response - - -def trace( - workflow_name: str, - trace_id: str | None = None, - group_id: str | None = None, - metadata: dict[str, Any] | None = None, - disabled: bool = False, -) -> Trace: - """ - Create a new trace. The trace will not be started automatically; you should either use - it as a context manager (`with trace(...):`) or call `trace.start()` + `trace.finish()` - manually. - - In addition to the workflow name and optional grouping identifier, you can provide - an arbitrary metadata dictionary to attach additional user-defined information to - the trace. - - Args: - workflow_name: The name of the logical app or workflow. For example, you might provide - "code_bot" for a coding agent, or "customer_support_agent" for a customer support agent. - trace_id: The ID of the trace. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_trace_id()` to generate a trace ID, to guarantee that IDs are - correctly formatted. - group_id: Optional grouping identifier to link multiple traces from the same conversation - or process. For instance, you might use a chat thread ID. - metadata: Optional dictionary of additional metadata to attach to the trace. - disabled: If True, we will return a Trace but the Trace will not be recorded. This will - not be checked if there's an existing trace and `even_if_trace_running` is True. - - Returns: - The newly created trace object. - """ - current_trace = GLOBAL_TRACE_PROVIDER.get_current_trace() - if current_trace: - logger.warning( - "Trace already exists. Creating a new trace, but this is probably a mistake." - ) - - return GLOBAL_TRACE_PROVIDER.create_trace( - name=workflow_name, - trace_id=trace_id, - group_id=group_id, - metadata=metadata, - disabled=disabled, - ) - - -def get_current_trace() -> Trace | None: - """Returns the currently active trace, if present.""" - return GLOBAL_TRACE_PROVIDER.get_current_trace() - - -def get_current_span() -> Span[Any] | None: - """Returns the currently active span, if present.""" - return GLOBAL_TRACE_PROVIDER.get_current_span() - - -def agent_span( - name: str, - handoffs: list[str] | None = None, - tools: list[str] | None = None, - output_type: str | None = None, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, -) -> Span[AgentSpanData]: - """Create a new agent span. The span will not be started automatically, you should either do - `with agent_span() ...` or call `span.start()` + `span.finish()` manually. - - Args: - name: The name of the agent. - handoffs: Optional list of agent names to which this agent could hand off control. - tools: Optional list of tool names available to this agent. - output_type: Optional name of the output type produced by the agent. - span_id: The ID of the span. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are - correctly formatted. - parent: The parent span or trace. If not provided, we will automatically use the current - trace/span as the parent. - disabled: If True, we will return a Span but the Span will not be recorded. - - Returns: - The newly created agent span. - """ - return GLOBAL_TRACE_PROVIDER.create_span( - span_data=AgentSpanData(name=name, handoffs=handoffs, tools=tools, output_type=output_type), - span_id=span_id, - parent=parent, - disabled=disabled, - ) - - -def function_span( - name: str, - input: str | None = None, - output: str | None = None, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, -) -> Span[FunctionSpanData]: - """Create a new function span. The span will not be started automatically, you should either do - `with function_span() ...` or call `span.start()` + `span.finish()` manually. - - Args: - name: The name of the function. - input: The input to the function. - output: The output of the function. - span_id: The ID of the span. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are - correctly formatted. - parent: The parent span or trace. If not provided, we will automatically use the current - trace/span as the parent. - disabled: If True, we will return a Span but the Span will not be recorded. - - Returns: - The newly created function span. - """ - return GLOBAL_TRACE_PROVIDER.create_span( - span_data=FunctionSpanData(name=name, input=input, output=output), - span_id=span_id, - parent=parent, - disabled=disabled, - ) - - -def generation_span( - input: Sequence[Mapping[str, Any]] | None = None, - output: Sequence[Mapping[str, Any]] | None = None, - model: str | None = None, - model_config: Mapping[str, Any] | None = None, - usage: dict[str, Any] | None = None, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, -) -> Span[GenerationSpanData]: - """Create a new generation span. The span will not be started automatically, you should either - do `with generation_span() ...` or call `span.start()` + `span.finish()` manually. - - This span captures the details of a model generation, including the - input message sequence, any generated outputs, the model name and - configuration, and usage data. If you only need to capture a model - response identifier, use `response_span()` instead. - - Args: - input: The sequence of input messages sent to the model. - output: The sequence of output messages received from the model. - model: The model identifier used for the generation. - model_config: The model configuration (hyperparameters) used. - usage: A dictionary of usage information (input tokens, output tokens, etc.). - span_id: The ID of the span. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are - correctly formatted. - parent: The parent span or trace. If not provided, we will automatically use the current - trace/span as the parent. - disabled: If True, we will return a Span but the Span will not be recorded. - - Returns: - The newly created generation span. - """ - return GLOBAL_TRACE_PROVIDER.create_span( - span_data=GenerationSpanData( - input=input, output=output, model=model, model_config=model_config, usage=usage - ), - span_id=span_id, - parent=parent, - disabled=disabled, - ) - - -def response_span( - response: Response | None = None, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, -) -> Span[ResponseSpanData]: - """Create a new response span. The span will not be started automatically, you should either do - `with response_span() ...` or call `span.start()` + `span.finish()` manually. - - Args: - response: The OpenAI Response object. - span_id: The ID of the span. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are - correctly formatted. - parent: The parent span or trace. If not provided, we will automatically use the current - trace/span as the parent. - disabled: If True, we will return a Span but the Span will not be recorded. - """ - return GLOBAL_TRACE_PROVIDER.create_span( - span_data=ResponseSpanData(response=response), - span_id=span_id, - parent=parent, - disabled=disabled, - ) - - -def handoff_span( - from_agent: str | None = None, - to_agent: str | None = None, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, -) -> Span[HandoffSpanData]: - """Create a new handoff span. The span will not be started automatically, you should either do - `with handoff_span() ...` or call `span.start()` + `span.finish()` manually. - - Args: - from_agent: The name of the agent that is handing off. - to_agent: The name of the agent that is receiving the handoff. - span_id: The ID of the span. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are - correctly formatted. - parent: The parent span or trace. If not provided, we will automatically use the current - trace/span as the parent. - disabled: If True, we will return a Span but the Span will not be recorded. - - Returns: - The newly created handoff span. - """ - return GLOBAL_TRACE_PROVIDER.create_span( - span_data=HandoffSpanData(from_agent=from_agent, to_agent=to_agent), - span_id=span_id, - parent=parent, - disabled=disabled, - ) - - -def custom_span( - name: str, - data: dict[str, Any] | None = None, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, -) -> Span[CustomSpanData]: - """Create a new custom span, to which you can add your own metadata. The span will not be - started automatically, you should either do `with custom_span() ...` or call - `span.start()` + `span.finish()` manually. - - Args: - name: The name of the custom span. - data: Arbitrary structured data to associate with the span. - span_id: The ID of the span. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are - correctly formatted. - parent: The parent span or trace. If not provided, we will automatically use the current - trace/span as the parent. - disabled: If True, we will return a Span but the Span will not be recorded. - - Returns: - The newly created custom span. - """ - return GLOBAL_TRACE_PROVIDER.create_span( - span_data=CustomSpanData(name=name, data=data or {}), - span_id=span_id, - parent=parent, - disabled=disabled, - ) - - -def guardrail_span( - name: str, - triggered: bool = False, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, -) -> Span[GuardrailSpanData]: - """Create a new guardrail span. The span will not be started automatically, you should either - do `with guardrail_span() ...` or call `span.start()` + `span.finish()` manually. - - Args: - name: The name of the guardrail. - triggered: Whether the guardrail was triggered. - span_id: The ID of the span. Optional. If not provided, we will generate an ID. We - recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are - correctly formatted. - parent: The parent span or trace. If not provided, we will automatically use the current - trace/span as the parent. - disabled: If True, we will return a Span but the Span will not be recorded. - """ - return GLOBAL_TRACE_PROVIDER.create_span( - span_data=GuardrailSpanData(name=name, triggered=triggered), - span_id=span_id, - parent=parent, - disabled=disabled, - ) diff --git a/tests/src/agents/tracing/logger.py b/tests/src/agents/tracing/logger.py deleted file mode 100644 index 661d09b5..00000000 --- a/tests/src/agents/tracing/logger.py +++ /dev/null @@ -1,3 +0,0 @@ -import logging - -logger = logging.getLogger("openai.agents.tracing") diff --git a/tests/src/agents/tracing/processor_interface.py b/tests/src/agents/tracing/processor_interface.py deleted file mode 100644 index 4dcd897c..00000000 --- a/tests/src/agents/tracing/processor_interface.py +++ /dev/null @@ -1,69 +0,0 @@ -import abc -from typing import TYPE_CHECKING, Any - -if TYPE_CHECKING: - from .spans import Span - from .traces import Trace - - -class TracingProcessor(abc.ABC): - """Interface for processing spans.""" - - @abc.abstractmethod - def on_trace_start(self, trace: "Trace") -> None: - """Called when a trace is started. - - Args: - trace: The trace that started. - """ - pass - - @abc.abstractmethod - def on_trace_end(self, trace: "Trace") -> None: - """Called when a trace is finished. - - Args: - trace: The trace that started. - """ - pass - - @abc.abstractmethod - def on_span_start(self, span: "Span[Any]") -> None: - """Called when a span is started. - - Args: - span: The span that started. - """ - pass - - @abc.abstractmethod - def on_span_end(self, span: "Span[Any]") -> None: - """Called when a span is finished. Should not block or raise exceptions. - - Args: - span: The span that finished. - """ - pass - - @abc.abstractmethod - def shutdown(self) -> None: - """Called when the application stops.""" - pass - - @abc.abstractmethod - def force_flush(self) -> None: - """Forces an immediate flush of all queued spans/traces.""" - pass - - -class TracingExporter(abc.ABC): - """Exports traces and spans. For example, could log them or send them to a backend.""" - - @abc.abstractmethod - def export(self, items: list["Trace | Span[Any]"]) -> None: - """Exports a list of traces and spans. - - Args: - items: The items to export. - """ - pass diff --git a/tests/src/agents/tracing/processors.py b/tests/src/agents/tracing/processors.py deleted file mode 100644 index 282bc23c..00000000 --- a/tests/src/agents/tracing/processors.py +++ /dev/null @@ -1,261 +0,0 @@ -from __future__ import annotations - -import os -import queue -import random -import threading -import time -from typing import Any - -import httpx - -from .logger import logger -from .processor_interface import TracingExporter, TracingProcessor -from .spans import Span -from .traces import Trace - - -class ConsoleSpanExporter(TracingExporter): - """Prints the traces and spans to the console.""" - - def export(self, items: list[Trace | Span[Any]]) -> None: - for item in items: - if isinstance(item, Trace): - print(f"[Exporter] Export trace_id={item.trace_id}, name={item.name}, ") - else: - print(f"[Exporter] Export span: {item.export()}") - - -class BackendSpanExporter(TracingExporter): - def __init__( - self, - api_key: str | None = None, - organization: str | None = None, - project: str | None = None, - endpoint: str = "https://api.openai.com/v1/traces/ingest", - max_retries: int = 3, - base_delay: float = 1.0, - max_delay: float = 30.0, - ): - """ - Args: - api_key: The API key for the "Authorization" header. Defaults to - `os.environ["OPENAI_TRACE_API_KEY"]` if not provided. - organization: The OpenAI organization to use. Defaults to - `os.environ["OPENAI_ORG_ID"]` if not provided. - project: The OpenAI project to use. Defaults to - `os.environ["OPENAI_PROJECT_ID"]` if not provided. - endpoint: The HTTP endpoint to which traces/spans are posted. - max_retries: Maximum number of retries upon failures. - base_delay: Base delay (in seconds) for the first backoff. - max_delay: Maximum delay (in seconds) for backoff growth. - """ - self.api_key = api_key or os.environ.get("OPENAI_API_KEY") - self.organization = organization or os.environ.get("OPENAI_ORG_ID") - self.project = project or os.environ.get("OPENAI_PROJECT_ID") - self.endpoint = endpoint - self.max_retries = max_retries - self.base_delay = base_delay - self.max_delay = max_delay - - # Keep a client open for connection pooling across multiple export calls - self._client = httpx.Client(timeout=httpx.Timeout(timeout=60, connect=5.0)) - - def set_api_key(self, api_key: str): - """Set the OpenAI API key for the exporter. - - Args: - api_key: The OpenAI API key to use. This is the same key used by the OpenAI Python - client. - """ - self.api_key = api_key - - def export(self, items: list[Trace | Span[Any]]) -> None: - if not items: - return - - if not self.api_key: - logger.warning("OPENAI_API_KEY is not set, skipping trace export") - return - - traces: list[dict[str, Any]] = [] - spans: list[dict[str, Any]] = [] - - data = [item.export() for item in items if item.export()] - payload = {"data": data} - - headers = { - "Authorization": f"Bearer {self.api_key}", - "Content-Type": "application/json", - "OpenAI-Beta": "traces=v1", - } - - # Exponential backoff loop - attempt = 0 - delay = self.base_delay - while True: - attempt += 1 - try: - response = self._client.post(url=self.endpoint, headers=headers, json=payload) - - # If the response is successful, break out of the loop - if response.status_code < 300: - logger.debug(f"Exported {len(traces)} traces, {len(spans)} spans") - return - - # If the response is a client error (4xx), we wont retry - if 400 <= response.status_code < 500: - logger.error(f"Tracing client error {response.status_code}: {response.text}") - return - - # For 5xx or other unexpected codes, treat it as transient and retry - logger.warning(f"Server error {response.status_code}, retrying.") - except httpx.RequestError as exc: - # Network or other I/O error, we'll retry - logger.warning(f"Request failed: {exc}") - - # If we reach here, we need to retry or give up - if attempt >= self.max_retries: - logger.error("Max retries reached, giving up on this batch.") - return - - # Exponential backoff + jitter - sleep_time = delay + random.uniform(0, 0.1 * delay) # 10% jitter - time.sleep(sleep_time) - delay = min(delay * 2, self.max_delay) - - def close(self): - """Close the underlying HTTP client.""" - self._client.close() - - -class BatchTraceProcessor(TracingProcessor): - """Some implementation notes: - 1. Using Queue, which is thread-safe. - 2. Using a background thread to export spans, to minimize any performance issues. - 3. Spans are stored in memory until they are exported. - """ - - def __init__( - self, - exporter: TracingExporter, - max_queue_size: int = 8192, - max_batch_size: int = 128, - schedule_delay: float = 5.0, - export_trigger_ratio: float = 0.7, - ): - """ - Args: - exporter: The exporter to use. - max_queue_size: The maximum number of spans to store in the queue. After this, we will - start dropping spans. - max_batch_size: The maximum number of spans to export in a single batch. - schedule_delay: The delay between checks for new spans to export. - export_trigger_ratio: The ratio of the queue size at which we will trigger an export. - """ - self._exporter = exporter - self._queue: queue.Queue[Trace | Span[Any]] = queue.Queue(maxsize=max_queue_size) - self._max_queue_size = max_queue_size - self._max_batch_size = max_batch_size - self._schedule_delay = schedule_delay - self._shutdown_event = threading.Event() - - # The queue size threshold at which we export immediately. - self._export_trigger_size = int(max_queue_size * export_trigger_ratio) - - # Track when we next *must* perform a scheduled export - self._next_export_time = time.time() + self._schedule_delay - - self._shutdown_event = threading.Event() - self._worker_thread = threading.Thread(target=self._run, daemon=True) - self._worker_thread.start() - - def on_trace_start(self, trace: Trace) -> None: - try: - self._queue.put_nowait(trace) - except queue.Full: - logger.warning("Queue is full, dropping trace.") - - def on_trace_end(self, trace: Trace) -> None: - # We send traces via on_trace_start, so we don't need to do anything here. - pass - - def on_span_start(self, span: Span[Any]) -> None: - # We send spans via on_span_end, so we don't need to do anything here. - pass - - def on_span_end(self, span: Span[Any]) -> None: - try: - self._queue.put_nowait(span) - except queue.Full: - logger.warning("Queue is full, dropping span.") - - def shutdown(self, timeout: float | None = None): - """ - Called when the application stops. We signal our thread to stop, then join it. - """ - self._shutdown_event.set() - self._worker_thread.join(timeout=timeout) - - def force_flush(self): - """ - Forces an immediate flush of all queued spans. - """ - self._export_batches(force=True) - - def _run(self): - while not self._shutdown_event.is_set(): - current_time = time.time() - queue_size = self._queue.qsize() - - # If it's time for a scheduled flush or queue is above the trigger threshold - if current_time >= self._next_export_time or queue_size >= self._export_trigger_size: - self._export_batches(force=False) - # Reset the next scheduled flush time - self._next_export_time = time.time() + self._schedule_delay - else: - # Sleep a short interval so we don't busy-wait. - time.sleep(0.2) - - # Final drain after shutdown - self._export_batches(force=True) - - def _export_batches(self, force: bool = False): - """Drains the queue and exports in batches. If force=True, export everything. - Otherwise, export up to `max_batch_size` repeatedly until the queue is empty or below a - certain threshold. - """ - while True: - items_to_export: list[Span[Any] | Trace] = [] - - # Gather a batch of spans up to max_batch_size - while not self._queue.empty() and ( - force or len(items_to_export) < self._max_batch_size - ): - try: - items_to_export.append(self._queue.get_nowait()) - except queue.Empty: - # Another thread might have emptied the queue between checks - break - - # If we collected nothing, we're done - if not items_to_export: - break - - # Export the batch - self._exporter.export(items_to_export) - - -# Create a shared global instance: -_global_exporter = BackendSpanExporter() -_global_processor = BatchTraceProcessor(_global_exporter) - - -def default_exporter() -> BackendSpanExporter: - """The default exporter, which exports traces and spans to the backend in batches.""" - return _global_exporter - - -def default_processor() -> BatchTraceProcessor: - """The default processor, which exports traces and spans to the backend in batches.""" - return _global_processor diff --git a/tests/src/agents/tracing/scope.py b/tests/src/agents/tracing/scope.py deleted file mode 100644 index 9ccd9f87..00000000 --- a/tests/src/agents/tracing/scope.py +++ /dev/null @@ -1,45 +0,0 @@ -# Holds the current active span -import contextvars -from typing import TYPE_CHECKING, Any - -from .logger import logger - -if TYPE_CHECKING: - from .spans import Span - from .traces import Trace - -_current_span: contextvars.ContextVar["Span[Any] | None"] = contextvars.ContextVar( - "current_span", default=None -) - -_current_trace: contextvars.ContextVar["Trace | None"] = contextvars.ContextVar( - "current_trace", default=None -) - - -class Scope: - @classmethod - def get_current_span(cls) -> "Span[Any] | None": - return _current_span.get() - - @classmethod - def set_current_span(cls, span: "Span[Any] | None") -> "contextvars.Token[Span[Any] | None]": - return _current_span.set(span) - - @classmethod - def reset_current_span(cls, token: "contextvars.Token[Span[Any] | None]") -> None: - _current_span.reset(token) - - @classmethod - def get_current_trace(cls) -> "Trace | None": - return _current_trace.get() - - @classmethod - def set_current_trace(cls, trace: "Trace | None") -> "contextvars.Token[Trace | None]": - logger.debug(f"Setting current trace: {trace.trace_id if trace else None}") - return _current_trace.set(trace) - - @classmethod - def reset_current_trace(cls, token: "contextvars.Token[Trace | None]") -> None: - logger.debug("Resetting current trace") - _current_trace.reset(token) diff --git a/tests/src/agents/tracing/setup.py b/tests/src/agents/tracing/setup.py deleted file mode 100644 index bc340c9f..00000000 --- a/tests/src/agents/tracing/setup.py +++ /dev/null @@ -1,211 +0,0 @@ -from __future__ import annotations - -import os -import threading -from typing import Any - -from . import util -from .logger import logger -from .processor_interface import TracingProcessor -from .scope import Scope -from .spans import NoOpSpan, Span, SpanImpl, TSpanData -from .traces import NoOpTrace, Trace, TraceImpl - - -class SynchronousMultiTracingProcessor(TracingProcessor): - """ - Forwards all calls to a list of TracingProcessors, in order of registration. - """ - - def __init__(self): - # Using a tuple to avoid race conditions when iterating over processors - self._processors: tuple[TracingProcessor, ...] = () - self._lock = threading.Lock() - - def add_tracing_processor(self, tracing_processor: TracingProcessor): - """ - Add a processor to the list of processors. Each processor will receive all traces/spans. - """ - with self._lock: - self._processors += (tracing_processor,) - - def set_processors(self, processors: list[TracingProcessor]): - """ - Set the list of processors. This will replace the current list of processors. - """ - with self._lock: - self._processors = tuple(processors) - - def on_trace_start(self, trace: Trace) -> None: - """ - Called when a trace is started. - """ - for processor in self._processors: - processor.on_trace_start(trace) - - def on_trace_end(self, trace: Trace) -> None: - """ - Called when a trace is finished. - """ - for processor in self._processors: - processor.on_trace_end(trace) - - def on_span_start(self, span: Span[Any]) -> None: - """ - Called when a span is started. - """ - for processor in self._processors: - processor.on_span_start(span) - - def on_span_end(self, span: Span[Any]) -> None: - """ - Called when a span is finished. - """ - for processor in self._processors: - processor.on_span_end(span) - - def shutdown(self) -> None: - """ - Called when the application stops. - """ - for processor in self._processors: - logger.debug(f"Shutting down trace processor {processor}") - processor.shutdown() - - def force_flush(self): - """ - Force the processors to flush their buffers. - """ - for processor in self._processors: - processor.force_flush() - - -class TraceProvider: - def __init__(self): - self._multi_processor = SynchronousMultiTracingProcessor() - self._disabled = os.environ.get("OPENAI_AGENTS_DISABLE_TRACING", "false").lower() in ( - "true", - "1", - ) - - def register_processor(self, processor: TracingProcessor): - """ - Add a processor to the list of processors. Each processor will receive all traces/spans. - """ - self._multi_processor.add_tracing_processor(processor) - - def set_processors(self, processors: list[TracingProcessor]): - """ - Set the list of processors. This will replace the current list of processors. - """ - self._multi_processor.set_processors(processors) - - def get_current_trace(self) -> Trace | None: - """ - Returns the currently active trace, if any. - """ - return Scope.get_current_trace() - - def get_current_span(self) -> Span[Any] | None: - """ - Returns the currently active span, if any. - """ - return Scope.get_current_span() - - def set_disabled(self, disabled: bool) -> None: - """ - Set whether tracing is disabled. - """ - self._disabled = disabled - - def create_trace( - self, - name: str, - trace_id: str | None = None, - group_id: str | None = None, - metadata: dict[str, Any] | None = None, - disabled: bool = False, - ) -> Trace: - """ - Create a new trace. - """ - if self._disabled or disabled: - logger.debug(f"Tracing is disabled. Not creating trace {name}") - return NoOpTrace() - - trace_id = trace_id or util.gen_trace_id() - - logger.debug(f"Creating trace {name} with id {trace_id}") - - return TraceImpl( - name=name, - trace_id=trace_id, - group_id=group_id, - metadata=metadata, - processor=self._multi_processor, - ) - - def create_span( - self, - span_data: TSpanData, - span_id: str | None = None, - parent: Trace | Span[Any] | None = None, - disabled: bool = False, - ) -> Span[TSpanData]: - """ - Create a new span. - """ - if self._disabled or disabled: - logger.debug(f"Tracing is disabled. Not creating span {span_data}") - return NoOpSpan(span_data) - - if not parent: - current_span = Scope.get_current_span() - current_trace = Scope.get_current_trace() - if current_trace is None: - logger.error( - "No active trace. Make sure to start a trace with `trace()` first" - "Returning NoOpSpan." - ) - return NoOpSpan(span_data) - elif isinstance(current_trace, NoOpTrace) or isinstance(current_span, NoOpSpan): - logger.debug( - f"Parent {current_span} or {current_trace} is no-op, returning NoOpSpan" - ) - return NoOpSpan(span_data) - - parent_id = current_span.span_id if current_span else None - trace_id = current_trace.trace_id - - elif isinstance(parent, Trace): - if isinstance(parent, NoOpTrace): - logger.debug(f"Parent {parent} is no-op, returning NoOpSpan") - return NoOpSpan(span_data) - trace_id = parent.trace_id - parent_id = None - elif isinstance(parent, Span): - if isinstance(parent, NoOpSpan): - logger.debug(f"Parent {parent} is no-op, returning NoOpSpan") - return NoOpSpan(span_data) - parent_id = parent.span_id - trace_id = parent.trace_id - - logger.debug(f"Creating span {span_data} with id {span_id}") - - return SpanImpl( - trace_id=trace_id, - span_id=span_id, - parent_id=parent_id, - processor=self._multi_processor, - span_data=span_data, - ) - - def shutdown(self) -> None: - try: - logger.debug("Shutting down trace provider") - self._multi_processor.shutdown() - except Exception as e: - logger.error(f"Error shutting down trace provider: {e}") - - -GLOBAL_TRACE_PROVIDER = TraceProvider() diff --git a/tests/src/agents/tracing/span_data.py b/tests/src/agents/tracing/span_data.py deleted file mode 100644 index 5e5d38cb..00000000 --- a/tests/src/agents/tracing/span_data.py +++ /dev/null @@ -1,188 +0,0 @@ -from __future__ import annotations - -import abc -from collections.abc import Mapping, Sequence -from typing import TYPE_CHECKING, Any - -if TYPE_CHECKING: - from openai.types.responses import Response, ResponseInputItemParam - - -class SpanData(abc.ABC): - @abc.abstractmethod - def export(self) -> dict[str, Any]: - pass - - @property - @abc.abstractmethod - def type(self) -> str: - pass - - -class AgentSpanData(SpanData): - __slots__ = ("name", "handoffs", "tools", "output_type") - - def __init__( - self, - name: str, - handoffs: list[str] | None = None, - tools: list[str] | None = None, - output_type: str | None = None, - ): - self.name = name - self.handoffs: list[str] | None = handoffs - self.tools: list[str] | None = tools - self.output_type: str | None = output_type - - @property - def type(self) -> str: - return "agent" - - def export(self) -> dict[str, Any]: - return { - "type": self.type, - "name": self.name, - "handoffs": self.handoffs, - "tools": self.tools, - "output_type": self.output_type, - } - - -class FunctionSpanData(SpanData): - __slots__ = ("name", "input", "output") - - def __init__(self, name: str, input: str | None, output: str | None): - self.name = name - self.input = input - self.output = output - - @property - def type(self) -> str: - return "function" - - def export(self) -> dict[str, Any]: - return { - "type": self.type, - "name": self.name, - "input": self.input, - "output": self.output, - } - - -class GenerationSpanData(SpanData): - __slots__ = ( - "input", - "output", - "model", - "model_config", - "usage", - ) - - def __init__( - self, - input: Sequence[Mapping[str, Any]] | None = None, - output: Sequence[Mapping[str, Any]] | None = None, - model: str | None = None, - model_config: Mapping[str, Any] | None = None, - usage: dict[str, Any] | None = None, - ): - self.input = input - self.output = output - self.model = model - self.model_config = model_config - self.usage = usage - - @property - def type(self) -> str: - return "generation" - - def export(self) -> dict[str, Any]: - return { - "type": self.type, - "input": self.input, - "output": self.output, - "model": self.model, - "model_config": self.model_config, - "usage": self.usage, - } - - -class ResponseSpanData(SpanData): - __slots__ = ("response", "input") - - def __init__( - self, - response: Response | None = None, - input: str | list[ResponseInputItemParam] | None = None, - ) -> None: - self.response = response - # This is not used by the OpenAI trace processors, but is useful for other tracing - # processor implementations - self.input = input - - @property - def type(self) -> str: - return "response" - - def export(self) -> dict[str, Any]: - return { - "type": self.type, - "response_id": self.response.id if self.response else None, - } - - -class HandoffSpanData(SpanData): - __slots__ = ("from_agent", "to_agent") - - def __init__(self, from_agent: str | None, to_agent: str | None): - self.from_agent = from_agent - self.to_agent = to_agent - - @property - def type(self) -> str: - return "handoff" - - def export(self) -> dict[str, Any]: - return { - "type": self.type, - "from_agent": self.from_agent, - "to_agent": self.to_agent, - } - - -class CustomSpanData(SpanData): - __slots__ = ("name", "data") - - def __init__(self, name: str, data: dict[str, Any]): - self.name = name - self.data = data - - @property - def type(self) -> str: - return "custom" - - def export(self) -> dict[str, Any]: - return { - "type": self.type, - "name": self.name, - "data": self.data, - } - - -class GuardrailSpanData(SpanData): - __slots__ = ("name", "triggered") - - def __init__(self, name: str, triggered: bool = False): - self.name = name - self.triggered = triggered - - @property - def type(self) -> str: - return "guardrail" - - def export(self) -> dict[str, Any]: - return { - "type": self.type, - "name": self.name, - "triggered": self.triggered, - } diff --git a/tests/src/agents/tracing/spans.py b/tests/src/agents/tracing/spans.py deleted file mode 100644 index d682a9a0..00000000 --- a/tests/src/agents/tracing/spans.py +++ /dev/null @@ -1,264 +0,0 @@ -from __future__ import annotations - -import abc -import contextvars -from typing import Any, Generic, TypeVar - -from typing_extensions import TypedDict - -from . import util -from .logger import logger -from .processor_interface import TracingProcessor -from .scope import Scope -from .span_data import SpanData - -TSpanData = TypeVar("TSpanData", bound=SpanData) - - -class SpanError(TypedDict): - message: str - data: dict[str, Any] | None - - -class Span(abc.ABC, Generic[TSpanData]): - @property - @abc.abstractmethod - def trace_id(self) -> str: - pass - - @property - @abc.abstractmethod - def span_id(self) -> str: - pass - - @property - @abc.abstractmethod - def span_data(self) -> TSpanData: - pass - - @abc.abstractmethod - def start(self, mark_as_current: bool = False): - """ - Start the span. - - Args: - mark_as_current: If true, the span will be marked as the current span. - """ - pass - - @abc.abstractmethod - def finish(self, reset_current: bool = False) -> None: - """ - Finish the span. - - Args: - reset_current: If true, the span will be reset as the current span. - """ - pass - - @abc.abstractmethod - def __enter__(self) -> Span[TSpanData]: - pass - - @abc.abstractmethod - def __exit__(self, exc_type, exc_val, exc_tb): - pass - - @property - @abc.abstractmethod - def parent_id(self) -> str | None: - pass - - @abc.abstractmethod - def set_error(self, error: SpanError) -> None: - pass - - @property - @abc.abstractmethod - def error(self) -> SpanError | None: - pass - - @abc.abstractmethod - def export(self) -> dict[str, Any] | None: - pass - - @property - @abc.abstractmethod - def started_at(self) -> str | None: - pass - - @property - @abc.abstractmethod - def ended_at(self) -> str | None: - pass - - -class NoOpSpan(Span[TSpanData]): - __slots__ = ("_span_data", "_prev_span_token") - - def __init__(self, span_data: TSpanData): - self._span_data = span_data - self._prev_span_token: contextvars.Token[Span[TSpanData] | None] | None = None - - @property - def trace_id(self) -> str: - return "no-op" - - @property - def span_id(self) -> str: - return "no-op" - - @property - def span_data(self) -> TSpanData: - return self._span_data - - @property - def parent_id(self) -> str | None: - return None - - def start(self, mark_as_current: bool = False): - if mark_as_current: - self._prev_span_token = Scope.set_current_span(self) - - def finish(self, reset_current: bool = False) -> None: - if reset_current and self._prev_span_token is not None: - Scope.reset_current_span(self._prev_span_token) - self._prev_span_token = None - - def __enter__(self) -> Span[TSpanData]: - self.start(mark_as_current=True) - return self - - def __exit__(self, exc_type, exc_val, exc_tb): - reset_current = True - if exc_type is GeneratorExit: - logger.debug("GeneratorExit, skipping span reset") - reset_current = False - - self.finish(reset_current=reset_current) - - def set_error(self, error: SpanError) -> None: - pass - - @property - def error(self) -> SpanError | None: - return None - - def export(self) -> dict[str, Any] | None: - return None - - @property - def started_at(self) -> str | None: - return None - - @property - def ended_at(self) -> str | None: - return None - - -class SpanImpl(Span[TSpanData]): - __slots__ = ( - "_trace_id", - "_span_id", - "_parent_id", - "_started_at", - "_ended_at", - "_error", - "_prev_span_token", - "_processor", - "_span_data", - ) - - def __init__( - self, - trace_id: str, - span_id: str | None, - parent_id: str | None, - processor: TracingProcessor, - span_data: TSpanData, - ): - self._trace_id = trace_id - self._span_id = span_id or util.gen_span_id() - self._parent_id = parent_id - self._started_at: str | None = None - self._ended_at: str | None = None - self._processor = processor - self._error: SpanError | None = None - self._prev_span_token: contextvars.Token[Span[TSpanData] | None] | None = None - self._span_data = span_data - - @property - def trace_id(self) -> str: - return self._trace_id - - @property - def span_id(self) -> str: - return self._span_id - - @property - def span_data(self) -> TSpanData: - return self._span_data - - @property - def parent_id(self) -> str | None: - return self._parent_id - - def start(self, mark_as_current: bool = False): - if self.started_at is not None: - logger.warning("Span already started") - return - - self._started_at = util.time_iso() - self._processor.on_span_start(self) - if mark_as_current: - self._prev_span_token = Scope.set_current_span(self) - - def finish(self, reset_current: bool = False) -> None: - if self.ended_at is not None: - logger.warning("Span already finished") - return - - self._ended_at = util.time_iso() - self._processor.on_span_end(self) - if reset_current and self._prev_span_token is not None: - Scope.reset_current_span(self._prev_span_token) - self._prev_span_token = None - - def __enter__(self) -> Span[TSpanData]: - self.start(mark_as_current=True) - return self - - def __exit__(self, exc_type, exc_val, exc_tb): - reset_current = True - if exc_type is GeneratorExit: - logger.debug("GeneratorExit, skipping span reset") - reset_current = False - - self.finish(reset_current=reset_current) - - def set_error(self, error: SpanError) -> None: - self._error = error - - @property - def error(self) -> SpanError | None: - return self._error - - @property - def started_at(self) -> str | None: - return self._started_at - - @property - def ended_at(self) -> str | None: - return self._ended_at - - def export(self) -> dict[str, Any] | None: - return { - "object": "trace.span", - "id": self.span_id, - "trace_id": self.trace_id, - "parent_id": self._parent_id, - "started_at": self._started_at, - "ended_at": self._ended_at, - "span_data": self.span_data.export(), - "error": self._error, - } diff --git a/tests/src/agents/tracing/traces.py b/tests/src/agents/tracing/traces.py deleted file mode 100644 index bf3b43df..00000000 --- a/tests/src/agents/tracing/traces.py +++ /dev/null @@ -1,195 +0,0 @@ -from __future__ import annotations - -import abc -import contextvars -from typing import Any - -from . import util -from .logger import logger -from .processor_interface import TracingProcessor -from .scope import Scope - - -class Trace: - """ - A trace is the root level object that tracing creates. It represents a logical "workflow". - """ - - @abc.abstractmethod - def __enter__(self) -> Trace: - pass - - @abc.abstractmethod - def __exit__(self, exc_type, exc_val, exc_tb): - pass - - @abc.abstractmethod - def start(self, mark_as_current: bool = False): - """ - Start the trace. - - Args: - mark_as_current: If true, the trace will be marked as the current trace. - """ - pass - - @abc.abstractmethod - def finish(self, reset_current: bool = False): - """ - Finish the trace. - - Args: - reset_current: If true, the trace will be reset as the current trace. - """ - pass - - @property - @abc.abstractmethod - def trace_id(self) -> str: - """ - The trace ID. - """ - pass - - @property - @abc.abstractmethod - def name(self) -> str: - """ - The name of the workflow being traced. - """ - pass - - @abc.abstractmethod - def export(self) -> dict[str, Any] | None: - """ - Export the trace as a dictionary. - """ - pass - - -class NoOpTrace(Trace): - """ - A no-op trace that will not be recorded. - """ - - def __init__(self): - self._started = False - self._prev_context_token: contextvars.Token[Trace | None] | None = None - - def __enter__(self) -> Trace: - if self._started: - if not self._prev_context_token: - logger.error("Trace already started but no context token set") - return self - - self._started = True - self.start(mark_as_current=True) - - return self - - def __exit__(self, exc_type, exc_val, exc_tb): - self.finish(reset_current=True) - - def start(self, mark_as_current: bool = False): - if mark_as_current: - self._prev_context_token = Scope.set_current_trace(self) - - def finish(self, reset_current: bool = False): - if reset_current and self._prev_context_token is not None: - Scope.reset_current_trace(self._prev_context_token) - self._prev_context_token = None - - @property - def trace_id(self) -> str: - return "no-op" - - @property - def name(self) -> str: - return "no-op" - - def export(self) -> dict[str, Any] | None: - return None - - -NO_OP_TRACE = NoOpTrace() - - -class TraceImpl(Trace): - """ - A trace that will be recorded by the tracing library. - """ - - __slots__ = ( - "_name", - "_trace_id", - "group_id", - "metadata", - "_prev_context_token", - "_processor", - "_started", - ) - - def __init__( - self, - name: str, - trace_id: str | None, - group_id: str | None, - metadata: dict[str, Any] | None, - processor: TracingProcessor, - ): - self._name = name - self._trace_id = trace_id or util.gen_trace_id() - self.group_id = group_id - self.metadata = metadata - self._prev_context_token: contextvars.Token[Trace | None] | None = None - self._processor = processor - self._started = False - - @property - def trace_id(self) -> str: - return self._trace_id - - @property - def name(self) -> str: - return self._name - - def start(self, mark_as_current: bool = False): - if self._started: - return - - self._started = True - self._processor.on_trace_start(self) - - if mark_as_current: - self._prev_context_token = Scope.set_current_trace(self) - - def finish(self, reset_current: bool = False): - if not self._started: - return - - self._processor.on_trace_end(self) - - if reset_current and self._prev_context_token is not None: - Scope.reset_current_trace(self._prev_context_token) - self._prev_context_token = None - - def __enter__(self) -> Trace: - if self._started: - if not self._prev_context_token: - logger.error("Trace already started but no context token set") - return self - - self.start(mark_as_current=True) - return self - - def __exit__(self, exc_type, exc_val, exc_tb): - self.finish(reset_current=exc_type is not GeneratorExit) - - def export(self) -> dict[str, Any] | None: - return { - "object": "trace", - "id": self.trace_id, - "workflow_name": self.name, - "group_id": self.group_id, - "metadata": self.metadata, - } diff --git a/tests/src/agents/tracing/util.py b/tests/src/agents/tracing/util.py deleted file mode 100644 index 3e5cad90..00000000 --- a/tests/src/agents/tracing/util.py +++ /dev/null @@ -1,17 +0,0 @@ -import uuid -from datetime import datetime, timezone - - -def time_iso() -> str: - """Returns the current time in ISO 8601 format.""" - return datetime.now(timezone.utc).isoformat() - - -def gen_trace_id() -> str: - """Generates a new trace ID.""" - return f"trace_{uuid.uuid4().hex}" - - -def gen_span_id() -> str: - """Generates a new span ID.""" - return f"span_{uuid.uuid4().hex[:24]}" diff --git a/tests/src/agents/usage.py b/tests/src/agents/usage.py deleted file mode 100644 index 23d989b4..00000000 --- a/tests/src/agents/usage.py +++ /dev/null @@ -1,22 +0,0 @@ -from dataclasses import dataclass - - -@dataclass -class Usage: - requests: int = 0 - """Total requests made to the LLM API.""" - - input_tokens: int = 0 - """Total input tokens sent, across all requests.""" - - output_tokens: int = 0 - """Total output tokens received, across all requests.""" - - total_tokens: int = 0 - """Total tokens sent and received, across all requests.""" - - def add(self, other: "Usage") -> None: - self.requests += other.requests if other.requests else 0 - self.input_tokens += other.input_tokens if other.input_tokens else 0 - self.output_tokens += other.output_tokens if other.output_tokens else 0 - self.total_tokens += other.total_tokens if other.total_tokens else 0 diff --git a/tests/src/agents/version.py b/tests/src/agents/version.py deleted file mode 100644 index a0b7e9be..00000000 --- a/tests/src/agents/version.py +++ /dev/null @@ -1,7 +0,0 @@ -import importlib.metadata - -try: - __version__ = importlib.metadata.version("agents") -except importlib.metadata.PackageNotFoundError: - # Fallback if running from source without being installed - __version__ = "0.0.0" diff --git a/tests/src/openai_agents.egg-info/PKG-INFO b/tests/src/openai_agents.egg-info/PKG-INFO deleted file mode 100644 index ebf2d7c2..00000000 --- a/tests/src/openai_agents.egg-info/PKG-INFO +++ /dev/null @@ -1,217 +0,0 @@ -Metadata-Version: 2.2 -Name: openai-agents -Version: 0.0.1 -Summary: OpenAI Agents SDK -Author-email: OpenAI -Project-URL: Homepage, https://github.com/openai/openai-agents-python -Project-URL: Repository, https://github.com/openai/openai-agents-python -Classifier: Typing :: Typed -Classifier: Intended Audience :: Developers -Classifier: Programming Language :: Python :: 3 -Classifier: Programming Language :: Python :: 3.9 -Classifier: Programming Language :: Python :: 3.10 -Classifier: Programming Language :: Python :: 3.11 -Classifier: Programming Language :: Python :: 3.12 -Classifier: Intended Audience :: Developers -Classifier: Intended Audience :: Information Technology -Classifier: Operating System :: OS Independent -Classifier: Operating System :: POSIX -Classifier: Operating System :: MacOS -Classifier: Operating System :: POSIX :: Linux -Classifier: Operating System :: Microsoft :: Windows -Classifier: Topic :: Software Development :: Libraries :: Python Modules -Requires-Python: >=3.9 -Description-Content-Type: text/markdown -Requires-Dist: openai@ {root:parent:uri}/openai-1.30.1-py3-none-any.whl -Requires-Dist: pydantic<3,>=2.10 -Requires-Dist: griffe<2,>=1.5.6 -Requires-Dist: typing-extensions<5,>=4.12.2 -Requires-Dist: requests<3,>=2.0 -Requires-Dist: types-requests<3,>=2.0 - -# OpenAI Agents SDK - -The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. - -### Core concepts: -1. [**Agents,**](docs/agents.md) which are LLMs configured with instructions, tools, guardrails, and handoffs -2. [**Handoffs,**](docs/handoffs.md) which allow agents to transfer control to other agents for specific tasks -3. [**Guardrails,**](docs/guardrails.md) which makes it easy to watch an agent execution and validate inputs/outputs -4. [**Tracing,**](docs/tracing.md) which automatically captures the entire agentic run, allowing you to view, debug and optimize your workflows - -Explore examples of the SDK in action in the [examples](examples) directory. - -## Using the SDK - -1. Set up python env - -``` -python -m venv env -source env/bin/activate -``` - -2. Install Agents SDK - -``` -pip install git+ssh://git@github.com/openai/agentsdk_prototype.git#subdirectory=agents -``` - -## Development (only needed if you need to edit the SDK/examples) - -0. Ensure you have [`uv`](https://docs.astral.sh/uv/) installed. - -```bash -uv --version -``` - -1. Install dependencies/setup virtual environment - -```bash -uv sync -``` - -2. Install the dependencies - -```bash -uv sync --all-extras --all-packages -``` - -3. Activate the virtual environment - -```bash -source .venv/bin/activate -``` - -## Tests - -Make sure the virtual environment is activated first. - -```bash -pytest -``` - -## Hello world example - -```py -from agents.agent import Agent -from agents.run import Runner -import asyncio - -agent = Agent( - name="Hello world", - instructions="You are a helpful agent." -) - -async def main(): - out = await Runner.run(agent, input="Hola, ¿cómo estás?") - print(out) - - -if __name__ == "__main__": - asyncio.run(main()) - -# The capital of the United States is Washington, D.C. -``` - -## Handoffs example - -```py -from agents.agent import Agent -from agents.run import Runner -import asyncio - -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], -) - - -async def main(): - out = await Runner.run(triage_agent, input="Hola, ¿cómo estás?") - print(out) - - -if __name__ == "__main__": - asyncio.run(main()) - -# ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás? -``` - -## Functions example - -```python -from agents.agent import Agent -from agents.run import Runner -import asyncio -from agents.tool import function_tool - - -@function_tool -def get_weather(city: str) -> str: - print(f"Getting weather for {city}") - return f"The weather in {city} is sunny." - - -agent = Agent( - name="Hello world", - instructions="You are a helpful agent.", - tools=[get_weather], -) - - -async def main(): - out = await Runner.run(agent, input="What's the weather in Tokyo?") - print(out.final_output) - - -if __name__ == "__main__": - asyncio.run(main()) -``` - -For more complex systems, we recommend including detailed instructions about handoffs. We have a recommendation in `handoff.RECOMMENDED_PROMPT_PREFIX` that can be used to add these instructions to an agent. - -```py -agent = Agent( - ..., - instructions=f"{handoff.RECOMMENDED_PROMPT_PREFIX}\n\n{instructions}" -) -``` - -## The agent loop - -When you call `Runner.run()`, we run a loop until we get a final output. - -1. We call the LLM, using the model and settings on the agent, and the message history. -2. The LLM returns a response, which may include tool calls. -3. If the response has a final output (see below for the more on this), we return it and end the loop. -4. If the response has a handoff, we set the agent to the new agent and go back to step 1. -5. We process the tool calls (if any) and append the tool responses messsages. Then we go to step 1. - -There is a `max_turns` parameter that you can use to limit the number of times the loop executes. - -### Final output - -There are two ways to get a **final output**: - -1. If you set an `output_type` on the agent, the LLM is given a special tool called `final_output`. If it uses this tool, the output of the tool is the final output. -2. If there's no `output_type`, then we assume the final output is a string. As soon as the LLM produces a message without any tool calls, that is considered the final output. - -As a result, the mental model for the agent loop is: - -1. If the current agent has an `output_type`, the loop runs until the agent uses that tool to return the final output. -2. If the current agent does not have an `output_type`, the loop runs until the current agent produces a message without any tool calls. - -## Common agent patterns - -There are a number of useful patterns in agentic apps. There are a number of examples in [`examples/agent_patterns`](examples/agent_patterns), and we recommend reading them. diff --git a/tests/src/openai_agents.egg-info/SOURCES.txt b/tests/src/openai_agents.egg-info/SOURCES.txt deleted file mode 100644 index 695ad1fc..00000000 --- a/tests/src/openai_agents.egg-info/SOURCES.txt +++ /dev/null @@ -1,81 +0,0 @@ -README.md -pyproject.toml -src/agents/__init__.py -src/agents/_config.py -src/agents/_debug.py -src/agents/_run_impl.py -src/agents/_utils.py -src/agents/agent.py -src/agents/agent_output.py -src/agents/call_agent_tool.py -src/agents/computer.py -src/agents/exceptions.py -src/agents/function_schema.py -src/agents/guardrail.py -src/agents/handoffs.py -src/agents/items.py -src/agents/lifecycle.py -src/agents/logger.py -src/agents/model_settings.py -src/agents/result.py -src/agents/run.py -src/agents/run_context.py -src/agents/strict_schema.py -src/agents/tool.py -src/agents/usage.py -src/agents/version.py -src/agents/extensions/__init__.py -src/agents/extensions/handoff_filters.py -src/agents/extensions/handoff_prompt.py -src/agents/models/__init__.py -src/agents/models/_openai_shared.py -src/agents/models/fake_id.py -src/agents/models/interface.py -src/agents/models/map.py -src/agents/models/openai_chatcompletions.py -src/agents/models/openai_responses.py -src/agents/tracing/__init__.py -src/agents/tracing/create.py -src/agents/tracing/logger.py -src/agents/tracing/processor_interface.py -src/agents/tracing/processors.py -src/agents/tracing/scope.py -src/agents/tracing/setup.py -src/agents/tracing/span_data.py -src/agents/tracing/spans.py -src/agents/tracing/traces.py -src/agents/tracing/util.py -src/openai_agents.egg-info/PKG-INFO -src/openai_agents.egg-info/SOURCES.txt -src/openai_agents.egg-info/dependency_links.txt -src/openai_agents.egg-info/requires.txt -src/openai_agents.egg-info/top_level.txt -tests/test_agent_config.py -tests/test_agent_hooks.py -tests/test_agent_runner.py -tests/test_agent_runner_streamed.py -tests/test_agent_tracing.py -tests/test_config.py -tests/test_doc_parsing.py -tests/test_function_schema.py -tests/test_function_tool.py -tests/test_function_tool_decorator.py -tests/test_global_hooks.py -tests/test_guardrails.py -tests/test_handoff_tool.py -tests/test_items_helpers.py -tests/test_max_turns.py -tests/test_model_mapper.py -tests/test_openai_chatcompletions_converter.py -tests/test_openai_responses_converter.py -tests/test_output_tool.py -tests/test_responses.py -tests/test_run_config.py -tests/test_run_step_execution.py -tests/test_run_step_processing.py -tests/test_tool_converter.py -tests/test_trace_processor.py -tests/test_tracing.py -tests/test_tracing_errors.py -tests/test_tracing_errors_streamed.py -tests/testing_processor.py \ No newline at end of file diff --git a/tests/src/openai_agents.egg-info/dependency_links.txt b/tests/src/openai_agents.egg-info/dependency_links.txt deleted file mode 100644 index 8b137891..00000000 --- a/tests/src/openai_agents.egg-info/dependency_links.txt +++ /dev/null @@ -1 +0,0 @@ - diff --git a/tests/src/openai_agents.egg-info/requires.txt b/tests/src/openai_agents.egg-info/requires.txt deleted file mode 100644 index 3dbad2b8..00000000 --- a/tests/src/openai_agents.egg-info/requires.txt +++ /dev/null @@ -1,6 +0,0 @@ -openai@ {root:parent:uri}/openai-1.30.1-py3-none-any.whl -pydantic<3,>=2.10 -griffe<2,>=1.5.6 -typing-extensions<5,>=4.12.2 -requests<3,>=2.0 -types-requests<3,>=2.0 diff --git a/tests/src/openai_agents.egg-info/top_level.txt b/tests/src/openai_agents.egg-info/top_level.txt deleted file mode 100644 index 4a33ff62..00000000 --- a/tests/src/openai_agents.egg-info/top_level.txt +++ /dev/null @@ -1 +0,0 @@ -agents From 865c0a3ba04abf6e531755b4025de2c3e508e745 Mon Sep 17 00:00:00 2001 From: Rohan Mehta Date: Tue, 11 Mar 2025 13:13:44 -0700 Subject: [PATCH 2/3] update gitignore, pycache --- .gitignore | 1 + .../agents/__pycache__/__init__.cpython-313.pyc | Bin 172 -> 0 bytes .../__pycache__/base_agent.cpython-313.pyc | Bin 929 -> 0 bytes .../__pycache__/planner_agent.cpython-313.pyc | Bin 1133 -> 0 bytes .../research_manager_agent.cpython-313.pyc | Bin 3906 -> 0 bytes .../__pycache__/search_agent.cpython-313.pyc | Bin 964 -> 0 bytes .../summarization_agent.cpython-313.pyc | Bin 625 -> 0 bytes .../__pycache__/writer_agent.cpython-313.pyc | Bin 1293 -> 0 bytes 8 files changed, 1 insertion(+) delete mode 100644 examples/research_bot/agents/__pycache__/__init__.cpython-313.pyc delete mode 100644 examples/research_bot/agents/__pycache__/base_agent.cpython-313.pyc delete mode 100644 examples/research_bot/agents/__pycache__/planner_agent.cpython-313.pyc delete mode 100644 examples/research_bot/agents/__pycache__/research_manager_agent.cpython-313.pyc delete mode 100644 examples/research_bot/agents/__pycache__/search_agent.cpython-313.pyc delete mode 100644 examples/research_bot/agents/__pycache__/summarization_agent.cpython-313.pyc delete mode 100644 examples/research_bot/agents/__pycache__/writer_agent.cpython-313.pyc diff --git a/.gitignore b/.gitignore index 9da95ba3..1def8a6a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ # Byte-compiled / optimized / DLL files __pycache__/ +**/__pycache__/ *.py[cod] *$py.class diff --git a/examples/research_bot/agents/__pycache__/__init__.cpython-313.pyc b/examples/research_bot/agents/__pycache__/__init__.cpython-313.pyc deleted file mode 100644 index a094b5a5310588de48141f37146944bc4283a4ae..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 172 zcmey&%ge<81b+h0rGx0lAOZ#$p^VQgK*m&tbOudEzm*I{OhDdekkl=2{m|mnqGJ7` zT>a$ylvMr1^whkP;*{+8f};GA{F2IoRQ=S7#N2|MRG^yF;?%^VKEC5pNEtmiR diff --git a/examples/research_bot/agents/__pycache__/base_agent.cpython-313.pyc b/examples/research_bot/agents/__pycache__/base_agent.cpython-313.pyc deleted file mode 100644 index f33d418871c61aa28bea1c82722cfc0b8c064195..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 929 zcmYjP&2G~`5MKW#ah%eW6p13WTPT8{QVY=w;zug#0i_}w++4s?WSni{HnFYU4OKY7 z4RN6yDwRj*Gw=>b*v z$>6ItHGvDB>Xp2L z0dXX|MX)VT|7Vvx(^I6iZn@S1+SPXzTJGv~`v>??T@~6!G!n%p2@m7Q@7EPkdgwFq zIPQ=>oEjTl5^Y}__@!*0Q(Xu-Vb>X^B%$7@CAvmM7)a6B3`xpsDtCYVB8NG$MFt?gfehU@tH!_ ztnFUN@ILhuHjPOlLLpVwmH!an6(C~aAnAuYBOF6|n!_2yonfD_HLH27(;}2cOH#2hxp#vv?NjO<)th3inXv|~TV}}w(d>ZuH5_o>Wfku#a zc6lus2|J*~=edKOt-8-EpNlo?jl%oPW1>K*zPE(~@DEDKZRm z0vF+nG@Er>n2SykN}QsYj5>bA!+^@~CCn+tX*F`#LWB7TUG`V#5^{#%7}2T> zaV`sSZ`z&*^dguFF!MpAnxZJbi%41ih8Dl0#neVuu8nWrIxWpA=GdyF8th-@=2HXq w)I@geVDqTES^xk5 diff --git a/examples/research_bot/agents/__pycache__/planner_agent.cpython-313.pyc b/examples/research_bot/agents/__pycache__/planner_agent.cpython-313.pyc deleted file mode 100644 index b836aaccefaaea442c2c69164006214838ee5e6f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1133 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 diff --git a/examples/research_bot/agents/__pycache__/search_agent.cpython-313.pyc b/examples/research_bot/agents/__pycache__/search_agent.cpython-313.pyc deleted file mode 100644 index b3281242f38bbe1eca339d39aef19fa8b6c80d19..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 964 zcmY*XL2DC16rN3X)22;IYbgq%JbIBp&6XC?f+$i!nqmuXO0fjOWOtGb?#`?;v#r~k zXV3lz{WC>x?SgplS4dEfiqH*db{W^<0Y8F zG~25Gw%Jyt@Lr6VFh%o_4FX10IPOXrx16H+T1G4mm@!<8G(B?&c`GxZiU9@1bcqG3 zHP?m;(}q|4mT4RS2GxfnAzVFMUS1!hbQSOicJrAkIwXlX+!LarI;EJ>)! zK@JhgY_}{nx(!_nZgNSc4QxEzgp?{eQZyZFO9nC1+VTt7TwgztD#E&LnwkuSTe5_5 z0jcD|5*{jUEM*vC9Or8wBnZYLFcQY}n4zL1jhV&ZkeCRW29!UNGQyTtq!qoJErijUsNi6i9`V6BJv{5BrwG7Uk2Yqru=hO3Vb9XP6;mgtYRp_Z`r4@$f{rvLx| diff --git a/examples/research_bot/agents/__pycache__/summarization_agent.cpython-313.pyc b/examples/research_bot/agents/__pycache__/summarization_agent.cpython-313.pyc deleted file mode 100644 index b809d7c5a494bde94badff40aa5cd0ecc2255b19..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 625 zcmZuvO^XyU5KVe!zlPbOiwVKG?lb#dl3JF z_#^x?f;Z`-p1kckc(-~!ZWbX_sK>#P*UuT_J2zTjbuAiq%rCl7TU#jkkw_0WIkxBQ%1b@H6Up~ zSZZ4>Y6}>G2@zd{xWouyhYw)AE1=>!Qw8t~i28k;z!URMJ3u}Zjj|d%!KI#8j9Mec zP?67T)rlzYlnENn@7!f3!h*0`ZZ#S}MLq=hcs`x}{Pg+WbPAWA@~~+{VHIm);keXL zqH$1p<6;;C&zIxeSQDEu_mP7sD^KeYavjmwFoDM&oR46fvUSd#I9AJZ6ODIhxvjEf zcaR$JOi!JnTMKQ*Z@|Q$?P4-Y+P=e5w?pGXq*`?Z;l-%e4(1rPCR2}{Z%=m4VTak+ z|5dEGB--cctDq^QRHn-3I$iH3HSOVpk`1={ t5e=EW+j{`Mu6k0+zlTEJzTOw7w|*SmxaucIFXi>Y!D;ecoKW}E{sH>R%#8p5 diff --git a/examples/research_bot/agents/__pycache__/writer_agent.cpython-313.pyc b/examples/research_bot/agents/__pycache__/writer_agent.cpython-313.pyc deleted file mode 100644 index be550b1efb6bd192deb292e8968ec6c3d8a0aa0f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1293 zcmY*ZPm9||6dzfV?e*@G4cm2h7n)83r5F->Lr6-X1X6k^3Hd{mQVND)RvO#GN;B%4 zQC#=dQ?I=Q+K8 zj*`wePPz{wXiv8Wz4zWc2;A1!+=!<-6FF|;M^m9JzX}NXL06Q6pqv_^qy`GY2oC8? z0JYqliHy#rozXc+E7cVJQauw!z82_NYOr*ILHxfk`eP+vF{D24T;@4F6|@BXT4w7^ zb|$C>IhBg%jrT3eRYr|21eFSpLH!y9&9oBqbg_8?H%1!El^yo{DQ2dtJfjl{#v(XO zQk4y6uBfhTE-`}#=?`9Ewli*NCQJ(QRG8XgEL5qjJQWCLlIuCulZ}`meKiy67DeU+ za4R-Ubp!|uR;b0y+|Y%t05SO*5kpxaSd9OlW{n&fl8P1_&N4k$9%{jD!-=#TPPtH1 zJ3}fEUnVS`uePR0?=QtJz}+-T%*CF7jMs6}h!HAxJeX?xIdy_fY+e8Vk& ze;o~O7uy4tnX1477w+1+OxAS5?N4-$T(hcVI61~jt<0a~*`VvXj456S#$1oFLT6R( zNaSw2nKkCIKErl&%SDD4MW*1}?AlF5fd3xcym5Er2KDV<8y{4oAa^O9?Up4eUgimpcKMi6Y;BpZLLGX^;ct;K|+U@xMMM#3qRlggI jemlA%`1#N$dk4#{{_^_A%ijKS@A$)3yx00=r%wGZ=IxVm From ce66d908a9b348d9f47aaf46376afe6c9b979216 Mon Sep 17 00:00:00 2001 From: Rohan Mehta Date: Tue, 11 Mar 2025 14:54:10 -0700 Subject: [PATCH 3/3] make format --- src/agents/agent_output.py | 2 +- src/agents/model_settings.py | 1 + tests/test_config.py | 9 ++++++--- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/src/agents/agent_output.py b/src/agents/agent_output.py index 8140d8c6..0c28800f 100644 --- a/src/agents/agent_output.py +++ b/src/agents/agent_output.py @@ -138,7 +138,7 @@ def _type_to_str(t: type[Any]) -> str: # It's a simple type like `str`, `int`, etc. return t.__name__ elif args: - args_str = ', '.join(_type_to_str(arg) for arg in args) + args_str = ", ".join(_type_to_str(arg) for arg in args) return f"{origin.__name__}[{args_str}]" else: return str(t) diff --git a/src/agents/model_settings.py b/src/agents/model_settings.py index 78cf9a83..d8178ae3 100644 --- a/src/agents/model_settings.py +++ b/src/agents/model_settings.py @@ -11,6 +11,7 @@ class ModelSettings: This class holds optional model configuration parameters (e.g. temperature, top_p, penalties, truncation, etc.). """ + temperature: float | None = None top_p: float | None = None frequency_penalty: float | None = None diff --git a/tests/test_config.py b/tests/test_config.py index 8f37200a..dba854db 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -49,13 +49,16 @@ def test_resp_set_default_openai_client(): def test_set_default_openai_api(): - assert isinstance(OpenAIProvider().get_model("gpt-4"), OpenAIResponsesModel), \ + assert isinstance(OpenAIProvider().get_model("gpt-4"), OpenAIResponsesModel), ( "Default should be responses" + ) set_default_openai_api("chat_completions") - assert isinstance(OpenAIProvider().get_model("gpt-4"), OpenAIChatCompletionsModel), \ + assert isinstance(OpenAIProvider().get_model("gpt-4"), OpenAIChatCompletionsModel), ( "Should be chat completions model" + ) set_default_openai_api("responses") - assert isinstance(OpenAIProvider().get_model("gpt-4"), OpenAIResponsesModel), \ + assert isinstance(OpenAIProvider().get_model("gpt-4"), OpenAIResponsesModel), ( "Should be responses model" + )