Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Agents

Create an agent
POST/agents
Delete an agent
DELETE/agents/{agent_id}
List agents
GET/agents
Retrieve an agent
GET/agents/{agent_id}
Update an agent
POST/agents/{agent_id}
ModelsExpand Collapse
Agent object { id, created_at, instructions, 10 more }

A reusable agent scoped to the caller’s project.

id: string

The ID of the reusable agent.

minLength0
created_at: number

The Unix timestamp, in seconds, when the agent was created.

formatint64
instructions: string or null

Custom instructions appended to the agent’s default base instructions.

minLength0
metadata: map[string]

Custom string key-value pairs attached to the agent.

model: string

The requested model name used for inference.

minLength0
multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

name: string or null

A human-readable name for the agent, or null if it is unnamed.

minLength0
object: "agent"

The object type. Always agent.

reasoning: AgentReasoning { effort, summary }

The resolved reasoning configuration, including the model default for an omitted effort.

service_tier: "auto" or "default" or "flex" or 2 more

The resolved service-tier policy used for model requests.

One of the following:
"auto"
"default"
"flex"
"priority"
"fast"
text: AgentText { format, verbosity }

The resolved configuration for text generated by the agent.

tools: array of PersistedAgentTool

Tools available to the agent.

One of the following:
Function object { defer_loading, description, name, 2 more }

A function defined by the application.

defer_loading: boolean

Whether the function is deferred and discovered through tool search.

description: string

A description of what the function does.

minLength0
name: string

The name of the function.

minLength0
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

ToolSearch object { type }

Discovers deferred function tools and loads them into the model context.

type: "tool_search"

The type of the object. Always tool_search.

ProgrammaticToolCalling object { enabled, type }

Enables calling tools from model-generated code.

enabled: boolean

Whether tools can be called from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

Tools provided by a remote MCP server without stored credentials.

allowed_tools: array of string or null

The MCP tools the agent may call, or null when all server tools are allowed.

connection_origin: "service" or "environment"

Where outbound MCP HTTP connections originate.

One of the following:
"service"
"environment"
credential_id: string or null

The vault credential selected for this MCP server, if any.

minLength0
request_metadata: map[unknown]

Metadata included with requests to this MCP server.

required: boolean

Whether this MCP server must initialize before the first turn.

server_label: string

A label used to identify the MCP server in tool calls.

minLength0

The credential-free transport used to connect to the MCP server.

type: "mcp"

The type of the object. Always mcp.

WebSearch object { allowed_domains, context_size, location, 2 more }

Web search.

allowed_domains: array of string or null

Allowed search domains, or null when the search is unrestricted.

context_size: "low" or "medium" or "high"

The amount of search context made available to the model. Defaults to medium.

One of the following:
"low"
"medium"
"high"
location: object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: string or null

The city name.

minLength0
country: string or null

The two-letter ISO country code, such as US.

minLength0
region: string or null

The region or state name.

minLength0
timezone: string or null

The IANA timezone, such as America/Los_Angeles.

minLength0
mode: "disabled" or "cached" or "live"

The source used for web search results.

One of the following:
"disabled"
"cached"
"live"
type: "web_search"

The type of the object. Always web_search.

updated_at: number

The Unix timestamp, in seconds, when the agent was last updated.

formatint64
AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to close a subagent.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to close.

minLength0
sender_agent_id: string

The ID of the agent requesting the close.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "close_subagent_call"

The item type. Always close_subagent_call.

AgentCommandExecutionItem object { id, command, cwd, 6 more }

A command execution produced by the agent.

id: string

The ID of the command execution item.

minLength0
command: string

The command that was executed.

minLength0
cwd: string or null

The working directory used to execute the command.

minLength0
duration_ms: number or null

The command duration in milliseconds.

formatint64
exit_code: number or null

The process exit code, if the command completed.

formatint64
output: string or null

The command output, if available.

minLength0

The status of the command execution.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "command_execution"

The item type. Always command_execution.

AgentContent = OutputText { text, type } or object { encrypted_content, type }

A plaintext or encrypted content part exchanged between agents.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }

A request to spawn a subagent.

id: string

The ID of the tool call item.

minLength0
agent_id: string

The ID of the agent that requested the subagent.

minLength0
content: array of AgentContent

The task given to the spawned agent.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

model: string or null

The model requested for the spawned agent.

minLength0
reasoning_effort: string or null

The reasoning effort requested for the spawned agent.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "create_subagent_call"

The item type. Always create_subagent_call.

AgentDeleted object { id, deleted, object }

A deleted reusable agent.

id: string

The ID of the deleted agent.

minLength0
deleted: boolean

Whether the agent was deleted. Always true.

object: "agent.deleted"

The object type. Always agent.deleted.

AgentFunctionCallItem object { id, arguments, call_id, 4 more }

A function call produced by the agent.

id: string

The ID of the function call item.

minLength0
arguments: unknown

The arguments to pass to the function.

call_id: string

The ID used to submit the function result.

minLength0
name: string

The name of the function to call.

minLength0

The status of the function call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "function_call"

The item type. Always function_call.

AgentFunctionCallOutput = string or array of InputContent

The text or model-input content supplied as a function result.

One of the following:
string
array of InputContent
One of the following:
InputText object { text, type }

Text input recorded in a session item.

text: string

The text supplied to the agent.

minLength0
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

Image input recorded in a session item.

image_url: string

The URL of the image supplied to the agent, which may be a base64-encoded data URL.

minLength0
type: "input_image"

The type of the object. Always input_image.

AgentFunctionCallOutputParam = string or array of InputContentParam

A function result represented as text or supported model-input content.

One of the following:
string
One of the following:
InputText object { text, type }

Text input to the model.

text: string

The text sent to the model.

minLength0
maxLength1048576
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

Image input to the model.

image_url: string

The URL of the image sent to the model.

minLength0
maxLength1048576
type: "input_image"

The type of the object. Always input_image.

AgentFunctionCallStatus = "in_progress" or "completed" or "failed" or "incomplete"

The status of a tool call.

One of the following:
"in_progress"

The call is in progress.

"completed"

The call completed successfully.

"failed"

The call failed.

"incomplete"

The call stopped before completing.

AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to interrupt a subagent’s current turn. The subagent remains available.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to interrupt.

minLength0
sender_agent_id: string

The ID of the agent requesting the interrupt.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "interrupt_subagent_call"

The item type. Always interrupt_subagent_call.

AgentMcpCallItem object { id, arguments, error, 6 more }

A call to a tool on an MCP server.

id: string

The ID of the MCP call item.

minLength0
arguments: unknown

The arguments passed to the MCP tool.

error: unknown

The error returned by the MCP tool, if any.

name: string

The name of the MCP tool.

minLength0
output: unknown

The output returned by the MCP tool, if any.

server_label: string

The label of the MCP server.

minLength0

The status of the MCP tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "mcp_call"

The item type. Always mcp_call.

AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 4 more }

Emitted when command execution produces an output delta.

delta: string

The output text that was appended.

minLength0
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the command execution item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.output.command_execution_output.delta"

The type of the object. Always agent.output.command_execution_output.delta.

AgentOutputItem = AgentSessionAssistantMessage { id, content, phase, 4 more } or AgentReasoningItem { id, status, summary, 2 more } or AgentFunctionCallItem { id, arguments, call_id, 4 more } or 9 more

An output item produced by an agent.

One of the following:
AgentSessionAssistantMessage object { id, content, phase, 4 more }

An assistant message produced by the agent.

id: string

The ID of the message.

minLength0
content: array of OutputText { text, type }

The content of the message.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

phase: "commentary" or "final_answer" or null

The phase of an assistant message.

One of the following:
"commentary"

Commentary produced while the agent works.

"final_answer"

The agent’s final answer.

role: "assistant"

The role of the message author. Always assistant.

The status of the message.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "message"

The item type. Always message.

AgentReasoningItem object { id, status, summary, 2 more }

A reasoning item produced by the agent.

id: string

The ID of the reasoning item.

minLength0
status: AgentOutputItemStatus or null

The status of an agent output item.

summary: array of SummaryText { text, type }

The reasoning summaries produced by the agent.

text: string

The reasoning summary text.

minLength0
type: "summary_text"

The content type. Always summary_text.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "reasoning"

The item type. Always reasoning.

AgentFunctionCallItem object { id, arguments, call_id, 4 more }

A function call produced by the agent.

id: string

The ID of the function call item.

minLength0
arguments: unknown

The arguments to pass to the function.

call_id: string

The ID used to submit the function result.

minLength0
name: string

The name of the function to call.

minLength0

The status of the function call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "function_call"

The item type. Always function_call.

AgentMcpCallItem object { id, arguments, error, 6 more }

A call to a tool on an MCP server.

id: string

The ID of the MCP call item.

minLength0
arguments: unknown

The arguments passed to the MCP tool.

error: unknown

The error returned by the MCP tool, if any.

name: string

The name of the MCP tool.

minLength0
output: unknown

The output returned by the MCP tool, if any.

server_label: string

The label of the MCP server.

minLength0

The status of the MCP tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "mcp_call"

The item type. Always mcp_call.

AgentWebSearchCallItem object { id, action, status, 2 more }

A web search call produced by the agent.

id: string

The ID of the web search call.

minLength0
action: WebSearchAction or null

An action performed by the web search tool.

The status of the web search call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "web_search_call"

The item type. Always web_search_call.

AgentCommandExecutionItem object { id, command, cwd, 6 more }

A command execution produced by the agent.

id: string

The ID of the command execution item.

minLength0
command: string

The command that was executed.

minLength0
cwd: string or null

The working directory used to execute the command.

minLength0
duration_ms: number or null

The command duration in milliseconds.

formatint64
exit_code: number or null

The process exit code, if the command completed.

formatint64
output: string or null

The command output, if available.

minLength0

The status of the command execution.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "command_execution"

The item type. Always command_execution.

AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }

A request to spawn a subagent.

id: string

The ID of the tool call item.

minLength0
agent_id: string

The ID of the agent that requested the subagent.

minLength0
content: array of AgentContent

The task given to the spawned agent.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

model: string or null

The model requested for the spawned agent.

minLength0
reasoning_effort: string or null

The reasoning effort requested for the spawned agent.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "create_subagent_call"

The item type. Always create_subagent_call.

AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }

A request to send input to another agent.

id: string

The ID of the tool call item.

minLength0
content: array of AgentContent

The input sent to the receiving agent.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

recipient_agent_id: string

The ID of the agent receiving the input.

minLength0
sender_agent_id: string

The ID of the agent sending the input.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "send_subagent_input_call"

The item type. Always send_subagent_input_call.

AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to resume a subagent.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to resume.

minLength0
sender_agent_id: string

The ID of the agent requesting the resume.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "resume_subagent_call"

The item type. Always resume_subagent_call.

AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }

A request to wait for one or more subagents.

id: string

The ID of the tool call item.

minLength0
recipient_agent_ids: array of string

The IDs of the agents to wait for.

