View on GitHub

Lightspeed Core Stack

Lightspeed Core Stack

LCORE OpenResponses API Specification

This document describes the LCORE implementation of the OpenResponses API, exposed via the POST /v1/responses endpoint. This endpoint follows the OpenResponses specification and is built on top of the Llama Stack Responses API. In addition, it introduces LCORE-specific extensions to preserve feature parity and defines explicit field mappings to reproduce the functionality of existing /v1/query and /v1/streaming_query endpoints.

Table of Contents

Introduction

The LCORE OpenResponses API provides a standards-aligned interface for AI response generation while preserving feature compatibility with existing LCORE workflows. In particular, the endpoint enriches requests and responses with LCORE-specific attributes, adjusts the semantics of some fields for compatibility, and enriches content of some streaming events.

The endpoint is designed to provide feature parity with existing query endpoints while offering a more direct interface to the underlying Responses API.

Endpoint Overview

Endpoint: POST /v1/responses

Request format: JSON — send the request payload following the Request Specification as a single JSON object in the request body.

Content-Type: application/json

Response format:

Request Specification

Inherited LLS OpenAPI Attributes

The following request attributes are supported as defined by the underlying Llama Stack Responses API and retain their original OpenResponses semantics unless otherwise stated:

Field Type Description Required
input string or array[object] Query text or structured input items Yes
model string Model ID (provider/model). Auto-selected if omitted No
conversation string Conversation ID (OpenAI or LCORE format). Mutually exclusive with previous_response_id No
include array[string] Extra output item types to include No
instructions string System prompt No
max_infer_iters integer Maximum of inference iterations No
max_output_tokens integer Maximum of output tokens No
max_tool_calls integer Maximum of tool calls per response No
metadata dictionary Custom metadata (tracking/logging) No
parallel_tool_calls boolean Allow parallel tool calls No
previous_response_id string Previous response ID for context. Mutually exclusive with conversation No
prompt object Prompt substitution template No
reasoning object Reasoning configuration (effort level) used for the response No
safety_identifier string Safety/guardrail identifier applied to the request No
store boolean Store in conversation history (default: true) No
stream boolean Stream response (default: false) No
temperature float Sampling temperature (0.0–2.0) No
text object Output format specification (JSON schema, JSON object, or text) No
tool_choice string or object Tool selection strategy (auto, required, none, or specific rules). Default: auto No
tools array[object] Tools available for request (file search, web search, functions, MCP). Default: all No

Note: reasoning and max_output_tokens are accepted for OpenResponses compatibility but are not yet supported in LCORE: the endpoint clears them before processing and logs a warning.

LCORE-Specific Extensions

The following fields are LCORE-specific request extensions and are not part of the standard LLS OpenAPI specification:

Field Type Description Required
generate_topic_summary boolean Generate topic summary for new conversations. Default: true No
shield_ids array[string] LCORE-configured shield name values to apply. If omitted, all configured shields are used. Not Llama Stack Safety resource names. No
solr object Optional mode and filters. Legacy top-level filter-only objects are still accepted. No

Field Mappings

The following table maps LCORE query request fields to the OpenResponses request fields used by POST /v1/responses.

Original LCORE Field LCORE OpenAPI Field Notes
query input The attribute allows to pass string-like input and also structured input of list of input items
conversation_id conversation Supports OpenAI conv_* format or LCORE hex UUID
provider + model model Concatenated as provider/model
system_prompt instructions Same meaning. Only change in attribute’s name
attachments input items Attachments can be passed as input messages with content of type input_file
no_tools tool_choice no_tools=true mapped to tool_choice="none"
vector_store_ids tools + tool_choice Restrict via file_search.vector_store_ids in LCORE format; translated to Llama Stack internally.
generate_topic_summary N/A Exposed directly (LCORE-specific)
shield_ids N/A Exposed directly (LCORE-specific)
solr N/A Exposed directly (LCORE-specific)

Note: The media_type attribute is not present in the LCORE specification, as downstream logic determines which format to process (structured output or textual output_text response attributes).

Structured request attributes: variants and usage

This section examines some of the more complex request attributes with explanation and example usage.

input

Required. Either a string or a list of input items. Each item is one of:

All input item objects have a common type discriminator that determines the subsequent structure. See Available OpenResponses items for detailed descriptions and examples of each item type.

