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

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Retrieve an agent

GET
/agents/{agent_id}

Retrieves a reusable agent by ID. See agent configuration.

Retrieve an agent

curl https://api.openai.com/v1/agents/$AGENT_ID \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"
200 — Example
{
  "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",
      "async": true
    }
  ],
  "updated_at": 0,
  "compaction": {
    "async": true
  },
  "experimental": {
    "time_awareness": true
  }
}
Path Parameters
agent_id: string

The ID of the reusable agent.

minLength0
maxLength1048576
Returns
Agent object { id, created_at, instructions, 12 more }

A reusable agent scoped to the caller’s project.

id: string

The ID of the reusable agent.

minLength0
created_at: integer

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

formatint64
instructions: string or null

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

minLength0
metadata: map[string]

Custom string key-value pairs attached to the agent.

model: string

The requested model name used for inference.

minLength0
multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled. Defaults to false.

max_concurrent_subagents: integer or null

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

formatint64
minimum1
maximum4294967295
name: string or null

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

minLength0
object: "agent" (default: "agent")

The object type. Always agent.

reasoning: AgentReasoning { effort, summary }

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

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

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: "concise" or "detailed" or "auto" or null

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: "auto" or "default" or "flex" or 3 more

The resolved service-tier policy used for model requests.

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

The resolved configuration for text generated by the agent.

format: TextFormat

The effective output format. Defaults to ordinary text.

One of the following:
Text object { type }

Generates ordinary text without a structured-output constraint.

type: "text" (default: "text")

The type of the object. Always text.

JSONSchema object { schema, type }

Constrains generated text to a JSON Schema.

schema: map[unknown]

The JSON Schema that generated text must match.

type: "json_schema" (default: "json_schema")

The type of the object. Always json_schema.

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

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

One of the following:
"low"
"medium"
"high"
tools: array of PersistedAgentTool

Tools available to the agent.

minItems0
maxItems2000
One of the following:
Function object { defer_loading, description, name, 3 more }

A function defined by the application.

defer_loading: boolean

Whether the function is deferred and discovered through tool search.

description: string

A description of what the function does.

minLength0
name: string

The name of the function.

minLength0
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function" (default: "function")

The type of the object. Always function.

async: optional boolean

Whether the agent continues without waiting for the function result.

ToolSearch object { type }

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

type: "tool_search" (default: "tool_search")

The type of the object. Always tool_search.

ProgrammaticToolCalling object { enabled, type }

Enables calling tools from model-generated code.

enabled: boolean

Whether tools can be called from model-generated code.

type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

The type of the object. Always programmatic_tool_calling.

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

Tools provided by a remote MCP server without stored credentials.

allowed_tools: array of string or null

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

minItems0
maxItems2000
connection_origin: "service" or "environment"

Where outbound MCP HTTP connections originate.

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

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

minLength0
request_metadata: map[unknown]

Metadata included with requests to this MCP server.

required: boolean

Whether this MCP server must initialize before the first turn.

server_label: string

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

minLength0
transport: PersistedMcpTransport

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

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

Connects to an MCP server over HTTP.

headers: map[string]

Non-secret HTTP headers sent to the MCP server.

server_url: string

The URL of the MCP server.

minLength0
type: "http" (default: "http")

The type of the object. Always http.

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

Starts an MCP server as a local process.

args: array of string

Arguments passed to the MCP server command.

minItems0
maxItems2000
command: string

The command used to start the MCP server.

minLength0
cwd: string

The working directory used to start the MCP server.

minLength0
env_vars: array of string

Environment variable names inherited from the execution environment.

minItems0
maxItems2000
type: "stdio" (default: "stdio")

The type of the object. Always stdio.

type: "mcp" (default: "mcp")

The type of the object. Always mcp.

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

Web search.

allowed_domains: array of string or null

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

minItems0
maxItems2000
context_size: "low" or "medium" or "high"

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

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

Approximate location used to localize search results, if provided.

city: string or null

The city name.

minLength0
country: string or null

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

minLength0
region: string or null

The region or state name.

minLength0
timezone: string or null

The IANA timezone, such as America/Los_Angeles.

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

The source used for web search results.

One of the following:
"disabled"
"cached"
"live"
type: "web_search" (default: "web_search")

The type of the object. Always web_search.

ComputerUse object { include_screenshots, type }

Browser use in an OpenAI-hosted session.

include_screenshots: boolean

Whether computer tool outputs include screenshots.

type: "computer_use" (default: "computer_use")

The type of the object. Always computer_use.

Automations object { type }

Lets the agent manage its own scheduled wakeups.

type: "automations" (default: "automations")

The type of the object. Always automations.

updated_at: integer

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

formatint64
compaction: optional object { async }

The effective context compaction settings.

async: boolean

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

experimental: optional object { time_awareness }

The effective experimental settings for the agent.

time_awareness: boolean

Whether the model receives periodic current-time reminders.

Returns Examples
200 — Example
{
  "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",
      "async": true
    }
  ],
  "updated_at": 0,
  "compaction": {
    "async": true
  },
  "experimental": {
    "time_awareness": true
  }
}