> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an Agent

> Revise an agent your organization owns, cutting a new version

Revise an agent your organization owns.

Every field is optional — omitted fields keep their current value. Each call cuts a new agent version rather than editing in place, so the previous state stays addressable.

Use the `id` returned by [Create an Agent](/api-reference/v1-agent/create-agent) as `{agentId}`.

Requires the **Agent: Full** permission at organization level.

<Warning>
  `blueprint`, `inputs` and `outputs` are replaced **wholesale**, not merged field by field. Send the complete object you want stored — a partial `inputs` map drops every variable you left out.
</Warning>

<Note>
  Unlike create, this endpoint can target either kind of agent: a Custom Agent authored through the API, or an Opus Agent authored in the Opus app. An agent's class is fixed when it is created and cannot be changed here — the `blueprint` you send must match it. See [Blueprint shapes](#blueprint-shapes).
</Note>

## Headers

<ParamField header="x-service-key" type="string" required>
  Your API authentication key
</ParamField>

## Path Parameters

<ParamField path="agentId" type="string" required>
  The agent to revise. This is `id` from [Create an Agent](/api-reference/v1-agent/create-agent) — not its `versionId`. Must be a UUID.
</ParamField>

## Body Parameters

The agent is nested under an `agent` key.

<ParamField body="agent" type="object" required>
  The fields to change. All of them are optional.
</ParamField>

<ParamField body="agent.name" type="string">
  Agent display name. Maximum 255 characters.
</ParamField>

<ParamField body="agent.description" type="string">
  What the agent does, shown under its name. Maximum 2048 characters.
</ParamField>

<ParamField body="agent.icon" type="string">
  Agent icon as a base64-encoded SVG (or PNG) — a plain string, with no `data:` prefix. Maximum 65535 characters.
</ParamField>

<ParamField body="agent.blueprint" type="object">
  Replacement implementation, in the shape matching the agent's class. Replaces the stored blueprint wholesale. Maximum 256KB JSON-encoded. See [Blueprint shapes](#blueprint-shapes).
</ParamField>

<ParamField body="agent.inputs" type="object">
  Replacement input schema, keyed by each variable's `variableName`. Same shape and limits as on create — see [Variable object](/api-reference/v1-agent/create-agent#variable-object).
</ParamField>

<ParamField body="agent.outputs" type="object">
  Replacement output schema. Same shape and limits as `inputs`.
</ParamField>

