---
title: OpenAI Responses API
tags: [mcp, state]
integrationType: model-provider
---

The [Responses API](https://platform.openai.com/docs/api-reference/responses) is OpenAI's interface for generating model responses and building agents. It is a superset of the [Chat Completions](./openai) API, with additional support for [built-in tools](#built-in-tools), server-side conversation state management, and multi-modal inputs.

## Installation

<Tabs>
<Tab label="Python">

```bash
pip install 'strands-agents[openai]' strands-agents-tools
```

Requires `openai>=2.0.0`. Install or upgrade with `pip install -U openai`.
</Tab>
<Tab label="TypeScript">

```bash
npm install @strands-agents/sdk openai
```
</Tab>
</Tabs>

## Usage

After installing dependencies, you can import and initialize the Responses provider as follows:

<Tabs>
<Tab label="Python">

```python
from strands import Agent
from strands.models.openai_responses import OpenAIResponsesModel

model = OpenAIResponsesModel(
    model_id="gpt-4o",
    client_args={"api_key": "<KEY>"},
)

agent = Agent(model=model)
response = agent("Hello!")
print(response)
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses_imports.ts:basic_usage_imports"

--8<-- "user-guide/concepts/model-providers/openai-responses.ts:basic_usage"
```

In TypeScript, both the Responses API and Chat Completions API are available through a single `OpenAIModel` class. The Responses API is selected by default. Pass `api: 'chat'` to use [Chat Completions](./openai) instead.
</Tab>
</Tabs>

### Amazon Bedrock (Mantle)

The Responses provider can connect to [Amazon Bedrock's OpenAI-compatible endpoints](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html) powered by Mantle. Authenticate with a [Bedrock API key](https://docs.aws.amazon.com/bedrock/latest/userguide/api-key-management.html) and point the client at your region's Mantle endpoint.

<Tabs>
<Tab label="Python">

```python
from strands import Agent
from strands.models.openai_responses import OpenAIResponsesModel

region = "us-east-1"
model = OpenAIResponsesModel(
    model_id="openai.gpt-oss-120b",
    client_args={
        "api_key": "<BEDROCK_API_KEY>",
        "base_url": f"https://bedrock-mantle.{region}.api.aws/v1",
    },
)

agent = Agent(model=model)
response = agent("What is 2+2?")
print(response)
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses_imports.ts:bedrock_mantle_imports"

--8<-- "user-guide/concepts/model-providers/openai-responses.ts:bedrock_mantle"
```
</Tab>
</Tabs>

## Configuration

### Client Configuration

<Tabs>
<Tab label="Python">

The `client_args` configure the underlying OpenAI client. For a complete list of available arguments, refer to the [OpenAI Python SDK](https://github.com/openai/openai-python).
</Tab>
<Tab label="TypeScript">

The `clientConfig` configures the underlying OpenAI client. For a complete list of available options, refer to the [OpenAI TypeScript SDK](https://github.com/openai/openai-node).
</Tab>
</Tabs>

### Model Configuration

The model configuration sets parameters for inference:

<Tabs>
<Tab label="Python">

|  Parameter | Description | Example | Options |
|------------|-------------|---------|---------|
| `model_id` | ID of a model to use | `gpt-4o` | [reference](https://platform.openai.com/docs/models) |
| `params` | Model and tool parameters | `{"tools": [{"type": "web_search"}]}` | [reference](https://platform.openai.com/docs/api-reference/responses/create) |
| `stateful` | Enable server-side conversation state | `True` | `True` / `False` |
</Tab>
<Tab label="TypeScript">

|  Parameter | Description | Example | Options |
|------------|-------------|---------|---------|
| `modelId` | ID of a model to use | `'gpt-4o'` | [reference](https://platform.openai.com/docs/models) |
| `maxTokens` | Maximum tokens to generate | `1000` | [reference](https://platform.openai.com/docs/api-reference/responses/create) |
| `temperature` | Controls randomness (0-2) | `0.7` | [reference](https://platform.openai.com/docs/api-reference/responses/create) |
| `topP` | Nucleus sampling (0-1) | `0.9` | [reference](https://platform.openai.com/docs/api-reference/responses/create) |
| `stateful` | Enable server-side conversation state | `true` | `true` / `false` |
| `params` | Additional parameters (e.g., built-in tools) | `{ tools: [{ type: 'web_search' }] }` | [reference](https://platform.openai.com/docs/api-reference/responses/create) |
</Tab>
</Tabs>

## Built-in Tools

Built-in tools run server-side and are passed via the `params` configuration. They work alongside any function tools registered on the agent.

### Web Search

<Tabs>
<Tab label="Python">

```python
model = OpenAIResponsesModel(
    model_id="gpt-4o",
    params={"tools": [{"type": "web_search"}]},
    client_args={"api_key": "<KEY>"},
)

agent = Agent(model=model)
response = agent("What are the latest developments in AI?")
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses.ts:web_search"
```
</Tab>
</Tabs>

Web search responses include URL citations that are streamed through the SDK's citation system.

### File Search

<Tabs>
<Tab label="Python">

```python
model = OpenAIResponsesModel(
    model_id="gpt-4o",
    params={
        "tools": [{"type": "file_search", "vector_store_ids": ["vs_abc123"]}],
    },
    client_args={"api_key": "<KEY>"},
)

agent = Agent(model=model)
response = agent("What does the document say about pricing?")
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses.ts:file_search"
```
</Tab>
</Tabs>

File search requires a [vector store](https://platform.openai.com/docs/guides/tools-file-search) with uploaded files. Text responses stream correctly; file citation annotations are not yet mapped to the SDK citation schema.

### Code Interpreter

<Tabs>
<Tab label="Python">

```python
model = OpenAIResponsesModel(
    model_id="gpt-4o",
    params={
        "tools": [{"type": "code_interpreter", "container": {"type": "auto"}}],
    },
    client_args={"api_key": "<KEY>"},
)

agent = Agent(model=model)
response = agent("Calculate the SHA-256 hash of 'hello world'")
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses.ts:code_interpreter"
```
</Tab>
</Tabs>

The model executes code server-side and includes the results in its text response. The executed code and stdout/stderr are not currently surfaced to the caller.

### Remote MCP

The `mcp` built-in tool connects the model to a remote [MCP](https://modelcontextprotocol.io/) server, letting it call tools hosted externally without any local MCP client setup.

<Tabs>
<Tab label="Python">

```python
model = OpenAIResponsesModel(
    model_id="gpt-4o",
    params={
        "tools": [
            {
                "type": "mcp",
                "server_label": "deepwiki",
                "server_url": "https://mcp.deepwiki.com/mcp",
                "require_approval": "never",
            }
        ]
    },
    client_args={"api_key": "<KEY>"},
)

agent = Agent(model=model)
response = agent("Using deepwiki, what language is the strands-agents/harness-sdk repo written in?")
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses.ts:remote_mcp"
```
</Tab>
</Tabs>

The model discovers and calls tools exposed by the remote MCP server. The approval flow is not currently surfaced, so `require_approval` must be set to `"never"`.

### Shell

The `shell` built-in tool runs shell commands inside a hosted container managed by OpenAI.

<Tabs>
<Tab label="Python">

```python
model = OpenAIResponsesModel(
    model_id="gpt-4o",
    params={
        "tools": [{"type": "shell", "environment": {"type": "container_auto"}}],
    },
    client_args={"api_key": "<KEY>"},
)

agent = Agent(model=model)
response = agent("Use the shell to compute the md5sum of the string 'hello world'.")
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses.ts:shell"
```
</Tab>
</Tabs>

The model executes commands server-side and includes the output in its text response.

## Server-side Conversation State

When `stateful` is enabled, the model manages conversation history server-side using OpenAI's `previous_response_id` mechanism. The agent's local message history is cleared after each turn, reducing payload size for multi-turn conversations.

<Tabs>
<Tab label="Python">

```python
model = OpenAIResponsesModel(
    model_id="gpt-4o",
    stateful=True,
    client_args={"api_key": "<KEY>"},
)

agent = Agent(model=model)
agent("My name is Alice.")
# agent.messages is empty; conversation state is on the server

response = agent("What is my name?")
# The model remembers "Alice" via server-side state
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "user-guide/concepts/model-providers/openai-responses.ts:stateful"
```
</Tab>
</Tabs>

When using a stateful model, the agent automatically uses a null conversation manager and throws an error if a conversation manager is also supplied.

## Advanced Features

### Token Counting

Token counting is used by context management strategies to estimate input tokens before each model call.

<Tabs>
<Tab label="Python">

The OpenAI Responses provider can use the native `responses.input_tokens.count()` API, which provides exact token counts including messages, instructions, and tool specifications.

You can enable native token counting with:

```python
model = OpenAIResponsesModel(
    model_id="gpt-4.1",
    use_native_token_count=True,
)
```

When disabled (or if the API call fails), falls back to estimation with a character-based heuristic (characters ÷ 4 for text, characters ÷ 2 for JSON).
</Tab>
<Tab label="TypeScript">

The OpenAI Responses provider does not currently implement native token counting in the TypeScript SDK. It uses estimation with a character-based heuristic (characters ÷ 4 for text, characters ÷ 2 for JSON).
</Tab>
</Tabs>

## References

- [Python API](@api/python/strands.models.openai_responses)
- [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses)
- [Amazon Bedrock Mantle](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html)
- [OpenAI Chat Completions](./openai) (alternative provider using the Chat Completions API)