include

Optional. List of output item types to include in the response that are excluded by default.

Allowed values (literal strings): web_search_call.action.sources, code_interpreter_call.outputs, computer_call_output.output.image_url, file_search_call.results, message.input_image.image_url, message.output_text.logprobs.

Examples:

{ "include": ["message.output_text.logprobs"] }

{ "include": ["message.output_text.logprobs", "file_search_call.results"] }

prompt

Optional. References a prompt template with variables for dynamic substitution.

The template can contain placeholders (variables) that are replaced at request time with the values you send in variables. Typical use cases: reusable system prompts (e.g. “You are an expert on ”), report generators that plug in a title and attachments, or standardized workflows that accept a few inputs.

When provided, the object must have an id (required); variables and version are optional.

Examples:

Template with multiple variable types (text, image, file):

{
  "prompt": {
    "id": "report_template",
    "variables": {
      "title": { "type": "input_text", "text": "Weekly summary" },
      "chart": { "type": "input_image", "image_url": "https://example.com/chart.png", "detail": "high" },
      "data": { "type": "input_file", "file_id": "file_xyz", "filename": "data.csv" }
    },
    "version": "2.0"
  }
}

Here the template report_template (version 2.0) might define placeholders such as ,, and ``; the backend substitutes them with the provided text, image, and file respectively.

reasoning

Optional. Reasoning effort configuration that controls how much “thinking” the model does before producing its answer. Supported on models that expose reasoning (e.g. o1/o3-style). Lower effort favors speed and fewer tokens; higher effort favors more thorough reasoning.

When provided, the object has a single key:

effort: One of "none", "minimal", "low", "medium", "high", or "xhigh". None leaves the default behavior to the backend.

Examples:

{ "reasoning": { "effort": "low" } }

{ "reasoning": { "effort": "high" } }

{ "reasoning": { "effort": "medium" } }

text

Optional. Text response configuration that tells the model how to format its main text output.

The text object constrains the model’s reply so it fits your downstream use. Without it, the backend uses a default (typically plain text). With it, you can request plain text (type: "text"), free-form JSON (type: "json_object"), or JSON that conforms to a schema (type: "json_schema"). For json_schema, you supply a JSON Schema; the model then fills in the structure (e.g. a form, a list of items, or a single field like answer).

When provided, the object has a single optional key format which has the following attributes:

Examples:

Plain text (explicit):

{ "text": { "format": { "type": "text" } } }

Free-form JSON (any valid JSON object):

{ "text": { "format": { "type": "json_object" } } }

JSON schema with optional name, description, and strict mode:

{
  "text": {
    "format": {
      "type": "json_schema",
      "name": "survey_response",
      "description": "User survey answers",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
          "comment": { "type": "string" }
        },
        "required": ["rating"]
      }
    }
  }
}

tool_choice

Optional. Tool selection strategy that controls whether and how the model uses tools. Does not affect inline RAG selection.

What it does: When tools are supplied by tools attribute, tool_choice decides if the model may call them, must call at least one, or must not use any. You can pass a simple mode string or a specific tool-config object to force a particular tool (e.g. always use file search or a given function). Omitted or null behaves like "auto". Typical use: disable tools for a plain-Q&A turn ("none"), force RAG-only (file_search), or constrain to a subset of tools (allowed_tools).

Simple modes (string):

Specific tool objects (object with type):

Examples:

Simple modes (string): use one of "auto", "required", or "none".

{ "tool_choice": "auto" }
{ "tool_choice": "required" }
{ "tool_choice": "none" }

Restrict tool usage to a specific subset using allowed_tools. You can control behavior with the mode field ("auto" or "required") and explicitly list permitted tools in the tools array.

The tools array acts as a key-value filter: each object specifies matching criteria (such as type, server_label, or name), and only tools that satisfy all provided attributes are allowed.

The example below limits tool usage to:

If the name field is omitted for an MCP tool, the filter applies to all tools available on the specified server.

{
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "required",
    "tools": [
      { "type": "file_search"},
      { "type": "mcp", "server_label": "server_1", "name": "tool_1" },
      { "type": "mcp", "server_label": "server_1", "name": "tool_2" }
    ]
  }
}

Force a single tool type: file_search, web_search, function, mcp, or custom.

