Responses API

Respond(; model="gpt-5.6-sol", input, kwargs...)

Configuration struct for an OpenAI Responses API request.

Key Fields

• model::String: Model to use (default: "gpt-5.6-sol")
• input::Any: A String or Vector{InputMessage} — the prompt input
• instructions::String: System-level instructions
• tools::Vector: Available tools (FunctionTool, WebSearchTool, FileSearchTool)
• previous_response_id::String: Chain to a previous response for multi-turn
• reasoning::Reasoning: Reasoning config for O-series models
• text::TextConfig: Output format (text, json, json_schema)
• temperature::Float64: Sampling temperature (0.0–2.0), mutually exclusive with top_p
• top_p::Float64: Nucleus sampling (0.0–1.0), mutually exclusive with temperature
• max_output_tokens::Int64: Max tokens in the response
• stream::Bool: Enable streaming
• truncation::String: "auto" or "disabled"
• store::Bool: Whether to store the response for later retrieval
• metadata::AbstractDict: Arbitrary metadata to attach
• user::String: End-user identifier

Examples

# Simple text
Respond(input="Tell me a joke")

# With instructions
Respond(input="Translate to French: Hello", instructions="You are a translator")

# Multi-turn via chaining
Respond(input="Tell me more", previous_response_id="resp_abc123")

# With tools
Respond(
    input="What's the weather in NYC?",
    tools=ResponseTool[function_tool("get_weather", "Get weather", parameters=Dict("type"=>"object", "properties"=>Dict("location"=>Dict("type"=>"string"))))]
)

# Reasoning (O-series models)
Respond(input="Solve this math problem...", model="o3", reasoning=Reasoning(effort="high"))

ResponseObject

Parsed response from the Responses API.

Accessors

• output_text(r) — extract concatenated text output
• function_calls(r) — extract function call outputs
• r.id, r.status, r.model — basic metadata
• r.output — full output array (raw dicts)
• r.usage — token usage info
• r.raw — the complete raw JSON dict

ResponseSuccess <: LLMRequestResponse

Successful response from the Responses API. Access the parsed response via .response.

ResponseFailure <: LLMRequestResponse

HTTP-level failure from the Responses API. Contains the response body, status code, and optional request ID.

ResponseCallError <: LLMRequestResponse

Exception-level error during a Responses API call (network, parsing, etc.).

output_text(r::ResponseObject)::String
output_text(r::ResponseSuccess)::String

Extract the concatenated text output from a response.

Examples

result = respond("Hello!")
output_text(result)  # => "Hi there! How can I help?"

function_calls(r::ResponseObject)::Vector{Dict{String,Any}}
function_calls(r::ResponseSuccess)::Vector{Dict{String,Any}}

Extract function call outputs from a response.

Each dict contains: "id", "call_id", "name", "arguments" (JSON string), "status".

Examples

result = respond("What's the weather?", tools=[function_tool("get_weather", ...)])
for call in function_calls(result)
    name = call["name"]
    args = JSON.parse(call["arguments"])
    # dispatch to your function...
end

url_citations(r) -> Vector{Dict{String,Any}}

URL-citation annotations on outputtext parts (from websearch).

Raw web_search_call output items (request results via include).

Raw file_search_call output items.

image_generation_results(r) -> Vector{String}

Base64 image results from image_generation_call output items.

Raw code_interpreter_call output items.

Raw mcp_call output items.

Raw mcp_approval_request output items (feed back via mcp_approval_response).

reasoning_summaries(r) -> Vector{String}

Reasoning-summary text from each reasoning output item.

Raw reasoning output items.

refusals(r) -> Vector{String}

Refusal messages from any refusal content part of the output messages.

The response's lifecycle status string (e.g. completed, requires_action); failed/error for non-success results.

