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.
Installation
uv pip install -U "agno[openai]"Authentication
Set your OPENAI_API_KEY environment variable. You can get one from OpenAI here.
export OPENAI_API_KEY=sk-***Example
Use OpenAIResponses with your Agent:
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")],
)
Parameters
See the OpenAI Responses docs.
| 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[Verbosity] | None | Controls verbosity of the model's output |
reasoning_effort | Optional[ReasoningEffort] | None | Reasoning effort level for reasoning models |
reasoning_summary | Optional[ReasoningSummary] | 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[ServiceTier] | 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 |
ReasoningEffort, ReasoningSummary, ServiceTier, and Verbosity are string-extensible aliases from agno.models.openai.types. Named effort values are none, minimal, low, medium, high, xhigh, and max; named tiers are auto, default, flex, scale, priority, fast, and ultrafast. Summary values include auto, concise, and detailed; verbosity includes low, medium, and high. Agno forwards these settings, but the selected OpenAI model, endpoint, and account determine which values are accepted.
OpenAIResponses is a subclass of the Model class and has access to the same params.