{ "tool_choice": { "type": "file_search" } }
{ "tool_choice": { "type": "web_search" } }
{ "tool_choice": { "type": "function", "name": "get_weather" } }
{ "tool_choice": { "type": "mcp", "server_label": "my_server", "name": "fetch_data" } }
{ "tool_choice": { "type": "custom", "name": "my_tool" } }

tools

Optional. List of tools the model is allowed to use for this request (file search, web search, function, MCP).

Each item in tools declares one capability: search a set of vector stores (file_search), use web search (web_search), call a function (function), or use tools from an MCP server (mcp). The model may then call these tools during the response (subject to tool_choice). If tools is null or omitted, LCORE automatically uses all tools from the LCORE configuration. Send tools only when you want to restrict the request to a specific subset of tools or vector stores (e.g. a single RAG index or only web search).

Tool types (each object has a required type):

Examples:

Omitted or null (use all tools configured in LCORE):

{ "tools": null }

Restrict to file search on two vector stores and web search:

{
  "tools": [
    { "type": "file_search", "vector_store_ids": ["vs_1", "vs_2"] },
    { "type": "web_search" }
  ]
}

All tool types in one request (file_search with optional params, web_search with context size, function with schema, mcp):

{
  "tools": [
    { "type": "file_search", "vector_store_ids": ["vs_docs"], "max_num_results": 5 },
    { "type": "web_search", "search_context_size": "high" },
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get weather for a city",
      "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
    },
    { "type": "mcp", "server_label": "my_mcp", "server_url": "https://mcp.example.com" }
  ]
}

Response Specification

Inherited LLS OpenAPI Fields

The following response attributes are inherited directly from the LLS OpenAPI specification:

Field Type Description
created_at integer Creation time (Unix)
completed_at integer Completion time (Unix), if set
error object Error details if failed or incompleted
id string Unique response ID or moderation ID
model string Model used for generation. If the client specified model in the request, it is echoed unchanged; if the server selected the model, the provider routing prefix is stripped (see Model Selection)
object string Always "response"
output array[object] Structured output (messages, tool calls, etc.)
parallel_tool_calls boolean Parallel tool calls allowed
previous_response_id string Previous response ID (multi-turn)
prompt object The input prompt object that was sent to the model
status string Status (e.g. completed, blocked, in_progress)
temperature float Temperature parameter used for generation
text object Text response configuration object used
top_p float Top-p sampling used
tools array[object] Internally resolved tools available during generation
tool_choice string or object Internally resolved tool selection used
truncation string Truncation strategy applied ("auto" or "disabled")
usage object Token usage (input_tokens, output_tokens, total_tokens)
instructions string System instructions used
max_tool_calls integer Max tool calls allowed
reasoning object Reasoning configuration applied
max_output_tokens integer Maximum output tokens allowed, if set
safety_identifier string Safety model or identifier used, if set
metadata dictionary Custom metadata specified in request
store boolean Whether the response was stored
output_text string Aggregated text from output items

Structured response output: object types and examples

The output array contains structured items. Each item has a type. Each list item is one of:

Note: No mcp_approval_response nor function_call_output here as they can serve only as input items.

All response item objects have a common type discriminator that determines subsequent structure. See Available OpenResponses items for detailed descriptions and examples of each item type.

LCORE-Specific Extensions

The following fields are LCORE-specific and enrich the standard LLS OpenAPI specification to achieve feature parity:

Field Type Description
conversation string Conversation ID (exposed as conversation, linked internally to request conversation attribute)
available_quotas object Available quotas as measured by all configured quota limiters (LCORE-specific)

Field Mappings

The following mappings are applied when converting from LLS OpenAPI format to LCORE format:

Original LCORE Field LCORE OpenAPI Field Notes
conversation_id conversation Exposed as conversation in the LLS response; linked internally to request conversation attribute
response output and output_text Mapped to both output (structured) or output_text (string)
input_tokens usage.input_tokens Token usage fields mapped to usage object
output_tokens usage.output_tokens Token usage fields mapped to usage object
tool_calls output items Tool activity represented via dedicated output items
tool_results output items Tool results represented via dedicated output items

Deprecated Fields: The following fields are not exposed in the LCORE OpenResponses specification:

Streaming Support

The LCORE OpenResponses API supports streaming responses when the stream parameter is set to true. When streaming is enabled:

