Responses

The responses and aresponses functions implement the OpenResponses specification, a vendor-neutral API for agentic AI systems. This API supports multi-turn conversations, tool use, and streaming events.

Return Types

The return type depends on the provider and whether streaming is enabled:

Condition	Return Type
OpenResponses-compliant provider (non-streaming)	openresponses_types.ResponseResource
OpenAI-native provider (non-streaming)	openai.types.responses.Response
Streaming (stream=True)	Iterator[ResponseStreamEvent] (sync) or AsyncIterator[ResponseStreamEvent] (async)

any_llm.responses()

def responses(
    model: str,
    input_data: str | list[EasyInputMessageParam | Message | ResponseOutputMessageParam | ResponseFileSearchToolCallParam | ResponseComputerToolCallParam | ComputerCallOutput | ResponseFunctionWebSearchParam | ResponseFunctionToolCallParam | FunctionCallOutput | ToolSearchCall | ResponseToolSearchOutputItemParamParam | ResponseReasoningItemParam | ResponseCompactionItemParamParam | ImageGenerationCall | ResponseCodeInterpreterToolCallParam | LocalShellCall | LocalShellCallOutput | ShellCall | ShellCallOutput | ApplyPatchCall | ApplyPatchCallOutput | McpListTools | McpApprovalRequest | McpApprovalResponse | McpCall | ResponseCustomToolCallOutputParam | ResponseCustomToolCallParam | ItemReference],
    *,
    provider: str | LLMProvider | None = None,
    tools: list[dict[str, Any] | Callable[..., Any]] | None = None,
    tool_choice: str | dict[str, Any] | None = None,
    max_output_tokens: int | None = None,
    temperature: float | None = None,
    top_p: float | None = None,
    stream: bool | None = None,
    api_key: str | None = None,
    api_base: str | None = None,
    instructions: str | None = None,
    max_tool_calls: int | None = None,
    parallel_tool_calls: int | None = None,
    reasoning: Any | None = None,
    text: Any | None = None,
    presence_penalty: float | None = None,
    frequency_penalty: float | None = None,
    truncation: str | None = None,
    store: bool | None = None,
    service_tier: str | None = None,
    user: str | None = None,
    metadata: dict[str, str] | None = None,
    previous_response_id: str | None = None,
    include: list[str] | None = None,
    background: bool | None = None,
    safety_identifier: str | None = None,
    prompt_cache_key: str | None = None,
    prompt_cache_retention: str | None = None,
    conversation: str | dict[str, Any] | None = None,
    client_args: dict[str, Any] | None = None,
    **kwargs: Any,
) -> types.ResponseResource | response.Response | Iterator[Annotated[Union[response_audio_delta_event.ResponseAudioDeltaEvent, response_audio_done_event.ResponseAudioDoneEvent, response_audio_transcript_delta_event.ResponseAudioTranscriptDeltaEvent, response_audio_transcript_done_event.ResponseAudioTranscriptDoneEvent, response_code_interpreter_call_code_delta_event.ResponseCodeInterpreterCallCodeDeltaEvent, response_code_interpreter_call_code_done_event.ResponseCodeInterpreterCallCodeDoneEvent, response_code_interpreter_call_completed_event.ResponseCodeInterpreterCallCompletedEvent, response_code_interpreter_call_in_progress_event.ResponseCodeInterpreterCallInProgressEvent, response_code_interpreter_call_interpreting_event.ResponseCodeInterpreterCallInterpretingEvent, response_completed_event.ResponseCompletedEvent, response_content_part_added_event.ResponseContentPartAddedEvent, response_content_part_done_event.ResponseContentPartDoneEvent, response_created_event.ResponseCreatedEvent, response_error_event.ResponseErrorEvent, response_file_search_call_completed_event.ResponseFileSearchCallCompletedEvent, response_file_search_call_in_progress_event.ResponseFileSearchCallInProgressEvent, response_file_search_call_searching_event.ResponseFileSearchCallSearchingEvent, response_function_call_arguments_delta_event.ResponseFunctionCallArgumentsDeltaEvent, response_function_call_arguments_done_event.ResponseFunctionCallArgumentsDoneEvent, response_in_progress_event.ResponseInProgressEvent, response_failed_event.ResponseFailedEvent, response_incomplete_event.ResponseIncompleteEvent, response_output_item_added_event.ResponseOutputItemAddedEvent, response_output_item_done_event.ResponseOutputItemDoneEvent, response_reasoning_summary_part_added_event.ResponseReasoningSummaryPartAddedEvent, response_reasoning_summary_part_done_event.ResponseReasoningSummaryPartDoneEvent, response_reasoning_summary_text_delta_event.ResponseReasoningSummaryTextDeltaEvent, response_reasoning_summary_text_done_event.ResponseReasoningSummaryTextDoneEvent, response_reasoning_text_delta_event.ResponseReasoningTextDeltaEvent, response_reasoning_text_done_event.ResponseReasoningTextDoneEvent, response_refusal_delta_event.ResponseRefusalDeltaEvent, response_refusal_done_event.ResponseRefusalDoneEvent, response_text_delta_event.ResponseTextDeltaEvent, response_text_done_event.ResponseTextDoneEvent, response_web_search_call_completed_event.ResponseWebSearchCallCompletedEvent, response_web_search_call_in_progress_event.ResponseWebSearchCallInProgressEvent, response_web_search_call_searching_event.ResponseWebSearchCallSearchingEvent, response_image_gen_call_completed_event.ResponseImageGenCallCompletedEvent, response_image_gen_call_generating_event.ResponseImageGenCallGeneratingEvent, response_image_gen_call_in_progress_event.ResponseImageGenCallInProgressEvent, response_image_gen_call_partial_image_event.ResponseImageGenCallPartialImageEvent, response_mcp_call_arguments_delta_event.ResponseMcpCallArgumentsDeltaEvent, response_mcp_call_arguments_done_event.ResponseMcpCallArgumentsDoneEvent, response_mcp_call_completed_event.ResponseMcpCallCompletedEvent, response_mcp_call_failed_event.ResponseMcpCallFailedEvent, response_mcp_call_in_progress_event.ResponseMcpCallInProgressEvent, response_mcp_list_tools_completed_event.ResponseMcpListToolsCompletedEvent, response_mcp_list_tools_failed_event.ResponseMcpListToolsFailedEvent, response_mcp_list_tools_in_progress_event.ResponseMcpListToolsInProgressEvent, response_output_text_annotation_added_event.ResponseOutputTextAnnotationAddedEvent, response_queued_event.ResponseQueuedEvent, response_custom_tool_call_input_delta_event.ResponseCustomToolCallInputDeltaEvent, response_custom_tool_call_input_done_event.ResponseCustomToolCallInputDoneEvent], PropertyInfo(alias='None', format=None, format_template='None', discriminator='type')]]