sender_agent_id: string

The ID of the agent waiting for results.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "wait_for_subagents_call"

The item type. Always wait_for_subagents_call.

AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to interrupt a subagent’s current turn. The subagent remains available.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to interrupt.

minLength0
sender_agent_id: string

The ID of the agent requesting the interrupt.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "interrupt_subagent_call"

The item type. Always interrupt_subagent_call.

AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to close a subagent.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to close.

minLength0
sender_agent_id: string

The ID of the agent requesting the close.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "close_subagent_call"

The item type. Always close_subagent_call.

AgentOutputItemStatus = "in_progress" or "completed" or "incomplete"

The status of an agent output item.

One of the following:
"in_progress"

The item is in progress.

"completed"

The item is complete.

"incomplete"

The item stopped before completing.

AgentReasoning object { effort, summary }

The reasoning configuration used by an agent.

effort: "none" or "minimal" or "low" or 4 more or null

The amount of reasoning effort used by an agent.

One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: "concise" or "detailed" or "auto" or null

The reasoning summary format requested from an agent.

One of the following:
"concise"

Returns a concise reasoning summary when supported.

"detailed"

Returns a detailed reasoning summary when supported.

"auto"

Automatically selects the most detailed summary supported by the model.

AgentReasoningItem object { id, status, summary, 2 more }

A reasoning item produced by the agent.

id: string

The ID of the reasoning item.

minLength0
status: AgentOutputItemStatus or null

The status of an agent output item.

summary: array of SummaryText { text, type }

The reasoning summaries produced by the agent.

text: string

The reasoning summary text.

minLength0
type: "summary_text"

The content type. Always summary_text.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "reasoning"

The item type. Always reasoning.

AgentReasoningParam object { effort, summary }

Reasoning configuration for the agent.

effort: optional "none" or "minimal" or "low" or 4 more or null

The amount of reasoning effort the model should use.

One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null

The reasoning summary format requested from the model.

One of the following:
"concise"

Returns a concise reasoning summary when supported.

"detailed"

Returns a detailed reasoning summary when supported.

"auto"

Automatically selects the most detailed summary supported by the model.

AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to resume a subagent.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to resume.

minLength0
sender_agent_id: string

The ID of the agent requesting the resume.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "resume_subagent_call"

The item type. Always resume_subagent_call.

AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }

A request to send input to another agent.

id: string

The ID of the tool call item.

minLength0
content: array of AgentContent

The input sent to the receiving agent.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

recipient_agent_id: string

The ID of the agent receiving the input.

minLength0
sender_agent_id: string

The ID of the agent sending the input.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "send_subagent_input_call"

The item type. Always send_subagent_input_call.

AgentSession object { id, agent, created_at, 9 more }

A Managed Agents session.

id: string

The ID of the session.

minLength0
agent: object { id, instructions, model, 6 more }

The agent running in the session.

id: string

The ID of the agent.

minLength0
instructions: string or null

Custom instructions appended to the agent’s default base instructions.

minLength0
model: string

The model used by the agent.

minLength0
multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

Configuration for creating and coordinating subagents.

name: string or null

The reusable agent’s name when the session was created, or null if no name was saved. Later changes to the agent’s name do not affect this value.

minLength0
reasoning: AgentReasoning { effort, summary }

The agent’s reasoning configuration.

service_tier: "auto" or "default" or "flex" or 2 more

The effective service-tier policy for model requests. Defaults to auto.

One of the following:
"auto"
"default"
"flex"
"priority"
"fast"
text: AgentText { format, verbosity }

Configuration for text generated by the agent.

tools: array of AgentTool

Tools available to the agent.

One of the following:
Function object { defer_loading, description, name, 2 more }

A function defined by the application.

defer_loading: boolean

Whether the function is deferred and discovered through tool search.

description: string

A description of what the function does.

minLength0
name: string

The name of the function.

minLength0
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

ProgrammaticToolCalling object { enabled, type }

Enables calling tools from model-generated code.

enabled: boolean

Whether tools can be called from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

Tools provided by a remote MCP server.

allowed_tools: array of string or null

The MCP tools the agent may call.

connection_origin: "service" or "environment"

Where outbound MCP HTTP connections originate.

One of the following:
"service"
"environment"
credential_id: string or null

The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.

minLength0
request_metadata: map[unknown]

Metadata included with requests to this MCP server.

required: boolean

Whether this MCP server must initialize before the first turn.

server_label: string

A label used to identify the MCP server in tool calls.

minLength0
transport: McpTransport

The transport used to connect to the MCP server.

type: "mcp"

The type of the object. Always mcp.

WebSearch object { allowed_domains, context_size, location, 2 more }

Web search.

allowed_domains: array of string or null

Allowed search domains, or null when the search is unrestricted.

context_size: "low" or "medium" or "high"

The amount of search context made available to the model. Defaults to medium.

One of the following:
"low"
"medium"
"high"
location: object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: string or null

The city name.

minLength0
country: string or null

The two-letter ISO country code, such as US.

minLength0
region: string or null

The region or state name.

minLength0
timezone: string or null

The IANA timezone, such as America/Los_Angeles.

minLength0
mode: "disabled" or "cached" or "live"

The source used for web search results.

One of the following:
"disabled"
"cached"
"live"
type: "web_search"

The type of the object. Always web_search.

created_at: number

The Unix timestamp, in seconds, when the session was created.

formatint64
environment: Environment

The execution environment for the session.

error: string or null

The error that caused the session to fail, if any.

minLength0
last_active_at: number

The Unix timestamp, in seconds, when the session was last active.

formatint64
metadata: map[string]

Custom string key-value pairs attached to the session.

object: "agent.session"

The object type. Always agent.session.

required_actions: array of object { arguments, call_id, name, 2 more } or object { environment_id, type }

Actions that must be completed before the session can continue.

One of the following:
FunctionCall object { arguments, call_id, name, 2 more }

Run a function tool and submit its result.

arguments: unknown

The arguments supplied by the model.

call_id: string

The ID to include when submitting the function result.

minLength0
name: string

The function name.

minLength0
turn_id: string

The ID of the turn that requested the function call.

minLength0
type: "function_call"

The type of the object. Always function_call.

EnvironmentConnection object { environment_id, type }

Reconnect a session environment.

environment_id: string

The ID of the environment to reconnect.

minLength0
type: "environment_connection"

The type of the object. Always environment_connection.

status: "idle" or "in_progress" or "requires_action" or "failed"

The current status of the session.

One of the following:
"idle"

The session has no turn in progress and is ready for input. A hosted environment may still be provisioning.

"in_progress"

The session is processing a turn.

"requires_action"

The session is waiting for one or more required actions.

"failed"

The session failed.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

vault_ids: array of string

The IDs of vaults made available to the session.

AgentSessionAssistantMessage object { id, content, phase, 4 more }

An assistant message produced by the agent.

id: string

The ID of the message.

minLength0
content: array of OutputText { text, type }

The content of the message.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

phase: "commentary" or "final_answer" or null

The phase of an assistant message.

One of the following:
"commentary"

Commentary produced while the agent works.

"final_answer"

The agent’s final answer.

role: "assistant"

The role of the message author. Always assistant.

The status of the message.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "message"

The item type. Always message.

AgentSessionCreatedEvent object { event_id, session, type }

Emitted when a session is created.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session that was created.

type: "agent.session.created"

The type of the object. Always agent.session.created.

AgentSessionDeleted object { id, deleted, object }

A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously.

id: string

The ID of the deleted session.

minLength0
deleted: boolean

Whether the session has been removed from the public API. Always true. Physical cleanup may still be in progress.

object: "agent.session.deleted"

The object type. Always agent.session.deleted.

AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }

Emitted when a session environment connects.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.connected"

The type of the object. Always agent.session.environment.connected.

AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }

Emitted when a session environment disconnects.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.disconnected"

The type of the object. Always agent.session.environment.disconnected.

AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }

Emitted when a session environment fails.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.failed"

The type of the object. Always agent.session.environment.failed.

AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }

Emitted while a session environment is being prepared.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.pending"

The type of the object. Always agent.session.environment.pending.

AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }

Emitted when a hosted session environment is ready to connect.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.ready"

The type of the object. Always agent.session.environment.ready.

AgentSessionEnvironmentState object { id, error, status, type }

The current state of a session environment.

id: string

The public ID of the environment.

minLength0
error: object { code, message, type } or null

An error reported while preparing a session environment.

code: string

A machine-readable error code.

minLength0
message: string

A human-readable error message.

minLength0
type: string

The error type.

minLength0
status: "pending" or "ready" or "connected" or 2 more

The environment’s connection status.

One of the following:
"pending"

The environment is being prepared.

"ready"

The environment is ready to connect.

"connected"

The environment is connected.

"disconnected"

The environment is disconnected.

"failed"

The environment failed to connect.

type: string

The environment type.

minLength0
AgentSessionErrorEvent object { error, event_id, session_id, type }

Emitted when a turn or session fails.

error: SessionError { code, message, param, type }

The error that occurred.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
type: "error"

The type of the object. Always error.

AgentSessionEvent = AgentSessionErrorEvent { error, event_id, session_id, type } or AgentSessionEnvironmentReadyEvent { environment, event_id, session_id, 2 more } or AgentOutputCommandExecutionOutputDeltaEvent { delta, event_id, item_id, 4 more } or 27 more

An event emitted by a Managed Agents session.

One of the following:
AgentSessionErrorEvent object { error, event_id, session_id, type }

Emitted when a turn or session fails.

error: SessionError { code, message, param, type }

The error that occurred.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
type: "error"

The type of the object. Always error.

AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }

Emitted when a hosted session environment is ready to connect.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.ready"

The type of the object. Always agent.session.environment.ready.

AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 4 more }

Emitted when command execution produces an output delta.

delta: string

The output text that was appended.

minLength0
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the command execution item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.output.command_execution_output.delta"

The type of the object. Always agent.output.command_execution_output.delta.

AgentSessionCreatedEvent object { event_id, session, type }

Emitted when a session is created.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session that was created.

type: "agent.session.created"

The type of the object. Always agent.session.created.

AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 2 more }

Emitted when a turn is created.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The turn at the time it was created.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.created"

The type of the object. Always agent.session.turn.created.

AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 2 more }

Emitted when a turn starts running.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The turn at the time it started running.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.in_progress"

The type of the object. Always agent.session.turn.in_progress.

AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn completes.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The completed turn.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.completed"

The type of the object. Always agent.session.turn.completed.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

AgentSessionTurnFailedEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn fails.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The failed turn.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.failed"

The type of the object. Always agent.session.turn.failed.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn is cancelled.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The cancelled turn.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.cancelled"

The type of the object. Always agent.session.turn.cancelled.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 3 more }

Emitted when an item is added to a turn.

event_id: string

The unique ID of the event.

minLength0

The item that was added.

output_index: number or null

The index of the item in the turn output, when the item is agent output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.item.added"

The type of the object. Always agent.session.turn.item.added.