Why a response is incomplete (the API's incomplete_details object), or nothing.

The response's raw token-usage dict; see token_usage for the typed TokenUsage.

respond(r::Respond; config=nothing, callback=nothing)

Send a request to the OpenAI Responses API.

Returns ResponseSuccess, ResponseFailure, or ResponseCallError.

Per-call config::RequestConfig overrides timeouts and the retry budget (max_attempts); the process/scoped defaults apply otherwise.

For streaming, set stream=true and pass a callback:

callback(chunk::Union{String, ResponseObject}, close::Ref{Bool})

A user InterruptException during a stream is not swallowed — it rethrows inside the task and surfaces as a TaskFailedException at fetch.

Throws ArgumentError before any network I/O when r.service is an endpoint type that declares its capabilities and lists neither :responses (OpenAI wire) nor :agentic (Gemini Interactions).

Examples

r = Respond(input="Tell me a joke")
result = respond(r)
if result isa ResponseSuccess
    println(output_text(result))
end

respond(input; kwargs...)

Convenience method: create a Respond from input + keyword arguments and send it.

Examples

# Simple text
result = respond("Tell me a joke")

# With instructions and model
result = respond("Translate: Hello", instructions="You are a translator", model="gpt-5.6-sol")

# With tools
result = respond("Search for Julia news", tools=[web_search()])

# Multi-turn
r1 = respond("Tell me a joke")
r2 = respond("Tell me another", previous_response_id=r1.response.id)

# Streaming
respond("Tell me a story", stream=true) do chunk, close
    if chunk isa String
        print(chunk)  # partial text delta
    end
end

respond(callback::Function, input; kwargs...)

do-block form for streaming. Automatically sets stream=true.

Examples

respond("Tell me a story") do chunk, close
    if chunk isa String
        print(chunk)
    elseif chunk isa ResponseObject
        println("\nDone! Status: ", chunk.status)
    end
end

get_response(response_id::String; service=OPENAIServiceEndpoint)

Retrieve an existing response by its ID.

Examples

result = get_response("resp_abc123")
if result isa ResponseSuccess
    println(output_text(result))
end

delete_response(response_id::String; service=OPENAIServiceEndpoint)

Delete a stored response by its ID. Returns a Dict with "id", "object", "deleted" keys.

Examples

result = delete_response("resp_abc123")
result["deleted"]  # => true

list_input_items(response_id::String; limit=20, order="desc", after=nothing, service=OPENAIServiceEndpoint)

List input items for a stored response. Returns a Dict with "data", "first_id", "last_id", "has_more".

Examples

items = list_input_items("resp_abc123")
for item in items["data"]
    println(item["type"], ": ", item)
end

cancel_response(response_id::String; service=OPENAIServiceEndpoint)

Cancel an in-progress response by its ID. Returns ResponseSuccess on success.

Examples

# Start a background response, then cancel it
result = respond("Write a very long essay", background=true)
cancel_result = cancel_response(result.response.id)
if cancel_result isa ResponseSuccess
    println("Cancelled: ", cancel_result.response.status)
end

compact_response(; model, input, kwargs...)

Compact a conversation by running a compaction pass. Returns opaque, encrypted items that can be passed as input to subsequent requests, reducing token usage in long conversations.

Fields

• model::String: Model to use for compaction
• input::Any: The conversation items to compact (typically the full conversation history)

Returns a Dict with "id", "object", "output", and "usage" keys.

Examples

compacted = compact_response(model="gpt-5.6-sol", input=[
    InputMessage(role="user", content="Hello"),
    Dict("type" => "message", "role" => "assistant", "status" => "completed",
         "content" => [Dict("type" => "output_text", "text" => "Hi there!")])
])
# Use compacted["output"] as input to the next request

count_input_tokens(; model, input, kwargs...)

Count the number of input tokens a request would use without actually generating a response. Useful for estimating costs or checking whether input fits within the context window.

Returns a Dict with "object" ("response.input_tokens") and "input_tokens" keys.

Examples

result = count_input_tokens(model="gpt-5.6-sol", input="Tell me a joke")
println("Input tokens: ", result["input_tokens"])

InputMessage(; role, content)

A structured input message for the Responses API.

Fields

• role::String: "user", "assistant", "system", or "developer"
• content::Any: String or a vector of content parts (see input_text, input_image, input_file)

Examples

InputMessage(role="user", content="What is 2+2?")
InputMessage(role="user", content=[input_text("Describe this:"), input_image("https://example.com/img.png")])

input_text(text::String)

Create an input_text content part for multimodal input messages.

input_image(url=nothing; detail=nothing, file_id=nothing)

Create an input_image content part. Provide either an image url or a file_id. detail can be "auto", "low", or "high".

input_file(; url=nothing, id=nothing, file_data=nothing, filename=nothing)

Create an input_file content part. Provide a url, a file id, or inline file_data (base64). filename is recommended when passing file_data.

ResponseTool

Abstract supertype for Responses API tools. Subtypes:

• FunctionTool
• WebSearchTool
• FileSearchTool

FunctionTool(; name, description=nothing, parameters=nothing, strict=nothing)

A function tool for the Responses API.

Examples

FunctionTool(
    name="get_weather",
    description="Get current weather for a location",
    parameters=Dict(
        "type" => "object",
        "properties" => Dict(
            "location" => Dict("type" => "string", "description" => "City name")
        ),
        "required" => ["location"]
    )
)

WebSearchTool(; type="web_search", search_context_size="medium", user_location=nothing, filters=nothing)

A web search tool for the Responses API. Allows the model to search the web.

• type: "web_search" (GA, default) or the legacy "web_search_preview"
• search_context_size: "low", "medium", or "high"
• user_location: Dict with keys like "country", "city", "region", "timezone"
• filters: Dict with "allowed_domains" / "blocked_domains" (GA only)

Fetch sources/results back via include=["web_search_call.results", "web_search_call.action.sources"].

FileSearchTool(; vector_store_ids, max_num_results=nothing, ranking_options=nothing, filters=nothing)

A file search tool for the Responses API. Searches over uploaded vector stores.

MCPTool(; server_label, server_url=nothing, connector_id=nothing, authorization=nothing,
        server_description=nothing, require_approval="never", allowed_tools=nothing,
        headers=nothing, tunnel_id=nothing)

A Model Context Protocol (MCP) tool for the Responses API. Connect the model to a remote MCP server (server_url), an OpenAI connector (connector_id, e.g. "connector_googledrive", "connector_gmail", "connector_dropbox"), or a Secure MCP Tunnel (tunnel_id). Use authorization for an OAuth access token. require_approval/allowed_tools accept the string or object forms.

ComputerUseTool(; display_width=1024, display_height=768, environment=nothing)

A computer use tool for the Responses API. Allows the model to interact with a virtual display via screenshots, mouse, and keyboard.

ImageGenerationTool(; background=nothing, output_format=nothing, output_compression=nothing, quality=nothing, size=nothing)

An image generation tool for the Responses API. Allows the model to generate images inline during a response.

CodeInterpreterTool(; container=nothing, file_ids=nothing)

A code interpreter tool for the Responses API. Allows the model to execute code in a sandboxed environment.

ComputerTool(; environment=nothing)

GA computer-use tool (type:"computer") for newer models. Unlike ComputerUseTool (computer_use_preview) it carries no display_width/display_height.

CustomTool(; name, description=nothing, format=nothing)

Custom tool (type:"custom") with free-form text input, or a grammar-constrained input via format = Dict("type"=>"grammar", "syntax"=>"lark"|"regex", "definition"=>...).

LocalShellTool()

Local shell tool (type:"local_shell"): the model emits shell commands you run on your own runtime (codex-style models).

ShellTool(; environment=nothing)

Hosted shell tool (type:"shell").

ApplyPatchTool()

Structured file-edit tool (type:"apply_patch").

function_tool(name, description=nothing; parameters=nothing, strict=nothing)

Shorthand constructor for FunctionTool.

function_tool(d::AbstractDict)

Construct a FunctionTool from a dict. Accepts both the bare format {"name": ...} and the wrapped format {"type": "function", "function": {"name": ...}}.

web_search(; context_size="medium", location=nothing)

Shorthand constructor for WebSearchTool.

file_search(store_ids::Vector{String}; max_results=nothing, ranking=nothing, filters=nothing)

Shorthand constructor for FileSearchTool.

mcp_tool(label, url; require_approval="never", allowed_tools=nothing, headers=nothing)

Shorthand constructor for MCPTool.

computer_use(; display_width=1024, display_height=768, environment=nothing)

Shorthand constructor for ComputerUseTool.

image_generation_tool(; kwargs...)

Shorthand constructor for ImageGenerationTool.

code_interpreter(; container=nothing, file_ids=nothing)

Shorthand constructor for CodeInterpreterTool.

Construct a ComputerTool (GA computer tool); for the preview variant with display dimensions use computer_use.

Construct a CustomTool (custom tool); format optionally constrains input to a grammar.

Construct a LocalShellTool (local_shell): the model emits commands you run on your own runtime.

Construct a ShellTool (hosted shell tool).

Construct an ApplyPatchTool (structured apply_patch file-edit tool).

mcp_approval_response(approval_request_id, approve; reason=nothing)

Build an mcp_approval_response input item to approve/deny a pending MCP tool call. Pass it back as an element of the next request's input.

tool_choice_function(name)

Force the model to call a specific function tool: {type:"function", name}.

tool_choice_hosted(type)

Force a specific hosted tool, e.g. tool_choice_hosted("file_search"), "image_generation", "code_interpreter". Note: the hosted web-search selector is "web_search_preview" (not "web_search").

tool_choice_allowed(mode, tools)

Constrain the model to a subset of tools: {type:"allowed_tools", mode, tools}. mode is "auto" or "required"; tools is a vector of tool-reference dicts.

tool_choice_mcp(server_label; name=nothing)

Force a specific MCP server (optionally a specific tool): {type:"mcp", server_label, name?}.

tool_choice_custom(name)

Force a specific custom tool: {type:"custom", name}.

tool_result(call_id, name, output) -> Dict

Neutral multi-turn tool-result input item for the agentic verb. Feed a function's output back via respond(Respond(; previous_response_id=id, input=[tool_result(...)])) — respond takes the input positionally or as a Respond, so a keyword-only call is a MethodError — or through tool_loop. Wire-neutral: OpenAI serializes it as function_call_output (ignoring name); the Gemini encoder translates it to function_result (which requires name). output is the function's return value as a string.

gemini_google_search() -> Dict

Hosted Google Search tool for the Gemini Interactions API. Pass in respond(...; tools=[gemini_google_search()], service=GEMINIServiceEndpoint).

gemini_code_execution() -> Dict

Hosted code-execution tool for the Gemini Interactions API. Pass in respond(...; tools=[gemini_code_execution()], service=GEMINIServiceEndpoint).

gemini_url_context() -> Dict

Hosted URL-context tool for the Gemini Interactions API. Pass in respond(...; tools=[gemini_url_context()], service=GEMINIServiceEndpoint).

TextConfig(; format=TextFormatSpec())

Wrapper for the text field in the Responses API request body.

TextFormatSpec(; type="text", name=nothing, description=nothing, schema=nothing, strict=nothing)

Output text format specification.

• type: "text" (default), "json_object", or "json_schema"
• For "json_schema": provide name, description, schema, and optionally strict

text_format(; kwargs...)

Create a TextConfig with the given format options.

json_schema_format(name, description, schema; strict=nothing)

Create a JSON Schema output format for structured output.

json_schema_format(d::AbstractDict)

Construct a JSON Schema TextConfig from a dict with keys "name", "description", and "schema".

json_object_format()

Create a JSON object output format (unstructured).

Reasoning(; effort=nothing, summary=nothing, generate_summary=nothing, context=nothing, mode=nothing)

Reasoning configuration for OpenAI and Gemini Interactions models.

• effort: model-dependent; OpenAI also supports "max" and "ultra" on selected models. Gemini 3.8 supports "low", "medium", and "high".
• summary: "auto", "concise", or "detailed" — request a reasoning summary in the output.
• generate_summary: deprecated alias serialized as summary; prefer summary. Gemini Interactions accepts summary="auto" for thought summaries.
• context: OpenAI persisted reasoning: "auto", "current_turn", or "all_turns".
• mode: OpenAI "standard" or "pro" execution; pro can consume more tokens.

PromptCacheOptions(; mode=nothing, ttl=nothing)

OpenAI prompt-cache controls for GPT-5.6 and later. mode is "implicit" or "explicit"; the supported ttl is "30m". Explicit mode caches only prefixes marked with prompt_cache_breakpoint in input content blocks.