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 yourOPENAI_API_KEY environment variable. You can get one from OpenAI here.
export OPENAI_API_KEY=sk-***
setx OPENAI_API_KEY sk-***
Example
UseOpenAIResponses 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")],
)
View more examples here.
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[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 class and has access to the same params.