---
title: "Update a variation"
method: PATCH
path: "/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}"
tags: ["AgentVariationService", "Agent Variations"]
---

# Update a variation

`PATCH /v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}`

Updates a variation for an agent

## Path parameters

- `workspaceId` string, required
- `agentId` string, required
- `id` string, required

## Request body

- UpdateAgentVariationRequest — Update agent variation request
  - `workspaceId` string — Workspace ID.
  - `agentId` string — Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.
  - `id` string — Variation ID. Accepts the canonical `agentvar_…` form or the `external_id:<value>` form.
  - `metadata` UpdateResourceMetadata — UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
  - `spec` AgentVariationSpec — AgentVariationSpec defines the operational configuration for a variation
    - `systemPromptTemplate` string — Liquid template for the system prompt of objectives using this variation. Rendered with CreateObjectiveRequest.system_prompt_data into Objective.system_prompt.
    - `progressiveDiscovery` AgentVariationSpecProgressiveDiscovery — ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
      - `maxTools` integer — The most tool names tool_search will load in a single call. Requesting more than this returns an error telling the model to retry in smaller batches -- it is a per-call batch limit, not a ceiling on how many tools an objective may end up with.
      - `hints` string[] — Free-text guidance appended to the discoverable-tools appendix in the system prompt. Hints steer the model's choice of tool names; they do not filter or rank anything, because tool_search matches names exactly rather than searching.
    - `constraints` AgentVariationSpecConstraints
      - `maxToolCalls` integer — The maximum number of tool calls that can be made. 0 means no limit.
      - `maxSubObjectives` integer — The maximum number of sub-objectives that can be created. 0 means no limit.
      - `inactivityTimeout` string — How long an objective may sit with no activity (no user messages, no LLM calls) before it is finalized as timed out. Between 1 minute and 24 hours, expressed as a duration string in seconds (e.g. "7200s"). When not set, objectives are still swept at the system-wide 24 hour maximum — every objective eventually reaches a terminal state. Note: no gnostic integer hint here on purpose. The Envoy gRPC-JSON transcoder only accepts the canonical protobuf JSON form for Durations — a "<seconds>s" string — so the SDKs must type this as a string (like AgentScheduleSpec.every), not an integer.
    - `description` string — Human-readable description of what this variation does or when it should be used
    - `modelConfig` AgentVariationSpecModelConfig — ModelConfig defines the model configuration for a variation
      - `modelId` string — The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")
      - `temperature` number, float — Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness
    - `compactionConfig` AgentVariationSpecCompactionConfig — CompactionConfig defines how context window compaction behaves for objectives using this variation.
      - `triggerThreshold` number, float — Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%)
      - `summarization` CompactionConfigSummarizationStrategy — SummarizationStrategy configures LLM-powered summarization of older conversation turns.
        - `instructions` string — Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions."
      - `toolResultClearing` CompactionConfigToolResultClearingStrategy — ToolResultClearingStrategy configures clearing of older tool result content.
        - `preserveRecentResults` integer — Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2
    - `firstUserMessageTemplate` string — Liquid template for the first user message of objectives using this variation. Rendered with CreateObjectiveRequest.first_user_message_data into Objective.first_user_message, the first user message in the LLM chat history. CreateObjectiveRequest.first_user_message, when set, overrides the rendered result. If neither this template nor first_user_message is present, objective creation is rejected with InvalidArgument.
  - `updateMask` string, field-mask — Fields to update

## Response `200`

OK