SSE Format: Each streaming event follows the Server-Sent Events (SSE) format:

Note: Streaming support maintains feature parity with the existing /v1/streaming_query endpoint, with the addition of LCORE-specific fields (conversation and available_quotas) in streaming events.

Metadata Extraction: Response metadata (referenced documents, rag_chunks, tool calls, tool results) is consistently extracted from the final response object after streaming completes internally, ensuring identical persistence models as in query endpoints.

Behavioral Differences

The /v1/responses endpoint follows the OpenResponses structure but also incorporates LCORE-specific features to maintain full feature compatibility with query endpoints.

Several behavioral differences and implementation details should be noted:

Conversation Handling

The conversation field in responses is a LCORE-managed extension. While not natively defined by the Llama Stack specification, it is internally resolved and always present in the response to preserve LCORE conversation-based model.

The endpoint accepts two conversation ID formats:

Both formats are automatically normalized internally before being forwarded to the underlying API.

Model Selection

In OpenResponses the model field is required; in LCORE it is optional. If you omit model from the request, one is chosen for you in this order:

  1. Conversation — For an existing conversation, the same model used last in that conversation is reused if still available.
  2. Default model — If a default model is configured, that model is used.
  3. First available — Otherwise, the first available LLM model is used.
  4. If no model can be selected (e.g. no default and no LLM models), the request fails with 404 (model not found).

Model in response: If the client specified a model in the request, it is echoed back unchanged in the response. If the server selected the model (because model was omitted from the request), the provider routing prefix is stripped and only the base model name is returned (e.g. google-vertex/publishers/google/models/gemini-2.5-flash → gemini-2.5-flash). This prevents leaking server infrastructure details and follows the same pattern as System Prompt Resolution.

Output Representation

Responses expose both:

Fields such as media_type, tool_calls, tool_results, rag_chunks, and referenced_documents are not exposed directly. Instead, tool activity and retrieval results are represented as structured items within the output array.

Tool Configuration Differences

Vector store IDs are configured within the tools as file_search tools rather than through separate parameters. MCP tools are configurable under mcp tool type. By default all tools that are configured in LCORE are used to support the response. The set of available tools can be maintained per-request by tool_choice or tools attributes.

Vector store IDs: Accepts LCORE format in requests and also outputs it in responses; LCORE translates to/from Llama Stack format internally.

The response includes tools and tool_choice fields that reflect the internally resolved configuration. More specifically, the final set of tools and selection constraints after internal resolution and filtering.

tool_choice only constrains how the model may use tools (including RAG via the file_search tool). It does not change inline RAG: vector store IDs you list under tools for file search are still used to build inline RAG context even if you set tool_choice to none or use an allowlist that omits file_search.

Server-Tool Merging

By default, the tools field acts as a per-request override: when provided, only the specified tools are available for that request, and server-configured tools (RAG, MCP) are not included. The server-tool merging feature allows clients to provide their own tools while also retaining all server-configured tools.

This is useful for hybrid MCP architectures where a client (e.g. Goose) runs its own local MCP servers or function tools but also needs access to server-configured RAG and MCP tools.

Enabling Server-Tool Merging

Set the X-LCS-Merge-Server-Tools: true request header to enable merging:

curl -X POST http://localhost:8090/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-LCS-Merge-Server-Tools: true" \
  -d '{
    "input": "Find relevant docs and run my analysis tool",
    "tools": [
      { "type": "mcp", "server_label": "my-local-tool", "server_url": "http://localhost:3000/sse" }
    ]
  }'

When this header is set:

  1. Client-provided tools are resolved first (BYOK translation, MCP header injection).
  2. Server-configured tools (RAG file_search, server MCP tools) are loaded from the LCORE configuration.
  3. The two sets are merged into a single tool list, with client tools appearing first.

When the header is absent or false, the tools field behaves as a standard per-request override: only the explicitly listed tools are used.

Conflict Detection

Merging rejects conflicting tools with an HTTP 409 Conflict error:

Example 409 response:

{
  "status_code": 409,
  "detail": {
    "response": "Tool conflict detected",
    "cause": "Client MCP tool 'my-server' conflicts with a server-configured MCP tool with the same server_label."
  }
}

Stream Filtering

