SpyBara
Go Premium

resources/beta/subresources/agents/methods/retrieve/index.md 2026-09-10 18:01 UTC to 2026-09-11 20:00 UTC

This page contains 400 additions and 0 deletions.

2026
Fri 11 20:00 Fri 18 22:59

Retrieve an agent

get /agents/{agent_id}

Retrieves a reusable agent by ID. See agent 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

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

Response

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