id: str

The ID of the agent.

minLength0
instructions: Optional[str]

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

minLength0
model: str

The model used by the agent.

minLength0
multi_agent: MultiAgentConfig

Configuration for creating and coordinating subagents.

enabled: bool

Whether subagent tools are enabled. Defaults to false.

max_concurrent_subagents: Optional[int]

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

formatint64
minimum1
maximum4294967295
name: Optional[str]

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

minLength0
reasoning: AgentReasoning

The agent’s reasoning configuration.

effort: Optional[Literal["none", "minimal", "low", 4 more]]

The requested reasoning effort, or null when the model selects its own default.

One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: Optional[Literal["concise", "detailed", "auto"]]

The requested reasoning summary format, or null when summaries are disabled.

One of the following:
"concise"

Returns a concise reasoning summary when supported.

"detailed"

Returns a detailed reasoning summary when supported.

"auto"

Automatically selects the most detailed summary supported by the model.

service_tier: Literal["auto", "default", "flex", 3 more]

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

One of the following:
"auto"
"default"
"flex"
"priority"
"fast"
"ultrafast"
text: AgentText

Configuration for text generated by the agent.

format: TextFormat

The effective output format. Defaults to ordinary text.

One of the following:
class TextFormatResourceText: …

Generates ordinary text without a structured-output constraint.

type: Literal["text"]

The type of the object. Always text.

class TextFormatResourceJSONSchema: …

Constrains generated text to a JSON Schema.

schema: Dict[str, object]

The JSON Schema that generated text must match.

type: Literal["json_schema"]

The type of the object. Always json_schema.

verbosity: Literal["low", "medium", "high"]

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

One of the following:
"low"
"medium"
"high"
tools: List[AgentTool]

Tools available to the agent.

minItems0
maxItems2000
One of the following:
class AgentToolResourceFunction: …

A function defined by the application.

defer_loading: bool

Whether the function is deferred and discovered through tool search.

description: str

A description of what the function does.

minLength0
name: str

The name of the function.

minLength0
parameters: Dict[str, object]

A JSON Schema object describing the function’s arguments.

type: Literal["function"]

The type of the object. Always function.

async_: Optional[bool]

Whether the agent continues without waiting for the function result.

class AgentToolResourceProgrammaticToolCalling: …

Enables calling tools from model-generated code.

enabled: bool

Whether tools can be called from model-generated code.

type: Literal["programmatic_tool_calling"]

The type of the object. Always programmatic_tool_calling.

class AgentToolResourceMcp: …

Tools provided by a remote MCP server.

allowed_tools: Optional[List[str]]

The MCP tools the agent may call.

minItems0
maxItems2000
connection_origin: Literal["service", "environment"]

Where outbound MCP HTTP connections originate.

One of the following:
"service"
"environment"
credential_id: Optional[str]

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

minLength0
request_metadata: Dict[str, object]

Metadata included with requests to this MCP server.

required: bool

Whether this MCP server must initialize before the first turn.

server_label: str

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

minLength0
transport: McpTransport

The transport used to connect to the MCP server.

One of the following:
class McpTransportResourceHTTP: …

Connects to an MCP server over HTTP.

server_url: str

The URL of the MCP server.

minLength0
type: Literal["http"]

The type of the object. Always http.

class McpTransportResourceStdio: …

Starts an MCP server as a local process.

args: List[str]

Arguments passed to the MCP server command.

minItems0
maxItems2000
command: str

The command used to start the MCP server.

minLength0
cwd: str

The working directory used to start the MCP server.

minLength0
env_vars: List[str]

Environment variable names inherited from the execution environment.

minItems0
maxItems2000
type: Literal["stdio"]

The type of the object. Always stdio.

type: Literal["mcp"]

The type of the object. Always mcp.

class AgentToolResourceWebSearch: …

Web search.

allowed_domains: Optional[List[str]]

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

minItems0
maxItems2000
context_size: Literal["low", "medium", "high"]

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

One of the following:
"low"
"medium"
"high"
location: Optional[AgentToolResourceWebSearchLocation]

Approximate location used to localize search results, if provided.

city: Optional[str]

The city name.

minLength0
country: Optional[str]

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

minLength0
region: Optional[str]

The region or state name.

minLength0
timezone: Optional[str]

The IANA timezone, such as America/Los_Angeles.

minLength0
mode: Literal["disabled", "cached", "live"]

The source used for web search results.

One of the following:
"disabled"
"cached"
"live"
type: Literal["web_search"]

The type of the object. Always web_search.

class AgentToolResourceComputerUse: …

Browser use in an OpenAI-hosted session.

include_screenshots: bool

Whether computer tool outputs include screenshots.

type: Literal["computer_use"]

The type of the object. Always computer_use.

class AgentToolResourceAutomations: …

Lets the agent manage its own scheduled wakeups.

type: Literal["automations"]

The type of the object. Always automations.

compaction: Optional[AgentCompaction]

The effective context compaction settings.

async_: bool

Whether context is compacted in the background. Defaults to true.

experimental: Optional[AgentExperimental]

The effective experimental settings for the agent.

time_awareness: bool

Whether the model receives periodic current-time reminders.