When server-tool merging is active, the response stream and output include items from both client and server tools. To keep streams clean for clients that manage their own tool execution, LCORE automatically distinguishes between server-deployed and client-provided tool output:

In streaming mode, server-deployed MCP events (e.g. mcp_call, mcp_list_tools) are filtered from the SSE stream so clients only see standard output types (message, function_call, etc.) for their own tools.

LCORE-Specific Extensions

The API introduces extensions that are not part of the OpenResponses specification:

System Prompt Resolution

The instructions field on the /v1/responses endpoint follows the same server-side system prompt resolution logic used by /v1/query. When the server processes a request, the instructions value is resolved using the following precedence (highest to lowest):

  1. Client-provided instructions — If the request includes a non-null instructions value and per-request customization is allowed, it is used as-is.
  2. Custom profile default prompt — If a custom profile is configured and defines a "default" prompt, that prompt is used.
  3. Configured system prompt — If customization.system_prompt is set in the server configuration, it is used.
  4. Built-in default — The hardcoded default system prompt ("You are a helpful assistant") is used as a last resort.

If the server configuration sets disable_query_system_prompt to true, any request that includes a non-null instructions value is rejected with a 422 Unprocessable Entity error. The error message references the instructions field specifically.

If the server substituted the system prompt, the response sets instructions to the placeholder <server prompt applied> instead of echoing the actual prompt. If the client provided their own instructions, they are echoed back unchanged. Server-deployed MCP tool definitions are also filtered from the response tools array; client-provided tools are preserved.

Streaming Differences

Streaming responses use Server-Sent Events (SSE) and are enriched with LCORE-specific metadata:

Implicit Conversation Management

This implementation introduces implicit conversation management, ensuring that every response is associated with a conversation and can be inspected through the Conversations API.

Users can provide context to the LLM using one of the following mutually exclusive strategies:

In LCORE, a conversation is modeled as a linear chain of user turns (request + response), where every turn belongs to exactly one conversation. Supporting previous_response_id as a context mechanism introduces branching semantics, which would break this linear structure if handled naively. To preserve a consistent conversation model, implicit conversation management applies the following rules:

Moderation responses (requests that fail shield moderation) follow the same conversation rules. However, only valid (successful) responses can be referenced via previous_response_id; moderation responses cannot be used as context for follow-up requests.

Blocked turns still appear in conversation history via the Conversations API, but they do not produce a referenceable response for continuation or forking. They are also excluded when determining the latest response in a conversation.

Examples

Basic Request (Non-Streaming)

curl -X POST http://localhost:8090/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "input": "What is Kubernetes?",
    "model": "openai/gpt-4-turbo",
    "store": true,
    "stream": false
  }'

Response:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1704067200,
  "completed_at": 1704067250,
  "model": "openai/gpt-4-turbo",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Kubernetes is an open-source container orchestration system..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50,
    "total_tokens": 150
  },
  "conversation": "conv_0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e",
  "available_quotas": {
    "daily": 1000,
    "monthly": 50000
  },
  "output_text": "Kubernetes is an open-source container orchestration system..."
}

Request with Conversation Continuation

curl -X POST http://localhost:8090/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "input": "Tell me more about it",
    "model": "openai/gpt-4-turbo",
    "conversation": "0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e",
    "store": true,
    "stream": false
  }'

Request with restricted Tools (RAG)

curl -X POST http://localhost:8090/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "input": "How do I deploy an application?",
    "model": "openai/gpt-4-turbo",
    "tools": [
      {
        "type": "file_search",
        "vector_store_ids": ["vs_abc123", "vs_def456"]
      }
    ],
    "store": true,
    "stream": false
  }'

Request with LCORE Extensions

curl -X POST http://localhost:8090/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "input": "What is machine learning?",
    "model": "openai/gpt-4-turbo",
    "generate_topic_summary": true,
    "store": true,
    "stream": false
  }'

Streaming Request

curl -X POST http://localhost:8090/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "input": "Explain Kubernetes architecture",
    "model": "openai/gpt-4-turbo",
    "stream": true,
    "store": true
  }'

Streaming Response (SSE format):

event: response.created
data: {"type":"response.created","response":{"id":"resp_abc123","conversation":"conv_0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e"}}

event: response.output_text.delta
data: {"delta":"Kubernetes"}

event: response.output_text.delta
data: {"delta":" is"}