<ParamField body="agent.categories" type="string[]">
  Replacement category list. Maximum 5 entries. See [Categories](/api-reference/v1-agent/create-agent#categories).
</ParamField>

<ParamField body="agent.status" type="string">
  Agent status — `active`, `inactive`, `soon` or `deprecated`.
</ParamField>

<ParamField body="agent.isNew" type="boolean">
  Show the "new" badge on the agent tile.
</ParamField>

<ParamField body="agent.isPopular" type="boolean">
  Show the "popular" badge on the agent tile.
</ParamField>

<ParamField body="agent.isBeta" type="boolean">
  Show the "beta" badge on the agent tile. Accepted but not echoed back in the response.
</ParamField>

## Blueprint shapes

`blueprint` takes one of two shapes, depending on the class of the agent you are updating. Whichever shape you send, its `model`/`provider` pair and its `backupModel`/`backupProvider` pair are validated exactly as they are on create — see [Models and providers](/api-reference/v1-agent/create-agent#models-and-providers).

### Custom Agents

Every agent created through [Create an Agent](/api-reference/v1-agent/create-agent) is a [Custom Agent](/tasks/agent/custom-agent) — a model driven by a system prompt and a prompt. Send the same shape that endpoint takes, see [Blueprint](/api-reference/v1-agent/create-agent#blueprint).

### Opus Agents

An [Opus Agent](/tasks/agent/opus-agent) follows a blueprint of ordered steps instead of raw prompts. These cannot be created through the API, but one authored in the Opus app can be revised here.

<ParamField body="blueprint" type="object" required>
  The blueprint itself. Fields below.
</ParamField>

<ParamField body="blueprint.objective" type="string" required>
  What the agent is for, in one sentence.
</ParamField>

<ParamField body="blueprint.inputDescription" type="string" required>
  What the agent receives.
</ParamField>

<ParamField body="blueprint.inputItems" type="object[]" required>
  The inputs, itemised. Each entry is `{ name, description }`.
</ParamField>

<ParamField body="blueprint.processDescription" type="string" required>
  How the agent gets from input to output.
</ParamField>

<ParamField body="blueprint.outputDescription" type="string" required>
  What the agent produces.
</ParamField>

<ParamField body="blueprint.outputItems" type="object[]" required>
  The outputs, itemised. Each entry is `{ name, description }`.
</ParamField>

<ParamField body="blueprint.requiredSteps" type="object[]" required>
  Ordered steps the agent must take, each `{ name, description }`. The authoring tools expect between two and five; this endpoint does not enforce that.
</ParamField>

<ParamField body="blueprint.description" type="string">
  Longer prose about the agent, carried alongside the objective. Stored and handed back unchanged.
</ParamField>

<ParamField body="model" type="string">
  Model the agent runs on, for example `gpt-4o`. Must be one the platform routes to.
</ParamField>

<ParamField body="provider" type="string">
  Provider of that model, for example `openai`. Must agree with the model when both are given.
</ParamField>

<ParamField body="backupModel" type="string">
  Model to fall back to. Validated the same way as `model`.
</ParamField>

<ParamField body="backupProvider" type="string">
  Provider of the fallback model. Validated the same way as `provider`.
</ParamField>

<Warning>
  `blueprint` is forwarded untouched and stored verbatim, and this endpoint does **not** check it against the agent's class — a blueprint of steps sent to a Custom Agent is stored as-is and leaves it running on empty prompts. Send the shape that matches the agent you are updating.
</Warning>

## Response

<ResponseField name="id" type="string" required>
  The agent id.
</ResponseField>

<ResponseField name="name" type="string" required>
  Agent display name.
</ResponseField>

<ResponseField name="description" type="string">
  Agent description.
</ResponseField>

<ResponseField name="icon" type="string">
  Agent icon.
</ResponseField>

<ResponseField name="categories" type="string[]">
  Categories the agent is filed under.
</ResponseField>

<ResponseField name="status" type="string">
  Agent status.
</ResponseField>

<ResponseField name="versionId" type="string">
  Id of the new version this call created.
</ResponseField>

<ResponseField name="groupId" type="string">
  Owning workspace, or `null` when the agent is visible across the marketplace.
</ResponseField>

## Errors

<ResponseField name="400" type="Bad Request">
  Invalid body, an `agentId` that is not a UUID, or a `blueprint` naming a model or provider the platform cannot route to.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Missing, invalid, or expired API key.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  The agent belongs to another organization, the API key is not org-scoped, or the key owner lacks the **Agent: Full** permission in the organization.
</ResponseField>

<ResponseField name="404" type="Not Found">
  No agent with that id.
</ResponseField>

<ResponseField name="422" type="Unprocessable Entity">
  Rejected downstream after passing validation here.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://operator.opus.com/api/v1/agent/{AGENT_ID} \
    --header 'Content-Type: application/json' \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --data '{
      "agent": {
        "name": "Adder v2",
        "description": "Adds two numbers and returns the total",
        "categories": ["numerical_computation", "aggregation_and_analysis"],
        "blueprint": {
          "systemPrompt": "You are a careful arithmetic assistant. Show no working.",
          "userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
          "model": "gpt-4o",
          "provider": "openai"
        },
        "status": "active",
        "isNew": false
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  agent_id = "{AGENT_ID}"
  url = f"https://operator.opus.com/api/v1/agent/{agent_id}"
  headers = {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}"
  }
  payload = {
      "agent": {
          "name": "Adder v2",
          "description": "Adds two numbers and returns the total",
          "categories": ["numerical_computation", "aggregation_and_analysis"],
          "blueprint": {
              "systemPrompt": "You are a careful arithmetic assistant. Show no working.",
              "userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
              "model": "gpt-4o",
              "provider": "openai",
          },
          "status": "active",
          "isNew": False,
      }
  }

  response = requests.patch(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const agentId = "{AGENT_ID}";

  const response = await fetch(`https://operator.opus.com/api/v1/agent/${agentId}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}",
    },
    body: JSON.stringify({
      agent: {
        name: "Adder v2",
        description: "Adds two numbers and returns the total",
        categories: ["numerical_computation", "aggregation_and_analysis"],
        blueprint: {
          systemPrompt: "You are a careful arithmetic assistant. Show no working.",
          userPrompt: "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
          model: "gpt-4o",
          provider: "openai",
        },
        status: "active",
        isNew: false,
      },
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "id": "{AGENT_ID}",
    "name": "Adder v2",
    "description": "Adds two numbers and returns the total",
    "icon": "{BASE64_ICON}",
    "categories": ["numerical_computation", "aggregation_and_analysis"],
    "status": "active",
    "versionId": "{NEW_AGENT_VERSION_ID}",
    "groupId": null
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.