AgentSessionIdleEvent object { event_id, session, type }

Emitted when a session becomes idle.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session that became idle.

type: "agent.session.idle"

The type of the object. Always agent.session.idle.

AgentSessionInProgressEvent object { event_id, session, type }

Emitted when a session starts processing a turn.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session that started processing.

type: "agent.session.in_progress"

The type of the object. Always agent.session.in_progress.

AgentSessionRequiresActionEvent object { event_id, session, type }

Emitted when a session is waiting for one or more required actions.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session and its current required actions.

type: "agent.session.requires_action"

The type of the object. Always agent.session.requires_action.

AgentSessionFailedEvent object { event_id, session, type }

Emitted when a session fails.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The failed session.

type: "agent.session.failed"

The type of the object. Always agent.session.failed.

AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }

Emitted while a session environment is being prepared.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.pending"

The type of the object. Always agent.session.environment.pending.

AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }

Emitted when a session environment connects.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.connected"

The type of the object. Always agent.session.environment.connected.

AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }

Emitted when a session environment disconnects.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.disconnected"

The type of the object. Always agent.session.environment.disconnected.

AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }

Emitted when a session environment fails.

environment: AgentSessionEnvironmentState { id, error, status, type }

The current environment state.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.environment.failed"

The type of the object. Always agent.session.environment.failed.

AgentSessionSubagentCreatedEvent object { event_id, subagent, type }

Emitted when a subagent is created.

event_id: string

The unique ID of the event.

minLength0
subagent: Subagent { id, closed_at, instructions, 6 more }

The subagent that was created.

type: "agent.session.subagent.created"

The type of the object. Always agent.session.subagent.created.

AgentSessionSubagentActiveEvent object { event_id, subagent, type }

Emitted when a closed subagent successfully resumes.

event_id: string

The unique ID of the event.

minLength0
subagent: Subagent { id, closed_at, instructions, 6 more }

The subagent that resumed.

type: "agent.session.subagent.active"

The type of the object. Always agent.session.subagent.active.

AgentSessionSubagentClosedEvent object { event_id, subagent, type }

Emitted when a subagent is closed.

event_id: string

The unique ID of the event.

minLength0
subagent: Subagent { id, closed_at, instructions, 6 more }

The subagent that was closed.

type: "agent.session.subagent.closed"

The type of the object. Always agent.session.subagent.closed.

AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 3 more }

Emitted when an output item is complete.

event_id: string

The unique ID of the event.

minLength0

The completed output item.

output_index: number

The index of the output item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.item.done"

The type of the object. Always agent.session.turn.item.done.

AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is added.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: OutputText { text, type }

The initial content part.

session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.content_part.added"

The type of the object. Always agent.session.turn.content_part.added.

AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 5 more }

Emitted when an output content part is complete.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: OutputText { text, type }

The completed content part.

session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.content_part.done"

The type of the object. Always agent.session.turn.content_part.done.

AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 5 more }

Emitted when text is appended to an output text content part.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
delta: string

The text that was appended.

minLength0
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.output_text.delta"

The type of the object. Always agent.session.turn.output_text.delta.

AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is complete.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
text: string

The complete output text.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.output_text.done"

The type of the object. Always agent.session.turn.output_text.done.

AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is added.

event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: SummaryText { text, type }

The initial summary part.

session_id: string

The ID of the session associated with the event.

minLength0
summary_index: number

The index of the summary content part.

formatint64
minimum0
maximum4294967295
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_part.added"

The type of the object. Always agent.session.turn.reasoning_summary_part.added.

AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 6 more }

Emitted when a reasoning summary part is complete.

event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: SummaryText { text, type }

The completed summary part.

session_id: string

The ID of the session associated with the event.

minLength0
status: "incomplete" or null

Present as incomplete when summary generation was interrupted.

summary_index: number

The index of the summary part.

formatint64
minimum0
maximum4294967295
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_part.done"

The type of the object. Always agent.session.turn.reasoning_summary_part.done.

AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 5 more }

Emitted when text is appended to a reasoning summary.

delta: string

The summary text that was appended.

minLength0
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
summary_index: number

The index of the summary content part.

formatint64
minimum0
maximum4294967295
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_text.delta"

The type of the object. Always agent.session.turn.reasoning_summary_text.delta.

AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is complete.

event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
summary_index: number

The index of the summary content part.

formatint64
minimum0
maximum4294967295
text: string

The complete reasoning summary text.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_text.done"

The type of the object. Always agent.session.turn.reasoning_summary_text.done.

AgentSessionFailedEvent object { event_id, session, type }

Emitted when a session fails.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The failed session.

type: "agent.session.failed"

The type of the object. Always agent.session.failed.

AgentSessionIdleEvent object { event_id, session, type }

Emitted when a session becomes idle.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session that became idle.

type: "agent.session.idle"

The type of the object. Always agent.session.idle.

AgentSessionInProgressEvent object { event_id, session, type }

Emitted when a session starts processing a turn.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session that started processing.

type: "agent.session.in_progress"

The type of the object. Always agent.session.in_progress.

AgentSessionInputMessageParam object { content, role, type }

A user message submitted to a session.

content: array of InputContentParam

The content of the message.

One of the following:
InputText object { text, type }

Text input to the model.

text: string

The text sent to the model.

minLength0
maxLength1048576
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

Image input to the model.

image_url: string

The URL of the image sent to the model.

minLength0
maxLength1048576
type: "input_image"

The type of the object. Always input_image.

role: "user"

The role of the message author. Always user.

type: optional "message"

The type of the input item. Always message.

AgentSessionInputParam = object { input, type } or object { type } or object { call_id, success, turn_id, 3 more }

Input submitted to an existing session.

One of the following:
AgentSessionInputMessage object { input, type }

Adds one or more user messages and starts a turn.

input: array of AgentSessionInputMessageParam { content, role, type }

The user messages to add to the session.

content: array of InputContentParam

The content of the message.

One of the following:
InputText object { text, type }

Text input to the model.

text: string

The text sent to the model.

minLength0
maxLength1048576
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

Image input to the model.

image_url: string

The URL of the image sent to the model.

minLength0
maxLength1048576
type: "input_image"

The type of the object. Always input_image.

role: "user"

The role of the message author. Always user.

type: optional "message"

The type of the input item. Always message.

type: "agent.session.input.message"

The type of the object. Always agent.session.input.message.

AgentSessionInputCancel object { type }

Cancels the session’s active turn.

type: "agent.session.input.cancel"

The type of the object. Always agent.session.input.cancel.

AgentSessionInputToolResult object { call_id, success, turn_id, 3 more }

Submits the result of a function call.

call_id: string

The ID of the function call.

minLength0
maxLength1048576
success: boolean

Whether the function call succeeded.

turn_id: string

The ID of the turn that requested the function call.

minLength0
maxLength1048576
type: "agent.session.input.tool_result"

The type of the object. Always agent.session.input.tool_result.

error: optional string or null

The error message when the call failed.

minLength0
maxLength1048576
output: optional AgentFunctionCallOutputParam or null

A function result represented as text or supported model-input content.

AgentSessionItem = AgentSessionMessage { id, content, phase, 4 more } or AgentReasoningItem { id, status, summary, 2 more } or AgentFunctionCallItem { id, arguments, call_id, 4 more } or 11 more

An item associated with a session turn.

One of the following:
AgentSessionMessage object { id, content, phase, 4 more }

A user or assistant message recorded in a session.

id: string or null

The ID of this item, or null for legacy user messages whose ID was not recorded.

minLength0
content: array of AgentSessionMessageContent

The content of the message. User messages contain input text or images; assistant messages contain output text.

One of the following:
InputText object { text, type }

Text supplied by the user.

text: string

The text supplied by the user.

minLength0
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

An image supplied by the user.

image_url: string

The URL of the image supplied by the user, which may be a base64-encoded data URL.

minLength0
type: "input_image"

The type of the object. Always input_image.

OutputText object { text, type }

Text produced by the assistant.

text: string

The text produced by the assistant.

minLength0
type: "output_text"

The type of the object. Always output_text.

phase: "commentary" or "final_answer" or null

The phase of an assistant message.

One of the following:
"commentary"

Commentary produced while the agent works.

"final_answer"

The agent’s final answer.

role: "user" or "assistant"

The role of the message author.

One of the following:
"user"
"assistant"

The status of the message. User messages are always completed.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "message"

The item type. Always message.

AgentReasoningItem object { id, status, summary, 2 more }

A reasoning item produced by the agent.

id: string

The ID of the reasoning item.

minLength0
status: AgentOutputItemStatus or null

The status of an agent output item.

summary: array of SummaryText { text, type }

The reasoning summaries produced by the agent.

text: string

The reasoning summary text.

minLength0
type: "summary_text"

The content type. Always summary_text.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "reasoning"

The item type. Always reasoning.

AgentFunctionCallItem object { id, arguments, call_id, 4 more }

A function call produced by the agent.

id: string

The ID of the function call item.

minLength0
arguments: unknown

The arguments to pass to the function.

call_id: string

The ID used to submit the function result.

minLength0
name: string

The name of the function to call.

minLength0

The status of the function call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "function_call"

The item type. Always function_call.

FunctionCallOutput object { id, call_id, error, 4 more }

The result supplied for a function call.

id: string

The ID of the function call output item.

minLength0
call_id: string

The ID of the function call that produced this output.

minLength0
error: string or null

The error message, if the call failed.

minLength0
output: AgentFunctionCallOutput or null

The text or model-input content supplied as a function result.

The status of the function call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "function_call_output"

The item type. Always function_call_output.

AgentMessage object { id, content, recipient_agent_id, 3 more }

A message exchanged between agent threads.

id: string

The ID of the message.

minLength0
content: array of AgentContent

The content exchanged between the agents.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

recipient_agent_id: string

The ID or name of the receiving agent.

minLength0
sender_agent_id: string

The ID or name of the sending agent.

minLength0
turn_id: string

The ID of the turn that contains this item.

minLength0
type: "agent_message"

The item type. Always agent_message.

AgentMcpCallItem object { id, arguments, error, 6 more }

A call to a tool on an MCP server.

id: string

The ID of the MCP call item.

minLength0
arguments: unknown

The arguments passed to the MCP tool.

error: unknown

The error returned by the MCP tool, if any.

name: string

The name of the MCP tool.

minLength0
output: unknown

The output returned by the MCP tool, if any.

server_label: string

The label of the MCP server.

minLength0

The status of the MCP tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "mcp_call"

The item type. Always mcp_call.

AgentWebSearchCallItem object { id, action, status, 2 more }

A web search call produced by the agent.

id: string

The ID of the web search call.

minLength0
action: WebSearchAction or null

An action performed by the web search tool.

The status of the web search call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "web_search_call"

The item type. Always web_search_call.

AgentCommandExecutionItem object { id, command, cwd, 6 more }

A command execution produced by the agent.

id: string

The ID of the command execution item.

minLength0
command: string

The command that was executed.