event: response.output_text.delta
data: {"delta":" an"}

...

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_abc123","conversation":"conv_0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e","usage":{"input_tokens":100,"output_tokens":50,"total_tokens":150},"available_quotas":{"daily":1000,"monthly":50000}}}

data: [DONE]

Error Handling

The endpoint returns standard HTTP status codes and error responses:

Status Code Description Example
200 Success Valid request processed successfully
401 Unauthorized Missing or invalid credentials
403 Forbidden Insufficient permissions or model override not allowed
404 Not Found Conversation, model, or provider not found
413 Payload Too Large Prompt exceeded model’s context window size
422 Unprocessable Entity Request validation failed
429 Too Many Requests Token quota exceeded
500 Internal Server Error Configuration not loaded or other server errors
503 Service Unavailable Unable to connect to Llama Stack backend

Available OpenResponses items

This section lists all available OpenResponses item types. All items have common attribute type that can be used to distinguish between them and infer their subsequent structure.

message

One turn with role and content (string or list of content parts).

Message with simple string content:

{ "input": [{ "type": "message", "role": "user", "content": "Hello" }] }

Message with complex input content (text/image/file).

{
  "input": [{
    "type": "message",
    "role": "user",
    "content": [
      { "type": "input_text", "text": "Summarize this" },
      { "type": "input_image", "image_url": "https://example.com/img.png", "detail": "auto" },
      { "type": "input_file", "file_id": "file_abc", "filename": "doc.pdf" }
    ]
  }]
}

Message with complex output content (text/refusal).

{
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "output_text", "text": "Here is a brief overview." },
    { "type": "refusal", "refusal": "I can't provide details on that part." }
  ]
}

web_search_call

Completed web search (multi-turn).

{ "input": [{ "type": "web_search_call", "id": "ws_1", "status": "completed" }] }

file_search_call

Result of a file (vector) search tool call from a previous turn. Include this in the input when continuing a multi-turn conversation so the model sees the search queries, status, and optional result snippets that were returned.

{
  "input": [{
    "type": "file_search_call",
    "id": "fs_1",
    "queries": ["error patterns"],
    "status": "completed",
    "results": [{ "file_id": "f_1", "filename": "app.log", "text": "Error at 42", "score": 0.95, "attributes": {} }]
  }]
}

function_call

Function tool call from a previous turn. Include this in the input when continuing a multi-turn conversation so the model sees the function name, call ID, and arguments that were invoked.

{ "input": [{ "type": "function_call", "call_id": "fc_1", "name": "get_weather", "arguments": "{\"city\": \"Boston\"}" }] }

function_call_output

Output of a function call passed back to the model. Include this in the input when continuing a multi-turn conversation after the model issued a function_call and the client has executed it; the model then sees the call_id and the tool’s output (and optional id, status).

{ "input": [{ "type": "function_call_output", "call_id": "fc_1", "output": "72°F, partly cloudy" }] }

mcp_call

Result of a Model Context Protocol (MCP) tool call from a previous turn. Include this in the input when continuing a multi-turn conversation so the model sees the server label, tool name, arguments, and optional output or error from the MCP server.

{ "input": [{ "type": "mcp_call", "id": "mcp_1", "server_label": "my_server", "name": "fetch_data", "arguments": "{}", "output": "result" }] }

mcp_list_tools

Result of listing tools from an MCP server in a previous turn. Include this in the input when continuing a multi-turn conversation so the model sees the server label and the list of available tools (names and input schemas) returned by the server.

{ "input": [{ "type": "mcp_list_tools", "id": "mlt_1", "server_label": "my_server", "tools": [{ "name": "tool_a", "input_schema": {} }] }] }

mcp_approval_request

A pending request for human approval of an MCP tool call. The model has asked to run a tool that requires approval; this item describes the tool name, server, and arguments so the client can prompt the user and then send an mcp_approval_response.

{ "input": [{ "type": "mcp_approval_request", "id": "mar_1", "name": "run_script", "server_label": "my_server", "arguments": "{}" }] }

mcp_approval_response

User’s decision on an mcp_approval_request: approve or deny the requested MCP tool call. Include this in the input for the next request so the model can continue or adjust its behavior based on the approval or denial (and optional reason).

{ "input": [{ "type": "mcp_approval_response", "approval_request_id": "mar_1", "approve": true }] }