mirror of https://github.com/aliasrobotics/cai.git
Fix docs
Signed-off-by: Víctor Mayoral Vilches <v.mayoralv@gmail.com>
This commit is contained in:
Víctor Mayoral Vilches
parent
1a22013bda
commit
f18e659ec8
|
|
@ -108,7 +108,7 @@ agent = Agent[UserContext](
|
|||
|
||||
## 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`][cai.agents.lifecycle.AgentHooks] class, and override the methods you're interested in.
|
||||
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`][cai.sdk.agents.lifecycle.AgentHooks] class, and override the methods you're interested in.
|
||||
|
||||
## Guardrails
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ robot_agent = pirate_agent.clone(
|
|||
|
||||
## Forcing tool use
|
||||
|
||||
Supplying a list of tools doesn't always mean the LLM will use a tool. You can force tool use by setting [`ModelSettings.tool_choice`][cai.agents.model_settings.ModelSettings.tool_choice]. Valid values are:
|
||||
Supplying a list of tools doesn't always mean the LLM will use a tool. You can force tool use by setting [`ModelSettings.tool_choice`][cai.sdk.agents.model_settings.ModelSettings.tool_choice]. Valid values are:
|
||||
|
||||
1. `auto`, which allows the LLM to decide whether or not to use a tool.
|
||||
2. `required`, which requires the LLM to use a tool (but it can intelligently decide which tool).
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## 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()`][cai.agents.set_default_openai_key] function to set the key.
|
||||
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()`][cai.sdk.agents.set_default_openai_key] function to set the key.
|
||||
|
||||
```python
|
||||
from cai.agents import set_default_openai_key
|
||||
|
|
@ -10,7 +10,7 @@ from cai.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 change this by using the [`set_default_openai_client()`][cai.agents.set_default_openai_client] function.
|
||||
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 change this by using the [`set_default_openai_client()`][cai.sdk.agents.set_default_openai_client] function.
|
||||
|
||||
```python
|
||||
from openai import AsyncOpenAI
|
||||
|
|
@ -20,7 +20,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...")
|
|||
set_default_openai_client(custom_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()`][cai.agents.set_default_openai_api] function.
|
||||
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()`][cai.sdk.agents.set_default_openai_api] function.
|
||||
|
||||
```python
|
||||
from cai.agents import set_default_openai_api
|
||||
|
|
@ -30,7 +30,7 @@ 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`][cai.agents.set_tracing_export_api_key] function.
|
||||
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`][cai.sdk.agents.set_tracing_export_api_key] function.
|
||||
|
||||
```python
|
||||
from cai.agents import set_tracing_export_api_key
|
||||
|
|
@ -38,7 +38,7 @@ from cai.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()`][cai.agents.set_tracing_disabled] function.
|
||||
You can also disable tracing entirely by using the [`set_tracing_disabled()`][cai.sdk.agents.set_tracing_disabled] function.
|
||||
|
||||
```python
|
||||
from cai.agents import set_tracing_disabled
|
||||
|
|
@ -50,7 +50,7 @@ set_tracing_disabled(True)
|
|||
|
||||
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()`][cai.agents.enable_verbose_stdout_logging] function.
|
||||
To enable verbose logging, use the [`enable_verbose_stdout_logging()`][cai.sdk.agents.enable_verbose_stdout_logging] function.
|
||||
|
||||
```python
|
||||
from cai.agents import enable_verbose_stdout_logging
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Context is an overloaded term. There are two main classes of context you might c
|
|||
|
||||
## Local context
|
||||
|
||||
This is represented via the [`RunContextWrapper`][cai.agents.run_context.RunContextWrapper] class and the [`context`][cai.agents.run_context.RunContextWrapper.context] property within it. The way this works is:
|
||||
This is represented via the [`RunContextWrapper`][cai.sdk.agents.run_context.RunContextWrapper] class and the [`context`][cai.sdk.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**))`.
|
||||
|
|
|
|||
|
|
@ -12,8 +12,8 @@ There are two kinds of 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`][cai.agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`InputGuardrailResult`][cai.agents.guardrail.InputGuardrailResult]
|
||||
3. Finally, we check if [`.tripwire_triggered`][cai.agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`InputGuardrailTripwireTriggered`][cai.agents.exceptions.InputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception.
|
||||
2. Next, the guardrail function runs to produce a [`GuardrailFunctionOutput`][cai.sdk.agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`InputGuardrailResult`][cai.sdk.agents.guardrail.InputGuardrailResult]
|
||||
3. Finally, we check if [`.tripwire_triggered`][cai.sdk.agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`InputGuardrailTripwireTriggered`][cai.sdk.agents.exceptions.InputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception.
|
||||
|
||||
!!! Note
|
||||
|
||||
|
|
@ -24,8 +24,8 @@ Input guardrails run in 3 steps:
|
|||
Output 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`][cai.agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`OutputGuardrailResult`][cai.agents.guardrail.OutputGuardrailResult]
|
||||
3. Finally, we check if [`.tripwire_triggered`][cai.agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`OutputGuardrailTripwireTriggered`][cai.agents.exceptions.OutputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception.
|
||||
2. Next, the guardrail function runs to produce a [`GuardrailFunctionOutput`][cai.sdk.agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`OutputGuardrailResult`][cai.sdk.agents.guardrail.OutputGuardrailResult]
|
||||
3. Finally, we check if [`.tripwire_triggered`][cai.sdk.agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`OutputGuardrailTripwireTriggered`][cai.sdk.agents.exceptions.OutputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception.
|
||||
|
||||
!!! Note
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ If the input or output fails the guardrail, the Guardrail can signal this with a
|
|||
|
||||
## Implementing a guardrail
|
||||
|
||||
You need to provide a function that receives input, and returns a [`GuardrailFunctionOutput`][cai.agents.guardrail.GuardrailFunctionOutput]. In this example, we'll do this by running an Agent under the hood.
|
||||
You need to provide a function that receives input, and returns a [`GuardrailFunctionOutput`][cai.sdk.agents.guardrail.GuardrailFunctionOutput]. In this example, we'll do this by running an Agent under the hood.
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
|
|
|
|||
|
|
@ -6,9 +6,9 @@ Handoffs are represented as tools to the LLM. So if there's a handoff to an agen
|
|||
|
||||
## Creating a handoff
|
||||
|
||||
All agents have a [`handoffs`][cai.agents.agent.Agent.handoffs] param, which can either take an `Agent` directly, or a `Handoff` object that customizes the Handoff.
|
||||
All agents have a [`handoffs`][cai.sdk.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()`][cai.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.
|
||||
You can create a handoff using the [`handoff()`][cai.sdk.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
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refun
|
|||
|
||||
### Customizing handoffs via the `handoff()` function
|
||||
|
||||
The [`handoff()`][cai.agents.handoffs.handoff] function lets you customize things.
|
||||
The [`handoff()`][cai.sdk.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_<agent_name>`. You can override this.
|
||||
|
|
@ -79,9 +79,9 @@ handoff_obj = handoff(
|
|||
|
||||
## 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`][cai.agents.handoffs.Handoff.input_filter]. An input filter is a function that receives the existing input via a [`HandoffInputData`][cai.agents.handoffs.HandoffInputData], and must return a new `HandoffInputData`.
|
||||
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`][cai.sdk.agents.handoffs.Handoff.input_filter]. An input filter is a function that receives the existing input via a [`HandoffInputData`][cai.sdk.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 [`cai.agents.extensions.handoff_filters`][]
|
||||
There are some common patterns (for example removing all tool calls from the history), which are implemented for you in [`cai.sdk.agents.extensions.handoff_filters`][]
|
||||
|
||||
```python
|
||||
from cai.agents import Agent, handoff
|
||||
|
|
@ -99,7 +99,7 @@ handoff_obj = handoff(
|
|||
|
||||
## 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 [`cai.agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][], or you can call [`cai.agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] to automatically add recommended data to your prompts.
|
||||
To make sure that LLMs understand handoffs properly, we recommend including information about handoffs in your agents. We have a suggested prefix in [`cai.sdk.agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][], or you can call [`cai.sdk.agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] to automatically add recommended data to your prompts.
|
||||
|
||||
```python
|
||||
from cai.agents import Agent
|
||||
|
|
|
|||
|
|
@ -2,20 +2,20 @@
|
|||
|
||||
The Agents SDK comes with out-of-the-box support for OpenAI models in two flavors:
|
||||
|
||||
- **Recommended**: the [`OpenAIResponsesModel`][cai.agents.models.openai_responses.OpenAIResponsesModel], which calls OpenAI APIs using the new [Responses API](https://platform.openai.com/docs/api-reference/responses).
|
||||
- The [`OpenAIChatCompletionsModel`][cai.agents.models.openai_chatcompletions.OpenAIChatCompletionsModel], which calls OpenAI APIs using the [Chat Completions API](https://platform.openai.com/docs/api-reference/chat).
|
||||
- **Recommended**: the [`OpenAIResponsesModel`][cai.sdk.agents.models.openai_responses.OpenAIResponsesModel], which calls OpenAI APIs using the new [Responses API](https://platform.openai.com/docs/api-reference/responses).
|
||||
- The [`OpenAIChatCompletionsModel`][cai.sdk.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`][cai.agents.Agent], you can select a specific model by either:
|
||||
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`][cai.sdk.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`][cai.agents.models.interface.ModelProvider] that can map that name to a Model instance.
|
||||
3. Directly providing a [`Model`][cai.agents.models.interface.Model] implementation.
|
||||
2. Passing any model name + a [`ModelProvider`][cai.sdk.agents.models.interface.ModelProvider] that can map that name to a Model instance.
|
||||
3. Directly providing a [`Model`][cai.sdk.agents.models.interface.Model] implementation.
|
||||
|
||||
!!!note
|
||||
|
||||
While our SDK supports both the [`OpenAIResponsesModel`][cai.agents.models.openai_responses.OpenAIResponsesModel] and the [`OpenAIChatCompletionsModel`][cai.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.
|
||||
While our SDK supports both the [`OpenAIResponsesModel`][cai.sdk.agents.models.openai_responses.OpenAIResponsesModel] and the [`OpenAIChatCompletionsModel`][cai.sdk.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 cai.agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
|
||||
|
|
@ -49,15 +49,15 @@ async def main():
|
|||
```
|
||||
|
||||
1. Sets the name of an OpenAI model directly.
|
||||
2. Provides a [`Model`][cai.agents.models.interface.Model] implementation.
|
||||
2. Provides a [`Model`][cai.sdk.agents.models.interface.Model] implementation.
|
||||
|
||||
## Using other LLM providers
|
||||
|
||||
You can use other LLM providers in 3 ways (examples [here](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)):
|
||||
|
||||
1. [`set_default_openai_client`][cai.agents.set_default_openai_client] is useful in cases where you want to globally use an instance of `AsyncOpenAI` as the LLM client. This is for cases where the LLM provider has an OpenAI compatible API endpoint, and you can set the `base_url` and `api_key`. See a configurable example in [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py).
|
||||
2. [`ModelProvider`][cai.agents.models.interface.ModelProvider] is at the `Runner.run` level. This lets you say "use a custom model provider for all agents in this run". See a configurable example in [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py).
|
||||
3. [`Agent.model`][cai.agents.agent.Agent.model] lets you specify the model on a specific Agent instance. This enables you to mix and match different providers for different agents. See a configurable example in [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py).
|
||||
1. [`set_default_openai_client`][cai.sdk.agents.set_default_openai_client] is useful in cases where you want to globally use an instance of `AsyncOpenAI` as the LLM client. This is for cases where the LLM provider has an OpenAI compatible API endpoint, and you can set the `base_url` and `api_key`. See a configurable example in [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py).
|
||||
2. [`ModelProvider`][cai.sdk.agents.models.interface.ModelProvider] is at the `Runner.run` level. This lets you say "use a custom model provider for all agents in this run". See a configurable example in [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py).
|
||||
3. [`Agent.model`][cai.sdk.agents.agent.Agent.model] lets you specify the model on a specific Agent instance. This enables you to mix and match different providers for different agents. See a configurable example in [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py).
|
||||
|
||||
In cases where you do not have an API key from `platform.openai.com`, we recommend disabling tracing via `set_tracing_disabled()`, or setting up a [different tracing processor](tracing.md).
|
||||
|
||||
|
|
@ -71,16 +71,16 @@ In cases where you do not have an API key from `platform.openai.com`, we recomme
|
|||
|
||||
If you get errors related to tracing, this is because traces are uploaded to OpenAI servers, and you don't have an OpenAI API key. You have three options to resolve this:
|
||||
|
||||
1. Disable tracing entirely: [`set_tracing_disabled(True)`][cai.agents.set_tracing_disabled].
|
||||
2. Set an OpenAI key for tracing: [`set_tracing_export_api_key(...)`][cai.agents.set_tracing_export_api_key]. This API key will only be used for uploading traces, and must be from [platform.openai.com](https://platform.openai.com/).
|
||||
1. Disable tracing entirely: [`set_tracing_disabled(True)`][cai.sdk.agents.set_tracing_disabled].
|
||||
2. Set an OpenAI key for tracing: [`set_tracing_export_api_key(...)`][cai.sdk.agents.set_tracing_export_api_key]. This API key will only be used for uploading traces, and must be from [platform.openai.com](https://platform.openai.com/).
|
||||
3. Use a non-OpenAI trace processor. See the [tracing docs](tracing.md#custom-tracing-processors).
|
||||
|
||||
### Responses API support
|
||||
|
||||
The SDK uses the Responses API by default, but most other LLM providers don't yet support it. You may see 404s or similar issues as a result. To resolve, you have two options:
|
||||
|
||||
1. Call [`set_default_openai_api("chat_completions")`][cai.agents.set_default_openai_api]. This works if you are setting `OPENAI_API_KEY` and `OPENAI_BASE_URL` via environment vars.
|
||||
2. Use [`OpenAIChatCompletionsModel`][cai.agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]. There are examples [here](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/).
|
||||
1. Call [`set_default_openai_api("chat_completions")`][cai.sdk.agents.set_default_openai_api]. This works if you are setting `OPENAI_API_KEY` and `OPENAI_BASE_URL` via environment vars.
|
||||
2. Use [`OpenAIChatCompletionsModel`][cai.sdk.agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]. There are examples [here](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/).
|
||||
|
||||
### Structured outputs support
|
||||
|
||||
|
|
|
|||
|
|
@ -2,14 +2,14 @@
|
|||
|
||||
When you call the `Runner.run` methods, you either get a:
|
||||
|
||||
- [`RunResult`][cai.agents.result.RunResult] if you call `run` or `run_sync`
|
||||
- [`RunResultStreaming`][cai.agents.result.RunResultStreaming] if you call `run_streamed`
|
||||
- [`RunResult`][cai.sdk.agents.result.RunResult] if you call `run` or `run_sync`
|
||||
- [`RunResultStreaming`][cai.sdk.agents.result.RunResultStreaming] if you call `run_streamed`
|
||||
|
||||
Both of these inherit from [`RunResultBase`][cai.agents.result.RunResultBase], which is where most useful information is present.
|
||||
Both of these inherit from [`RunResultBase`][cai.sdk.agents.result.RunResultBase], which is where most useful information is present.
|
||||
|
||||
## Final output
|
||||
|
||||
The [`final_output`][cai.agents.result.RunResultBase.final_output] property contains the final output of the last agent that ran. This is either:
|
||||
The [`final_output`][cai.sdk.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.
|
||||
|
|
@ -20,33 +20,33 @@ The [`final_output`][cai.agents.result.RunResultBase.final_output] property cont
|
|||
|
||||
## Inputs for the next turn
|
||||
|
||||
You can use [`result.to_input_list()`][cai.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.
|
||||
You can use [`result.to_input_list()`][cai.sdk.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`][cai.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.
|
||||
The [`last_agent`][cai.sdk.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`][cai.agents.result.RunResultBase.new_items] property contains the new items generated during the run. The items are [`RunItem`][cai.agents.items.RunItem]s. A run item wraps the raw item generated by the LLM.
|
||||
The [`new_items`][cai.sdk.agents.result.RunResultBase.new_items] property contains the new items generated during the run. The items are [`RunItem`][cai.sdk.agents.items.RunItem]s. A run item wraps the raw item generated by the LLM.
|
||||
|
||||
- [`MessageOutputItem`][cai.agents.items.MessageOutputItem] indicates a message from the LLM. The raw item is the message generated.
|
||||
- [`HandoffCallItem`][cai.agents.items.HandoffCallItem] indicates that the LLM called the handoff tool. The raw item is the tool call item from the LLM.
|
||||
- [`HandoffOutputItem`][cai.agents.items.HandoffOutputItem] indicates that a handoff occurred. The raw item is the tool response to the handoff tool call. You can also access the source/target agents from the item.
|
||||
- [`ToolCallItem`][cai.agents.items.ToolCallItem] indicates that the LLM invoked a tool.
|
||||
- [`ToolCallOutputItem`][cai.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`][cai.agents.items.ReasoningItem] indicates a reasoning item from the LLM. The raw item is the reasoning generated.
|
||||
- [`MessageOutputItem`][cai.sdk.agents.items.MessageOutputItem] indicates a message from the LLM. The raw item is the message generated.
|
||||
- [`HandoffCallItem`][cai.sdk.agents.items.HandoffCallItem] indicates that the LLM called the handoff tool. The raw item is the tool call item from the LLM.
|
||||
- [`HandoffOutputItem`][cai.sdk.agents.items.HandoffOutputItem] indicates that a handoff occurred. The raw item is the tool response to the handoff tool call. You can also access the source/target agents from the item.
|
||||
- [`ToolCallItem`][cai.sdk.agents.items.ToolCallItem] indicates that the LLM invoked a tool.
|
||||
- [`ToolCallOutputItem`][cai.sdk.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`][cai.sdk.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`][cai.agents.result.RunResultBase.input_guardrail_results] and [`output_guardrail_results`][cai.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.
|
||||
The [`input_guardrail_results`][cai.sdk.agents.result.RunResultBase.input_guardrail_results] and [`output_guardrail_results`][cai.sdk.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`][cai.agents.result.RunResultBase.raw_responses] property contains the [`ModelResponse`][cai.agents.items.ModelResponse]s generated by the LLM.
|
||||
The [`raw_responses`][cai.sdk.agents.result.RunResultBase.raw_responses] property contains the [`ModelResponse`][cai.sdk.agents.items.ModelResponse]s generated by the LLM.
|
||||
|
||||
### Original input
|
||||
|
||||
The [`input`][cai.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.
|
||||
The [`input`][cai.sdk.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.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# Running agents
|
||||
|
||||
You can run agents via the [`Runner`][cai.agents.run.Runner] class. You have 3 options:
|
||||
You can run agents via the [`Runner`][cai.sdk.agents.run.Runner] class. You have 3 options:
|
||||
|
||||
1. [`Runner.run()`][cai.agents.run.Runner.run], which runs async and returns a [`RunResult`][cai.agents.result.RunResult].
|
||||
2. [`Runner.run_sync()`][cai.agents.run.Runner.run_sync], which is a sync method and just runs `.run()` under the hood.
|
||||
3. [`Runner.run_streamed()`][cai.agents.run.Runner.run_streamed], which runs async and returns a [`RunResultStreaming`][cai.agents.result.RunResultStreaming]. It calls the LLM in streaming mode, and streams those events to you as they are received.
|
||||
1. [`Runner.run()`][cai.sdk.agents.run.Runner.run], which runs async and returns a [`RunResult`][cai.sdk.agents.result.RunResult].
|
||||
2. [`Runner.run_sync()`][cai.sdk.agents.run.Runner.run_sync], which is a sync method and just runs `.run()` under the hood.
|
||||
3. [`Runner.run_streamed()`][cai.sdk.agents.run.Runner.run_streamed], which runs async and returns a [`RunResultStreaming`][cai.sdk.agents.result.RunResultStreaming]. It calls the LLM in streaming mode, and streams those events to you as they are received.
|
||||
|
||||
```python
|
||||
from cai.agents import Agent, Runner
|
||||
|
|
@ -32,7 +32,7 @@ The runner then runs a loop:
|
|||
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`][cai.agents.exceptions.MaxTurnsExceeded] exception.
|
||||
3. If we exceed the `max_turns` passed, we raise a [`MaxTurnsExceeded`][cai.sdk.agents.exceptions.MaxTurnsExceeded] exception.
|
||||
|
||||
!!! note
|
||||
|
||||
|
|
@ -40,21 +40,21 @@ The runner then runs a loop:
|
|||
|
||||
## Streaming
|
||||
|
||||
Streaming allows you to additionally receive streaming events as the LLM runs. Once the stream is done, the [`RunResultStreaming`][cai.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).
|
||||
Streaming allows you to additionally receive streaming events as the LLM runs. Once the stream is done, the [`RunResultStreaming`][cai.sdk.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`][cai.agents.run.RunConfig.model]: Allows setting a global LLM model to use, irrespective of what `model` each Agent has.
|
||||
- [`model_provider`][cai.agents.run.RunConfig.model_provider]: A model provider for looking up model names, which defaults to OpenAI.
|
||||
- [`model_settings`][cai.agents.run.RunConfig.model_settings]: Overrides agent-specific settings. For example, you can set a global `temperature` or `top_p`.
|
||||
- [`input_guardrails`][cai.agents.run.RunConfig.input_guardrails], [`output_guardrails`][cai.agents.run.RunConfig.output_guardrails]: A list of input or output guardrails to include on all runs.
|
||||
- [`handoff_input_filter`][cai.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`][cai.agents.handoffs.Handoff.input_filter] for more details.
|
||||
- [`tracing_disabled`][cai.agents.run.RunConfig.tracing_disabled]: Allows you to disable [tracing](tracing.md) for the entire run.
|
||||
- [`trace_include_sensitive_data`][cai.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`][cai.agents.run.RunConfig.workflow_name], [`trace_id`][cai.agents.run.RunConfig.trace_id], [`group_id`][cai.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`][cai.agents.run.RunConfig.trace_metadata]: Metadata to include on all traces.
|
||||
- [`model`][cai.sdk.agents.run.RunConfig.model]: Allows setting a global LLM model to use, irrespective of what `model` each Agent has.
|
||||
- [`model_provider`][cai.sdk.agents.run.RunConfig.model_provider]: A model provider for looking up model names, which defaults to OpenAI.
|
||||
- [`model_settings`][cai.sdk.agents.run.RunConfig.model_settings]: Overrides agent-specific settings. For example, you can set a global `temperature` or `top_p`.
|
||||
- [`input_guardrails`][cai.sdk.agents.run.RunConfig.input_guardrails], [`output_guardrails`][cai.sdk.agents.run.RunConfig.output_guardrails]: A list of input or output guardrails to include on all runs.
|
||||
- [`handoff_input_filter`][cai.sdk.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`][cai.sdk.agents.handoffs.Handoff.input_filter] for more details.
|
||||
- [`tracing_disabled`][cai.sdk.agents.run.RunConfig.tracing_disabled]: Allows you to disable [tracing](tracing.md) for the entire run.
|
||||
- [`trace_include_sensitive_data`][cai.sdk.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`][cai.sdk.agents.run.RunConfig.workflow_name], [`trace_id`][cai.sdk.agents.run.RunConfig.trace_id], [`group_id`][cai.sdk.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`][cai.sdk.agents.run.RunConfig.trace_metadata]: Metadata to include on all traces.
|
||||
|
||||
## Conversations/chat threads
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ Calling any of the run methods can result in one or more agents running (and hen
|
|||
|
||||
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()`][cai.agents.result.RunResultBase.to_input_list] method to get the inputs for the next turn.
|
||||
You can use the base [`RunResultBase.to_input_list()`][cai.sdk.agents.result.RunResultBase.to_input_list] method to get the inputs for the next turn.
|
||||
|
||||
```python
|
||||
async def main():
|
||||
|
|
@ -86,10 +86,10 @@ async def main():
|
|||
|
||||
## Exceptions
|
||||
|
||||
The SDK raises exceptions in certain cases. The full list is in [`cai.agents.exceptions`][]. As an overview:
|
||||
The SDK raises exceptions in certain cases. The full list is in [`cai.sdk.agents.exceptions`][]. As an overview:
|
||||
|
||||
- [`AgentsException`][cai.agents.exceptions.AgentsException] is the base class for all exceptions raised in the SDK.
|
||||
- [`MaxTurnsExceeded`][cai.agents.exceptions.MaxTurnsExceeded] is raised when the run exceeds the `max_turns` passed to the run methods.
|
||||
- [`ModelBehaviorError`][cai.agents.exceptions.ModelBehaviorError] is raised when the model produces invalid outputs, e.g. malformed JSON or using non-existent tools.
|
||||
- [`UserError`][cai.agents.exceptions.UserError] is raised when you (the person writing code using the SDK) make an error using the SDK.
|
||||
- [`InputGuardrailTripwireTriggered`][cai.agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][cai.agents.exceptions.OutputGuardrailTripwireTriggered] is raised when a [guardrail](guardrails.md) is tripped.
|
||||
- [`AgentsException`][cai.sdk.agents.exceptions.AgentsException] is the base class for all exceptions raised in the SDK.
|
||||
- [`MaxTurnsExceeded`][cai.sdk.agents.exceptions.MaxTurnsExceeded] is raised when the run exceeds the `max_turns` passed to the run methods.
|
||||
- [`ModelBehaviorError`][cai.sdk.agents.exceptions.ModelBehaviorError] is raised when the model produces invalid outputs, e.g. malformed JSON or using non-existent tools.
|
||||
- [`UserError`][cai.sdk.agents.exceptions.UserError] is raised when you (the person writing code using the SDK) make an error using the SDK.
|
||||
- [`InputGuardrailTripwireTriggered`][cai.sdk.agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][cai.sdk.agents.exceptions.OutputGuardrailTripwireTriggered] is raised when a [guardrail](guardrails.md) is tripped.
|
||||
|
|
|
|||
|
|
@ -2,11 +2,11 @@
|
|||
|
||||
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()`][cai.agents.run.Runner.run_streamed], which will give you a [`RunResultStreaming`][cai.agents.result.RunResultStreaming]. Calling `result.stream_events()` gives you an async stream of [`StreamEvent`][cai.agents.stream_events.StreamEvent] objects, which are described below.
|
||||
To stream, you can call [`Runner.run_streamed()`][cai.sdk.agents.run.Runner.run_streamed], which will give you a [`RunResultStreaming`][cai.sdk.agents.result.RunResultStreaming]. Calling `result.stream_events()` gives you an async stream of [`StreamEvent`][cai.sdk.agents.stream_events.StreamEvent] objects, which are described below.
|
||||
|
||||
## Raw response events
|
||||
|
||||
[`RawResponsesStreamEvent`][cai.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.
|
||||
[`RawResponsesStreamEvent`][cai.sdk.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.
|
||||
|
||||
|
|
@ -33,7 +33,7 @@ if __name__ == "__main__":
|
|||
|
||||
## Run item events and agent events
|
||||
|
||||
[`RunItemStreamEvent`][cai.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`][cai.agents.stream_events.AgentUpdatedStreamEvent] gives you updates when the current agent changes (e.g. as the result of a handoff).
|
||||
[`RunItemStreamEvent`][cai.sdk.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`][cai.sdk.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.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,11 +8,11 @@ Tools let agents take actions: things like fetching data, running code, calling
|
|||
|
||||
## Hosted tools
|
||||
|
||||
OpenAI offers a few built-in tools when using the [`OpenAIResponsesModel`][cai.agents.models.openai_responses.OpenAIResponsesModel]:
|
||||
OpenAI offers a few built-in tools when using the [`OpenAIResponsesModel`][cai.sdk.agents.models.openai_responses.OpenAIResponsesModel]:
|
||||
|
||||
- The [`WebSearchTool`][cai.agents.tool.WebSearchTool] lets an agent search the web.
|
||||
- The [`FileSearchTool`][cai.agents.tool.FileSearchTool] allows retrieving information from your OpenAI Vector Stores.
|
||||
- The [`ComputerTool`][cai.agents.tool.ComputerTool] allows automating computer use tasks.
|
||||
- The [`WebSearchTool`][cai.sdk.agents.tool.WebSearchTool] lets an agent search the web.
|
||||
- The [`FileSearchTool`][cai.sdk.agents.tool.FileSearchTool] allows retrieving information from your OpenAI Vector Stores.
|
||||
- The [`ComputerTool`][cai.sdk.agents.tool.ComputerTool] allows automating computer use tasks.
|
||||
|
||||
```python
|
||||
from cai.agents import Agent, FileSearchTool, Runner, WebSearchTool
|
||||
|
|
@ -171,7 +171,7 @@ for tool in agent.tools:
|
|||
|
||||
### Custom function tools
|
||||
|
||||
Sometimes, you don't want to use a Python function as a tool. You can directly create a [`FunctionTool`][cai.agents.tool.FunctionTool] if you prefer. You'll need to provide:
|
||||
Sometimes, you don't want to use a Python function as a tool. You can directly create a [`FunctionTool`][cai.sdk.agents.tool.FunctionTool] if you prefer. You'll need to provide:
|
||||
|
||||
- `name`
|
||||
- `description`
|
||||
|
|
@ -216,7 +216,7 @@ As mentioned before, we automatically parse the function signature to extract th
|
|||
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 [`cai.agents.function_schema`][].
|
||||
The code for the schema extraction lives in [`cai.sdk.agents.function_schema`][].
|
||||
|
||||
## Agents as tools
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ The Agents SDK includes built-in tracing, collecting a comprehensive record of e
|
|||
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 [`cai.agents.run.RunConfig.tracing_disabled`][] to `True`
|
||||
2. You can disable tracing for a single run by setting [`cai.sdk.agents.run.RunConfig.tracing_disabled`][] to `True`
|
||||
|
||||
***For organizations operating under a Zero Data Retention (ZDR) policy using OpenAI's APIs, tracing is unavailable.***
|
||||
|
||||
|
|
@ -39,7 +39,7 @@ By default, the SDK traces the following:
|
|||
- Audio outputs (text-to-speech) are wrapped in a `speech_span()`
|
||||
- Related audio spans may be parented under a `speech_group_span()`
|
||||
|
||||
By default, the trace is named "Agent trace". You can set this name if you use `trace`, or you can can configure the name and other properties with the [`RunConfig`][cai.agents.run.RunConfig].
|
||||
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`][cai.sdk.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).
|
||||
|
||||
|
|
@ -64,16 +64,16 @@ async def main():
|
|||
|
||||
## Creating traces
|
||||
|
||||
You can use the [`trace()`][cai.agents.tracing.trace] function to create a trace. Traces need to be started and finished. You have two options to do so:
|
||||
You can use the [`trace()`][cai.sdk.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()`][cai.agents.tracing.Trace.start] and [`trace.finish()`][cai.agents.tracing.Trace.finish].
|
||||
2. You can also manually call [`trace.start()`][cai.sdk.agents.tracing.Trace.start] and [`trace.finish()`][cai.sdk.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()`][cai.agents.tracing.create] methods to create a span. In general, you don't need to manually create spans. A [`custom_span()`][cai.agents.tracing.custom_span] function is available for tracking custom span information.
|
||||
You can use the various [`*_span()`][cai.sdk.agents.tracing.create] methods to create a span. In general, you don't need to manually create spans. A [`custom_span()`][cai.sdk.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).
|
||||
|
||||
|
|
@ -81,21 +81,21 @@ Spans are automatically part of the current trace, and are nested under the near
|
|||
|
||||
Certain spans may capture potentially sensitive data.
|
||||
|
||||
The `generation_span()` stores the inputs/outputs of the LLM generation, and `function_span()` stores the inputs/outputs of function calls. These may contain sensitive data, so you can disable capturing that data via [`RunConfig.trace_include_sensitive_data`][cai.agents.run.RunConfig.trace_include_sensitive_data].
|
||||
The `generation_span()` stores the inputs/outputs of the LLM generation, and `function_span()` stores the inputs/outputs of function calls. These may contain sensitive data, so you can disable capturing that data via [`RunConfig.trace_include_sensitive_data`][cai.sdk.agents.run.RunConfig.trace_include_sensitive_data].
|
||||
|
||||
Similarly, Audio spans include base64-encoded PCM data for input and output audio by default. You can disable capturing this audio data by configuring [`VoicePipelineConfig.trace_include_sensitive_audio_data`][cai.agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data].
|
||||
Similarly, Audio spans include base64-encoded PCM data for input and output audio by default. You can disable capturing this audio data by configuring [`VoicePipelineConfig.trace_include_sensitive_audio_data`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data].
|
||||
|
||||
## Custom tracing processors
|
||||
|
||||
The high level architecture for tracing is:
|
||||
|
||||
- At initialization, we create a global [`TraceProvider`][cai.agents.tracing.setup.TraceProvider], which is responsible for creating traces.
|
||||
- We configure the `TraceProvider` with a [`BatchTraceProcessor`][cai.agents.tracing.processors.BatchTraceProcessor] that sends traces/spans in batches to a [`BackendSpanExporter`][cai.agents.tracing.processors.BackendSpanExporter], which exports the spans and traces to the OpenAI backend in batches.
|
||||
- At initialization, we create a global [`TraceProvider`][cai.sdk.agents.tracing.setup.TraceProvider], which is responsible for creating traces.
|
||||
- We configure the `TraceProvider` with a [`BatchTraceProcessor`][cai.sdk.agents.tracing.processors.BatchTraceProcessor] that sends traces/spans in batches to a [`BackendSpanExporter`][cai.sdk.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()`][cai.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()`][cai.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.
|
||||
1. [`add_trace_processor()`][cai.sdk.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()`][cai.sdk.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 tracing processors list
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Pipelines and workflows
|
||||
|
||||
[`VoicePipeline`][cai.agents.voice.pipeline.VoicePipeline] is a class that makes it easy to turn your agentic workflows into a voice app. You pass in a workflow to run, and the pipeline takes care of transcribing input audio, detecting when the audio ends, calling your workflow at the right time, and turning the workflow output back into audio.
|
||||
[`VoicePipeline`][cai.sdk.agents.voice.pipeline.VoicePipeline] is a class that makes it easy to turn your agentic workflows into a voice app. You pass in a workflow to run, and the pipeline takes care of transcribing input audio, detecting when the audio ends, calling your workflow at the right time, and turning the workflow output back into audio.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
|
|
@ -32,27 +32,27 @@ graph LR
|
|||
|
||||
When you create a pipeline, you can set a few things:
|
||||
|
||||
1. The [`workflow`][cai.agents.voice.workflow.VoiceWorkflowBase], which is the code that runs each time new audio is transcribed.
|
||||
2. The [`speech-to-text`][cai.agents.voice.model.STTModel] and [`text-to-speech`][cai.agents.voice.model.TTSModel] models used
|
||||
3. The [`config`][cai.agents.voice.pipeline_config.VoicePipelineConfig], which lets you configure things like:
|
||||
1. The [`workflow`][cai.sdk.agents.voice.workflow.VoiceWorkflowBase], which is the code that runs each time new audio is transcribed.
|
||||
2. The [`speech-to-text`][cai.sdk.agents.voice.model.STTModel] and [`text-to-speech`][cai.sdk.agents.voice.model.TTSModel] models used
|
||||
3. The [`config`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig], which lets you configure things like:
|
||||
- A model provider, which can map model names to models
|
||||
- Tracing, including whether to disable tracing, whether audio files are uploaded, the workflow name, trace IDs etc.
|
||||
- Settings on the TTS and STT models, like the prompt, language and data types used.
|
||||
|
||||
## Running a pipeline
|
||||
|
||||
You can run a pipeline via the [`run()`][cai.agents.voice.pipeline.VoicePipeline.run] method, which lets you pass in audio input in two forms:
|
||||
You can run a pipeline via the [`run()`][cai.sdk.agents.voice.pipeline.VoicePipeline.run] method, which lets you pass in audio input in two forms:
|
||||
|
||||
1. [`AudioInput`][cai.agents.voice.input.AudioInput] is used when you have a full audio transcript, and just want to produce a result for it. This is useful in cases where you don't need to detect when a speaker is done speaking; for example, when you have pre-recorded audio or in push-to-talk apps where it's clear when the user is done speaking.
|
||||
2. [`StreamedAudioInput`][cai.agents.voice.input.StreamedAudioInput] is used when you might need to detect when a user is done speaking. It allows you to push audio chunks as they are detected, and the voice pipeline will automatically run the agent workflow at the right time, via a process called "activity detection".
|
||||
1. [`AudioInput`][cai.sdk.agents.voice.input.AudioInput] is used when you have a full audio transcript, and just want to produce a result for it. This is useful in cases where you don't need to detect when a speaker is done speaking; for example, when you have pre-recorded audio or in push-to-talk apps where it's clear when the user is done speaking.
|
||||
2. [`StreamedAudioInput`][cai.sdk.agents.voice.input.StreamedAudioInput] is used when you might need to detect when a user is done speaking. It allows you to push audio chunks as they are detected, and the voice pipeline will automatically run the agent workflow at the right time, via a process called "activity detection".
|
||||
|
||||
## Results
|
||||
|
||||
The result of a voice pipeline run is a [`StreamedAudioResult`][cai.agents.voice.result.StreamedAudioResult]. This is an object that lets you stream events as they occur. There are a few kinds of [`VoiceStreamEvent`][cai.agents.voice.events.VoiceStreamEvent], including:
|
||||
The result of a voice pipeline run is a [`StreamedAudioResult`][cai.sdk.agents.voice.result.StreamedAudioResult]. This is an object that lets you stream events as they occur. There are a few kinds of [`VoiceStreamEvent`][cai.sdk.agents.voice.events.VoiceStreamEvent], including:
|
||||
|
||||
1. [`VoiceStreamEventAudio`][cai.agents.voice.events.VoiceStreamEventAudio], which contains a chunk of audio.
|
||||
2. [`VoiceStreamEventLifecycle`][cai.agents.voice.events.VoiceStreamEventLifecycle], which informs you of lifecycle events like a turn starting or ending.
|
||||
3. [`VoiceStreamEventError`][cai.agents.voice.events.VoiceStreamEventError], is an error event.
|
||||
1. [`VoiceStreamEventAudio`][cai.sdk.agents.voice.events.VoiceStreamEventAudio], which contains a chunk of audio.
|
||||
2. [`VoiceStreamEventLifecycle`][cai.sdk.agents.voice.events.VoiceStreamEventLifecycle], which informs you of lifecycle events like a turn starting or ending.
|
||||
3. [`VoiceStreamEventError`][cai.sdk.agents.voice.events.VoiceStreamEventError], is an error event.
|
||||
|
||||
```python
|
||||
|
||||
|
|
@ -72,4 +72,4 @@ async for event in result.stream():
|
|||
|
||||
### Interruptions
|
||||
|
||||
The Agents SDK currently does not support any built-in interruptions support for [`StreamedAudioInput`][cai.agents.voice.input.StreamedAudioInput]. Instead for every detected turn it will trigger a separate run of your workflow. If you want to handle interruptions inside your application you can listen to the [`VoiceStreamEventLifecycle`][cai.agents.voice.events.VoiceStreamEventLifecycle] events. `turn_started` will indicate that a new turn was transcribed and processing is beginning. `turn_ended` will trigger after all the audio was dispatched for a respective turn. You could use these events to mute the microphone of the speaker when the model starts a turn and unmute it after you flushed all the related audio for a turn.
|
||||
The Agents SDK currently does not support any built-in interruptions support for [`StreamedAudioInput`][cai.sdk.agents.voice.input.StreamedAudioInput]. Instead for every detected turn it will trigger a separate run of your workflow. If you want to handle interruptions inside your application you can listen to the [`VoiceStreamEventLifecycle`][cai.sdk.agents.voice.events.VoiceStreamEventLifecycle] events. `turn_started` will indicate that a new turn was transcribed and processing is beginning. `turn_ended` will trigger after all the audio was dispatched for a respective turn. You could use these events to mute the microphone of the speaker when the model starts a turn and unmute it after you flushed all the related audio for a turn.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ pip install 'openai-agents[voice]'
|
|||
|
||||
## Concepts
|
||||
|
||||
The main concept to know about is a [`VoicePipeline`][cai.agents.voice.pipeline.VoicePipeline], which is a 3 step process:
|
||||
The main concept to know about is a [`VoicePipeline`][cai.sdk.agents.voice.pipeline.VoicePipeline], which is a 3 step process:
|
||||
|
||||
1. Run a speech-to-text model to turn audio into text.
|
||||
2. Run your code, which is usually an agentic workflow, to produce a result.
|
||||
|
|
@ -88,7 +88,7 @@ agent = Agent(
|
|||
|
||||
## Voice pipeline
|
||||
|
||||
We'll set up a simple voice pipeline, using [`SingleAgentVoiceWorkflow`][cai.agents.voice.workflow.SingleAgentVoiceWorkflow] as the workflow.
|
||||
We'll set up a simple voice pipeline, using [`SingleAgentVoiceWorkflow`][cai.sdk.agents.voice.workflow.SingleAgentVoiceWorkflow] as the workflow.
|
||||
|
||||
```python
|
||||
from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline
|
||||
|
|
|
|||
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
Just like the way [agents are traced](../tracing.md), voice pipelines are also automatically traced.
|
||||
|
||||
You can read the tracing doc above for basic tracing information, but you can additionally configure tracing of a pipeline via [`VoicePipelineConfig`][cai.agents.voice.pipeline_config.VoicePipelineConfig].
|
||||
You can read the tracing doc above for basic tracing information, but you can additionally configure tracing of a pipeline via [`VoicePipelineConfig`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig].
|
||||
|
||||
Key tracing related fields are:
|
||||
|
||||
- [`tracing_disabled`][cai.agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: controls whether tracing is disabled. By default, tracing is enabled.
|
||||
- [`trace_include_sensitive_data`][cai.agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: controls whether traces include potentially sensitive data, like audio transcripts. This is specifically for the voice pipeline, and not for anything that goes on inside your Workflow.
|
||||
- [`trace_include_sensitive_audio_data`][cai.agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: controls whether traces include audio data.
|
||||
- [`workflow_name`][cai.agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: The name of the trace workflow.
|
||||
- [`group_id`][cai.agents.voice.pipeline_config.VoicePipelineConfig.group_id]: The `group_id` of the trace, which lets you link multiple traces.
|
||||
- [`trace_metadata`][cai.agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: Additional metadata to include with the trace.
|
||||
- [`tracing_disabled`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: controls whether tracing is disabled. By default, tracing is enabled.
|
||||
- [`trace_include_sensitive_data`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: controls whether traces include potentially sensitive data, like audio transcripts. This is specifically for the voice pipeline, and not for anything that goes on inside your Workflow.
|
||||
- [`trace_include_sensitive_audio_data`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: controls whether traces include audio data.
|
||||
- [`workflow_name`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: The name of the trace workflow.
|
||||
- [`group_id`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig.group_id]: The `group_id` of the trace, which lets you link multiple traces.
|
||||
- [`trace_metadata`][cai.sdk.agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: Additional metadata to include with the trace.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
"""
|
||||
CAI SDK.
|
||||
"""
|
||||
|
||||
from . import agents
|
||||
|
||||
__all__ = ["agents"]
|
||||
Loading…
Reference in New Issue