minLength0
cwd: string or null

The working directory used to execute the command.

minLength0
duration_ms: number or null

The command duration in milliseconds.

formatint64
exit_code: number or null

The process exit code, if the command completed.

formatint64
output: string or null

The command output, if available.

minLength0

The status of the command execution.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "command_execution"

The item type. Always command_execution.

AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }

A request to spawn a subagent.

id: string

The ID of the tool call item.

minLength0
agent_id: string

The ID of the agent that requested the subagent.

minLength0
content: array of AgentContent

The task given to the spawned agent.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

model: string or null

The model requested for the spawned agent.

minLength0
reasoning_effort: string or null

The reasoning effort requested for the spawned agent.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "create_subagent_call"

The item type. Always create_subagent_call.

AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }

A request to send input to another agent.

id: string

The ID of the tool call item.

minLength0
content: array of AgentContent

The input sent to the receiving agent.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

recipient_agent_id: string

The ID of the agent receiving the input.

minLength0
sender_agent_id: string

The ID of the agent sending the input.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "send_subagent_input_call"

The item type. Always send_subagent_input_call.

AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to resume a subagent.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to resume.

minLength0
sender_agent_id: string

The ID of the agent requesting the resume.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "resume_subagent_call"

The item type. Always resume_subagent_call.

AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }

A request to wait for one or more subagents.

id: string

The ID of the tool call item.

minLength0
recipient_agent_ids: array of string

The IDs of the agents to wait for.

sender_agent_id: string

The ID of the agent waiting for results.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "wait_for_subagents_call"

The item type. Always wait_for_subagents_call.

AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to interrupt a subagent’s current turn. The subagent remains available.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to interrupt.

minLength0
sender_agent_id: string

The ID of the agent requesting the interrupt.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "interrupt_subagent_call"

The item type. Always interrupt_subagent_call.

AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to close a subagent.

id: string

The ID of the tool call item.

minLength0
recipient_agent_id: string

The ID of the agent to close.

minLength0
sender_agent_id: string

The ID of the agent requesting the close.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "close_subagent_call"

The item type. Always close_subagent_call.

AgentSessionMessage object { id, content, phase, 4 more }

A user or assistant message recorded in a session.

id: string or null

The ID of this item, or null for legacy user messages whose ID was not recorded.

minLength0
content: array of AgentSessionMessageContent

The content of the message. User messages contain input text or images; assistant messages contain output text.

One of the following:
InputText object { text, type }

Text supplied by the user.

text: string

The text supplied by the user.

minLength0
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

An image supplied by the user.

image_url: string

The URL of the image supplied by the user, which may be a base64-encoded data URL.

minLength0
type: "input_image"

The type of the object. Always input_image.

OutputText object { text, type }

Text produced by the assistant.

text: string

The text produced by the assistant.

minLength0
type: "output_text"

The type of the object. Always output_text.

phase: "commentary" or "final_answer" or null

The phase of an assistant message.

One of the following:
"commentary"

Commentary produced while the agent works.

"final_answer"

The agent’s final answer.

role: "user" or "assistant"

The role of the message author.

One of the following:
"user"
"assistant"

The status of the message. User messages are always completed.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "message"

The item type. Always message.

AgentSessionMessageContent = object { text, type } or object { image_url, type } or object { text, type }

A content part in a session message.

One of the following:
InputText object { text, type }

Text supplied by the user.

text: string

The text supplied by the user.

minLength0
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

An image supplied by the user.

image_url: string

The URL of the image supplied by the user, which may be a base64-encoded data URL.

minLength0
type: "input_image"

The type of the object. Always input_image.

OutputText object { text, type }

Text produced by the assistant.

text: string

The text produced by the assistant.

minLength0
type: "output_text"

The type of the object. Always output_text.

AgentSessionRequiresActionEvent object { event_id, session, type }

Emitted when a session is waiting for one or more required actions.

event_id: string

The unique ID of the event.

minLength0
session: AgentSession { id, agent, created_at, 9 more }

The session and its current required actions.

type: "agent.session.requires_action"

The type of the object. Always agent.session.requires_action.

AgentSessionSubagentActiveEvent object { event_id, subagent, type }

Emitted when a closed subagent successfully resumes.

event_id: string

The unique ID of the event.

minLength0
subagent: Subagent { id, closed_at, instructions, 6 more }

The subagent that resumed.

type: "agent.session.subagent.active"

The type of the object. Always agent.session.subagent.active.

AgentSessionSubagentClosedEvent object { event_id, subagent, type }

Emitted when a subagent is closed.

event_id: string

The unique ID of the event.

minLength0
subagent: Subagent { id, closed_at, instructions, 6 more }

The subagent that was closed.

type: "agent.session.subagent.closed"

The type of the object. Always agent.session.subagent.closed.

AgentSessionSubagentCreatedEvent object { event_id, subagent, type }

Emitted when a subagent is created.

event_id: string

The unique ID of the event.

minLength0
subagent: Subagent { id, closed_at, instructions, 6 more }

The subagent that was created.

type: "agent.session.subagent.created"

The type of the object. Always agent.session.subagent.created.

AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn is cancelled.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The cancelled turn.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.cancelled"

The type of the object. Always agent.session.turn.cancelled.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn completes.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The completed turn.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.completed"

The type of the object. Always agent.session.turn.completed.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is added.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: OutputText { text, type }

The initial content part.

session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.content_part.added"

The type of the object. Always agent.session.turn.content_part.added.

AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 5 more }

Emitted when an output content part is complete.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: OutputText { text, type }

The completed content part.

session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.content_part.done"

The type of the object. Always agent.session.turn.content_part.done.

AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 2 more }

Emitted when a turn is created.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The turn at the time it was created.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.created"

The type of the object. Always agent.session.turn.created.

AgentSessionTurnFailedEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn fails.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The failed turn.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.failed"

The type of the object. Always agent.session.turn.failed.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 2 more }

Emitted when a turn starts running.

event_id: string

The unique ID of the event.

minLength0
session_id: string

The ID of the session associated with the event.

minLength0
turn: Turn { id, agent_id, completed_at, 8 more }

The turn at the time it started running.

turn_id: string

The ID of the turn associated with the event.

minLength0
type: "agent.session.turn.in_progress"

The type of the object. Always agent.session.turn.in_progress.

AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 3 more }

Emitted when an item is added to a turn.

event_id: string

The unique ID of the event.

minLength0

The item that was added.

output_index: number or null

The index of the item in the turn output, when the item is agent output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.item.added"

The type of the object. Always agent.session.turn.item.added.

AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 3 more }

Emitted when an output item is complete.

event_id: string

The unique ID of the event.

minLength0

The completed output item.

output_index: number

The index of the output item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.item.done"

The type of the object. Always agent.session.turn.item.done.

AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 5 more }

Emitted when text is appended to an output text content part.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
delta: string

The text that was appended.

minLength0
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.output_text.delta"

The type of the object. Always agent.session.turn.output_text.delta.

AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is complete.

content_index: number

The index of the content part in the message.

formatint64
minimum0
maximum4294967295
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the message item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
text: string

The complete output text.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.output_text.done"

The type of the object. Always agent.session.turn.output_text.done.

AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is added.

event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: SummaryText { text, type }

The initial summary part.

session_id: string

The ID of the session associated with the event.

minLength0
summary_index: number

The index of the summary content part.

formatint64
minimum0
maximum4294967295
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_part.added"

The type of the object. Always agent.session.turn.reasoning_summary_part.added.

AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 6 more }

Emitted when a reasoning summary part is complete.

event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
part: SummaryText { text, type }

The completed summary part.

session_id: string

The ID of the session associated with the event.

minLength0
status: "incomplete" or null

Present as incomplete when summary generation was interrupted.

summary_index: number

The index of the summary part.

formatint64
minimum0
maximum4294967295
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_part.done"

The type of the object. Always agent.session.turn.reasoning_summary_part.done.

AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 5 more }

Emitted when text is appended to a reasoning summary.

delta: string

The summary text that was appended.

minLength0
event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
summary_index: number

The index of the summary content part.

formatint64
minimum0
maximum4294967295
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_text.delta"

The type of the object. Always agent.session.turn.reasoning_summary_text.delta.

AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is complete.

event_id: string

The unique ID of the event.

minLength0
item_id: string

The ID of the reasoning item.

minLength0
output_index: number

The index of the item in the turn output.

formatint64
minimum0
maximum4294967295
session_id: string

The ID of the session associated with the event.

minLength0
summary_index: number

The index of the summary content part.

formatint64
minimum0
maximum4294967295
text: string

The complete reasoning summary text.

minLength0
turn_id: string or null

The ID of the turn associated with the event, when applicable.

minLength0
type: "agent.session.turn.reasoning_summary_text.done"

The type of the object. Always agent.session.turn.reasoning_summary_text.done.

AgentText object { format, verbosity }

The text configuration used by an agent.

format: TextFormat

The effective output format. Defaults to ordinary text.

verbosity: "low" or "medium" or "high"

The amount of text produced by the agent. Defaults to medium.

One of the following:
"low"
"medium"
"high"
AgentTextParam object { format, verbosity }

Configuration for text generated by the agent.

format: optional TextFormatParam or null

The output format for generated text.

verbosity: optional "low" or "medium" or "high" or null

The amount of text the model should produce.

One of the following:
"low"

Produces less text.

"medium"

Uses the default amount of text.

"high"

Produces more text.

AgentTool = object { defer_loading, description, name, 2 more } or object { enabled, type } or object { allowed_tools, connection_origin, credential_id, 5 more } or object { allowed_domains, context_size, location, 2 more }

A tool available to the agent.

One of the following:
Function object { defer_loading, description, name, 2 more }

A function defined by the application.

defer_loading: boolean

Whether the function is deferred and discovered through tool search.

description: string

A description of what the function does.

minLength0
name: string

The name of the function.

minLength0
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

ProgrammaticToolCalling object { enabled, type }

Enables calling tools from model-generated code.

enabled: boolean

Whether tools can be called from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

Tools provided by a remote MCP server.

allowed_tools: array of string or null

The MCP tools the agent may call.

connection_origin: "service" or "environment"

Where outbound MCP HTTP connections originate.

One of the following:
"service"
"environment"
credential_id: string or null

The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.

minLength0
request_metadata: map[unknown]

Metadata included with requests to this MCP server.

required: boolean

Whether this MCP server must initialize before the first turn.

server_label: string

A label used to identify the MCP server in tool calls.

minLength0
transport: McpTransport

The transport used to connect to the MCP server.

type: "mcp"

The type of the object. Always mcp.

WebSearch object { allowed_domains, context_size, location, 2 more }

Web search.

allowed_domains: array of string or null

Allowed search domains, or null when the search is unrestricted.

context_size: "low" or "medium" or "high"

The amount of search context made available to the model. Defaults to medium.

One of the following:
"low"
"medium"
"high"
location: object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: string or null

The city name.

minLength0
country: string or null

The two-letter ISO country code, such as US.

