API Reference

Beta

Agents

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Update an agent

beta.agents.update(stragent_id, AgentUpdateParams**kwargs) -> Agent

POST/agents/{agent_id}

Updates a reusable agent. See agent configuration.

ParametersExpand Collapse

agent_id: str

minLength0

maxLength1048576

instructions: Optional[str]

Additional instructions appended to the agent’s default base instructions. Omit to leave unchanged.

minLength0

maxLength1048576

metadata: Optional[Dict[str, str]]

Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.

model: Optional[str]

The model to use for the agent. The requested model name is preserved.

minLength0

maxLength1048576

multi_agent: Optional[MultiAgentConfigParam]

Explicit configuration for creating and coordinating subagents.

name: Optional[str]

A replacement name. Omit to leave unchanged, or pass null to clear it.

minLength0

maxLength128

reasoning: Optional[AgentReasoningParam]

Reasoning configuration for the agent.

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

The service tier used for model requests.

text: Optional[AgentTextParam]

Configuration for text generated by the agent.

tools: Optional[Iterable[PersistedAgentToolParam]]

Tools available to the agent.

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

Update an agent

Python

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
agent = client.beta.agents.update(
    agent_id="agent_id",
)
print(agent.id)

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
}