Skip to content

docs: reformat run module docstrings to Google style for better mkdocstrings rendering #1740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 17, 2025
Merged

docs: reformat run module docstrings to Google style for better mkdocstrings rendering #1740

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1d735c1
docs: reformat run module docstrings to Google style for better mkdoc…
MuhammedSuhaib Sep 15, 2025
9ae3c26
docs: reformat run module docstrings to Google style
MuhammedSuhaib Sep 15, 2025
91a0d00
Merge branch 'main' into main
MuhammedSuhaib Sep 16, 2025
2288fe4
Keep the correct grammar → its output items ✅ (not it's).
MuhammedSuhaib Sep 16, 2025
83bb95b
Merge branch 'main' into main
MuhammedSuhaib Sep 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 102 additions & 58 deletions src/agents/run.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand Down