minLength0
region: string or null

The region or state name.

minLength0
timezone: string or null

The IANA timezone, such as America/Los_Angeles.

minLength0
mode: "disabled" or "cached" or "live"

The source used for web search results.

One of the following:
"disabled"
"cached"
"live"
type: "web_search"

The type of the object. Always web_search.

AgentToolParam = object { description, name, parameters, 2 more } or object { type } or object { type, enabled } or 2 more

A tool available to the agent.

One of the following:
Function object { description, name, parameters, 2 more }

A function defined by the application.

description: string

A description of what the function does.

minLength0
maxLength1048576
name: string

The name of the function.

minLength0
maxLength1048576
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

defer_loading: optional boolean

Whether this function is deferred and discovered through tool search. Defaults to false.

ToolSearch object { type }

Discovers deferred function tools and loads them into the model context.

type: "tool_search"

The type of the object. Always tool_search.

ProgrammaticToolCalling object { type, enabled }

Enables calling tools from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

enabled: optional boolean

Whether tools can be called from model-generated code. Defaults to true.

Mcp object { server_label, transport, type, 5 more }

Tools provided by a remote MCP server.

server_label: string

A label used to identify the MCP server in tool calls.

minLength0
maxLength1048576

The transport used to connect to the MCP server.

type: "mcp"

The type of the object. Always mcp.

allowed_tools: optional array of string or null

The MCP tools the agent may call. All server tools are allowed when omitted.

connection_origin: optional "service" or "environment" or null

Where outbound MCP HTTP connections originate.

One of the following:
"service"

Uses the Managed Agents service network.

"environment"

Uses the session’s execution environment.

credential_id: optional string or null

The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL.

minLength0
maxLength1048576
request_metadata: optional map[unknown] or null

Metadata included with requests to this MCP server.

required: optional boolean

Whether this MCP server must initialize before the first turn. Defaults to false.

WebSearch object { type, allowed_domains, context_size, 2 more }

Web search.

type: "web_search"

The type of the object. Always web_search.

allowed_domains: optional array of string or null

Domains the search may include.

context_size: optional "low" or "medium" or "high" or null

The amount of web search context made available to the model.

One of the following:
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: optional string or null

The city name.

minLength0
maxLength1048576
country: optional string or null

The two-letter ISO country code, such as US.

minLength0
maxLength1048576
region: optional string or null

The region or state name.

minLength0
maxLength1048576
timezone: optional string or null

The IANA timezone, such as America/Los_Angeles.

minLength0
maxLength1048576
mode: optional "disabled" or "cached" or "live" or null

The source used for web search results.

One of the following:
"disabled"

Disables web search.

"cached"

Uses cached search results.

"live"

Searches the live web.

AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }

A request to wait for one or more subagents.

id: string

The ID of the tool call item.

minLength0
recipient_agent_ids: array of string

The IDs of the agents to wait for.

sender_agent_id: string

The ID of the agent waiting for results.

minLength0

The status of the tool call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "wait_for_subagents_call"

The item type. Always wait_for_subagents_call.

AgentWebSearchCallItem object { id, action, status, 2 more }

A web search call produced by the agent.

id: string

The ID of the web search call.

minLength0
action: WebSearchAction or null

An action performed by the web search tool.

The status of the web search call.

turn_id: string

The ID of the turn that contains this item.

minLength0
type: "web_search_call"

The item type. Always web_search_call.

Environment = object { type } or object { id, capability_directories, files, 5 more } or object { id, capability_directories, remote_url, 2 more }

The execution environment for a session.

One of the following:
None object { type }

The session talks to CCA without selecting or provisioning an execution environment.

type: "none"

The type of the object. Always none.

OpenAIHosted object { id, capability_directories, files, 5 more }

An environment hosted by OpenAI.

id: string

The public ID of the environment.

minLength0
capability_directories: array of string

Directories that contain capabilities exposed to the agent.

files: array of HostedEnvironmentFile

Files available in the environment, excluding their contents.

