# Agents ## Create an agent **post** `/agents` Creates a reusable agent without storing credentials. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Body Parameters - `model: string` The model to use for the agent. The requested model name is preserved. - `instructions: optional string or null` Additional instructions appended to the agent's default base instructions. Omit or set to null to add no custom instructions. - `metadata: optional map[string] or null` Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. - `multi_agent: optional MultiAgentConfigParam or null` 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. - `name: optional string or null` A human-readable name for the agent. Omission or null leaves the agent unnamed. - `reasoning: optional AgentReasoningParam or null` 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. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` The reasoning summary format requested from the model. - `"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. - `service_tier: optional "auto" or "default" or "flex" or 2 more or null` The service tier used for model requests. - `"auto"` Selects the service tier automatically. - `"default"` Uses the default service tier. - `"flex"` Uses the flex service tier. - `"priority"` Uses the priority service tier. - `"fast"` Uses the fast service tier. - `text: optional AgentTextParam or null` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. - `tools: optional array of PersistedAgentToolParam or null` Tools available to the agent. Defaults to an empty list. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `transport: PersistedMcpTransportParam` The credential-free transport used to connect to the MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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. - `type: "mcp"` The type of the object. Always `mcp`. - `"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. - `"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. - `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`. - `"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. - `"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. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. ### Returns - `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. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` 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. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `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. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```http curl https://api.openai.com/v1/agents \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "model" }' ``` #### Response ```json { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ``` ## Delete an agent **delete** `/agents/{agent_id}` Deletes a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Path Parameters - `agent_id: string` ### Returns - `AgentDeleted object { id, deleted, object }` A deleted reusable agent. - `id: string` The ID of the deleted agent. - `deleted: boolean` Whether the agent was deleted. Always `true`. - `object: "agent.deleted"` The object type. Always `agent.deleted`. - `"agent.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/$AGENT_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.deleted" } ``` ## List agents **get** `/agents` Lists reusable agents in the current project. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number or null` The maximum number of resources to return. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Agent` The resources returned in this page, in the requested sort order. - `id: string` The ID of the reusable agent. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` 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. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `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. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent **get** `/agents/{agent_id}` Retrieves a reusable agent by ID. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Path Parameters - `agent_id: string` ### Returns - `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. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` 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. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `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. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```http curl https://api.openai.com/v1/agents/$AGENT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ``` ## Update an agent **post** `/agents/{agent_id}` Updates a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Path Parameters - `agent_id: string` ### Body Parameters - `instructions: optional string or null` Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `metadata: optional map[string] or null` Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. - `model: optional string` The model to use for the agent. The requested model name is preserved. - `multi_agent: optional MultiAgentConfigParam or null` 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. - `name: optional string or null` A replacement name. Omit to leave unchanged, or pass null to clear it. - `reasoning: optional AgentReasoningParam or null` 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. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` The reasoning summary format requested from the model. - `"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. - `service_tier: optional "auto" or "default" or "flex" or 2 more or null` The service tier used for model requests. - `"auto"` Selects the service tier automatically. - `"default"` Uses the default service tier. - `"flex"` Uses the flex service tier. - `"priority"` Uses the priority service tier. - `"fast"` Uses the fast service tier. - `text: optional AgentTextParam or null` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. - `tools: optional array of PersistedAgentToolParam or null` Tools available to the agent. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `transport: PersistedMcpTransportParam` The credential-free transport used to connect to the MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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. - `type: "mcp"` The type of the object. Always `mcp`. - `"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. - `"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. - `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`. - `"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. - `"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. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. ### Returns - `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. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` 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. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `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. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```http curl https://api.openai.com/v1/agents/$AGENT_ID \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ``` ## Domain Types ### Agent - `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. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` 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. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `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. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Agent Close Subagent Call Item - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. ### Agent Command Execution Item - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` ### Agent Content - `AgentContent = OutputText or object { encrypted_content, type }` A plaintext or encrypted content part exchanged between agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` ### Agent Create Subagent Call Item - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. ### Agent Deleted - `AgentDeleted object { id, deleted, object }` A deleted reusable agent. - `id: string` The ID of the deleted agent. - `deleted: boolean` Whether the agent was deleted. Always `true`. - `object: "agent.deleted"` The object type. Always `agent.deleted`. - `"agent.deleted"` ### Agent Function Call Item - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` ### Agent Function Call Output - `AgentFunctionCallOutput = string or array of InputContent` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Agent Function Call Output Param - `AgentFunctionCallOutputParam = string or array of InputContentParam` A function result represented as text or supported model-input content. - `string` - `array of InputContentParam` - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Agent Function Call Status - `AgentFunctionCallStatus = "in_progress" or "completed" or "failed" or "incomplete"` The status of a tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. ### Agent Interrupt Subagent Call Item - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. ### Agent Mcp Call Item - `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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` ### Agent Output Command Execution Output Delta Event - `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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the command execution item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.output.command_execution_output.delta"` The type of the object. Always `agent.output.command_execution_output.delta`. - `"agent.output.command_execution_output.delta"` ### Agent Output Item - `AgentOutputItem = AgentSessionAssistantMessage or AgentReasoningItem or AgentFunctionCallItem or 9 more` An output item produced by an agent. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `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. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. ### Agent Output Item Status - `AgentOutputItemStatus = "in_progress" or "completed" or "incomplete"` The status of an agent output item. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. ### Agent Reasoning - `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. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. ### Agent Reasoning Item - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` ### Agent Reasoning Param - `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. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` The reasoning summary format requested from the model. - `"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. ### Agent Resume Subagent Call Item - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. ### Agent Send Subagent Input Call Item - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. ### Agent Session - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Agent Session Assistant Message - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` ### Agent Session Created Event - `AgentSessionCreatedEvent object { event_id, session, type }` Emitted when a session is created. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that was created. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.created"` The type of the object. Always `agent.session.created`. - `"agent.session.created"` ### Agent Session Deleted - `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. - `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`. - `"agent.session.deleted"` ### Agent Session Environment Connected Event - `AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment connects. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.connected"` The type of the object. Always `agent.session.environment.connected`. - `"agent.session.environment.connected"` ### Agent Session Environment Disconnected Event - `AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment disconnects. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.disconnected"` The type of the object. Always `agent.session.environment.disconnected`. - `"agent.session.environment.disconnected"` ### Agent Session Environment Failed Event - `AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment fails. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.failed"` The type of the object. Always `agent.session.environment.failed`. - `"agent.session.environment.failed"` ### Agent Session Environment Pending Event - `AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }` Emitted while a session environment is being prepared. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.pending"` The type of the object. Always `agent.session.environment.pending`. - `"agent.session.environment.pending"` ### Agent Session Environment Ready Event - `AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }` Emitted when a hosted session environment is ready to connect. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.ready"` The type of the object. Always `agent.session.environment.ready`. - `"agent.session.environment.ready"` ### Agent Session Environment State - `AgentSessionEnvironmentState object { id, error, status, type }` The current state of a session environment. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. ### Agent Session Error Event - `AgentSessionErrorEvent object { error, event_id, session_id, type }` Emitted when a turn or session fails. - `error: SessionError` The error that occurred. - `code: string or null` The machine-readable error code, if any. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `type: "error"` The type of the object. Always `error`. - `"error"` ### Agent Session Event - `AgentSessionEvent = AgentSessionErrorEvent or AgentSessionEnvironmentReadyEvent or AgentOutputCommandExecutionOutputDeltaEvent or 27 more` An event emitted by a Managed Agents session. - `AgentSessionErrorEvent object { error, event_id, session_id, type }` Emitted when a turn or session fails. - `error: SessionError` The error that occurred. - `code: string or null` The machine-readable error code, if any. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `type: "error"` The type of the object. Always `error`. - `"error"` - `AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }` Emitted when a hosted session environment is ready to connect. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.ready"` The type of the object. Always `agent.session.environment.ready`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the command execution item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.output.command_execution_output.delta"` The type of the object. Always `agent.output.command_execution_output.delta`. - `"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. - `session: AgentSession` The session that was created. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.created"` The type of the object. Always `agent.session.created`. - `"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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it was created. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` Recorded token usage for a session or turn. Usage is best effort and may change. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.created"` The type of the object. Always `agent.session.turn.created`. - `"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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it started running. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.in_progress"` The type of the object. Always `agent.session.turn.in_progress`. - `"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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The completed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.completed"` The type of the object. Always `agent.session.turn.completed`. - `"agent.session.turn.completed"` - `usage: TokenUsage 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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The failed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.failed"` The type of the object. Always `agent.session.turn.failed`. - `"agent.session.turn.failed"` - `usage: TokenUsage 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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The cancelled turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.cancelled"` The type of the object. Always `agent.session.turn.cancelled`. - `"agent.session.turn.cancelled"` - `usage: TokenUsage 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. - `item: AgentSessionItem` The item that was added. - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"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. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number or null` The index of the item in the turn output, when the item is agent output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.added"` The type of the object. Always `agent.session.turn.item.added`. - `"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. - `session: AgentSession` The session that became idle. - `type: "agent.session.idle"` The type of the object. Always `agent.session.idle`. - `"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. - `session: AgentSession` The session that started processing. - `type: "agent.session.in_progress"` The type of the object. Always `agent.session.in_progress`. - `"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. - `session: AgentSession` The session and its current required actions. - `type: "agent.session.requires_action"` The type of the object. Always `agent.session.requires_action`. - `"agent.session.requires_action"` - `AgentSessionFailedEvent object { event_id, session, type }` Emitted when a session fails. - `event_id: string` The unique ID of the event. - `session: AgentSession` The failed session. - `type: "agent.session.failed"` The type of the object. Always `agent.session.failed`. - `"agent.session.failed"` - `AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }` Emitted while a session environment is being prepared. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.pending"` The type of the object. Always `agent.session.environment.pending`. - `"agent.session.environment.pending"` - `AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment connects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.connected"` The type of the object. Always `agent.session.environment.connected`. - `"agent.session.environment.connected"` - `AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment disconnects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.disconnected"` The type of the object. Always `agent.session.environment.disconnected`. - `"agent.session.environment.disconnected"` - `AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment fails. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.failed"` The type of the object. Always `agent.session.environment.failed`. - `"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. - `subagent: Subagent` The subagent that was created. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.created"` The type of the object. Always `agent.session.subagent.created`. - `"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. - `subagent: Subagent` The subagent that resumed. - `type: "agent.session.subagent.active"` The type of the object. Always `agent.session.subagent.active`. - `"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. - `subagent: Subagent` The subagent that was closed. - `type: "agent.session.subagent.closed"` The type of the object. Always `agent.session.subagent.closed`. - `"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. - `item: AgentOutputItem` The completed output item. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `output_index: number` The index of the output item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.done"` The type of the object. Always `agent.session.turn.item.done`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The initial content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.added"` The type of the object. Always `agent.session.turn.content_part.added`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The completed content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.done"` The type of the object. Always `agent.session.turn.content_part.done`. - `"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. - `delta: string` The text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.delta"` The type of the object. Always `agent.session.turn.output_text.delta`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `text: string` The complete output text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.done"` The type of the object. Always `agent.session.turn.output_text.done`. - `"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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The initial summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.added"` The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. - `"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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The completed summary part. - `session_id: string` The ID of the session associated with the event. - `status: "incomplete" or null` Present as `incomplete` when summary generation was interrupted. - `"incomplete"` - `summary_index: number` The index of the summary part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.done"` The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.delta"` The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. - `"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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `text: string` The complete reasoning summary text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.done"` The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. - `"agent.session.turn.reasoning_summary_text.done"` ### Agent Session Failed Event - `AgentSessionFailedEvent object { event_id, session, type }` Emitted when a session fails. - `event_id: string` The unique ID of the event. - `session: AgentSession` The failed session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.failed"` The type of the object. Always `agent.session.failed`. - `"agent.session.failed"` ### Agent Session Idle Event - `AgentSessionIdleEvent object { event_id, session, type }` Emitted when a session becomes idle. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that became idle. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.idle"` The type of the object. Always `agent.session.idle`. - `"agent.session.idle"` ### Agent Session In Progress Event - `AgentSessionInProgressEvent object { event_id, session, type }` Emitted when a session starts processing a turn. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that started processing. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.in_progress"` The type of the object. Always `agent.session.in_progress`. - `"agent.session.in_progress"` ### Agent Session Input Message Param - `AgentSessionInputMessageParam object { content, role, type }` A user message submitted to a session. - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` ### Agent Session Input Param - `AgentSessionInputParam = object { input, type } or object { type } or object { call_id, success, turn_id, 3 more }` Input submitted to an existing session. - `AgentSessionInputMessage object { input, type }` Adds one or more user messages and starts a turn. - `input: array of AgentSessionInputMessageParam` The user messages to add to the session. - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` - `type: "agent.session.input.message"` The type of the object. Always `agent.session.input.message`. - `"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`. - `"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. - `success: boolean` Whether the function call succeeded. - `turn_id: string` The ID of the turn that requested the function call. - `type: "agent.session.input.tool_result"` The type of the object. Always `agent.session.input.tool_result`. - `"agent.session.input.tool_result"` - `error: optional string or null` The error message when the call failed. - `output: optional AgentFunctionCallOutputParam or null` A function result represented as text or supported model-input content. - `string` - `array of InputContentParam` - `InputText object { text, type }` Text input to the model. - `InputImage object { image_url, type }` Image input to the model. ### Agent Session Item - `AgentSessionItem = AgentSessionMessage or AgentReasoningItem or AgentFunctionCallItem or 11 more` An item associated with a session turn. - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"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. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. ### Agent Session Message - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` ### Agent Session Message Content - `AgentSessionMessageContent = object { text, type } or object { image_url, type } or object { text, type }` A content part in a session message. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` ### Agent Session Requires Action Event - `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. - `session: AgentSession` The session and its current required actions. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.requires_action"` The type of the object. Always `agent.session.requires_action`. - `"agent.session.requires_action"` ### Agent Session Subagent Active Event - `AgentSessionSubagentActiveEvent object { event_id, subagent, type }` Emitted when a closed subagent successfully resumes. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that resumed. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.active"` The type of the object. Always `agent.session.subagent.active`. - `"agent.session.subagent.active"` ### Agent Session Subagent Closed Event - `AgentSessionSubagentClosedEvent object { event_id, subagent, type }` Emitted when a subagent is closed. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was closed. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.closed"` The type of the object. Always `agent.session.subagent.closed`. - `"agent.session.subagent.closed"` ### Agent Session Subagent Created Event - `AgentSessionSubagentCreatedEvent object { event_id, subagent, type }` Emitted when a subagent is created. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was created. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.created"` The type of the object. Always `agent.session.subagent.created`. - `"agent.session.subagent.created"` ### Agent Session Turn Cancelled Event - `AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn is cancelled. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The cancelled turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.cancelled"` The type of the object. Always `agent.session.turn.cancelled`. - `"agent.session.turn.cancelled"` - `usage: TokenUsage or null` Recorded token usage for a session or turn. Usage is best effort and may change. ### Agent Session Turn Completed Event - `AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn completes. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The completed turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.completed"` The type of the object. Always `agent.session.turn.completed`. - `"agent.session.turn.completed"` - `usage: TokenUsage or null` Recorded token usage for a session or turn. Usage is best effort and may change. ### Agent Session Turn Content Part Added Event - `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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The initial content part. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.added"` The type of the object. Always `agent.session.turn.content_part.added`. - `"agent.session.turn.content_part.added"` ### Agent Session Turn Content Part Done Event - `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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The completed content part. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.done"` The type of the object. Always `agent.session.turn.content_part.done`. - `"agent.session.turn.content_part.done"` ### Agent Session Turn Created Event - `AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn is created. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it was created. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.created"` The type of the object. Always `agent.session.turn.created`. - `"agent.session.turn.created"` ### Agent Session Turn Failed Event - `AgentSessionTurnFailedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn fails. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The failed turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.failed"` The type of the object. Always `agent.session.turn.failed`. - `"agent.session.turn.failed"` - `usage: TokenUsage or null` Recorded token usage for a session or turn. Usage is best effort and may change. ### Agent Session Turn In Progress Event - `AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn starts running. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it started running. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.in_progress"` The type of the object. Always `agent.session.turn.in_progress`. - `"agent.session.turn.in_progress"` ### Agent Session Turn Item Added Event - `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. - `item: AgentSessionItem` The item that was added. - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"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. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number or null` The index of the item in the turn output, when the item is agent output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.added"` The type of the object. Always `agent.session.turn.item.added`. - `"agent.session.turn.item.added"` ### Agent Session Turn Item Done Event - `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. - `item: AgentOutputItem` The completed output item. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `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. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number` The index of the output item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.done"` The type of the object. Always `agent.session.turn.item.done`. - `"agent.session.turn.item.done"` ### Agent Session Turn Output Text Delta Event - `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. - `delta: string` The text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.delta"` The type of the object. Always `agent.session.turn.output_text.delta`. - `"agent.session.turn.output_text.delta"` ### Agent Session Turn Output Text Done Event - `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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `text: string` The complete output text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.done"` The type of the object. Always `agent.session.turn.output_text.done`. - `"agent.session.turn.output_text.done"` ### Agent Session Turn Reasoning Summary Part Added Event - `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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The initial summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.added"` The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. - `"agent.session.turn.reasoning_summary_part.added"` ### Agent Session Turn Reasoning Summary Part Done Event - `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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The completed summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `session_id: string` The ID of the session associated with the event. - `status: "incomplete" or null` Present as `incomplete` when summary generation was interrupted. - `"incomplete"` - `summary_index: number` The index of the summary part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.done"` The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. - `"agent.session.turn.reasoning_summary_part.done"` ### Agent Session Turn Reasoning Summary Text Delta Event - `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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.delta"` The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. - `"agent.session.turn.reasoning_summary_text.delta"` ### Agent Session Turn Reasoning Summary Text Done Event - `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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `text: string` The complete reasoning summary text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.done"` The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. - `"agent.session.turn.reasoning_summary_text.done"` ### Agent Text - `AgentText object { format, verbosity }` The text configuration used by an agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` ### Agent Text Param - `AgentTextParam object { format, verbosity }` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. ### Agent Tool - `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. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` ### Agent Tool Param - `AgentToolParam = object { description, name, parameters, 2 more } or object { type } or object { type, enabled } or 2 more` A tool available to the agent. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `transport: McpTransportParam` The transport used to connect to the MCP server. - `HTTP object { server_url, type, authorization, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `authorization: optional string or null` The authorization value sent to the MCP server, if any. - `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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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. - `type: "mcp"` The type of the object. Always `mcp`. - `"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. - `"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. - `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`. - `"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. - `"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. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. ### Agent Wait For Subagents Call Item - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. ### Agent Web Search Call Item - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` ### Environment - `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. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. ### Environment Param - `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. - `None object { type }` Runs the agent without an execution environment. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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. - `files: optional array of HostedEnvironmentFileParam or null` Files available before the agent starts. Defaults to an empty list. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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 or null` Plugins provided as inline ZIP archives. Defaults to an empty list. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Ordered, confidential setup commands. Command bodies are never returned. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - `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`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"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`. - `"self_hosted"` - `workspace_directory: string` Absolute project directory inside the self-hosted environment. - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. ### Hosted Environment File - `HostedEnvironmentFile = HostedEnvironmentFileID or object { id, path, size_bytes, type }` Metadata for a file materialized in an OpenAI-hosted execution environment. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Environment File ID - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` ### Hosted Environment File Param - `HostedEnvironmentFileParam = object { file_id, path, type } or object { data, path, type }` A file materialized in an OpenAI-hosted execution environment. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Plugin - `HostedPlugin object { description, name, type }` A plugin installed from an inline ZIP archive. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Plugin Param - `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`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Skill - `HostedSkill = HostedSkillReference or object { description, name, type }` A skill installed in an OpenAI-hosted environment. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Skill Param - `HostedSkillParam = object { skill_id, type, version } or object { description, name, source, type }` A skill installed in an OpenAI-hosted environment. - `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`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Skill Reference - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. ### Inline Capability Source Param - `InlineCapabilitySourceParam object { data, media_type, type }` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` ### Input Content - `InputContent = object { text, type } or object { image_url, type }` User-provided content recorded in a session item. - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Input Content Param - `InputContentParam = object { text, type } or object { image_url, type }` Content included in an input message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Mcp Transport - `McpTransport = object { server_url, type } or object { args, command, cwd, 2 more }` The transport used to connect to an MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` ### Mcp Transport Param - `McpTransportParam = object { server_url, type, authorization, headers } or object { command, cwd, type, 3 more }` The transport used to connect to an MCP server. - `HTTP object { server_url, type, authorization, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `authorization: optional string or null` The authorization value sent to the MCP server, if any. - `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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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. ### Multi Agent Config - `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. ### Multi Agent Config Param - `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. ### Output Text - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` ### Persisted Agent Tool - `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. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `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. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` ### Persisted Agent Tool Param - `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. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `transport: PersistedMcpTransportParam` The credential-free transport used to connect to the MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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. - `type: "mcp"` The type of the object. Always `mcp`. - `"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. - `"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. - `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`. - `"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. - `"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. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. ### Persisted Mcp Transport - `PersistedMcpTransport = object { headers, server_url, type } or object { args, command, cwd, 2 more }` A credential-free transport used to connect to an MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` ### Persisted Mcp Transport Param - `PersistedMcpTransportParam = object { server_url, type, headers } or object { command, cwd, type, 2 more }` A credential-free transport used to connect to an MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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. ### Session Error - `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. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. ### Session Turn Error - `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 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. ### Setup Command Param - `SetupCommandParam object { command, cwd }` A confidential setup command executed before the hosted agent starts. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. ### Subagent - `Subagent object { id, closed_at, instructions, 6 more }` A subagent created within a session. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. ### Summary Text - `SummaryText object { text, type }` A reasoning summary content part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` ### Text Format - `TextFormat = object { type } or object { schema, type }` The effective output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` ### Text Format Param - `TextFormatParam = object { type } or object { schema, type }` The output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` ### Token Usage - `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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. ### Web Search Action - `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. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` # Environments ## Retrieve an agent environment **get** `/agents/environments/{environment_id}` Retrieves an execution environment's connection status and safe installed metadata. See [environment lifecycle](/api/docs/guides/agents-api/environments/lifecycle). ### Path Parameters - `environment_id: string` ### Returns - `EnvironmentInfo object { id, files, object, 4 more }` Safe metadata for a first-class execution environment. - `id: string` The ID of the environment. - `files: array of HostedEnvironmentFile` Files installed in the environment, without their contents. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `object: "agent.environment"` The object type. Always `agent.environment`. - `"agent.environment"` - `plugins: array of HostedPlugin` Plugins installed in the environment, without their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, without their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `status: "pending" or "connected" or "disconnected" or 2 more` The current environment connection status. - `"pending"` - `"connected"` - `"disconnected"` - `"expired"` - `"failed"` - `type: "openai_hosted" or "self_hosted"` Whether the environment is hosted by OpenAI or by the application. - `"openai_hosted"` - `"self_hosted"` ### Example ```http curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "files": [ { "id": "id", "file_id": "file_id", "path": "path", "size_bytes": 0, "type": "file_id" } ], "object": "agent.environment", "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "description": "description", "name": "name", "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "status": "pending", "type": "openai_hosted" } ``` ## Domain Types ### Environment Info - `EnvironmentInfo object { id, files, object, 4 more }` Safe metadata for a first-class execution environment. - `id: string` The ID of the environment. - `files: array of HostedEnvironmentFile` Files installed in the environment, without their contents. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `object: "agent.environment"` The object type. Always `agent.environment`. - `"agent.environment"` - `plugins: array of HostedPlugin` Plugins installed in the environment, without their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, without their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `status: "pending" or "connected" or "disconnected" or 2 more` The current environment connection status. - `"pending"` - `"connected"` - `"disconnected"` - `"expired"` - `"failed"` - `type: "openai_hosted" or "self_hosted"` Whether the environment is hosted by OpenAI or by the application. - `"openai_hosted"` - `"self_hosted"` # Files ## Create an agent environment file **post** `/agents/environments/{environment_id}/files` Copies inline bytes or a Files API file into a connected execution environment. See [environment files](/api/docs/guides/agents-api/environments/files). ### Path Parameters - `environment_id: string` ### Body Parameters - `hosted_environment_file_param: HostedEnvironmentFileParam` A file materialized in an OpenAI-hosted execution environment. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Returns - `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. - `object: "agent.environment.file"` The object type. Always `agent.environment.file`. - `"agent.environment.file"` - `path: string` The absolute file path inside the environment's workspace. - `size_bytes: number` The file size in bytes. ### Example ```http curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID/files \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "environment_id": "environment_id", "object": "agent.environment.file", "path": "path", "size_bytes": 0 } ``` ## List agent environment files **get** `/agents/environments/{environment_id}/files` Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination. See [environment files](/api/docs/guides/agents-api/environments/files). ### Path Parameters - `environment_id: string` ### Query Parameters - `limit: optional number or null` The maximum number of files to return, between 1 and 100. - `order: optional "asc" or "desc"` Sort by case-sensitive path components. Defaults to descending. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. - `page: optional string` The opaque token from the previous page. Keep the same path, order, and limit. - `path: optional string or null` Restrict the listing to this absolute workspace directory. ### Returns - `data: array of EnvironmentFile` Files available on the current page. - `environment_id: string` The ID of the environment containing this file. - `object: "agent.environment.file"` The object type. Always `agent.environment.file`. - `"agent.environment.file"` - `path: string` The absolute file path inside the environment's workspace. - `size_bytes: number` The file size in bytes. - `has_more: boolean` Whether more files follow this page. - `next: string or null` The opaque cursor to use when requesting the next page, if any. - `object: "page"` The object type. Always `page`. - `"page"` ### Example ```http curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID/files \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "environment_id": "environment_id", "object": "agent.environment.file", "path": "path", "size_bytes": 0 } ], "has_more": true, "next": "next", "object": "page" } ``` ## Domain Types ### Environment File - `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. - `object: "agent.environment.file"` The object type. Always `agent.environment.file`. - `"agent.environment.file"` - `path: string` The absolute file path inside the environment's workspace. - `size_bytes: number` The file size in bytes. # Templates ## Create an agent environment template **post** `/agents/environments/templates` Creates reusable environment configuration without returning confidential setup commands or environment values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Body Parameters - `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. - `files: optional array of HostedEnvironmentFileParam or null` Files available before the agent starts. Defaults to an empty list. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: optional string or null` An optional human-readable display name for the template. - `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. - `"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 or null` Plugins provided as inline ZIP archives. Defaults to an empty list. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Ordered, confidential setup commands. Command bodies are never returned. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - `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`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Returns - `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. - `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. - `files: array of object { file_id, path, type } or object { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `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. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `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. - `"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`. - `"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` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of object { skill_id, type, version } or object { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `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. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Example ```http curl https://api.openai.com/v1/agents/environments/templates \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ``` ## Delete an agent environment template **delete** `/agents/environments/templates/{environment_template_id}` Deletes reusable environment configuration and all confidential template inputs. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Path Parameters - `environment_template_id: string` ### Returns - `EnvironmentTemplateDeleted object { id, deleted, object }` A deleted reusable environment template. - `id: string` The ID of the deleted environment template. - `deleted: boolean` Whether the environment template was deleted. Always `true`. - `object: "agent.environment.template.deleted"` The object type. Always `agent.environment.template.deleted`. - `"agent.environment.template.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.environment.template.deleted" } ``` ## List agent environment templates **get** `/agents/environments/templates` Lists reusable environment templates without returning confidential values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of EnvironmentTemplate` The resources returned in this page, in the requested sort order. - `id: string` The ID of the reusable environment template. - `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. - `files: array of object { file_id, path, type } or object { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `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. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `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. - `"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`. - `"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` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of object { skill_id, type, version } or object { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `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. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/environments/templates \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent environment template **get** `/agents/environments/templates/{environment_template_id}` Retrieves reusable environment configuration without returning confidential values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Path Parameters - `environment_template_id: string` ### Returns - `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. - `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. - `files: array of object { file_id, path, type } or object { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `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. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `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. - `"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`. - `"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` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of object { skill_id, type, version } or object { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `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. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Example ```http curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ``` ## Update an agent environment template **post** `/agents/environments/templates/{environment_template_id}` Updates reusable environment configuration without returning confidential values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Path Parameters - `environment_template_id: string` ### Body Parameters - `capability_directories: optional array of string or null` Directories that expose capabilities to the agent. - `env: optional map[string] or null` Replacement confidential environment values. - `files: optional array of HostedEnvironmentFileParam or null` Replacement file configuration materialized for each new session. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: optional string or null` A replacement human-readable display name, or `null` to clear the name. - `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. - `"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 or null` Replacement plugin configuration installed for each new session. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Replacement confidential setup commands, never included in returned resources. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Replacement skill configuration installed for each new session. - `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`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Returns - `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. - `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. - `files: array of object { file_id, path, type } or object { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `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. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `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. - `"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`. - `"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` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of object { skill_id, type, version } or object { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `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. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Example ```http curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ``` ## Domain Types ### Environment Template - `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. - `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. - `files: array of object { file_id, path, type } or object { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `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. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `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. - `"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`. - `"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` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of object { skill_id, type, version } or object { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `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. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Environment Template Deleted - `EnvironmentTemplateDeleted object { id, deleted, object }` A deleted reusable environment template. - `id: string` The ID of the deleted environment template. - `deleted: boolean` Whether the environment template was deleted. Always `true`. - `object: "agent.environment.template.deleted"` The object type. Always `agent.environment.template.deleted`. - `"agent.environment.template.deleted"` # Sessions ## Create an agent session **post** `/agents/sessions` Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See [running sessions](/api/docs/guides/agents-api/sessions). ### Body Parameters - `environment: EnvironmentParam` An inline execution environment or a reference to an environment template. - `None object { type }` Runs the agent without an execution environment. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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. - `files: optional array of HostedEnvironmentFileParam or null` Files available before the agent starts. Defaults to an empty list. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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 or null` Plugins provided as inline ZIP archives. Defaults to an empty list. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Ordered, confidential setup commands. Command bodies are never returned. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - `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`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"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`. - `"self_hosted"` - `workspace_directory: string` Absolute project directory inside the self-hosted environment. - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `agent: optional object { instructions, model, multi_agent, 4 more }` Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required. - `instructions: optional string or null` Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `model: optional string` The model to use for the agent. The requested model name is preserved. - `multi_agent: optional MultiAgentConfigParam or null` 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. - `reasoning: optional AgentReasoningParam or null` 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. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` The reasoning summary format requested from the model. - `"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. - `service_tier: optional "auto" or "default" or "flex" or 2 more or null` The service tier used for model requests. - `"auto"` Selects the service tier automatically. - `"default"` Uses the default service tier. - `"flex"` Uses the flex service tier. - `"priority"` Uses the priority service tier. - `"fast"` Uses the fast service tier. - `text: optional AgentTextParam or null` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. - `tools: optional array of AgentToolParam or null` Tools available to the agent. Omit to inherit, or pass null to clear them. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `transport: McpTransportParam` The transport used to connect to the MCP server. - `HTTP object { server_url, type, authorization, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `authorization: optional string or null` The authorization value sent to the MCP server, if any. - `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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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. - `type: "mcp"` The type of the object. Always `mcp`. - `"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. - `"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. - `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`. - `"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. - `"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. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. - `agent_id: optional string` The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged. - `input: optional string or array of AgentSessionInputMessageParam or null` Initial input submitted when creating a session. - `string` - `array of AgentSessionInputMessageParam` - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` - `metadata: optional map[string] or null` Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. - `stream: optional boolean` Whether to stream session events as server-sent events. Defaults to `false`. - `vault_ids: optional array of string or null` The IDs of vaults made available to the session. ### Returns - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Example ```http curl https://api.openai.com/v1/agents/sessions \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "environment": { "type": "none" } }' ``` #### Response ```json { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "arguments": {}, "call_id": "call_id", "name": "name", "turn_id": "turn_id", "type": "function_call" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ``` ## Delete an agent session **delete** `/agents/sessions/{session_id}` Removes a managed agent session from the public API and returns a deletion confirmation. Physical cleanup may continue asynchronously. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Path Parameters - `session_id: string` ### Returns - `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. - `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`. - `"agent.session.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.session.deleted" } ``` ## List agent sessions **get** `/agents/sessions` Lists managed agent sessions using ID-based pagination and the requested sort order. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `agent_id: optional string` Only return sessions whose root agent has this ID. Omit to return sessions for all agents. - `limit: optional number or null` The maximum number of resources to return. - `order: optional "asc" or "desc"` Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSession` The resources returned in this page, in the requested sort order. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "arguments": {}, "call_id": "call_id", "name": "name", "turn_id": "turn_id", "type": "function_call" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent session **get** `/agents/sessions/{session_id}` Retrieves the current state of a managed agent session. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Path Parameters - `session_id: string` ### Returns - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "arguments": {}, "call_id": "call_id", "name": "name", "turn_id": "turn_id", "type": "function_call" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ``` ## Update an agent session **post** `/agents/sessions/{session_id}` Updates session metadata. Omitted fields are unchanged. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Path Parameters - `session_id: string` ### Body Parameters - `metadata: optional map[string] or null` Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. ### Returns - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "arguments": {}, "call_id": "call_id", "name": "name", "turn_id": "turn_id", "type": "function_call" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ``` # Artifacts ## Retrieve agent session artifact content **get** `/agents/sessions/{session_id}/artifacts/{artifact_id}/content` Downloads immutable session artifact bytes after the execution environment expires. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` - `artifact_id: string` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID/content \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` ## Delete an agent session artifact **delete** `/agents/sessions/{session_id}/artifacts/{artifact_id}` Deletes an immutable session artifact without deleting its live environment file or original Files API object. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` - `artifact_id: string` ### Returns - `SessionArtifactDeleted object { id, deleted, object }` Confirmation that an immutable session artifact was deleted. - `id: string` The ID of the deleted session artifact. - `deleted: boolean` Whether the session artifact was deleted. Always `true`. - `object: "agent.session.artifact.deleted"` The object type. Always `agent.session.artifact.deleted`. - `"agent.session.artifact.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.session.artifact.deleted" } ``` ## List agent session artifacts **get** `/agents/sessions/{session_id}/artifacts` Lists immutable artifacts published by completed hosted session turns. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string or null` Return artifacts after this immutable artifact ID. - `environment_id: optional string or null` Restrict the listing to artifacts produced by this environment. - `limit: optional number or null` The maximum number of artifacts to return, between 1 and 100. - `order: optional "asc" or "desc"` Sort by creation time and ID. Defaults to descending. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of SessionArtifact` The resources returned in this page, in the requested sort order. - `id: string` The immutable artifact ID. - `created_at: number` The Unix timestamp, in seconds, when the artifact was published. - `environment_id: string` The ID of the environment that produced the artifact. - `object: "agent.session.artifact"` The object type. Always `agent.session.artifact`. - `"agent.session.artifact"` - `path: string` The original absolute file path in the execution environment. - `session_id: string` The ID of the session that owns the artifact. - `size_bytes: number` The immutable artifact size in bytes. - `turn_id: string` The ID of the completed turn that published the artifact. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "created_at": 0, "environment_id": "environment_id", "object": "agent.session.artifact", "path": "path", "session_id": "session_id", "size_bytes": 0, "turn_id": "turn_id" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent session artifact **get** `/agents/sessions/{session_id}/artifacts/{artifact_id}` Retrieves immutable metadata for one durable session artifact. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` - `artifact_id: string` ### Returns - `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. - `created_at: number` The Unix timestamp, in seconds, when the artifact was published. - `environment_id: string` The ID of the environment that produced the artifact. - `object: "agent.session.artifact"` The object type. Always `agent.session.artifact`. - `"agent.session.artifact"` - `path: string` The original absolute file path in the execution environment. - `session_id: string` The ID of the session that owns the artifact. - `size_bytes: number` The immutable artifact size in bytes. - `turn_id: string` The ID of the completed turn that published the artifact. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "environment_id": "environment_id", "object": "agent.session.artifact", "path": "path", "session_id": "session_id", "size_bytes": 0, "turn_id": "turn_id" } ``` ## Domain Types ### Session Artifact - `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. - `created_at: number` The Unix timestamp, in seconds, when the artifact was published. - `environment_id: string` The ID of the environment that produced the artifact. - `object: "agent.session.artifact"` The object type. Always `agent.session.artifact`. - `"agent.session.artifact"` - `path: string` The original absolute file path in the execution environment. - `session_id: string` The ID of the session that owns the artifact. - `size_bytes: number` The immutable artifact size in bytes. - `turn_id: string` The ID of the completed turn that published the artifact. ### Session Artifact Deleted - `SessionArtifactDeleted object { id, deleted, object }` Confirmation that an immutable session artifact was deleted. - `id: string` The ID of the deleted session artifact. - `deleted: boolean` Whether the session artifact was deleted. Always `true`. - `object: "agent.session.artifact.deleted"` The object type. Always `agent.session.artifact.deleted`. - `"agent.session.artifact.deleted"` # Events ## Create agent session input events **post** `/agents/sessions/{session_id}/events` Submits message, cancellation, or tool-result events to a managed agent session. See [session events](/api/docs/guides/agents-api/sessions/events). ### Header Parameters - `"Idempotency-Key": optional string` ### Path Parameters - `session_id: string` ### Body Parameters - `events: array of AgentSessionInputParam` The input events to submit to the session. - `AgentSessionInputMessage object { input, type }` Adds one or more user messages and starts a turn. - `input: array of AgentSessionInputMessageParam` The user messages to add to the session. - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` - `type: "agent.session.input.message"` The type of the object. Always `agent.session.input.message`. - `"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`. - `"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. - `success: boolean` Whether the function call succeeded. - `turn_id: string` The ID of the turn that requested the function call. - `type: "agent.session.input.tool_result"` The type of the object. Always `agent.session.input.tool_result`. - `"agent.session.input.tool_result"` - `error: optional string or null` The error message when the call failed. - `output: optional AgentFunctionCallOutputParam or null` A function result represented as text or supported model-input content. - `string` - `array of InputContentParam` - `InputText object { text, type }` Text input to the model. - `InputImage object { image_url, type }` Image input to the model. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "events": [ { "input": [ { "content": [ { "text": "text", "type": "input_text" } ], "role": "user" } ], "type": "agent.session.input.message" } ] }' ``` ## Stream agent session events **get** `/agents/sessions/{session_id}/events` Streams live events for an agent session. See [session events](/api/docs/guides/agents-api/sessions/events). ### Path Parameters - `session_id: string` ### Returns - `AgentSessionEvent = AgentSessionErrorEvent or AgentSessionEnvironmentReadyEvent or AgentOutputCommandExecutionOutputDeltaEvent or 27 more` An event emitted by a Managed Agents session. - `AgentSessionErrorEvent object { error, event_id, session_id, type }` Emitted when a turn or session fails. - `error: SessionError` The error that occurred. - `code: string or null` The machine-readable error code, if any. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `type: "error"` The type of the object. Always `error`. - `"error"` - `AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }` Emitted when a hosted session environment is ready to connect. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` An error reported while preparing a session environment. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 2 more` The environment's connection status. - `"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. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.ready"` The type of the object. Always `agent.session.environment.ready`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the command execution item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.output.command_execution_output.delta"` The type of the object. Always `agent.output.command_execution_output.delta`. - `"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. - `session: AgentSession` The session that was created. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` 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. - `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. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort used by an agent. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `service_tier: "auto" or "default" or "flex" or 2 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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. - `"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. - `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. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, files, 5 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `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. - `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. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"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. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"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. - `"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` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"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. - `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. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"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. - `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. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"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 or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.created"` The type of the object. Always `agent.session.created`. - `"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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it was created. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` Recorded token usage for a session or turn. Usage is best effort and may change. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.created"` The type of the object. Always `agent.session.turn.created`. - `"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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it started running. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.in_progress"` The type of the object. Always `agent.session.turn.in_progress`. - `"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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The completed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.completed"` The type of the object. Always `agent.session.turn.completed`. - `"agent.session.turn.completed"` - `usage: TokenUsage 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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The failed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.failed"` The type of the object. Always `agent.session.turn.failed`. - `"agent.session.turn.failed"` - `usage: TokenUsage 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. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The cancelled turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.cancelled"` The type of the object. Always `agent.session.turn.cancelled`. - `"agent.session.turn.cancelled"` - `usage: TokenUsage 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. - `item: AgentSessionItem` The item that was added. - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"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. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number or null` The index of the item in the turn output, when the item is agent output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.added"` The type of the object. Always `agent.session.turn.item.added`. - `"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. - `session: AgentSession` The session that became idle. - `type: "agent.session.idle"` The type of the object. Always `agent.session.idle`. - `"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. - `session: AgentSession` The session that started processing. - `type: "agent.session.in_progress"` The type of the object. Always `agent.session.in_progress`. - `"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. - `session: AgentSession` The session and its current required actions. - `type: "agent.session.requires_action"` The type of the object. Always `agent.session.requires_action`. - `"agent.session.requires_action"` - `AgentSessionFailedEvent object { event_id, session, type }` Emitted when a session fails. - `event_id: string` The unique ID of the event. - `session: AgentSession` The failed session. - `type: "agent.session.failed"` The type of the object. Always `agent.session.failed`. - `"agent.session.failed"` - `AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }` Emitted while a session environment is being prepared. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.pending"` The type of the object. Always `agent.session.environment.pending`. - `"agent.session.environment.pending"` - `AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment connects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.connected"` The type of the object. Always `agent.session.environment.connected`. - `"agent.session.environment.connected"` - `AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment disconnects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.disconnected"` The type of the object. Always `agent.session.environment.disconnected`. - `"agent.session.environment.disconnected"` - `AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment fails. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.failed"` The type of the object. Always `agent.session.environment.failed`. - `"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. - `subagent: Subagent` The subagent that was created. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.created"` The type of the object. Always `agent.session.subagent.created`. - `"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. - `subagent: Subagent` The subagent that resumed. - `type: "agent.session.subagent.active"` The type of the object. Always `agent.session.subagent.active`. - `"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. - `subagent: Subagent` The subagent that was closed. - `type: "agent.session.subagent.closed"` The type of the object. Always `agent.session.subagent.closed`. - `"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. - `item: AgentOutputItem` The completed output item. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `output_index: number` The index of the output item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.done"` The type of the object. Always `agent.session.turn.item.done`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The initial content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.added"` The type of the object. Always `agent.session.turn.content_part.added`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The completed content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.done"` The type of the object. Always `agent.session.turn.content_part.done`. - `"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. - `delta: string` The text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.delta"` The type of the object. Always `agent.session.turn.output_text.delta`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `text: string` The complete output text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.done"` The type of the object. Always `agent.session.turn.output_text.done`. - `"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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The initial summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.added"` The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. - `"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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The completed summary part. - `session_id: string` The ID of the session associated with the event. - `status: "incomplete" or null` Present as `incomplete` when summary generation was interrupted. - `"incomplete"` - `summary_index: number` The index of the summary part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.done"` The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. - `"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. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.delta"` The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. - `"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. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `text: string` The complete reasoning summary text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.done"` The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. - `"agent.session.turn.reasoning_summary_text.done"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` # Items ## List agent session items **get** `/agents/sessions/{session_id}/items` Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history. See [inspecting agent output](/api/docs/guides/agents-api/observability). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSessionItem` The resources returned in this page, in the requested sort order. - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"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. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/items \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "content": [ { "text": "text", "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "turn_id": "turn_id", "type": "message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` # Subagents ## List session subagents **get** `/agents/sessions/{session_id}/subagents` Lists subagents in a session, including nested and closed subagents. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Subagent` The resources returned in this page, in the requested sort order. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "closed_at": 0, "instructions": [ { "text": "text", "type": "output_text" } ], "name": "name", "object": "agent.session.subagent", "opened_at": 0, "parent_agent_id": "parent_agent_id", "session_id": "session_id", "status": "active" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a session subagent **get** `/agents/sessions/{session_id}/subagents/{subagent_id}` Retrieves a subagent belonging to this session. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` ### Returns - `Subagent object { id, closed_at, instructions, 6 more }` A subagent created within a session. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `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. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "closed_at": 0, "instructions": [ { "text": "text", "type": "output_text" } ], "name": "name", "object": "agent.session.subagent", "opened_at": 0, "parent_agent_id": "parent_agent_id", "session_id": "session_id", "status": "active" } ``` # Items ## List subagent items **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/items` Lists this subagent's own items across all of its turns. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSessionItem` The resources returned in this page, in the requested sort order. - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"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. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/items \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "content": [ { "text": "text", "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "turn_id": "turn_id", "type": "message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` # Turns ## List subagent turns **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/turns` Lists all turns of this subagent, including turns after a resume. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Turn` The resources returned in this page, in the requested sort order. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a subagent turn **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}` Retrieves a turn belonging to this subagent. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` - `turn_id: string` ### Returns - `Turn object { id, agent_id, completed_at, 8 more }` The canonical public representation of a session turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns/$TURN_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ``` # Items ## List subagent turn items **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items` Lists items belonging to one turn of this subagent. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` - `turn_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSessionItem` The resources returned in this page, in the requested sort order. - `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. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of an agent output item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"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. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"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. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"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. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"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. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"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. - `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. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"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. - `action: WebSearchAction or null` An action performed by the web search tool. - `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. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"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. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"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. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `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. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `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. - `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. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `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. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns/$TURN_ID/items \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "content": [ { "text": "text", "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "turn_id": "turn_id", "type": "message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` # Turns ## List agent session turns **get** `/agents/sessions/{session_id}/turns` Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order. See [session turns](/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Turn` The resources returned in this page, in the requested sort order. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent session turn **get** `/agents/sessions/{session_id}/turns/{turn_id}` Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session. See [session turns](/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). ### Path Parameters - `session_id: string` - `turn_id: string` ### Returns - `Turn object { id, agent_id, completed_at, 8 more }` The canonical public representation of a session turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns/$TURN_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ``` ## Domain Types ### Turn - `Turn object { id, agent_id, completed_at, 8 more }` The canonical public representation of a session turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `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. - `error: SessionTurnError or null` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 14 more` A stable, machine-readable failure category. - `"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. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"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. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"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. - `usage: TokenUsage or null` 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. - `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. - `output_tokens: number` The number of output tokens generated by the agent. - `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. - `total_tokens: number` The total number of input and output tokens used by the agent. # Vaults ## Create a vault **post** `/vaults` Creates a vault for the current project. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Body Parameters - `metadata: optional map[string] or null` Key-value pairs to associate with the vault, such as an application or team identifier. - `name: optional string` The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. ### Returns - `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. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `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. - `object: "vault"` The object type. Always `vault`. - `"vault"` ### Example ```http curl https://api.openai.com/v1/vaults \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault" } ``` ## Delete a vault **delete** `/vaults/{vault_id}` Deletes a vault and all its credentials. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Returns - `VaultDeleted object { id, deleted, object }` Confirmation that a vault was deleted. - `id: string` The ID of the deleted vault. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.deleted"` The object type. Always `vault.deleted`. - `"vault.deleted"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "vault.deleted" } ``` ## List vaults **get** `/vaults` Lists vaults using ID-based pagination. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number or null` The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100. - `order: optional "asc" or "desc"` Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. - `status: optional VaultStatusFilter` Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default. - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` - `array of VaultStatus` - `"active"` - `"archived"` ### Returns - `data: array of Vault` The resources returned in this page, in the requested sort order. - `id: string` The ID of the vault. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `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. - `object: "vault"` The object type. Always `vault`. - `"vault"` - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/vaults \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a vault **get** `/vaults/{vault_id}` Retrieves a vault by its ID. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Returns - `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. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `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. - `object: "vault"` The object type. Always `vault`. - `"vault"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault" } ``` ## Domain Types ### Vault - `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. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `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. - `object: "vault"` The object type. Always `vault`. - `"vault"` ### Vault Deleted - `VaultDeleted object { id, deleted, object }` Confirmation that a vault was deleted. - `id: string` The ID of the deleted vault. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.deleted"` The object type. Always `vault.deleted`. - `"vault.deleted"` ### Vault Status - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` ### Vault Status Filter - `VaultStatusFilter = VaultStatus or array of VaultStatus` One or more lifecycle statuses to include when listing vaults or credentials. - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` - `array of VaultStatus` - `"active"` - `"archived"` # Credentials ## Create a vault credential **post** `/vaults/{vault_id}/credentials` Creates a vault credential. Secret values are write-only and are never returned. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Body Parameters - `auth: CredentialAuthCreateParam` The authentication method and secret values to store for the MCP server. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `expires_at: optional string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `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. - `refresh_token: string` The refresh token to store. This secret is never returned in credential resources. - `token_endpoint: string` The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token. - `token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam` How the OAuth client authenticates to the token endpoint. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"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. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `resource: optional string or null` The resource URI to send to the OAuth token endpoint during refresh, if required. - `scope: optional string or null` Space-separated OAuth scopes to request during refresh, if required. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `name: string` The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. ### Returns - `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. - `auth: CredentialAuth` The authentication method and non-secret configuration for the MCP server. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `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. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "auth": { "access_token": "access_token", "mcp_server_url": "mcp_server_url", "type": "mcp_oauth" }, "name": "x" }' ``` #### Response ```json { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ``` ## Delete a vault credential **delete** `/vaults/{vault_id}/credentials/{credential_id}` Deletes a vault credential. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` - `credential_id: string` ### Returns - `CredentialDeleted object { id, deleted, object }` Confirmation that a vault credential was deleted. - `id: string` The ID of the deleted credential. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.credential.deleted"` The object type. Always `vault.credential.deleted`. - `"vault.credential.deleted"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "vault.credential.deleted" } ``` ## List vault credentials **get** `/vaults/{vault_id}/credentials` Lists a vault's credentials using ID-based pagination without returning secret values. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number or null` The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100. - `order: optional "asc" or "desc"` Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. - `status: optional VaultStatusFilter` Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default. - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` - `array of VaultStatus` - `"active"` - `"archived"` ### Returns - `data: array of Credential` The resources returned in this page, in the requested sort order. - `id: string` The ID of the credential. - `auth: CredentialAuth` The authentication method and non-secret configuration for the MCP server. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `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. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a vault credential **get** `/vaults/{vault_id}/credentials/{credential_id}` Retrieves vault credential metadata without returning secret values. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` - `credential_id: string` ### Returns - `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. - `auth: CredentialAuth` The authentication method and non-secret configuration for the MCP server. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `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. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ``` ## Rotate a vault credential **post** `/vaults/{vault_id}/credentials/{credential_id}` Rotates a vault credential's write-only secret and returns only credential metadata. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` - `credential_id: string` ### Body Parameters - `auth: CredentialAuthRotateParam` Replacement values for the credential's existing authentication method. - `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`. - `"mcp_oauth"` - `access_token: optional string or null` A write-only replacement OAuth access token. - `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. - `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. - `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. - `token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null` Client-secret updates that preserve the credential's OAuth authentication method. - `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_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. - `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_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. - `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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` ### Returns - `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. - `auth: CredentialAuth` The authentication method and non-secret configuration for the MCP server. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `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. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "auth": { "type": "mcp_oauth" } }' ``` #### Response ```json { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ``` ## Domain Types ### Credential - `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. - `auth: CredentialAuth` The authentication method and non-secret configuration for the MCP server. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `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. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Credential Auth - `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. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `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. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` ### Credential Auth Create Param - `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. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `expires_at: optional string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `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. - `refresh_token: string` The refresh token to store. This secret is never returned in credential resources. - `token_endpoint: string` The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token. - `token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam` How the OAuth client authenticates to the token endpoint. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"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. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `resource: optional string or null` The resource URI to send to the OAuth token endpoint during refresh, if required. - `scope: optional string or null` Space-separated OAuth scopes to request during refresh, if required. - `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. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` ### Credential Auth Rotate Param - `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. - `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`. - `"mcp_oauth"` - `access_token: optional string or null` A write-only replacement OAuth access token. - `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. - `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. - `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. - `token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null` Client-secret updates that preserve the credential's OAuth authentication method. - `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_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. - `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_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. - `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. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` ### Credential Deleted - `CredentialDeleted object { id, deleted, object }` Confirmation that a vault credential was deleted. - `id: string` The ID of the deleted credential. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.credential.deleted"` The object type. Always `vault.credential.deleted`. - `"vault.credential.deleted"` ### Mcp OAuth Token Endpoint Auth - `McpOauthTokenEndpointAuth = object { type } or object { type } or object { type }` The client authentication method used for OAuth token refresh. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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`. - `"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`. - `"client_secret_post"` ### Mcp OAuth Token Endpoint Auth Create Param - `McpOauthTokenEndpointAuthCreateParam = object { type } or object { client_secret, type } or object { client_secret, type }` Client authentication credentials for OAuth token refresh. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"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. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"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. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` ### Mcp OAuth Token Endpoint Auth Rotate Param - `McpOauthTokenEndpointAuthRotateParam = object { type, client_secret } or object { type, client_secret }` Client-secret updates that preserve the credential's OAuth authentication method. - `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_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. - `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_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.