API Reference

Beta

Agents

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve an agent

beta.agents.retrieve(agent_id) -> Agent { id, created_at, instructions, 10 more }

GET/agents/{agent_id}

Retrieves a reusable agent by ID. See agent configuration.

ParametersExpand Collapse

agent_id: String

minLength0

maxLength1048576

ReturnsExpand Collapse

class Agent { id, created_at, instructions, 10 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

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

minLength0

metadata: Hash[Symbol, 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.

name: String

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.

service_tier: :auto | :default | :flex | 2 more

The resolved service-tier policy used for model requests.

text: AgentText { format_, verbosity }

The resolved configuration for text generated by the agent.

tools: Array[PersistedAgentTool]

Tools available to the agent.

updated_at: Integer

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

formatint64

Retrieve an agent

Ruby

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

agent = openai.beta.agents.retrieve("agent_id")

puts(agent)

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"
    }
  ],
  "updated_at": 0
}

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"
    }
  ],
  "updated_at": 0
}