One of the following:
HostedEnvironmentFileID object { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "file_id"

The type of the object. Always file_id.

Inline object { id, path, size_bytes, type }

A file supplied inline when the session was created.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

network: object { access, allowed_domains }

The effective network access policy for the environment.

access: "enabled" or "disabled" or "restricted"

The environment’s network access mode.

One of the following:
"enabled"

Allows unrestricted network access.

"disabled"

Disables network access.

"restricted"

Allows access only to configured domains.

allowed_domains: array of string

Domains the environment may access when network access is restricted.

packages: object { npm, python, system }

Packages installed in the environment.

npm: array of string

npm packages installed globally in the environment.

python: array of string

Python packages installed in the environment.

system: array of string

System packages installed in the environment.

plugins: array of HostedPlugin { description, name, type }

Plugins installed in the environment, excluding their archive contents.

description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

skills: array of HostedSkill

Skills installed in the environment, excluding their archive contents.

One of the following:
HostedSkillReference object { description, name, skill_id, 2 more }

A skill installed from the Skills API.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string

The concrete skill version installed for this session.

minLength0
Inline object { description, name, type }

A skill installed from an inline ZIP archive.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
type: "inline"

The type of the object. Always inline.

type: "openai_hosted"

The type of the object. Always openai_hosted.

SelfHosted object { id, capability_directories, remote_url, 2 more }

An environment hosted by the application.

id: string

The public ID of the environment.

minLength0
capability_directories: array of string

Directories that contain capabilities exposed to the agent.

remote_url: string

Pass this URL unchanged to codex exec-server --remote when connecting this environment.

minLength0
type: "self_hosted"

The type of the object. Always self_hosted.

workspace_directory: string

The absolute project directory inside the environment. Defaults to /workspace.

minLength0
EnvironmentParam = object { type } or object { type, capability_directories, env, 7 more } or object { type, workspace_directory, capability_directories }

The execution environment and optional reusable template for a session.

One of the following:
None object { type }

Runs the agent without an execution environment.

type: "none"

The type of the object. Always none.

OpenAIHosted object { type, capability_directories, env, 7 more }

An OpenAI-hosted environment, optionally based on a reusable template.

type: "openai_hosted"

The type of the object. Always openai_hosted.

capability_directories: optional array of string or null

Directories that contain capabilities exposed to the agent. Defaults to an empty list.

env: optional map[string] or null

Environment variables made available to the agent.

environment_template_id: optional string

A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy.

minLength0
maxLength64
files: optional array of HostedEnvironmentFileParam or null

Files available before the agent starts. Defaults to an empty list.

One of the following:
FileID object { file_id, path, type }

A file previously uploaded through the OpenAI Files API.

file_id: string

The ID of the uploaded file.

minLength1
maxLength256
path: string

The absolute destination path inside /workspace.

minLength1
maxLength4096
type: "file_id"

The type of the object. Always file_id.

Inline object { data, path, type }

A file supplied directly as standard-base64 data.

data: string

The standard-base64-encoded file contents.

minLength0
maxLength6990508
path: string

The absolute destination path inside /workspace.

minLength1
maxLength4096
type: "inline"

The type of the object. Always inline.

network: optional object { access, allowed_domains } or null

Network access for an OpenAI-hosted environment.

access: "enabled" or "disabled" or "restricted"

The environment’s network access mode.

One of the following:
"enabled"

Allows unrestricted network access, matching an omitted network policy.

"disabled"

Disables network access.

"restricted"

Allows access only to configured domains.

allowed_domains: optional array of string or null

Domains the environment may access when network access is restricted.

packages: optional object { npm, python, system } or null

Packages to install in an OpenAI-hosted environment.

npm: optional array of string or null

npm packages to install globally. Defaults to an empty list.

python: optional array of string or null

Python packages to install. Defaults to an empty list.

system: optional array of string or null

System packages to install. Defaults to an empty list.

plugins: optional array of HostedPluginParam { description, name, source, type } or null

Plugins provided as inline ZIP archives. Defaults to an empty list.

description: string

The plugin description declared in .codex-plugin/plugin.json.

minLength0
maxLength1048576
name: string

The plugin name declared in .codex-plugin/plugin.json.

minLength1
maxLength64
source: InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

type: "inline"

The type of the object. Always inline.

setup_commands: optional array of SetupCommandParam { command, cwd } or null

Ordered, confidential setup commands. Command bodies are never returned.

command: string

The shell command to execute.

minLength0
maxLength65536
cwd: optional string or null

The absolute working directory. Defaults to /workspace.

minLength0
maxLength4096
skills: optional array of HostedSkillParam or null

Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list.

One of the following:
SkillReference object { skill_id, type, version }

References a skill uploaded through the Skills API.

skill_id: string

The ID of the skill created through /v1/skills.

minLength1
maxLength64
type: "skill_reference"

The type of the object. Always skill_reference.

version: optional string or null

The skill version, a positive integer or latest; omission selects the default.

minLength0
maxLength1048576
Inline object { description, name, source, type }

Supplies a skill ZIP directly in the session request.

description: string

The skill description declared in SKILL.md.

minLength0
maxLength1048576
name: string

The skill name declared in SKILL.md.

minLength1
maxLength64
source: InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

type: "inline"

The type of the object. Always inline.

SelfHosted object { type, workspace_directory, capability_directories }

An application-hosted environment configured inline.

type: "self_hosted"

The type of the object. Always self_hosted.

workspace_directory: string

Absolute project directory inside the self-hosted environment.

minLength0
maxLength1048576
capability_directories: optional array of string or null

Directories that contain capabilities exposed to the agent. Defaults to an empty list.

HostedEnvironmentFile = HostedEnvironmentFileID { id, file_id, path, 2 more } or object { id, path, size_bytes, type }

Metadata for a file materialized in an OpenAI-hosted execution environment.

One of the following:
HostedEnvironmentFileID object { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "file_id"

The type of the object. Always file_id.

Inline object { id, path, size_bytes, type }

A file supplied inline when the session was created.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

HostedEnvironmentFileID object { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "file_id"

The type of the object. Always file_id.

HostedEnvironmentFileParam = object { file_id, path, type } or object { data, path, type }

A file materialized in an OpenAI-hosted execution environment.

One of the following:
FileID object { file_id, path, type }

A file previously uploaded through the OpenAI Files API.

file_id: string

The ID of the uploaded file.

minLength1
maxLength256
path: string

The absolute destination path inside /workspace.

minLength1
maxLength4096
type: "file_id"

The type of the object. Always file_id.

Inline object { data, path, type }

A file supplied directly as standard-base64 data.

data: string

The standard-base64-encoded file contents.

minLength0
maxLength6990508
path: string

The absolute destination path inside /workspace.

minLength1
maxLength4096
type: "inline"

The type of the object. Always inline.

HostedPlugin object { description, name, type }

A plugin installed from an inline ZIP archive.

description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

HostedPluginParam object { description, name, source, type }

Supplies a plugin ZIP directly in the session request.

description: string

The plugin description declared in .codex-plugin/plugin.json.

minLength0
maxLength1048576
name: string

The plugin name declared in .codex-plugin/plugin.json.

minLength1
maxLength64
source: InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

type: "inline"

The type of the object. Always inline.

HostedSkill = HostedSkillReference { description, name, skill_id, 2 more } or object { description, name, type }

A skill installed in an OpenAI-hosted environment.

One of the following:
HostedSkillReference object { description, name, skill_id, 2 more }

A skill installed from the Skills API.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string

The concrete skill version installed for this session.

minLength0
Inline object { description, name, type }

A skill installed from an inline ZIP archive.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
type: "inline"

The type of the object. Always inline.

HostedSkillParam = object { skill_id, type, version } or object { description, name, source, type }

A skill installed in an OpenAI-hosted environment.

One of the following:
SkillReference object { skill_id, type, version }

References a skill uploaded through the Skills API.

skill_id: string

The ID of the skill created through /v1/skills.

minLength1
maxLength64
type: "skill_reference"

The type of the object. Always skill_reference.

version: optional string or null

The skill version, a positive integer or latest; omission selects the default.

minLength0
maxLength1048576
Inline object { description, name, source, type }

Supplies a skill ZIP directly in the session request.

description: string

The skill description declared in SKILL.md.

minLength0
maxLength1048576
name: string

The skill name declared in SKILL.md.

minLength1
maxLength64
source: InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

type: "inline"

The type of the object. Always inline.

HostedSkillReference object { description, name, skill_id, 2 more }

A skill installed from the Skills API.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string

The concrete skill version installed for this session.

minLength0
InlineCapabilitySourceParam object { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

data: string

Standard-base64 encoded ZIP archive bytes.

minLength1
maxLength70254592
media_type: "application/zip"

The archive media type, always application/zip.

type: "base64"

The type of the object. Always base64.

InputContent = object { text, type } or object { image_url, type }

User-provided content recorded in a session item.

One of the following:
InputText object { text, type }

Text input recorded in a session item.

text: string

The text supplied to the agent.

minLength0
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

Image input recorded in a session item.

image_url: string

The URL of the image supplied to the agent, which may be a base64-encoded data URL.

minLength0
type: "input_image"

The type of the object. Always input_image.

InputContentParam = object { text, type } or object { image_url, type }

Content included in an input message.

One of the following:
InputText object { text, type }

Text input to the model.

text: string

The text sent to the model.

minLength0
maxLength1048576
type: "input_text"

The type of the object. Always input_text.

InputImage object { image_url, type }

Image input to the model.

image_url: string

The URL of the image sent to the model.

minLength0
maxLength1048576
type: "input_image"

The type of the object. Always input_image.

McpTransport = object { server_url, type } or object { args, command, cwd, 2 more }

The transport used to connect to an MCP server.

One of the following:
HTTP object { server_url, type }

Connects to an MCP server over HTTP.

server_url: string

The URL of the MCP server.

minLength0
type: "http"

The type of the object. Always http.

Stdio object { args, command, cwd, 2 more }

Starts an MCP server as a local process.

args: array of string

Arguments passed to the MCP server command.

command: string

The command used to start the MCP server.

minLength0
cwd: string

The working directory used to start the MCP server.

minLength0
env_vars: array of string

Environment variable names inherited from the execution environment.

type: "stdio"

The type of the object. Always stdio.

McpTransportParam = object { server_url, type, authorization, headers } or object { command, cwd, type, 3 more }

The transport used to connect to an MCP server.

One of the following:
HTTP object { server_url, type, authorization, headers }

Connects to an MCP server over HTTP.

server_url: string

The URL of the MCP server.

minLength0
maxLength1048576
type: "http"

The type of the object. Always http.

authorization: optional string or null

The authorization value sent to the MCP server, if any.

minLength0
maxLength1048576
headers: optional map[string] or null

Additional HTTP headers sent to the MCP server.

Stdio object { command, cwd, type, 3 more }

Starts an MCP server as a local process.

command: string

The command used to start the MCP server.

minLength0
maxLength1048576
cwd: string

The working directory used to start the MCP server.

minLength0
maxLength1048576
type: "stdio"

The type of the object. Always stdio.

args: optional array of string or null

Arguments passed to the MCP server command.

env: optional map[string] or null

Environment variables set for the MCP server process.

env_vars: optional array of string or null

Environment variable names to inherit from the selected execution environment.

MultiAgentConfig object { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled. Defaults to false.

max_concurrent_subagents: number or null

Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.

formatint64
minimum1
maximum4294967295
MultiAgentConfigParam object { enabled, max_concurrent_subagents }

Explicit configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled.

max_concurrent_subagents: optional number

Maximum number of subagents that may run concurrently. Defaults to 6.

formatint64
minimum1
maximum4294967295
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

PersistedAgentTool = object { defer_loading, description, name, 2 more } or object { type } or object { enabled, type } or 2 more

A credential-free tool available to a reusable agent.

One of the following:
Function object { defer_loading, description, name, 2 more }

A function defined by the application.

defer_loading: boolean

Whether the function is deferred and discovered through tool search.

description: string

A description of what the function does.

minLength0
name: string

The name of the function.

minLength0
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

ToolSearch object { type }

Discovers deferred function tools and loads them into the model context.

type: "tool_search"

The type of the object. Always tool_search.

ProgrammaticToolCalling object { enabled, type }

Enables calling tools from model-generated code.

enabled: boolean

Whether tools can be called from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

Tools provided by a remote MCP server without stored credentials.

allowed_tools: array of string or null

The MCP tools the agent may call, or null when all server tools are allowed.

connection_origin: "service" or "environment"

Where outbound MCP HTTP connections originate.

One of the following:
"service"
"environment"
credential_id: string or null

The vault credential selected for this MCP server, if any.

minLength0
request_metadata: map[unknown]

Metadata included with requests to this MCP server.

required: boolean

Whether this MCP server must initialize before the first turn.

server_label: string

A label used to identify the MCP server in tool calls.

minLength0

The credential-free transport used to connect to the MCP server.

type: "mcp"

The type of the object. Always mcp.

WebSearch object { allowed_domains, context_size, location, 2 more }

Web search.

allowed_domains: array of string or null

Allowed search domains, or null when the search is unrestricted.

context_size: "low" or "medium" or "high"

The amount of search context made available to the model. Defaults to medium.

One of the following:
"low"
"medium"
"high"
location: object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: string or null

The city name.

minLength0
country: string or null

The two-letter ISO country code, such as US.

minLength0
region: string or null

The region or state name.

minLength0
timezone: string or null

The IANA timezone, such as America/Los_Angeles.

minLength0
mode: "disabled" or "cached" or "live"

The source used for web search results.

One of the following:
"disabled"
"cached"
"live"
type: "web_search"

The type of the object. Always web_search.

PersistedAgentToolParam = object { description, name, parameters, 2 more } or object { type } or object { type, enabled } or 2 more

A tool that can be stored on a reusable agent without session credentials.

One of the following:
Function object { description, name, parameters, 2 more }

A function defined by the application.

description: string

A description of what the function does.

minLength0
maxLength1048576
name: string

The name of the function.

minLength0
maxLength1048576
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

defer_loading: optional boolean

Whether this function is deferred and discovered through tool search. Defaults to false.

ToolSearch object { type }

Discovers deferred function tools and loads them into the model context.

type: "tool_search"

The type of the object. Always tool_search.

ProgrammaticToolCalling object { type, enabled }

Enables calling tools from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

enabled: optional boolean

Whether tools can be called from model-generated code. Defaults to true.

Mcp object { server_label, transport, type, 5 more }

Tools provided by a remote MCP server without stored credentials.

server_label: string

A label used to identify the MCP server in tool calls.

minLength0
maxLength1048576

The credential-free transport used to connect to the MCP server.

type: "mcp"

The type of the object. Always mcp.

allowed_tools: optional array of string or null

The MCP tools the agent may call. All server tools are allowed when omitted.

connection_origin: optional "service" or "environment" or null

Where outbound MCP HTTP connections originate.

One of the following:
"service"

Uses the Managed Agents service network.

"environment"

Uses the session’s execution environment.

credential_id: optional string or null

The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL.

minLength0
maxLength1048576
request_metadata: optional map[unknown] or null

Metadata included with requests to this MCP server.

required: optional boolean

Whether this MCP server must initialize before the first turn. Defaults to false.

WebSearch object { type, allowed_domains, context_size, 2 more }

Web search.

type: "web_search"

The type of the object. Always web_search.

allowed_domains: optional array of string or null

Domains the search may include.

context_size: optional "low" or "medium" or "high" or null

The amount of web search context made available to the model.

One of the following:
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: optional string or null

The city name.

minLength0
maxLength1048576
country: optional string or null

The two-letter ISO country code, such as US.

minLength0
maxLength1048576
region: optional string or null

The region or state name.

minLength0
maxLength1048576
timezone: optional string or null

The IANA timezone, such as America/Los_Angeles.

minLength0
maxLength1048576
mode: optional "disabled" or "cached" or "live" or null

The source used for web search results.

One of the following:
"disabled"

Disables web search.

"cached"

Uses cached search results.

"live"

Searches the live web.

PersistedMcpTransport = object { headers, server_url, type } or object { args, command, cwd, 2 more }

A credential-free transport used to connect to an MCP server.

One of the following:
HTTP object { headers, server_url, type }

Connects to an MCP server over HTTP.

headers: map[string]

Non-secret HTTP headers sent to the MCP server.

server_url: string

The URL of the MCP server.

minLength0
type: "http"

The type of the object. Always http.

Stdio object { args, command, cwd, 2 more }

Starts an MCP server as a local process.

args: array of string

Arguments passed to the MCP server command.

command: string

The command used to start the MCP server.

minLength0
cwd: string

The working directory used to start the MCP server.

minLength0
env_vars: array of string

Environment variable names inherited from the execution environment.

type: "stdio"

The type of the object. Always stdio.

PersistedMcpTransportParam = object { server_url, type, headers } or object { command, cwd, type, 2 more }

A credential-free transport used to connect to an MCP server.

One of the following:
HTTP object { server_url, type, headers }

Connects to an MCP server over HTTP.

server_url: string

The URL of the MCP server.

minLength0
maxLength1048576
type: "http"

The type of the object. Always http.

headers: optional map[string] or null

Non-secret HTTP headers sent to the MCP server.

Stdio object { command, cwd, type, 2 more }

Starts an MCP server as a local process.

command: string

The command used to start the MCP server.

minLength0
maxLength1048576
cwd: string

The working directory used to start the MCP server.

minLength0
maxLength1048576
type: "stdio"

The type of the object. Always stdio.

args: optional array of string or null

Arguments passed to the MCP server command.

env_vars: optional array of string or null

Environment variable names to inherit from the selected execution environment.

SessionError object { code, message, param, type }

An error payload with the same public fields as Responses API streaming errors.

code: string or null

The machine-readable error code, if any.

minLength0
message: string

A customer-safe explanation of the error.

minLength0
param: string or null

The request parameter associated with the error, if any.

minLength0
type: string

The error type.

minLength0
SessionTurnError object { code, message }

A customer-safe error describing why a session request failed.

code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 13 more

A stable, machine-readable failure category.

One of the following:
"context_length_exceeded"

The request exceeds the model’s context window.

"session_budget_exceeded"

The session has reached its usage budget.

"usage_limit_exceeded"

The organization has reached a usage, plan, or billing limit.

"rate_limit_exceeded"

The request exceeds the available rate limit.

"server_overloaded"

The model service is temporarily overloaded.

"cyber_policy"

The request was rejected by a safety policy.

"connection_failed"

The request could not connect to the model service.

"server_error"

The model service encountered an unexpected error.

"authentication_error"

The API credentials are invalid or lack the required access.

"invalid_request"

The request contains invalid input or configuration.

"resource_not_found"

The requested model or resource is unavailable.

"sandbox_error"

The request could not complete in its execution environment.

"executor_version_incompatible"

The executor must be upgraded before it can run this turn.

"active_turn_not_steerable"

The session cannot accept additional input while a request is running.

"request_timeout"

The request timed out before the model service responded.

"internal_error"

An unexpected internal error prevented the session request from completing.

message: string

A customer-safe explanation of the failure.

minLength0
SetupCommandParam object { command, cwd }

A confidential setup command executed before the hosted agent starts.

command: string

The shell command to execute.

minLength0
maxLength65536
cwd: optional string or null

The absolute working directory. Defaults to /workspace.

minLength0
maxLength4096
Subagent object { id, closed_at, instructions, 6 more }

A subagent created within a session.

id: string

The ID of the subagent.

minLength0
closed_at: number or null

The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume.

formatint64
instructions: array of AgentContent or null

Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available.

One of the following:
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text"

The content type. Always output_text.

EncryptedContent object { encrypted_content, type }

Encrypted content exchanged between agents.

encrypted_content: string

The encrypted content payload.

minLength0
type: "encrypted_content"

The content type. Always encrypted_content.

name: string or null

The runner-assigned nickname, or null when unavailable.

minLength0
object: "agent.session.subagent"

The object type. Always agent.session.subagent.

opened_at: number

The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it.

formatint64
parent_agent_id: string

The ID of the agent that created this subagent.

minLength0
session_id: string

The ID of the session that owns the subagent.

minLength0
status: "active" or "closed"

The current status of the subagent.

One of the following:
"active"

The subagent remains available, including while idle between turns.

"closed"

The subagent is closed.

SummaryText object { text, type }

A reasoning summary content part.

text: string

The reasoning summary text.

minLength0
type: "summary_text"

The content type. Always summary_text.

TextFormat = object { type } or object { schema, type }

The effective output format for generated text.

One of the following:
Text object { type }

Generates ordinary text without a structured-output constraint.

type: "text"

The type of the object. Always text.

JSONSchema object { schema, type }

Constrains generated text to a JSON Schema.

schema: map[unknown]

The JSON Schema that generated text must match.

type: "json_schema"

The type of the object. Always json_schema.

TextFormatParam = object { type } or object { schema, type }

The output format for generated text.

One of the following:
Text object { type }

Generates ordinary text without a structured-output constraint.

type: "text"

The type of the object. Always text.

JSONSchema object { schema, type }

Constrains generated text to a JSON Schema.

schema: map[unknown]

The JSON Schema that generated text must match.

type: "json_schema"

The type of the object. Always json_schema.

TokenUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }

Recorded token usage for a session or turn. Usage is best effort and may change.

input_tokens: number

The number of input tokens used by the agent.

formatint64
input_tokens_details: object { cached_tokens }

A breakdown of the agent’s input token usage.

cached_tokens: number

The number of input tokens retrieved from the prompt cache.

formatint64
output_tokens: number

The number of output tokens generated by the agent.

formatint64
output_tokens_details: object { reasoning_tokens }

A breakdown of the agent’s output token usage.

reasoning_tokens: number

The number of output tokens used for reasoning.

formatint64
total_tokens: number

The total number of input and output tokens used by the agent.

formatint64
WebSearchAction = object { queries, query, type } or object { type, url } or object { pattern, type, url } or object { type }

An action performed by the web search tool.

One of the following:
Search object { queries, query, type }

A search query or group of search queries.

queries: array of string or null

The search queries, when multiple queries were used.

query: string or null

The search query, when a single query was used.

minLength0
type: "search"

The type of the object. Always search.

OpenPage object { type, url }

Opens a web page.

type: "open_page"

The type of the object. Always open_page.

url: string or null

The URL of the page that was opened.

minLength0
FindInPage object { pattern, type, url }

Finds text within a web page.

pattern: string or null

The text pattern that was searched for.

minLength0
type: "find_in_page"

The type of the object. Always find_in_page.

url: string or null

The URL of the page that was searched.

minLength0
Other object { type }

Another web search action.

type: "other"

The type of the object. Always other.

AgentsEnvironments

Retrieve an agent environment
GET/agents/environments/{environment_id}
ModelsExpand Collapse
EnvironmentInfo object { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

id: string

The ID of the environment.

minLength0
files: array of HostedEnvironmentFile

Files installed in the environment, without their contents.

One of the following:
HostedEnvironmentFileID object { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "file_id"

The type of the object. Always file_id.

Inline object { id, path, size_bytes, type }

A file supplied inline when the session was created.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

object: "agent.environment"

The object type. Always agent.environment.

plugins: array of HostedPlugin { description, name, type }

Plugins installed in the environment, without their archive contents.

description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

skills: array of HostedSkill

Skills installed in the environment, without their archive contents.

One of the following:
HostedSkillReference object { description, name, skill_id, 2 more }

A skill installed from the Skills API.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string

The concrete skill version installed for this session.

minLength0
Inline object { description, name, type }

A skill installed from an inline ZIP archive.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
type: "inline"

The type of the object. Always inline.

status: "pending" or "connected" or "disconnected" or 2 more

The current environment connection status.

One of the following:
"pending"
"connected"
"disconnected"
"expired"
"failed"
type: "openai_hosted" or "self_hosted"

Whether the environment is hosted by OpenAI or by the application.

One of the following:
"openai_hosted"
"self_hosted"

AgentsEnvironmentsFiles

Create an agent environment file
POST/agents/environments/{environment_id}/files
List agent environment files
GET/agents/environments/{environment_id}/files
ModelsExpand Collapse
EnvironmentFile object { environment_id, object, path, size_bytes }

A live file in an execution environment.

environment_id: string

The ID of the environment containing this file.

minLength0
object: "agent.environment.file"

The object type. Always agent.environment.file.

path: string

The absolute file path inside the environment’s workspace.

minLength0
size_bytes: number

The file size in bytes.

formatint64
minimum0

AgentsEnvironmentsTemplates

Create an agent environment template
POST/agents/environments/templates
Delete an agent environment template
DELETE/agents/environments/templates/{environment_template_id}
List agent environment templates
GET/agents/environments/templates
Retrieve an agent environment template
GET/agents/environments/templates/{environment_template_id}
Update an agent environment template
POST/agents/environments/templates/{environment_template_id}
ModelsExpand Collapse
EnvironmentTemplate object { id, capability_directories, created_at, 8 more }

Reusable configuration that provisions a fresh OpenAI-hosted environment for each session.

id: string

The ID of the reusable environment template.

minLength0
capability_directories: array of string

Directories that expose capabilities to the agent.

created_at: number

The Unix timestamp, in seconds, when the template was created.

formatint64
files: array of object { file_id, path, type } or object { path, size_bytes, type }

Safe file metadata, excluding contents and session-scoped file IDs.

One of the following:
FileID object { file_id, path, type }

A project-scoped Files API reference resolved separately for each session.

file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
type: "file_id"

The type of the object. Always file_id.

Inline object { path, size_bytes, type }

Metadata for confidential inline file contents.

path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded size of the inline file in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

name: string or null

An optional human-readable display name for the template.

minLength0
network: object { access, allowed_domains }

Runtime network access for each OpenAI-hosted environment.

access: "enabled" or "disabled" or "restricted"

The environment’s network access mode.

One of the following:
"enabled"

Allows unrestricted network access.

"disabled"

Disables network access.

"restricted"

Allows access only to configured domains.

allowed_domains: array of string

Domains the environment may access when network access is restricted.

object: "agent.environment.template"

The object type. Always agent.environment.template.

packages: object { npm, python, system }

Packages installed in each fresh OpenAI-hosted environment.

npm: array of string

npm packages installed globally in the environment.

python: array of string

Python packages installed in the environment.

system: array of string

System packages installed in the environment.

plugins: array of HostedPlugin { description, name, type }

Safe plugin metadata, excluding inline archive contents.

description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

skills: array of object { skill_id, type, version } or object { description, name, type }

Safe skill metadata, preserving unresolved version selectors.

One of the following:
SkillReference object { skill_id, type, version }

A skill resolved afresh from the Skills API whenever a session starts.

skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string or null

The requested version selector, including latest.

minLength0
Inline object { description, name, type }

Safe metadata for an inline skill archive.

description: string

The skill description declared in SKILL.md.

minLength0
name: string

The skill name declared in SKILL.md.

minLength0
type: "inline"

The type of the object. Always inline.

updated_at: number

The Unix timestamp, in seconds, when the template was last updated.

formatint64
EnvironmentTemplateDeleted object { id, deleted, object }

A deleted reusable environment template.

id: string

The ID of the deleted environment template.

minLength0
deleted: boolean

Whether the environment template was deleted. Always true.

object: "agent.environment.template.deleted"

The object type. Always agent.environment.template.deleted.

AgentsSessions

Create an agent session
POST/agents/sessions
Delete an agent session
DELETE/agents/sessions/{session_id}
List agent sessions
GET/agents/sessions
Retrieve an agent session
GET/agents/sessions/{session_id}
Update an agent session
POST/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content
GET/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
DELETE/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
GET/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
GET/agents/sessions/{session_id}/artifacts/{artifact_id}
ModelsExpand Collapse
SessionArtifact object { id, created_at, environment_id, 5 more }

An immutable file published by a completed hosted session turn.

id: string

The immutable artifact ID.

minLength0
created_at: number

The Unix timestamp, in seconds, when the artifact was published.

formatint64
environment_id: string

The ID of the environment that produced the artifact.

minLength0
object: "agent.session.artifact"

The object type. Always agent.session.artifact.

path: string

The original absolute file path in the execution environment.

minLength0
session_id: string

The ID of the session that owns the artifact.

minLength0
size_bytes: number

The immutable artifact size in bytes.

formatint64
minimum0
turn_id: string

The ID of the completed turn that published the artifact.

minLength0
SessionArtifactDeleted object { id, deleted, object }

Confirmation that an immutable session artifact was deleted.

id: string

The ID of the deleted session artifact.

minLength0
deleted: boolean

Whether the session artifact was deleted. Always true.

object: "agent.session.artifact.deleted"

The object type. Always agent.session.artifact.deleted.

AgentsSessionsEvents

Create agent session input events
POST/agents/sessions/{session_id}/events
Stream agent session events
GET/agents/sessions/{session_id}/events

AgentsSessionsItems

List agent session items
GET/agents/sessions/{session_id}/items

AgentsSessionsSubagents

List session subagents
GET/agents/sessions/{session_id}/subagents
Retrieve a session subagent
GET/agents/sessions/{session_id}/subagents/{subagent_id}

AgentsSessionsSubagentsItems

List subagent items
GET/agents/sessions/{session_id}/subagents/{subagent_id}/items

AgentsSessionsSubagentsTurns

List subagent turns
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

AgentsSessionsSubagentsTurnsItems

List subagent turn items
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items

AgentsSessionsTurns

List agent session turns
GET/agents/sessions/{session_id}/turns
Retrieve an agent session turn
GET/agents/sessions/{session_id}/turns/{turn_id}
ModelsExpand Collapse
Turn object { id, agent_id, completed_at, 8 more }

The canonical public representation of a session turn.

id: string

The ID of the turn.

minLength0
agent_id: string

The ID of the agent that ran the turn.

minLength0
completed_at: number or null

The Unix timestamp, in seconds, when the turn reached a terminal state.

formatint64
created_at: number

The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable.

formatint64
error: SessionTurnError { code, message } or null

A customer-safe error describing why a session request failed.

object: "agent.session.turn"

The object type. Always agent.session.turn.

session_id: string

The ID of the session that owns the turn.

minLength0
started_at: number or null

The Unix timestamp, in seconds, when the turn started.

formatint64
status: "queued" or "in_progress" or "waiting" or 3 more

The current status of the turn.

One of the following:
"queued"

The turn is waiting to start.

"in_progress"

The turn is in progress.

"waiting"

The turn is waiting for external input.

"completed"

The turn completed successfully.

"failed"

The turn failed.

"cancelled"

The turn was cancelled.

subagent_id: string or null

The ID of the subagent that ran the turn, if applicable.

minLength0
usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Recorded token usage for a session or turn. Usage is best effort and may change.

AgentsVaults

Create a vault
POST/vaults
Delete a vault
DELETE/vaults/{vault_id}
List vaults
GET/vaults
Retrieve a vault
GET/vaults/{vault_id}
ModelsExpand Collapse
Vault object { id, created_at, metadata, 2 more }

A collection of credentials that agent tools can use to authenticate to MCP servers.

id: string

The ID of the vault.

minLength0
created_at: number

The Unix timestamp, in seconds, when the vault was created.

formatint64
metadata: map[string]

Key-value pairs associated with the vault, such as an application or team identifier.

name: string or null

The human-readable name of the vault, if set.

minLength0
object: "vault"

The object type. Always vault.

VaultDeleted object { id, deleted, object }

Confirmation that a vault was deleted.

id: string

The ID of the deleted vault.

minLength0
deleted: boolean

Whether the resource was deleted. Always true.

object: "vault.deleted"

The object type. Always vault.deleted.

VaultStatus = "active" or "archived"

Whether a vault or credential is active or archived.

One of the following:
"active"
"archived"
VaultStatusFilter = VaultStatus or array of VaultStatus

One or more lifecycle statuses to include when listing vaults or credentials.

One of the following:
VaultStatus = "active" or "archived"

Whether a vault or credential is active or archived.

One of the following:
"active"
"archived"
array of VaultStatus
One of the following:
"active"
"archived"

AgentsVaultsCredentials

Create a vault credential
POST/vaults/{vault_id}/credentials
Delete a vault credential
DELETE/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
GET/vaults/{vault_id}/credentials
Retrieve a vault credential
GET/vaults/{vault_id}/credentials/{credential_id}
Rotate a vault credential
POST/vaults/{vault_id}/credentials/{credential_id}
ModelsExpand Collapse
Credential object { id, auth, created_at, 4 more }

Metadata for a stored MCP server credential. Secret values are never returned.

id: string

The ID of the credential.

minLength0

The authentication method and non-secret configuration for the MCP server.

created_at: number

The Unix timestamp, in seconds, when the credential was created.

formatint64
name: string

The human-readable name of the credential.

minLength0
object: "vault.credential"

The object type. Always vault.credential.

updated_at: number

The Unix timestamp, in seconds, when the credential was last updated.

formatint64
vault_id: string

The ID of the vault containing this credential.

minLength0
CredentialAuth = object { expires_at, mcp_server_url, refresh, type } or object { mcp_server_url, type }

The MCP server and authentication configuration of a vault credential, excluding secrets.

One of the following:
McpOauth object { expires_at, mcp_server_url, refresh, type }

Public metadata for an OAuth credential; tokens and client secrets are never returned.

expires_at: string or null

When the OAuth access token expires, as an RFC 3339 timestamp, if known.

minLength0
mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
refresh: object { client_id, resource, scope, 2 more } or null

Configuration used to refresh an MCP OAuth access token, excluding secret values.

client_id: string

The OAuth client ID used when requesting a new access token.

minLength0
resource: string or null

The resource URI sent to the OAuth token endpoint during refresh, if configured.

minLength0
scope: string or null

Space-separated OAuth scopes requested during refresh, if configured.

minLength0
token_endpoint: string

The HTTPS OAuth token endpoint used for refresh.

minLength0
token_endpoint_auth: McpOauthTokenEndpointAuth

How the OAuth client authenticates to the token endpoint, excluding its client secret.

type: "mcp_oauth"

The type of the object. Always mcp_oauth.

StaticBearer object { mcp_server_url, type }

Metadata for a bearer-token credential, without automatic OAuth refresh.

mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
type: "static_bearer"

The type of the object. Always static_bearer.

CredentialAuthCreateParam = object { access_token, mcp_server_url, type, 2 more } or object { token, mcp_server_url, type }

Authentication credentials for an MCP server used by agent tools.

One of the following:
McpOauth object { access_token, mcp_server_url, type, 2 more }

An OAuth credential for an HTTPS MCP destination.

access_token: string

A write-only OAuth access token; never returned by credential resources.

minLength0
maxLength1048576
mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
maxLength1048576
type: "mcp_oauth"

The type of the object. Always mcp_oauth.

expires_at: optional string or null

When the OAuth access token expires, as an RFC 3339 timestamp, if known.

minLength0
maxLength1048576
refresh: optional object { client_id, refresh_token, token_endpoint, 3 more } or null

Configuration for refreshing the access token of an MCP OAuth credential.

client_id: string

The OAuth client ID used when requesting a new access token.

minLength0
maxLength1048576
refresh_token: string

The refresh token to store. This secret is never returned in credential resources.

minLength0
maxLength1048576
token_endpoint: string

The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token.

minLength0
maxLength1048576

How the OAuth client authenticates to the token endpoint.

resource: optional string or null

The resource URI to send to the OAuth token endpoint during refresh, if required.

minLength0
maxLength1048576
scope: optional string or null

Space-separated OAuth scopes to request during refresh, if required.

minLength0
maxLength1048576
StaticBearer object { token, mcp_server_url, type }

A bearer token for an MCP server, without automatic OAuth refresh.

token: string

The bearer token to store. This secret is never returned in credential resources.

minLength0
maxLength1048576
mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
maxLength1048576
type: "static_bearer"

The type of the object. Always static_bearer.

CredentialAuthRotateParam = object { type, access_token, expires_at, refresh } or object { token, type }

Updates to a vault credential without changing its authentication method or MCP server.

One of the following:
McpOauth object { type, access_token, expires_at, refresh }

Rotate an OAuth credential for an HTTPS MCP destination.

type: "mcp_oauth"

The type of the object. Always mcp_oauth.

access_token: optional string or null

A write-only replacement OAuth access token.

minLength0
maxLength1048576
expires_at: optional string or null

The replacement expiry as an RFC 3339 timestamp, or null to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared.

minLength0
maxLength1048576
refresh: optional object { refresh_token, scope, token_endpoint_auth } or null

Updates to an MCP credential’s existing OAuth refresh configuration.

refresh_token: optional string or null

The replacement refresh token. Omit or pass null to keep the stored token. This secret is never returned in resources.

minLength0
maxLength1048576
scope: optional string or null

Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass null to stop sending a scope parameter.

minLength0
maxLength1048576
token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null

Client-secret updates that preserve the credential’s OAuth authentication method.

StaticBearer object { token, type }

Replace the bearer token for the credential’s MCP server.

token: string

The replacement bearer token. This secret is never returned in credential resources.

minLength0
maxLength1048576
type: "static_bearer"

The type of the object. Always static_bearer.

CredentialDeleted object { id, deleted, object }

Confirmation that a vault credential was deleted.

id: string

The ID of the deleted credential.

minLength0
deleted: boolean

Whether the resource was deleted. Always true.

object: "vault.credential.deleted"

The object type. Always vault.credential.deleted.

McpOauthTokenEndpointAuth = object { type } or object { type } or object { type }

The client authentication method used for OAuth token refresh.

One of the following:
None object { type }

Sends the client ID without a client secret.

type: "none"

The type of the object. Always none.

ClientSecretBasic object { type }

Sends the client ID and secret using HTTP Basic authentication.

type: "client_secret_basic"

The type of the object. Always client_secret_basic.

ClientSecretPost object { type }

Sends the client ID and secret in the token request body.

type: "client_secret_post"

The type of the object. Always client_secret_post.

McpOauthTokenEndpointAuthCreateParam = object { type } or object { client_secret, type } or object { client_secret, type }

Client authentication credentials for OAuth token refresh.

One of the following:
None object { type }

Sends the client ID without a client secret.

type: "none"

The type of the object. Always none.

ClientSecretBasic object { client_secret, type }

Sends the client ID and secret using HTTP Basic authentication.

client_secret: string

The OAuth client secret to store. Never returned in credential resources.

minLength0
maxLength1048576
type: "client_secret_basic"

The type of the object. Always client_secret_basic.

ClientSecretPost object { client_secret, type }

Sends the client ID and secret in the token request body.

client_secret: string

The OAuth client secret to store. Never returned in credential resources.

minLength0
maxLength1048576
type: "client_secret_post"

The type of the object. Always client_secret_post.

McpOauthTokenEndpointAuthRotateParam = object { type, client_secret } or object { type, client_secret }

Client-secret updates that preserve the credential’s OAuth authentication method.

One of the following:
ClientSecretBasic object { type, client_secret }

Updates credentials sent using HTTP Basic authentication.

type: "client_secret_basic"

The type of the object. Always client_secret_basic.

client_secret: optional string or null

The replacement OAuth client secret. Omit or pass null to keep the stored secret. This secret is never returned in resources.

minLength0
maxLength1048576
ClientSecretPost object { type, client_secret }

Updates credentials sent in the token request body.

type: "client_secret_post"

The type of the object. Always client_secret_post.

client_secret: optional string or null

The replacement OAuth client secret. Omit or pass null to keep the stored secret. This secret is never returned in resources.

minLength0
maxLength1048576