> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Responses

> Use OpenAI's Responses API with Agno agents.

`OpenAIResponses` is a class for interacting with OpenAI models using the Responses API, which is distinct from the Chat Completions API. It supports tool use, file processing, and knowledge retrieval.

## Authentication

Set your `OPENAI_API_KEY` environment variable. You can get one [from OpenAI here](https://platform.openai.com/account/api-keys).

```bash Mac theme={null}
export OPENAI_API_KEY=sk-***
```

```bash Windows theme={null}
setx OPENAI_API_KEY sk-***
```

## Example

Use `OpenAIResponses` with your `Agent`:

```python agent.py theme={null}

from agno.agent import Agent
from agno.media import File
from agno.models.openai.responses import OpenAIResponses

agent = Agent(
    model=OpenAIResponses(id="gpt-5-mini"),
    tools=[{"type": "file_search"}, {"type": "web_search_preview"}],
    markdown=True,
)

agent.print_response(
    "Summarize the contents of the attached file and search the web for more information.",
    files=[File(url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf")],
)

```

> [!NOTE]
>
> View more examples [here](https://agno-v2.mintlify.site/models/providers/native/openai/responses/usage/basic-stream.md).

## Parameters

See the [OpenAI Responses docs](https://platform.openai.com/docs/api-reference/responses).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | `str` | `"gpt-5.4-mini"` | The id of the OpenAI model to use with Responses API |
| `name` | `str` | `"OpenAIResponses"` | The name of the model |
| `provider` | `str` | `"OpenAI"` | The provider of the model |
| `include` | `Optional[List[str]]` | `None` | Additional output data to include in the response |
| `max_output_tokens` | `Optional[int]` | `None` | Maximum number of output tokens to generate |
| `max_tool_calls` | `Optional[int]` | `None` | Maximum number of tool calls allowed in the response |
| `metadata` | `Optional[Dict[str, Any]]` | `None` | Developer-defined metadata to associate with the response |
| `parallel_tool_calls` | `Optional[bool]` | `None` | Whether to enable parallel function calling |
| `reasoning` | `Optional[Dict[str, Any]]` | `None` | Reasoning configuration for reasoning models |
| `verbosity` | `Optional[Literal["low", "medium", "high"]]` | `None` | Controls verbosity of the model's output |
| `reasoning_effort` | `Optional[Literal["minimal", "low", "medium", "high"]]` | `None` | Reasoning effort level for reasoning models |
| `reasoning_summary` | `Optional[Literal["auto", "concise", "detailed"]]` | `None` | Level of detail for reasoning summaries |
| `store` | `Optional[bool]` | `None` | Whether to store the response for later retrieval |
| `temperature` | `Optional[float]` | `None` | Controls randomness in the model's output (0.0 to 2.0) |
| `top_p` | `Optional[float]` | `None` | Controls diversity via nucleus sampling (0.0 to 1.0) |
| `truncation` | `Optional[Literal["auto", "disabled"]]` | `None` | Truncation strategy when context exceeds the window |
| `user` | `Optional[str]` | `None` | A unique identifier representing your end-user |
| `service_tier` | `Optional[Literal["auto", "default", "flex", "priority"]]` | `None` | Service tier to use for the request |
| `strict_output` | `bool` | `True` | Controls schema adherence for structured outputs |
| `background` | `Optional[bool]` | `None` | Enables background mode for long-running tasks. Not supported for streaming |
| `background_poll_interval` | `float` | `2.0` | Interval in seconds between polling attempts in background mode |
| `background_max_wait` | `float` | `600.0` | Maximum time in seconds to wait for a background response before cancelling |
| `extra_headers` | `Optional[Any]` | `None` | Additional headers to include in requests |
| `extra_query` | `Optional[Any]` | `None` | Additional query parameters to include in requests |
| `extra_body` | `Optional[Any]` | `None` | Additional body parameters to include in requests |
| `request_params` | `Optional[Dict[str, Any]]` | `None` | Additional parameters to include in the request |
| `api_key` | `Optional[str]` | `None` | The API key for authenticating with OpenAI (defaults to OPENAI\_API\_KEY env var) |
| `organization` | `Optional[str]` | `None` | The organization ID to use for requests |
| `base_url` | `Optional[Union[str, httpx.URL]]` | `None` | The base URL for the OpenAI API |
| `timeout` | `Optional[float]` | `None` | Request timeout in seconds |
| `max_retries` | `Optional[int]` | `None` | Maximum number of retries for failed requests |
| `default_headers` | `Optional[Dict[str, str]]` | `None` | Default headers to include in all requests |
| `default_query` | `Optional[Dict[str, str]]` | `None` | Default query parameters to include in all requests |
| `http_client` | `Optional[Union[httpx.Client, httpx.AsyncClient]]` | `None` | HTTP client instance for making requests |
| `client_params` | `Optional[Dict[str, Any]]` | `None` | Additional parameters for client configuration |
| `client` | `Optional[OpenAI]` | `None` | A pre-configured instance of the OpenAI client |
| `async_client` | `Optional[AsyncOpenAI]` | `None` | A pre-configured instance of the async OpenAI client |
| `vector_store_name` | `str` | `"knowledge_base"` | Name of the vector store created for the `file_search` built-in tool |
| `role_map` | `Dict[str, str]` | Maps `system` to `developer` | Mapping of message roles to OpenAI Responses roles |

`OpenAIResponses` is a subclass of the [Model](https://agno-v2.mintlify.site/reference/models/model.md) class and has access to the same params.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.