strands.models.openai

OpenAI model provider.

Docs: https://platform.openai.com/docs/overview

Client

class Client(Protocol)

Defined in: src/strands/models/openai.py:40

Protocol defining the OpenAI-compatible interface for the underlying provider client.

chat

@property
def chat() -> Any

Defined in: src/strands/models/openai.py:45

Chat completions interface.

OpenAIModel

class OpenAIModel(Model)

Defined in: src/strands/models/openai.py:50

OpenAI model provider implementation.

OpenAIConfig

class OpenAIConfig(TypedDict)

Defined in: src/strands/models/openai.py:55

Configuration options for OpenAI 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_tokens). For a complete list of supported parameters, see https://platform.openai.com/docs/api-reference/chat/create.

init

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

Defined in: src/strands/models/openai.py:69

Initialize provider instance.

Arguments:

client - Pre-configured OpenAI-compatible client to reuse across requests. When provided, this client will be reused for all requests and will NOT be closed by the model. The caller is responsible for managing the client lifecycle. This is useful for:
- Injecting custom client wrappers (e.g., GuardrailsAsyncOpenAI)
- Reusing connection pools within a single event loop/worker
- Centralizing observability, retries, and networking policy
- Pointing to custom model gateways
Note - The client should not be shared across different asyncio event loops.
client_args - Arguments for the OpenAI client (legacy approach). For a complete list of supported arguments, see https://pypi.org/project/openai/.
**model_config - Configuration options for the OpenAI model.

Raises:

ValueError - If both client and client_args are provided.

update_config

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

Defined in: src/strands/models/openai.py:107

Update the OpenAI model configuration with the provided arguments.

Arguments:

**model_config - Configuration overrides.

get_config

@override
def get_config() -> OpenAIConfig

Defined in: src/strands/models/openai.py:117

Get the OpenAI model configuration.

Returns:

The OpenAI model configuration.

format_request_message_content

@classmethod
def format_request_message_content(cls, content: ContentBlock,
                                   **kwargs: Any) -> dict[str, Any]

Defined in: src/strands/models/openai.py:126

Format an OpenAI compatible content block.

Arguments:

content - Message content.
**kwargs - Additional keyword arguments for future extensibility.

Returns:

OpenAI compatible content block.

Raises:

TypeError - If the content block type cannot be converted to an OpenAI-compatible format.

format_request_message_tool_call

@classmethod
def format_request_message_tool_call(cls, tool_use: ToolUse,
                                     **kwargs: Any) -> dict[str, Any]

Defined in: src/strands/models/openai.py:169

Format an OpenAI compatible tool call.

Arguments:

tool_use - Tool use requested by the model.
**kwargs - Additional keyword arguments for future extensibility.

Returns:

OpenAI compatible tool call.

format_request_tool_message

@classmethod
def format_request_tool_message(cls, tool_result: ToolResult,
                                **kwargs: Any) -> dict[str, Any]

Defined in: src/strands/models/openai.py:189

Format an OpenAI compatible tool message.

Arguments:

tool_result - Tool result collected from a tool execution.
**kwargs - Additional keyword arguments for future extensibility.

Returns:

OpenAI compatible tool message.

format_request_messages

@classmethod
def format_request_messages(cls,
                            messages: Messages,
                            system_prompt: str | None = None,
                            *,
                            system_prompt_content: list[SystemContentBlock]
                            | None = None,
                            **kwargs: Any) -> list[dict[str, Any]]

Defined in: src/strands/models/openai.py:399

Format an OpenAI compatible messages array.

Arguments:

messages - List of message objects to be processed by the model.
system_prompt - System prompt to provide context to the model.
system_prompt_content - System prompt content blocks to provide context to the model.
**kwargs - Additional keyword arguments for future extensibility.

Returns:

An OpenAI compatible messages array.

format_request

def format_request(messages: Messages,
                   tool_specs: list[ToolSpec] | None = None,
                   system_prompt: str | None = None,
                   tool_choice: ToolChoice | None = None,
                   *,
                   system_prompt_content: list[SystemContentBlock]
                   | None = None,
                   **kwargs: Any) -> dict[str, Any]

Defined in: src/strands/models/openai.py:423

Format an OpenAI compatible chat streaming request.

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.
system_prompt_content - System prompt content blocks to provide context to the model.
**kwargs - Additional keyword arguments for future extensibility.

Returns:

An OpenAI compatible chat streaming request.

Raises:

TypeError - If a message contains a content block type that cannot be converted to an OpenAI-compatible format.

format_chunk

def format_chunk(event: dict[str, Any], **kwargs: Any) -> StreamEvent

Defined in: src/strands/models/openai.py:472

Format an OpenAI response event into a standardized message chunk.

Arguments:

event - A response event from the OpenAI compatible model.
**kwargs - Additional keyword arguments for future extensibility.

Returns:

The formatted chunk.

Raises:

RuntimeError - If chunk_type is not recognized. This error should never be encountered as chunk_type is controlled in the stream method.

stream

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

Defined in: src/strands/models/openai.py:574

Stream conversation with the OpenAI 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.
**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.py:714

Get structured output from the 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).