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

Suggested
Overview Models Agents Tools Audio & voice Production API reference
API Reference
Beta
Agents

List agents

beta.agents.list(AgentListParams**kwargs) -> SyncCursorPage[Agent]
GET/agents

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

ParametersExpand Collapse
after: Optional[str]

Return resources after this resource ID in the selected order.

minLength0
maxLength1048576
limit: Optional[int]

The maximum number of resources to return.

formatint64
minimum1
order: Optional[Literal["asc", "desc"]]

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

ReturnsExpand Collapse
class Agent: …

A reusable agent scoped to the caller’s project.

id: str

The ID of the reusable agent.

minLength0
created_at: int

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

formatint64
instructions: Optional[str]

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

minLength0
metadata: Dict[str, str]

Custom string key-value pairs attached to the agent.

model: str

The requested model name used for inference.

minLength0
multi_agent: MultiAgentConfig

The resolved configuration for creating and coordinating subagents.

name: Optional[str]

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

minLength0
object: Literal["agent"]

The object type. Always agent.

reasoning: AgentReasoning

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

service_tier: Literal["auto", "default", "flex", 2 more]

The resolved service-tier policy used for model requests.

text: AgentText

The resolved configuration for text generated by the agent.

tools: List[PersistedAgentTool]

Tools available to the agent.

updated_at: int

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

formatint64

List agents

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.beta.agents.list()
page = page.data[0]
print(page.id)
{
  "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"
}