List agents

GET/agents

Lists reusable agents in the current project. See agent configuration.

Query ParametersExpand Collapse

after: optional string

Return resources after this resource ID in the selected order.

minLength0

maxLength1048576

limit: optional number or null

The maximum number of resources to return.

formatint64

minimum1

order: optional "asc" or "desc"

The order in which resources are returned. Defaults to desc.

One of the following:

"asc"

Returns resources in ascending order.

"desc"

Returns resources in descending order.

ReturnsExpand Collapse

data: array of Agent { id, created_at, instructions, 10 more }

The resources returned in this page, in the requested sort order.

id: string

The ID of the reusable agent.

minLength0

created_at: number

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

formatint64

instructions: string or null

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

minLength0

metadata: map[string]

Custom string key-value pairs attached to the agent.

model: string

The requested model name used for inference.

minLength0

multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled. Defaults to false.

max_concurrent_subagents: number or null

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

formatint64

minimum1

maximum4294967295

name: string or null

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

minLength0

object: "agent"

The object type. Always agent.

reasoning: AgentReasoning { effort, summary }

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

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

The amount of reasoning effort used by an agent.

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

"max"

summary: "concise" or "detailed" or "auto" or null

The reasoning summary format requested from an agent.

One of the following:

"concise"

Returns a concise reasoning summary when supported.

"detailed"

Returns a detailed reasoning summary when supported.

"auto"

Automatically selects the most detailed summary supported by the model.

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

The resolved service-tier policy used for model requests.

One of the following:

"auto"

"default"

"flex"

"priority"

"fast"

text: AgentText { format, verbosity }

The resolved configuration for text generated by the agent.

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"

The type of the object. Always text.

JSONSchema object { schema, type }

Constrains generated text to a JSON Schema.

schema: map[unknown]

The JSON Schema that generated text must match.

type: "json_schema"

The type of the object. Always json_schema.

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.

One of the following:

Function object { defer_loading, description, name, 2 more }

A function defined by the application.

defer_loading: boolean

Whether the function is deferred and discovered through tool search.

description: string

A description of what the function does.

minLength0

name: string

The name of the function.

minLength0

parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

ToolSearch object { type }

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

type: "tool_search"

The type of the object. Always tool_search.

ProgrammaticToolCalling object { enabled, type }

Enables calling tools from model-generated code.

enabled: boolean

Whether tools can be called from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

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

Tools provided by a remote MCP server without stored credentials.

allowed_tools: array of string or null

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

connection_origin: "service" or "environment"

Where outbound MCP HTTP connections originate.

One of the following:

"service"

"environment"

credential_id: string or null

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

minLength0

request_metadata: map[unknown]

Metadata included with requests to this MCP server.

required: boolean

Whether this MCP server must initialize before the first turn.

server_label: string

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

minLength0

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"

The type of the object. Always http.

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

Starts an MCP server as a local process.

args: array of string

Arguments passed to the MCP server command.

command: string

The command used to start the MCP server.

minLength0

cwd: string

The working directory used to start the MCP server.

minLength0

env_vars: array of string

Environment variable names inherited from the execution environment.

type: "stdio"

The type of the object. Always stdio.

type: "mcp"

The type of the object. Always mcp.

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

Web search.

allowed_domains: array of string or null

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

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

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

One of the following:

"low"

"medium"

"high"

location: object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: string or null

The city name.

minLength0

country: string or null

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

minLength0

region: string or null

The region or state name.

minLength0

timezone: string or null

The IANA timezone, such as America/Los_Angeles.

minLength0

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

The source used for web search results.

One of the following:

"disabled"

"cached"

"live"

type: "web_search"

The type of the object. Always web_search.

updated_at: number

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

formatint64

first_id: string or null

The ID of the first resource in data, or null if the page is empty.

minLength0

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.

minLength0

object: "list"

The object type, which is always list.

List agents

curl https://api.openai.com/v1/agents \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

{
  "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"
}

Returns Examples

{
  "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"
}

Suggested

Suggested

List agents

Query ParametersExpand Collapse

ReturnsExpand Collapse

List agents

Returns Examples