The identity and technical contract details declared by the specification.
EnvironmentTemplateListResource
object
A page of Agents API resources, with IDs for retrieving additional pages.
5 properties
5 required
AgentToolConfigParamWebSearch
object
Web search.
5 properties
1 required
SessionEventAgentSessionTurnContentPartAdded
object
Emitted when an output text content part is added.
8 properties
8 required
InterruptSubagentCallItemResource
object
A request to interrupt a subagent's current turn. The subagent remains available.
6 properties
6 required
InputContentParamInputText
object
Text input to the model.
2 properties
2 required
McpTransportResource
The transport used to connect to an MCP server.
HostedEnvironmentFileResourceFileId
object
A file copied from the OpenAI Files API.
5 properties
5 required
InlineCapabilitySourceParam
The encoded ZIP archive for an inline skill or plugin.
FunctionCallItemResource
object
A function call produced by the agent.
7 properties
7 required
CreateEnvironmentTemplateParams
object
Parameters for creating a reusable, project-scoped OpenAI-hosted environment template.
9 properties
SessionStatusResource
string
The current status of a session.
SessionEventAgentSessionTurnReasoningSummaryTextDelta
object
Emitted when text is appended to a reasoning summary.
8 properties
8 required
UpdateSessionAgentParam
object
Model settings that can change after session creation.
3 properties
HostedPluginResourceInline
object
A plugin installed from an inline ZIP archive.
3 properties
3 required
TurnStatusResource
string
The current status of a turn.
SessionEventError
object
Emitted when a turn or session fails.
4 properties
4 required
McpTransportResourceStdio
object
Starts an MCP server as a local process.
5 properties
5 required
SubagentObjectResource
string
The object type for a subagent.
VerbosityResource
string
The amount of text produced by an agent.
TextFormatResourceText
object
Generates ordinary text without a structured-output constraint.
1 property
1 required
SessionTurnListResource
object
A page of Agents API resources, with IDs for retrieving additional pages.
5 properties
5 required
SessionTurnErrorResource
object
A customer-safe error describing why a session request failed.
2 properties
2 required
AgentToolConfigParamFunction
object
A function defined by the application.
5 properties
4 required
InputContentResource
User-provided content recorded in a session item.
InputContentResourceInputImage
object
Image input recorded in a session item.
2 properties
2 required
TextFormatResourceJsonSchema
object
Constrains generated text to a JSON Schema.
2 properties
2 required
McpConnectionOriginParam
string
Where outbound MCP HTTP connections originate.
WebSearchContextSizeParam
string
The amount of web search context made available to the model.
SessionEventAgentSessionTurnItemDone
object
Emitted when an output item is complete.
6 properties
6 required
MessagePhaseResource
string
The phase of an assistant message.
ErrorResponse-2
object
An API error response.
1 property
1 required
SessionInputParam
Input submitted to an existing session.
SessionEventAgentSessionTurnReasoningSummaryPartAdded
object
Emitted when a reasoning summary content part is added.
8 properties
8 required
SessionEnvironmentStatusResource
string
The connection status of a session environment.
SessionEventAgentSessionTurnReasoningSummaryTextDone
object
Emitted when a reasoning summary content part is complete.
8 properties
8 required
InputContentParam
Content included in an input message.
HostedPluginParam
A plugin installed in an OpenAI-hosted environment.
EnvironmentStatusResource
string
The public lifecycle status of an execution environment.
ErrorBodyResource
object
Details about an API error.
4 properties
4 required
OutputTokensDetailsResource
object
A breakdown of output token usage for a session or turn.
1 property
1 required
NetworkAccessParam
string
The network access mode for an OpenAI-hosted environment.
SessionEvent
An event emitted by a Managed Agents session.
SessionEventAgentSessionCreated
object
Emitted when a session is created.
3 properties
3 required
SubagentResource
object
A subagent created within a session.
9 properties
9 required
MultiAgentConfigResource
object
The resolved configuration for creating and coordinating subagents.
2 properties
2 required
EnvironmentParam
The execution environment and optional reusable template for a session.
EnvironmentResourceNone
object
The session talks to CCA without selecting or provisioning an execution environment.
1 property
1 required
CreateAgentSessionParams
object
Parameters for creating a Managed Agents session.
7 properties
1 required
SessionEventAgentSessionEnvironmentReady
object
Emitted when a hosted session environment is ready to connect.
5 properties
5 required
ReasoningEffortParam
string
The amount of reasoning effort the model should use.
SessionInputParamAgentSessionInputMessage
object
Adds one or more user messages and starts a turn.
2 properties
2 required
SessionRequiredActionResourceFunctionCall
object
Run a function tool and submit its result.
5 properties
5 required
SessionInputParamAgentSessionInputCancel
object
Cancels the session's active turn.
1 property
1 required
McpTransportResourceHttp
object
Connects to an MCP server over HTTP.
2 properties
2 required
SessionEventAgentSessionTurnCancelled
object
Emitted when a turn is cancelled.
6 properties
6 required
SendSubagentInputCallItemResource
object
A request to send input to another agent.
7 properties
7 required
SessionArtifactResource
object
An immutable file published by a completed hosted session turn.
8 properties
8 required
SessionEventAgentSessionEnvironmentReset
object
Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox's files and processes do not.
6 properties
6 required
PersistedAgentToolConfigParamFunction
object
A function defined by the application.
5 properties
4 required
MessageItemResource
object
A user or assistant message recorded in a session.
7 properties
7 required
PersistedAgentToolConfigParamMcp
object
Tools provided by a remote MCP server without stored credentials.
8 properties
3 required
HostedPluginParamInline
object
Supplies a plugin ZIP directly in the session request.
4 properties
4 required
PersistedMcpTransportConfigParamStdio
object
Starts an MCP server as a local process.
5 properties
3 required
SessionEventAgentSessionTurnOutputTextDelta
object
Emitted when text is appended to an output text content part.
8 properties
8 required
WaitForSubagentsCallItemResource
object
A request to wait for one or more subagents.
6 properties
6 required
UpdateEnvironmentTemplateParams
object
Fields to replace on an existing reusable OpenAI-hosted environment template.
9 properties
SessionEventAgentSessionFailed
object
Emitted when a session fails.
3 properties
3 required
SubagentStatusResource
string
The current status of a subagent.
HostedTemplateSkillResourceInline
object
Safe metadata for an inline skill archive.
3 properties
3 required
EnvironmentTypeResource
string
The kind of execution environment.
McpTransportConfigParamStdio
object
Starts an MCP server as a local process.
6 properties
3 required
AgentListResource
object
A page of Agents API resources, with IDs for retrieving additional pages.
5 properties
5 required
InlineCapabilitySourceParamBase64
object
Provides ZIP bytes encoded with standard base64.
3 properties
3 required
HostedSkillParam
A skill installed in an OpenAI-hosted environment.
SessionAgentResource
object
The effective agent configuration for a session.
9 properties
9 required
SessionEventAgentSessionTurnCreated
object
Emitted when a turn is created.
5 properties
5 required
HostedTemplateFileResource
Safe metadata for a file configured by an environment template.
EnvironmentPackagesParam
object
Packages to install in an OpenAI-hosted environment.
3 properties
SessionEventAgentSessionEnvironmentConnected
object
Emitted when a session environment connects.
5 properties
5 required
SessionEventAgentSessionRequiresAction
object
Emitted when a session is waiting for one or more required actions.
3 properties
3 required
WebSearchActionResource
An action performed by the web search tool.
McpTransportConfigParam
The transport used to connect to an MCP server.
SessionRequiredActionResource
An action that must be completed before a session can continue.
PersistedAgentToolConfigParam
A tool that can be stored on a reusable agent without session credentials.
SessionMessageRoleResource
string
The author of a session message.
EnvironmentTemplateResource
object
Reusable configuration that provisions a fresh OpenAI-hosted environment for each session.
11 properties
11 required
NetworkPolicyParam
object
Network access for an OpenAI-hosted environment.
2 properties
1 required
ListOrderParam
string
The order in which paginated resources are returned.
HostedTemplateFileResourceFileId
object
A project-scoped Files API reference resolved separately for each session.
3 properties
3 required
HostedSkillResourceInline
object
A skill installed from an inline ZIP archive.
3 properties
3 required
WebSearchLocationParam
object
Approximate user location used to localize web search results.
4 properties
SessionEnvironmentStateResource
object
The current state of a session environment.
4 properties
4 required
SessionEventAgentSessionTurnInProgress
object
Emitted when a turn starts running.
5 properties
5 required
UpdateAgentParams
object
Fields to replace on an existing reusable agent.
9 properties
AgentToolConfigParam
A tool available to the agent.
EnvironmentFilePageObjectResource
string
The object type for a page of files in an execution environment.
FunctionCallOutputResource
The text or model-input content supplied as a function result.
DeletedSessionArtifactResource
object
Confirmation that an immutable session artifact was deleted.
3 properties
3 required
DeletedSessionResource
object
A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously.
3 properties
3 required
EnvironmentResourceSelfHosted
object
An environment hosted by the application.
5 properties
5 required
FunctionCallStatusResource
string
The status of a tool call.
MessageContentResourceInputImage
object
An image supplied by the user.
2 properties
2 required
WebSearchActionResourceFindInPage
object
Finds text within a web page.
3 properties
3 required
AgentToolResource
A tool available to the agent.
TurnObjectResource
string
The object type for a turn.
TokenUsageResource
object
Recorded token usage for a session or turn. Usage is best effort and may change.
5 properties
5 required
SessionAgentConfigParam
object
Agent configuration for a session. Omitted fields inherit from agentid when supplied. Supplied objects and arrays replace the whole field; null resets nullable…
7 properties
MessageContentResourceInputText
object
Text supplied by the user.
2 properties
2 required
TextFormatParamText
object
Generates ordinary text without a structured-output constraint.
1 property
1 required
HostedPluginResource
A plugin installed in an OpenAI-hosted environment.
SessionListResource
object
A page of Agents API resources, with IDs for retrieving additional pages.
5 properties
5 required
SessionEventAgentSessionTurnFailed
object
Emitted when a turn fails.
6 properties
6 required
PersistedMcpTransportResource
A credential-free transport used to connect to an MCP server.
HostedTemplateSkillResource
Safe metadata for a skill configured by an environment template.
SessionEnvironmentErrorResource
object
An error reported while preparing a session environment.
3 properties
3 required
VerbosityParam
string
The amount of text the model should produce.
SessionEventAgentSessionInProgress
object
Emitted when a session starts processing a turn.
3 properties
3 required
PersistedAgentToolResource
A credential-free tool available to a reusable agent.
NetworkPolicyResource
object
Network access for an OpenAI-hosted environment.
2 properties
2 required
InputContentParamInputImage
object
Image input to the model.
2 properties
2 required
DeletedAgentResource
object
A deleted reusable agent.
3 properties
3 required
AgentResource
object
A reusable agent scoped to the caller's project.
13 properties
13 required
CreateSessionEventsParams
object
Input events submitted to an existing session.
1 property
1 required
AgentToolConfigParamMcp
object
Tools provided by a remote MCP server.
8 properties
3 required
EnvironmentPackagesResource
object
Packages installed in an OpenAI-hosted environment.
3 properties
3 required
AgentOutputItemResource
An output item produced by an agent.
AgentToolConfigParamToolSearch
object
Discovers deferred function tools and loads them into the model context.
1 property
1 required
SessionEventAgentSessionIdle
object
Emitted when a session becomes idle.
3 properties
3 required
HostedEnvironmentFileParamInline
object
A file supplied directly as standard-base64 data.
3 properties
3 required
McpTransportConfigParamHttp
object
Connects to an MCP server over HTTP.
4 properties
2 required
SessionEventAgentSessionEnvironmentPending
object
Emitted while a session environment is being prepared.
5 properties
5 required
HostedSkillParamInline
object
Supplies a skill ZIP directly in the session request.
4 properties
4 required
PersistedAgentToolResourceWebSearch
object
Web search.
5 properties
5 required
EnvironmentFileResource
object
A live file in an execution environment.
4 properties
4 required
ServiceTierParam
string
The service tier used for model requests.
SessionRequiredActionResourceEnvironmentConnection
object
Reconnect a session environment.
2 properties
2 required
SessionArtifactListResource
object
A page of Agents API resources, with IDs for retrieving additional pages.
5 properties
5 required
ReasoningSummaryResource
string
The reasoning summary format requested from an agent.
SessionErrorResource
object
An error payload with the same public fields as Responses API streaming errors.
4 properties
4 required
UpdateSessionReasoningParam
object
Reasoning effort for subsequent turns. The reasoning summary stays unchanged.
1 property
AgentToolConfigParamProgrammaticToolCalling
object
Enables calling tools from model-generated code.
2 properties
1 required
PublicEnvironmentResource
object
Safe metadata for a first-class execution environment.
7 properties
7 required
CreateSubagentCallItemResource
object
A request to spawn a subagent.
8 properties
8 required
SessionEventAgentSessionTurnReasoningSummaryPartDone
object
Emitted when a reasoning summary part is complete.
9 properties
9 required
InputTokensDetailsResource
object
A breakdown of input token usage for a session or turn.
1 property
1 required
SessionEventAgentSessionTurnOutputTextDone
object
Emitted when an output text content part is complete.
8 properties
8 required
SessionEventAgentOutputCommandExecutionOutputDelta
object
Emitted when command execution produces an output delta.
7 properties
7 required
EnvironmentResourceOpenaiHosted
object
An environment hosted by OpenAI.
8 properties
8 required
McpConnectionOriginResource
string
Where outbound MCP HTTP connections originate.
TextParam
object
Configuration for text generated by the agent.
2 properties
SessionEventAgentSessionSubagentActive
object
Emitted when a closed subagent successfully resumes.
3 properties
3 required
SessionItemListResource
object
A page of messages, reasoning, and tool calls from a session's item history.
5 properties
5 required
EnvironmentParamSelfHosted
object
An application-hosted environment configured inline.
3 properties
2 required
UpdateAgentSessionParams
object
Fields to update on an existing session.
2 properties
InputMessageParam
object
A user message submitted to a session.
3 properties
2 required
TurnResource
object
The canonical public representation of a session turn.
11 properties
11 required
SessionEventAgentSessionEnvironmentFailed
object
Emitted when a session environment fails.
5 properties
5 required
AssistantMessageItemResource
object
An assistant message produced by the agent.
7 properties
7 required
FunctionCallOutputItemResource
object
The result supplied for a function call.
7 properties
7 required
CreateAgentParams
object
Parameters for creating a reusable agent.
9 properties
1 required
SessionResource
object
A Managed Agents session.
12 properties
12 required
TextResource
object
The text configuration used by an agent.
2 properties
2 required
SessionTurnErrorCodeResource
string
Stable public categories for session request failures.
SessionEventAgentSessionEnvironmentDisconnected
object
Emitted when a session environment disconnects.
5 properties
5 required
InputContentResourceInputText
object
Text input recorded in a session item.
2 properties
2 required
EnvironmentParamOpenaiHosted
object
An existing OpenAI-hosted environment or new inline/template-based hosted configuration.
10 properties
1 required
PersistedAgentToolConfigParamProgrammaticToolCalling
object
Enables calling tools from model-generated code.
2 properties
1 required
AgentToolResourceProgrammaticToolCalling
object
Enables calling tools from model-generated code.
2 properties
2 required
OutputTextResource
object
A text content part produced by the agent.
2 properties
2 required
PersistedMcpTransportConfigParamHttp
object
Connects to an MCP server over HTTP.
3 properties
2 required
ResumeSubagentCallItemResource
object
A request to resume a subagent.
6 properties
6 required
WebSearchModeResource
string
The source used for web search results.
PersistedMcpTransportConfigParam
A credential-free transport used to connect to an MCP server.
HostedSkillResourceSkillReference
object
A skill installed from the Skills API.
5 properties
5 required
CreateSessionInputParam
Initial input submitted when creating a session.
EnvironmentParamNone
object
Runs the agent without an execution environment.
1 property
1 required
HostedSkillResource
A skill installed in an OpenAI-hosted environment.
HostedEnvironmentFileResourceInline
object
A file supplied inline when the session was created.
4 properties
4 required
NetworkAccessResource
string
The network access mode for an OpenAI-hosted environment.
WebSearchCallItemResource
object
A web search call produced by the agent.
5 properties
5 required
SessionEventAgentSessionSubagentCreated
object
Emitted when a subagent is created.
3 properties
3 required
HostedSkillParamSkillReference
object
References a skill uploaded through the Skills API.
3 properties
2 required
MessageContentResource
A content part in a session message.
CommandExecutionItemResource
object
A command execution produced by the agent.
9 properties
9 required
HostedEnvironmentFileParamFileId
object
A file previously uploaded through the OpenAI Files API.
3 properties
3 required
TextFormatParamJsonSchema
object
Constrains generated text to a JSON Schema.
2 properties
2 required
WebSearchModeParam
string
The source used for web search results.
HostedTemplateFileResourceInline
object
Metadata for confidential inline file contents.
3 properties
3 required
AgentToolResourceMcp
object
Tools provided by a remote MCP server.
8 properties
8 required
AgentContentResource
A plaintext or encrypted content part exchanged between agents.
WebSearchActionResourceSearch
object
A search query or group of search queries.
3 properties
3 required
McpCallItemResource
object
A call to a tool on an MCP server.
9 properties
9 required
SessionEventAgentSessionTurnItemAdded
object
Emitted when an item is added to a turn.
6 properties
6 required
TextFormatResource
The effective output format for generated text.
ReasoningItemResource
object
A reasoning item produced by the agent.
5 properties
5 required
PersistedAgentToolResourceToolSearch
object
Discovers deferred function tools and loads them into the model context.
1 property
1 required
AgentToolResourceWebSearch
object
Web search.
5 properties
5 required
SessionEventAgentSessionSubagentClosed
object
Emitted when a subagent is closed.
3 properties
3 required
HostedTemplateSkillResourceSkillReference
object
A skill resolved afresh from the Skills API whenever a session starts.
3 properties
3 required
SessionEventAgentSessionTurnContentPartDone
object
Emitted when an output content part is complete.
8 properties
8 required
SummaryTextResource
object
A reasoning summary content part.
2 properties
2 required
PersistedAgentToolConfigParamWebSearch
object
Web search.
5 properties
1 required
PersistedAgentToolResourceProgrammaticToolCalling
object
Enables calling tools from model-generated code.
2 properties
2 required
TextFormatParam
The output format for generated text.
SessionInputParamAgentSessionInputToolResult
object
Submits the result of a function call.
6 properties
4 required
ReasoningEffortResource
string
The amount of reasoning effort used by an agent.
PersistedAgentToolResourceMcp
object
Tools provided by a remote MCP server without stored credentials.
8 properties
8 required
ServiceTierResource
string
The service-tier policy configured for an agent.
MultiAgentConfigCurrentParam
object
Explicit configuration for creating and coordinating subagents.
2 properties
1 required
EncryptedContentResource
object
Encrypted content exchanged between agents.
2 properties
2 required
AgentToolResourceFunction
object
A function defined by the application.
5 properties
5 required
HostedEnvironmentFileParam
A file materialized in an OpenAI-hosted execution environment.
ReasoningSummaryParam
string
The reasoning summary format requested from the model.
PersistedMcpTransportResourceHttp
object
Connects to an MCP server over HTTP.
3 properties
3 required
ReasoningParam
object
Reasoning configuration for the agent.
2 properties
OutputItemStatusResource
string
The status of an agent output item.
FunctionCallOutputParam
A function result represented as text or supported model-input content.
WebSearchLocationResource
object
Approximate user location used to localize web search results.
4 properties
4 required
MessageContentResourceOutputText
object
Text produced by the assistant.
2 properties
2 required
ReasoningResource
object
The reasoning configuration used by an agent.
2 properties
2 required
PersistedAgentToolConfigParamToolSearch
object
Discovers deferred function tools and loads them into the model context.
1 property
1 required
WebSearchContextSizeResource
string
The amount of web search context made available to the model.
WebSearchActionResourceOther
object
Another web search action.
1 property
1 required
WebSearchActionResourceOpenPage
object
Opens a web page.
2 properties
2 required
EnvironmentFileListResource
object
A paginated list of live execution environment files.
4 properties
4 required
PersistedAgentToolResourceFunction
object
A function defined by the application.
5 properties
5 required
CloseSubagentCallItemResource
object
A request to close a subagent.
6 properties
6 required
EnvironmentResource
The execution environment for a session.
DeletedEnvironmentTemplateResource
object
A deleted reusable environment template.
3 properties
3 required
AgentMessageItemResource
object
A message exchanged between agent threads.
6 properties
6 required
HostedEnvironmentFileResource
Metadata for a file materialized in an OpenAI-hosted execution environment.
SessionTurnItemResource
An item associated with a session turn.
PersistedMcpTransportResourceStdio
object
Starts an MCP server as a local process.
5 properties
5 required
SessionEventAgentSessionTurnCompleted
object
Emitted when a turn completes.
6 properties
6 required
SetupCommandParam
object
A confidential setup command executed before the hosted agent starts.
2 properties
1 required
The full machine-readable OpenAPI contract behind this narrative.
Other APIs OpenAI publishes across the network.