--- title: "Upgrade an agent from an AgentTemplate" method: POST path: "/api/v1/agents/{agent}/upgrade" --- # Upgrade an agent from an AgentTemplate `POST /api/v1/agents/{agent}/upgrade` 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. ## Path parameters - `agent` string, required ## Request body - object - `dry_run` boolean — When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply. - `email` string — Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. - `expected_review_fingerprint` string — 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. - `identity` string — Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. - `metadata` object — 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`). - `model` string — Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model. - `name` string — Instance-specific name override. Pins this value so the template upgrade does not overwrite it. - `originator` string — Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. - `phone_number` string — Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. - `template` string — ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. ## Response `200` Successful response - AgentUpgradeResponse — Response returned by the agent upgrade endpoint, combining the updated agent, its source Solution and template, and the full upgrade diff. - `agent` Agent — An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks. - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants. - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`. - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `app` string — ID of the application that owns this agent (`dap_...`). - `created_at` string, date-time — When the agent was created (ISO 8601). - `default_model` string — Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`). - `email` string — Email address provisioned for this agent. `null` if email delivery is not configured. - `id` string, required — Agent ID (`agi_...`). - `identity` string — System-level identity prompt that shapes the agent's persona and behavior. - `last_applied_template_config` string — ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents. - `lookup_key` string — Stable, user-defined identifier for this agent within the application. Unique per app. - `metadata` object — Arbitrary key-value metadata attached to the agent. Not interpreted by the platform. - `name` string — Human-readable display name for the agent. `null` if not set. - `org` string — ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped. - `org_name` string — Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded. - `originator` string — Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name). - `phone_number` string — Phone number provisioned for this agent. `null` if SMS is not configured. - `sandbox` string — ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments. - `source_solution` AgentSourceSolution — Summary of the Solution and AgentTemplate that an agent was last provisioned from. Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. - `solution` SolutionSummary, required — A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information. - `category_keys` string[] — Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none. - `created_at` string, date-time — When the Solution config was first imported (ISO 8601). - `description` string — Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one. - `id` string, required — Solution config ID (`cfg_...`). - `kind` string, required — Resource type. Always `"Solution"`. - `latest_solution` string — When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise. - `latest_version` string — When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise. - `lookup_key` string — The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set. - `metadata` object — Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none. - `name` string — Human-facing display name declared in the Solution body. `null` when the Solution body does not set one. - `org` string — Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions. - `org_logo` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record. - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file. - `height` integer — Height of the image in pixels. `null` if not known. - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity. - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known. - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing. - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires. - `width` integer — Width of the image in pixels. `null` if not known. - `org_name` string — Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`. - `org_slug` string — Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve. - `owners` string[], required — Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer's org scope). - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. - `solution_id` string — Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it. - `solution_version` string — Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version. - `tag_keys` string[] — Freeform tag keys declared in the Solution body. An empty array when the body declares none. - `template_kind` string — Wrapped template kind — `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles. - `templates` SolutionTemplateSummary[], required — Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references. - `description` string — Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel. - `display_name` string — Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`. - `id` string — Template config ID (`cfg_...`). `null` for inline-only templates. - `kind` string, required — Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved. - `lookup_key` string — Lookup key stamped on the template config at import time. `null` when no lookup key was assigned. - `name` string — Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`. - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. - `virtual_path` string — Stable virtual path assigned to the template config. `null` when no virtual path was set. - `updated_at` string, date-time — When the Solution config was last modified (ISO 8601). - `upgrade_available` boolean, required — `true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows. - `virtual_path` string — The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset. - `template` UpgradeTemplateSummary, required — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. - `created_at` string, date-time — When this template config was created (ISO 8601). - `description` string — Description of the template from the config body. `null` if the current version has no `description` field. - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field. - `id` string, required — Template config ID (`cfg_...`). - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`). - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set. - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field. - `updated_at` string, date-time — When this template config was last modified (ISO 8601). - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set. - `team` string — ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped. - `updated_at` string, date-time — When the agent was last modified (ISO 8601). - `user` string — ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped. - `solution` SolutionSummary, required — A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information. - `category_keys` string[] — Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none. - `created_at` string, date-time — When the Solution config was first imported (ISO 8601). - `description` string — Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one. - `id` string, required — Solution config ID (`cfg_...`). - `kind` string, required — Resource type. Always `"Solution"`. - `latest_solution` string — When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise. - `latest_version` string — When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise. - `lookup_key` string — The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set. - `metadata` object — Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none. - `name` string — Human-facing display name declared in the Solution body. `null` when the Solution body does not set one. - `org` string — Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions. - `org_logo` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record. - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file. - `height` integer — Height of the image in pixels. `null` if not known. - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity. - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known. - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing. - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires. - `width` integer — Width of the image in pixels. `null` if not known. - `org_name` string — Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`. - `org_slug` string — Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve. - `owners` string[], required — Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer's org scope). - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. - `solution_id` string — Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it. - `solution_version` string — Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version. - `tag_keys` string[] — Freeform tag keys declared in the Solution body. An empty array when the body declares none. - `template_kind` string — Wrapped template kind — `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles. - `templates` SolutionTemplateSummary[], required — Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references. - `description` string — Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel. - `display_name` string — Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`. - `id` string — Template config ID (`cfg_...`). `null` for inline-only templates. - `kind` string, required — Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved. - `lookup_key` string — Lookup key stamped on the template config at import time. `null` when no lookup key was assigned. - `name` string — Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`. - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. - `virtual_path` string — Stable virtual path assigned to the template config. `null` when no virtual path was set. - `updated_at` string, date-time — When the Solution config was last modified (ISO 8601). - `upgrade_available` boolean, required — `true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows. - `virtual_path` string — The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset. - `template` UpgradeTemplateSummary, required — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. - `created_at` string, date-time — When this template config was created (ISO 8601). - `description` string — Description of the template from the config body. `null` if the current version has no `description` field. - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field. - `id` string, required — Template config ID (`cfg_...`). - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`). - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set. - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field. - `updated_at` string, date-time — When this template config was last modified (ISO 8601). - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set. - `upgrade_result` AgentUpgradeResult, required — The computed diff and outcome of an agent upgrade operation, including the full list of per-resource changes. - `changes` AgentUpgradeChange[], required — Ordered list of per-resource changes that will be (or were) applied by this upgrade. - `action` string, required — The operation that will be performed. One of `"add"`, `"update"`, `"remove"`, or `"noop"`. - `description` string — Description of the child resource this change touches, when one is set. `null` when no description is available. - `field_changes` AgentUpgradeFieldChange[] — Field-level diff entries for this change. Populated only when `action` is `"update"`; empty or absent for `add`, `remove`, and `noop` entries. - `baseline` unknown - `field` string, required — Name of the field that will change, e.g. `"name"` or `"identity"`. - `locally_edited` boolean — `true` when the agent's current value differs from `baseline`, indicating a local edit that this upgrade will overwrite. `false` when the current value matches the baseline. `null` when `baseline` is unavailable. Populated only on `agent_base` field changes. - `new` unknown - `old` unknown - `id` string — Public ID of the existing resource being updated or removed (e.g. `atl_...`, `arn_...`). `null` for `add` entries. - `key` string — Lookup key of the resource derived from its source template. `null` when the template has no lookup key. - `name` string — Human-facing name of the child resource this change touches (tool/routine/skill/computer name, or builtin tool key for unnamed builtin tools). Falls back to the source template's name. `null` for the synthetic `agent_base` entry. - `parent_template_config` UpgradeTemplateSummary, required — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. - `created_at` string, date-time — When this template config was created (ISO 8601). - `description` string — Description of the template from the config body. `null` if the current version has no `description` field. - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field. - `id` string, required — Template config ID (`cfg_...`). - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`). - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set. - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field. - `updated_at` string, date-time — When this template config was last modified (ISO 8601). - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set. - `resource` object — Resource-type-specific identity details. Tools: `tool_type`, `builtin_tool_key`, `name_prefix`, `handler_type`, `instruction`. Routines: `handler_type`, `preset_name`, `event_type`, `schedule`, `trigger_context`. Skills: `instruction`. Computers: `region`. Only populated keys are present; `null` when nothing is known. - `resource_type` string, required — Type of the child resource being changed. One of `"agent"`, `"tool"`, `"routine"`, `"skill"`, or `"computer"`. - `source_template_config` UpgradeTemplateSummary — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. - `created_at` string, date-time — When this template config was created (ISO 8601). - `description` string — Description of the template from the config body. `null` if the current version has no `description` field. - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field. - `id` string, required — Template config ID (`cfg_...`). - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`). - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set. - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field. - `updated_at` string, date-time — When this template config was last modified (ISO 8601). - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set. - `dry_run` boolean, required — `true` when the request was a dry run and no changes were persisted to the agent. - `mode` string, required — Upgrade mode that was used. One of `"full"` (apply all changes) or `"review"` (require fingerprint confirmation). - `review_fingerprint` string — Opaque fingerprint of the computed diff. Pass this value back as `review_fingerprint` to confirm and apply a `"review"` mode upgrade. - `status` string, required — Outcome of the upgrade. `"ready"` for a dry-run (no changes applied); `"upgraded"` when the upgrade was committed. - `summary` AgentUpgradeSummary, required — Aggregate counts of each change type produced by an agent upgrade diff. - `adds` integer, required — Number of child resources that will be created by this upgrade. - `noops` integer, required — Number of child resources with no changes in this upgrade. - `removes` integer, required — Number of child resources that will be removed by this upgrade. - `updates` integer, required — Number of child resources that will be updated by this upgrade. ## Other responses - `400` — Bad request - `401` — Unauthorized - `403` — App-scoped token required. Use a token scoped to the target app.; Forbidden - `404` — Agent not found; Template not found - `409` — Agent template changed since review; prepare the diff again. - `422` — Agent has no tracked template; Template has no parent Solution; Config is not an agent template; Validation failed --- [API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)