Sign in

v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Upgrade an agent from an AgentTemplate

Upgrades an existing agent by reconciling it against an AgentTemplate from a Solution. Supports two modes:

  • "reapply" (default) — re-applies the agent's currently tracked template, picking up any changes the template author has made since the last apply.
  • "replace" — moves the agent to a different template. template is required in this mode.

Set dry_run: true to compute and return the full upgrade diff (adds, updates, removes, noops) without writing any changes. The response includes a review_fingerprint you can pass back via expected_review_fingerprint on the live apply to guard against the diff changing between review and execution.

Safe overrides (name, email, phone_number, metadata, identity, originator, model) let you pin instance-specific values that should not be overwritten by the template during the upgrade.

The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

post/api/v1/agents/{agent}/upgrade

Path parameters

agentstring required

ID (agi_...) or lookup_key of the agent to upgrade.

Request body

dry_runboolean

When true, computes and returns the full upgrade diff without persisting any changes. Use with expected_review_fingerprint to guard the live apply.

emailstring

Instance-specific email address override. Pins this value so the template upgrade does not overwrite it.

expected_review_fingerprintstring

Stale-review guard. Pass the review_fingerprint returned by a prior dry_run response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches.

identitystring

Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it.

metadataobject

Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it.

mode'reapply' | 'replace'

Upgrade mode. "reapply" (default) refreshes the agent's tracked template; "replace" moves the agent to a different template (requires template).

modelstring

Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model.

namestring

Instance-specific name override. Pins this value so the template upgrade does not overwrite it.

originatorstring

Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it.

phone_numberstring

Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it.

templatestring

ID (cfg_...) or lookup_key of the target AgentTemplate config. Optional in "reapply" mode; required in "replace" mode.

Example request

{
  "dry_run": true,
  "email": "user@example.com",
  "expected_review_fingerprint": "string",
  "identity": "string",
  "metadata": {
    "key": "value"
  },
  "mode": "reapply",
  "model": "string",
  "name": "Example Name",
  "originator": "string",
  "phone_number": "+15555550123",
  "template": "string"
}

Response

Successful response

Example response

{
  "agent": {
    "acl": {
      "add": [
        {
          "actions": [
            "read",
            "write"
          ],
          "principal": "string",
          "principal_type": "user"
        }
      ],
      "grants": [
        {
          "actions": [
            "read",
            "write"
          ],
          "principal": "string",
          "principal_type": "user"
        }
      ],
      "remove": [
        {
          "principal": "string",
          "principal_type": "user"
        }
      ]
    },
    "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
    "created_at": "2024-01-01T00:00:00Z",
    "default_model": "claude-3-7-sonnet-latest",
    "email": "user@example.com",
    "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "identity": "You are a helpful assistant that answers questions about ArchAstro products.",
    "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
    "lookup_key": "string",
    "metadata": {
      "key": "value"
    },
    "name": "Example Name",
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "org_name": "Example Name",
    "originator": "deploy-pipeline",
    "phone_number": "+15555550123",
    "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
    "source_solution": {
      "solution": {
        "category_keys": [
          "string"
        ],
        "created_at": "2024-01-01T00:00:00Z",
        "description": "An example description.",
        "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "kind": "Solution",
        "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "latest_version": "1.0.0",
        "lookup_key": "string",
        "metadata": {
          "key": "value"
        },
        "name": "Example Name",
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "org_logo": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "org_name": "Example Name",
        "org_slug": "example-slug",
        "owners": [
          "string"
        ],
        "readme_url": "https://example.com",
        "solution_id": "01234567-89ab-cdef-0123-456789abcdef",
        "solution_version": "1.2.0",
        "tag_keys": [
          "string"
        ],
        "template_kind": "AgentTemplate",
        "templates": [
          {
            "description": "An example description.",
            "display_name": "Example Name",
            "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
            "kind": "AgentTemplate",
            "lookup_key": "string",
            "name": "Example Name",
            "readme_url": "https://example.com",
            "virtual_path": "string"
          }
        ],
        "updated_at": "2024-01-01T00:00:00Z",
        "upgrade_available": true,
        "virtual_path": "string"
      },
      "template": {
        "created_at": "2024-01-01T00:00:00Z",
        "description": "An example description.",
        "display_name": "Example Name",
        "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "kind": "agent_tool_template",
        "lookup_key": "string",
        "name": "Example Name",
        "updated_at": "2024-01-01T00:00:00Z",
        "virtual_path": "string"
      }
    },
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "updated_at": "2024-01-01T00:00:00Z",
    "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
  },
  "solution": {
    "category_keys": [
      "string"
    ],
    "created_at": "2024-01-01T00:00:00Z",
    "description": "An example description.",
    "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
    "kind": "Solution",
    "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
    "latest_version": "1.0.0",
    "lookup_key": "string",
    "metadata": {
      "key": "value"
    },
    "name": "Example Name",
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "org_logo": {
      "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
      "height": 600,
      "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
      "mime_type": "application/json",
      "refresh_url": "https://example.com",
      "url": "https://example.com",
      "width": 800
    },
    "org_name": "Example Name",
    "org_slug": "example-slug",
    "owners": [
      "string"
    ],
    "readme_url": "https://example.com",
    "solution_id": "01234567-89ab-cdef-0123-456789abcdef",
    "solution_version": "1.2.0",
    "tag_keys": [
      "string"
    ],
    "template_kind": "AgentTemplate",
    "templates": [
      {
        "description": "An example description.",
        "display_name": "Example Name",
        "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "kind": "AgentTemplate",
        "lookup_key": "string",
        "name": "Example Name",
        "readme_url": "https://example.com",
        "virtual_path": "string"
      }
    ],
    "updated_at": "2024-01-01T00:00:00Z",
    "upgrade_available": true,
    "virtual_path": "string"
  },
  "template": {
    "created_at": "2024-01-01T00:00:00Z",
    "description": "An example description.",
    "display_name": "Example Name",
    "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
    "kind": "agent_tool_template",
    "lookup_key": "string",
    "name": "Example Name",
    "updated_at": "2024-01-01T00:00:00Z",
    "virtual_path": "string"
  },
  "upgrade_result": {
    "changes": [
      {
        "action": "update",
        "description": "An example description.",
        "field_changes": [
          {
            "field": "name",
            "locally_edited": true
          }
        ],
        "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "key": "string",
        "name": "Example Name",
        "parent_template_config": {
          "created_at": "2024-01-01T00:00:00Z",
          "description": "An example description.",
          "display_name": "Example Name",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "agent_tool_template",
          "lookup_key": "string",
          "name": "Example Name",
          "updated_at": "2024-01-01T00:00:00Z",
          "virtual_path": "string"
        },
        "resource": {},
        "resource_type": "tool",
        "source_template_config": {
          "created_at": "2024-01-01T00:00:00Z",
          "description": "An example description.",
          "display_name": "Example Name",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "agent_tool_template",
          "lookup_key": "string",
          "name": "Example Name",
          "updated_at": "2024-01-01T00:00:00Z",
          "virtual_path": "string"
        }
      }
    ],
    "dry_run": true,
    "mode": "full",
    "review_fingerprint": "string",
    "status": "upgraded",
    "summary": {
      "adds": 1,
      "noops": 1,
      "removes": 1,
      "updates": 1
    }
  }
}