strands.models.openai_responses

OpenAI model provider using the Responses API.

Note: Built-in tools (web search, code interpreter, file search) are not yet supported.

Docs: https://platform.openai.com/docs/api-reference/responses

Client

class Client(Protocol)

Defined in: src/strands/models/openai_responses.py:95

Protocol defining the OpenAI Responses API interface for the underlying provider client.

responses

@property
def responses() -> Any

Defined in: src/strands/models/openai_responses.py:100

Responses interface.

OpenAIResponsesModel

class OpenAIResponsesModel(Model)

Defined in: src/strands/models/openai_responses.py:105

OpenAI Responses API model provider implementation.

Notes:

This implementation currently only supports function tools (custom tools defined via tool_specs). OpenAI’s built-in system tools are not yet supported.

OpenAIResponsesConfig

class OpenAIResponsesConfig(TypedDict)

Defined in: src/strands/models/openai_responses.py:116

Configuration options for OpenAI Responses API models.

Attributes:

• model_id - Model ID (e.g., “gpt-4o”). For a complete list of supported models, see https://platform.openai.com/docs/models.
• params - Model parameters (e.g., max_output_tokens, temperature, etc.). For a complete list of supported parameters, see https://platform.openai.com/docs/api-reference/responses/create.
• stateful - Whether to enable server-side conversation state management. When True, the server stores conversation history and the client does not need to send the full message history with each request. Defaults to False.

__init__

def __init__(client_args: dict[str, Any] | None = None,
             **model_config: Unpack[OpenAIResponsesConfig]) -> None

Defined in: src/strands/models/openai_responses.py:134

Initialize provider instance.

Arguments:

• client_args - Arguments for the OpenAI client. For a complete list of supported arguments, see https://pypi.org/project/openai/.
• **model_config - Configuration options for the OpenAI Responses API model.

stateful

@property
@override
def stateful() -> bool

Defined in: src/strands/models/openai_responses.py:152

Whether server-side conversation storage is enabled.

Derived from the stateful configuration option.

update_config

@override
def update_config(**model_config: Unpack[OpenAIResponsesConfig]) -> None

Defined in: src/strands/models/openai_responses.py:160

Update the OpenAI Responses API model configuration with the provided arguments.

Arguments:

• **model_config - Configuration overrides.

get_config

@override
def get_config() -> OpenAIResponsesConfig

Defined in: src/strands/models/openai_responses.py:170

Get the OpenAI Responses API model configuration.

Returns:

The OpenAI Responses API model configuration.

stream

@override
async def stream(messages: Messages,
                 tool_specs: list[ToolSpec] | None = None,
                 system_prompt: str | None = None,
                 *,
                 tool_choice: ToolChoice | None = None,
                 model_state: dict[str, Any] | None = None,
                 **kwargs: Any) -> AsyncGenerator[StreamEvent, None]

Defined in: src/strands/models/openai_responses.py:179

Stream conversation with the OpenAI Responses API model.

Arguments:

• messages - List of message objects to be processed by the model.
• tool_specs - List of tool specifications to make available to the model.
• system_prompt - System prompt to provide context to the model.
• tool_choice - Selection strategy for tool invocation.
• model_state - Runtime state for model providers (e.g., server-side response ids).
• **kwargs - Additional keyword arguments for future extensibility.

Yields:

Formatted message chunks from the model.

Raises:

• ContextWindowOverflowException - If the input exceeds the model’s context window.
• ModelThrottledException - If the request is throttled by OpenAI (rate limits).

structured_output

@override
async def structured_output(
        output_model: type[T],
        prompt: Messages,
        system_prompt: str | None = None,
        **kwargs: Any) -> AsyncGenerator[dict[str, T | Any], None]

Defined in: src/strands/models/openai_responses.py:353

Get structured output from the OpenAI Responses API model.

Arguments:

• output_model - The output model to use for the agent.
• prompt - The prompt messages to use for the agent.
• system_prompt - System prompt to provide context to the model.
• **kwargs - Additional keyword arguments for future extensibility.

Yields:

Model events with the last being the structured output.

Raises:

• ContextWindowOverflowException - If the input exceeds the model’s context window.
• ModelThrottledException - If the request is throttled by OpenAI (rate limits).