any_llm.aresponses()

Async variant with the same parameters. Returns ResponseResource | Response | AsyncIterator[ResponseStreamEvent].

async def aresponses(
    model: str,
    input_data: str | list[EasyInputMessageParam | Message | ResponseOutputMessageParam | ResponseFileSearchToolCallParam | ResponseComputerToolCallParam | ComputerCallOutput | ResponseFunctionWebSearchParam | ResponseFunctionToolCallParam | FunctionCallOutput | ToolSearchCall | ResponseToolSearchOutputItemParamParam | ResponseReasoningItemParam | ResponseCompactionItemParamParam | ImageGenerationCall | ResponseCodeInterpreterToolCallParam | LocalShellCall | LocalShellCallOutput | ShellCall | ShellCallOutput | ApplyPatchCall | ApplyPatchCallOutput | McpListTools | McpApprovalRequest | McpApprovalResponse | McpCall | ResponseCustomToolCallOutputParam | ResponseCustomToolCallParam | ItemReference],
    *,
    provider: str | LLMProvider | None = None,
    tools: list[dict[str, Any] | Callable[..., Any]] | None = None,
    tool_choice: str | dict[str, Any] | None = None,
    max_output_tokens: int | None = None,
    temperature: float | None = None,
    top_p: float | None = None,
    stream: bool | None = None,
    api_key: str | None = None,
    api_base: str | None = None,
    instructions: str | None = None,
    max_tool_calls: int | None = None,
    parallel_tool_calls: int | None = None,
    reasoning: Any | None = None,
    text: Any | None = None,
    presence_penalty: float | None = None,
    frequency_penalty: float | None = None,
    truncation: str | None = None,
    store: bool | None = None,
    service_tier: str | None = None,
    user: str | None = None,
    metadata: dict[str, str] | None = None,
    previous_response_id: str | None = None,
    include: list[str] | None = None,
    background: bool | None = None,
    safety_identifier: str | None = None,
    prompt_cache_key: str | None = None,
    prompt_cache_retention: str | None = None,
    conversation: str | dict[str, Any] | None = None,
    client_args: dict[str, Any] | None = None,
    **kwargs: Any,
) -> types.ResponseResource | response.Response | AsyncIterator[Annotated[Union[response_audio_delta_event.ResponseAudioDeltaEvent, response_audio_done_event.ResponseAudioDoneEvent, response_audio_transcript_delta_event.ResponseAudioTranscriptDeltaEvent, response_audio_transcript_done_event.ResponseAudioTranscriptDoneEvent, response_code_interpreter_call_code_delta_event.ResponseCodeInterpreterCallCodeDeltaEvent, response_code_interpreter_call_code_done_event.ResponseCodeInterpreterCallCodeDoneEvent, response_code_interpreter_call_completed_event.ResponseCodeInterpreterCallCompletedEvent, response_code_interpreter_call_in_progress_event.ResponseCodeInterpreterCallInProgressEvent, response_code_interpreter_call_interpreting_event.ResponseCodeInterpreterCallInterpretingEvent, response_completed_event.ResponseCompletedEvent, response_content_part_added_event.ResponseContentPartAddedEvent, response_content_part_done_event.ResponseContentPartDoneEvent, response_created_event.ResponseCreatedEvent, response_error_event.ResponseErrorEvent, response_file_search_call_completed_event.ResponseFileSearchCallCompletedEvent, response_file_search_call_in_progress_event.ResponseFileSearchCallInProgressEvent, response_file_search_call_searching_event.ResponseFileSearchCallSearchingEvent, response_function_call_arguments_delta_event.ResponseFunctionCallArgumentsDeltaEvent, response_function_call_arguments_done_event.ResponseFunctionCallArgumentsDoneEvent, response_in_progress_event.ResponseInProgressEvent, response_failed_event.ResponseFailedEvent, response_incomplete_event.ResponseIncompleteEvent, response_output_item_added_event.ResponseOutputItemAddedEvent, response_output_item_done_event.ResponseOutputItemDoneEvent, response_reasoning_summary_part_added_event.ResponseReasoningSummaryPartAddedEvent, response_reasoning_summary_part_done_event.ResponseReasoningSummaryPartDoneEvent, response_reasoning_summary_text_delta_event.ResponseReasoningSummaryTextDeltaEvent, response_reasoning_summary_text_done_event.ResponseReasoningSummaryTextDoneEvent, response_reasoning_text_delta_event.ResponseReasoningTextDeltaEvent, response_reasoning_text_done_event.ResponseReasoningTextDoneEvent, response_refusal_delta_event.ResponseRefusalDeltaEvent, response_refusal_done_event.ResponseRefusalDoneEvent, response_text_delta_event.ResponseTextDeltaEvent, response_text_done_event.ResponseTextDoneEvent, response_web_search_call_completed_event.ResponseWebSearchCallCompletedEvent, response_web_search_call_in_progress_event.ResponseWebSearchCallInProgressEvent, response_web_search_call_searching_event.ResponseWebSearchCallSearchingEvent, response_image_gen_call_completed_event.ResponseImageGenCallCompletedEvent, response_image_gen_call_generating_event.ResponseImageGenCallGeneratingEvent, response_image_gen_call_in_progress_event.ResponseImageGenCallInProgressEvent, response_image_gen_call_partial_image_event.ResponseImageGenCallPartialImageEvent, response_mcp_call_arguments_delta_event.ResponseMcpCallArgumentsDeltaEvent, response_mcp_call_arguments_done_event.ResponseMcpCallArgumentsDoneEvent, response_mcp_call_completed_event.ResponseMcpCallCompletedEvent, response_mcp_call_failed_event.ResponseMcpCallFailedEvent, response_mcp_call_in_progress_event.ResponseMcpCallInProgressEvent, response_mcp_list_tools_completed_event.ResponseMcpListToolsCompletedEvent, response_mcp_list_tools_failed_event.ResponseMcpListToolsFailedEvent, response_mcp_list_tools_in_progress_event.ResponseMcpListToolsInProgressEvent, response_output_text_annotation_added_event.ResponseOutputTextAnnotationAddedEvent, response_queued_event.ResponseQueuedEvent, response_custom_tool_call_input_delta_event.ResponseCustomToolCallInputDeltaEvent, response_custom_tool_call_input_done_event.ResponseCustomToolCallInputDoneEvent], PropertyInfo(alias='None', format=None, format_template='None', discriminator='type')]]

