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

Update an agent

client.Beta.Agents.Update(ctx, agentID, body) (*Agent, error)
POST/agents/{agent_id}

Updates a reusable agent. See agent configuration.

ParametersExpand Collapse
agentID string
minLength0
maxLength1048576
body BetaAgentUpdateParams
ReturnsExpand Collapse
type Agent struct{…}

A reusable agent scoped to the caller’s project.

ID string

The ID of the reusable agent.

minLength0
CreatedAt int64

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 map[string, string]

Custom string key-value pairs attached to the agent.

Model string

The requested model name used for inference.

minLength0
MultiAgent MultiAgentConfig

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

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

ServiceTier AgentServiceTier

The resolved service-tier policy used for model requests.

Text AgentText

The resolved configuration for text generated by the agent.

Tools []PersistedAgentToolUnion

Tools available to the agent.

UpdatedAt int64

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

formatint64

Update an agent

package main

import (
    "context"
    "log"

    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/packages/param"
)

func main() {
    client := openai.NewClient()
    ctx := context.Background()
    agentID := "your-agent-id"

    // 1. Omit reasoning: keep its current settings while renaming the agent.
    _, err := client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{
        Name: openai.String("Renamed"),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Send null: reset reasoning to the model's defaults.
    _, err = client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{
        Reasoning: param.NullStruct[openai.AgentReasoningParam](),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 3. Send an object: replace the entire reasoning configuration, without merging.
    // The agent's model must support the "low" reasoning effort.
    _, err = client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{
        Reasoning: openai.AgentReasoningParam{Effort: openai.AgentReasoningParamEffortLow},
    })
    if err != nil {
        log.Fatal(err)
    }
}

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