diff --git a/src/agents/run.py b/src/agents/run.py index 205ee0113..42339eb50 100644 --- a/src/agents/run.py +++ b/src/agents/run.py @@ -243,40 +243,54 @@ async def run( conversation_id: str | None = None, session: Session | 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. + """ + 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. + + 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: + 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. + 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). + 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. - previous_response_id: The ID of the previous response, if using OpenAI models via the - Responses API, this allows you to skip passing in input from the previous turn. - conversation_id: The conversation ID (https://platform.openai.com/docs/guides/conversation-state?api-mode=responses). + previous_response_id: The ID of the previous response. If using OpenAI + models via the Responses API, this allows you to skip passing in input + from the previous turn. + conversation_id: The conversation ID + (https://platform.openai.com/docs/guides/conversation-state?api-mode=responses). If provided, the conversation will be used to read and write items. Every agent will have access to the conversation history so far, - and it's output items will be written to the conversation. + and its output items will be written to the conversation. We recommend only using this if you are exclusively using OpenAI models; other model providers don't write to the Conversation object, so you'll end up having partial conversations stored. session: A session for automatic conversation history management. + 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. + 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. """ + runner = DEFAULT_AGENT_RUNNER return await runner.run( starting_agent, @@ -304,37 +318,52 @@ def run_sync( conversation_id: str | None = None, session: Session | 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. + """ + Run a workflow synchronously, starting at the given agent. + + Note: + 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: + + 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. + + 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: + 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. + 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). + 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. - previous_response_id: The ID of the previous response, if using OpenAI models via the - Responses API, this allows you to skip passing in input from the previous turn. + previous_response_id: The ID of the previous response, if using OpenAI + models via the Responses API, this allows you to skip passing in input + from the previous turn. conversation_id: The ID of the stored conversation, if any. session: A session for automatic conversation history management. + 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. + 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. """ + runner = DEFAULT_AGENT_RUNNER return runner.run_sync( starting_agent, @@ -361,34 +390,49 @@ def run_streamed( conversation_id: str | None = None, session: Session | 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. + """ + 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. + + 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. + + 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: + 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. + 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). + 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. - previous_response_id: The ID of the previous response, if using OpenAI models via the - Responses API, this allows you to skip passing in input from the previous turn. + previous_response_id: The ID of the previous response, if using OpenAI + models via the Responses API, this allows you to skip passing in input + from the previous turn. conversation_id: The ID of the stored conversation, if any. session: A session for automatic conversation history management. + Returns: - A result object that contains data about the run, as well as a method to stream events. + A result object that contains data about the run, as well as a method to + stream events. """ + runner = DEFAULT_AGENT_RUNNER return runner.run_streamed( starting_agent,