API Reference

Beta

Agents

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List agents

beta.agents.list(**kwargs) -> CursorPage<Agent { id, created_at, instructions, 10 more } >

GET/agents

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

ParametersExpand Collapse

after: String

Return resources after this resource ID in the selected order.

minLength0

maxLength1048576

limit: Integer

The maximum number of resources to return.

formatint64

minimum1

order: :asc | :desc

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

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

List agents

Ruby

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

require "openai"

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

page = openai.beta.agents.list

puts(page)

200 example

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

200 example

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