Parameters

Parameter	Type	Default	Description
model	str	required	Model identifier. Recommended: Use with separate provider parameter (e.g., model=‘gpt-4o’, provider=‘openai’). Alternative: Combined format ‘provider:model’ (e.g., ‘openai:gpt-4o’). Legacy format ‘provider/model’ is also supported but deprecated.
input_data	str | list[EasyInputMessageParam | Message | ResponseOutputMessageParam | ResponseFileSearchToolCallParam | ResponseComputerToolCallParam | ComputerCallOutput | ResponseFunctionWebSearchParam | ResponseFunctionToolCallParam | FunctionCallOutput | ToolSearchCall | ResponseToolSearchOutputItemParamParam | ResponseReasoningItemParam | ResponseCompactionItemParamParam | ImageGenerationCall | ResponseCodeInterpreterToolCallParam | LocalShellCall | LocalShellCallOutput | ShellCall | ShellCallOutput | ApplyPatchCall | ApplyPatchCallOutput | McpListTools | McpApprovalRequest | McpApprovalResponse | McpCall | ResponseCustomToolCallOutputParam | ResponseCustomToolCallParam | ItemReference]	required	The input payload accepted by provider’s Responses API. For OpenAI-compatible providers, this is typically a list mixing text, images, and tool instructions, or a dict per OpenAI spec.
provider	str | LLMProvider | None	None	Recommended: Provider name to use for the request (e.g., ‘openai’, ‘mistral’). When provided, the model parameter should contain only the model name.
tools	list[dict[str, Any] | Callable[..., Any]] | None	None	Optional tools for tool calling (Python callables or OpenAI tool dicts)
tool_choice	str | dict[str, Any] | None	None	Controls which tools the model can call
max_output_tokens	int | None	None	Maximum number of output tokens to generate
temperature	float | None	None	Controls randomness in the response (0.0 to 2.0)
top_p	float | None	None	Controls diversity via nucleus sampling (0.0 to 1.0)
stream	bool | None	None	Whether to stream response events
api_key	str | None	None	API key for the provider
api_base	str | None	None	Base URL for the provider API
instructions	str | None	None	A system (or developer) message inserted into the model’s context.
max_tool_calls	int | None	None	The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored.
parallel_tool_calls	int | None	None	Whether to allow the model to run tool calls in parallel.
reasoning	Any | None	None	Configuration options for reasoning models.
text	Any | None	None	Configuration options for a text response from the model. Can be plain text or structured JSON data.
presence_penalty	float | None	None	Penalizes new tokens based on whether they appear in the text so far.
frequency_penalty	float | None	None	Penalizes new tokens based on their frequency in the text so far.
truncation	str | None	None	Controls how the service truncates input when it exceeds the model context window.
store	bool | None	None	Whether to store the response so it can be retrieved later.
service_tier	str | None	None	The service tier to use for this request.
user	str | None	None	A unique identifier representing your end user.
metadata	dict[str, str] | None	None	Key-value pairs for custom metadata (up to 16 pairs).
previous_response_id	str | None	None	The ID of the response to use as the prior turn for this request.
include	list[str] | None	None	Items to include in the response (e.g., ‘reasoning.encrypted_content’).
background	bool | None	None	Whether to run the request in the background and return immediately.
safety_identifier	str | None	None	A stable identifier used for safety monitoring and abuse detection.
prompt_cache_key	str | None	None	A key to use when reading from or writing to the prompt cache.
prompt_cache_retention	str | None	None	How long to retain a prompt cache entry created by this request.
conversation	str | dict[str, Any] | None	None	The conversation to associate this response with (ID string or ConversationParam object).
client_args	dict[str, Any] | None	None	Additional provider-specific arguments that will be passed to the provider’s client instantiation.
**kwargs	Any	required	Additional provider-specific arguments that will be passed to the provider’s API call.

Usage

Basic response

from any_llm import responses

result = responses(
    model="gpt-4.1-mini",
    provider="openai",
    input_data="What is the capital of France?",
)
print(result.output_text)

With instructions

result = responses(
    model="gpt-4.1-mini",
    provider="openai",
    input_data="Translate to French: Hello, how are you?",
    instructions="You are a professional translator. Always respond with only the translation.",
)

Streaming

for event in responses(
    model="gpt-4.1-mini",
    provider="openai",
    input_data="Tell me a short story.",
    stream=True,
):
    print(event)

Multi-turn with previous_response_id

first = responses(
    model="gpt-4.1-mini",
    provider="openai",
    input_data="My name is Alice.",
    store=True,
)

second = responses(
    model="gpt-4.1-mini",
    provider="openai",
    input_data="What is my name?",
    previous_response_id=first.id,
)

Note

Not all providers support the Responses API. Check the providers page for support details, or query ProviderMetadata.responses programmatically.