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

Agent beta().agents().update(AgentUpdateParamsparams = AgentUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
POST/agents/{agent_id}

Updates a reusable agent. See agent configuration.

ParametersExpand Collapse
AgentUpdateParams params
Optional<String> agentId
minLength0
maxLength1048576
Optional<String> instructions

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

minLength0
maxLength1048576
Optional<Metadata> metadata

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.

Optional<String> model

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

minLength0
maxLength1048576
Optional<MultiAgentConfigParam> multiAgent

Configuration for creating and coordinating subagents.

Optional<String> name

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

minLength0
maxLength128
Optional<AgentReasoningParam> reasoning

Configuration for model reasoning. Omit to keep the current settings; pass null to reset to the model’s default effort.

Optional<ServiceTier> serviceTier

The service tier used for model requests.

Optional<AgentTextParam> text

Configuration for text generated by the agent.

Optional<List<PersistedAgentToolParam>> tools

Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.

ReturnsExpand Collapse
class Agent:

A reusable agent scoped to the caller’s project.

String id

The ID of the reusable agent.

minLength0
long createdAt

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

formatint64
Optional<String> instructions

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

minLength0
Metadata metadata

Custom string key-value pairs attached to the agent.

String model

The requested model name used for inference.

minLength0
MultiAgentConfig multiAgent

The resolved configuration for creating and coordinating subagents.

Optional<String> name

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

minLength0
JsonValue; object_ "agent"constant"agent"constant

The object type. Always agent.

AgentReasoning reasoning

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

ServiceTier serviceTier

The resolved service-tier policy used for model requests.

AgentText text

The resolved configuration for text generated by the agent.

List<PersistedAgentTool> tools

Tools available to the agent.

long updatedAt

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

formatint64

Update an agent

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.beta.agents.AgentReasoningParam;
import com.openai.models.beta.agents.AgentUpdateParams;

public class AgentUpdateExample {
    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();
        String agentId = "your-agent-id";

        // 1. Omit reasoning: keep its current settings while renaming the agent.
        client.beta().agents().update(AgentUpdateParams.builder()
            .agentId(agentId)
            .name("Renamed")
            .build());

        // 2. Send null: reset reasoning to the model's defaults.
        client.beta().agents().update(AgentUpdateParams.builder()
            .agentId(agentId)
            .reasoning(JsonValue.from(null))
            .build());

        // 3. Send an object: replace the entire reasoning configuration, without merging.
        // The agent's model must support the "low" reasoning effort.
        client.beta().agents().update(AgentUpdateParams.builder()
            .agentId(agentId)
            .reasoning(AgentReasoningParam.builder()
                .effort(AgentReasoningParam.Effort.LOW)
                .build())
            .build());
    }
}

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