- AgentVariation — AgentVariation resource
  - `metadata` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
    - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")
    - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
    - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID)
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
    - `profileId` string, required — ID of the actor (user or service account) that created this resource
    - `createdAt` string, date-time, required — Timestamp when this resource was created
    - `updatedAt` string, date-time — Timestamp when this resource was last updated
  - `spec` AgentVariationSpec, required — AgentVariationSpec defines the operational configuration for a variation
    - `systemPromptTemplate` string — Liquid template for the system prompt of objectives using this variation. Rendered with CreateObjectiveRequest.system_prompt_data into Objective.system_prompt.
    - `progressiveDiscovery` AgentVariationSpecProgressiveDiscovery — ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
      - `maxTools` integer — The most tool names tool_search will load in a single call. Requesting more than this returns an error telling the model to retry in smaller batches -- it is a per-call batch limit, not a ceiling on how many tools an objective may end up with.
      - `hints` string[] — Free-text guidance appended to the discoverable-tools appendix in the system prompt. Hints steer the model's choice of tool names; they do not filter or rank anything, because tool_search matches names exactly rather than searching.
    - `constraints` AgentVariationSpecConstraints
      - `maxToolCalls` integer — The maximum number of tool calls that can be made. 0 means no limit.
      - `maxSubObjectives` integer — The maximum number of sub-objectives that can be created. 0 means no limit.
      - `inactivityTimeout` string — How long an objective may sit with no activity (no user messages, no LLM calls) before it is finalized as timed out. Between 1 minute and 24 hours, expressed as a duration string in seconds (e.g. "7200s"). When not set, objectives are still swept at the system-wide 24 hour maximum — every objective eventually reaches a terminal state. Note: no gnostic integer hint here on purpose. The Envoy gRPC-JSON transcoder only accepts the canonical protobuf JSON form for Durations — a "<seconds>s" string — so the SDKs must type this as a string (like AgentScheduleSpec.every), not an integer.
    - `description` string — Human-readable description of what this variation does or when it should be used
    - `modelConfig` AgentVariationSpecModelConfig — ModelConfig defines the model configuration for a variation
      - `modelId` string — The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")
      - `temperature` number, float — Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness
    - `compactionConfig` AgentVariationSpecCompactionConfig — CompactionConfig defines how context window compaction behaves for objectives using this variation.
      - `triggerThreshold` number, float — Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%)
      - `summarization` CompactionConfigSummarizationStrategy — SummarizationStrategy configures LLM-powered summarization of older conversation turns.
        - `instructions` string — Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions."
      - `toolResultClearing` CompactionConfigToolResultClearingStrategy — ToolResultClearingStrategy configures clearing of older tool result content.
        - `preserveRecentResults` integer — Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2
    - `firstUserMessageTemplate` string — Liquid template for the first user message of objectives using this variation. Rendered with CreateObjectiveRequest.first_user_message_data into Objective.first_user_message, the first user message in the LLM chat history. CreateObjectiveRequest.first_user_message, when set, overrides the rendered result. If neither this template nor first_user_message is present, objective creation is rejected with InvalidArgument.
  - `info` AgentVariationInfo — AgentVariationInfo provides read-only summary information about a variation
    - `toolCount` integer — Number of individual tools assigned to this variation
    - `toolSetCount` integer — Number of tool sets assigned to this variation
    - `subAgentCount` integer — Number of sub-agents assigned to this variation
    - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
      - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
        - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")
        - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
        - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
        - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
        - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
        - `profileId` string, required
        - `createdAt` string, date-time
      - `spec` ProfileSpec, required — Configuration for a profile.
        - `email` string — Email address of the profile. Required and unique within an account for user profiles.
        - `name` string — Display name (e.g., "Bobby Tables").
        - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal.
    - `model` ResourceMetadata — Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
      - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")
      - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
      - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID)
      - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
      - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
      - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
      - `profileId` string, required — ID of the actor (user or service account) that created this resource
      - `createdAt` string, date-time, required — Timestamp when this resource was created
      - `updatedAt` string, date-time — Timestamp when this resource was last updated
    - `score` number, float — Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.
    - `feedbackCount` integer — Total number of objective feedbacks received for this variation
    - `assignments` VariationAssignment[] — All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation's full assignment list without calling the add/remove endpoints just to enumerate.
      - union — A read-only reference to a single tool, tool set, or sub-agent attached to a variation. Read the full set of assignments via `AgentVariationInfo.assignments`; mutations go through the dedicated add/remove assignment endpoints. The `id` identifies the assignment itself (not the referenced resource) and is the handle used to remove the assignment. It is returned by the add endpoint and present on every entry in `AgentVariationInfo.assignments`.
        - VariationAssignmentTool
          - `type` 'tool', required
          - `tool` BareMetadata, required — BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
            - `id` string
            - `name` string — Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).
          - `id` string
        - VariationAssignmentToolSet
          - `type` 'toolSet', required
          - `toolSet` BareMetadata, required — BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
            - `id` string
            - `name` string — Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).
          - `id` string
        - VariationAssignmentAgent
          - `type` 'agent', required
          - `agent` BareMetadata, required — BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
            - `id` string
            - `name` string — Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).
          - `id` string
    - `memoryLayerAssignments` VariationMemoryLayerAssignment[] — Read-only list of memory layer assignments for this variation, returned in ascending `position` (most specific first — resolution order). Capped at 10 entries.
      - `id` string — Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer's id.
      - `memoryLayer` BareMetadata — BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
        - `id` string
        - `name` string — Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).
      - `position` integer — Position in the variation's baseline cascade. Position is specificity, CSS-style: a LOWER position is more specific and is consulted first; the highest-position assignment is the most general fallback. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment's position is rejected with InvalidArgument.
    - `memoryLayerCount` integer — Count of memory layer assignments.

## Other responses

- `default` — Default error response

## Changes

- **2026-07-19** `3ecc1debabfa` — 2 breaking, 4 warning, 1 info
  - added `#/components/schemas/VariationAssignment_Tool, #/components/schemas/VariationAssignment_ToolSet, #/components/schemas/VariationAssignment_Agent` to the `info/allOf[#/components/schemas/AgentVariationInfo]/assignments/items/` response property `oneOf` list for the response status `200`
  - the `info/allOf[#/components/schemas/AgentVariationInfo]/assignments/items/` response's property type/format changed from `object`/`` to ``/`` for status `200`
  - removed the optional property `info/allOf[#/components/schemas/AgentVariationInfo]/assignments/items/agent` from the response with the `200` status
  - removed the optional property `info/allOf[#/components/schemas/AgentVariationInfo]/assignments/items/id` from the response with the `200` status
  - …3 more
- **2026-07-08** `7a9fa80ead32` — 2 warning
  - removed the request property `spec/progressiveDiscovery/allOf[#/components/schemas/AgentVariationSpec_ProgressiveDiscovery]/rerankThreshold`
  - removed the optional property `spec/allOf[#/components/schemas/AgentVariationSpec]/progressiveDiscovery/allOf[#/components/schemas/AgentVariationSpec_ProgressiveDiscovery]/rerankThreshold` from the response with the `200` status
- **2026-07-08** `631a0b9462a9` — 2 warning
  - removed the request property `spec/weight`
  - removed the optional property `spec/allOf[#/components/schemas/AgentVariationSpec]/weight` from the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/cadenya/apis/cadenya-api/changes/v1/workspaces/:workspaceId/agents/:agentId/variations/:id/patch.md)

---

[API](https://skmtc.dev/cadenya/apis/cadenya-api.md) · [All operations](https://skmtc.dev/cadenya/apis/cadenya-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cadenya/cadenya-api/revisions/ac1a7f084068/schema)