# Variations

## List variations

`$ cadenya agents:variations list`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations`

Lists all variations for an agent

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--bundle-key: optional string`

  Filter by bundle_key — return only resources owned by this bundle.

- `--cursor: optional string`

  Pagination cursor from previous response

- `--include-info: optional boolean`

  When true, the `info` field on each returned variation is populated.
  Requests with this flag count more against your rate limit.

- `--limit: optional number`

  Maximum number of results to return

- `--sort-order: optional string`

  Sort order for results (asc or desc by creation time)

### Returns

- `ListAgentVariationsResponse: object { items, pagination }`

  List agent variations response

  - `items: optional array of AgentVariation`

    - `metadata: object { id, accountId, createdAt, 6 more }`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: string`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `accountId: string`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `createdAt: string`

        Timestamp when this resource was created

      - `name: string`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profileId: string`

        ID of the actor (user or service account) that created this resource

      - `workspaceId: string`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundleKey: optional string`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `externalId: optional string`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: optional map[string]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: object { compactionConfig, constraints, description, 6 more }`

      AgentVariationSpec defines the operational configuration for a variation

      - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }`

        CompactionConfig defines how context window compaction behaves for objectives using this variation.

        - `summarization: optional object { instructions }`

          SummarizationStrategy configures LLM-powered summarization of older conversation turns.

          - `instructions: optional 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: optional object { preserveRecentResults }`

          ToolResultClearingStrategy configures clearing of older tool result content.

          - `preserveRecentResults: optional number`

            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

        - `triggerThreshold: optional number`

          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%)

      - `constraints: optional object { maxSubObjectives, maxToolCalls }`

        Execution constraints

        - `maxSubObjectives: optional number`

          The maximum number of sub-objectives that can be created. 0 means no limit.

        - `maxToolCalls: optional number`

          The maximum number of tool calls that can be made. 0 means no limit.

      - `description: optional string`

        Human-readable description of what this variation does or when it should be used

      - `enableEpisodicMemory: optional boolean`

        Enable episodic memory for objectives using this variation.
        When true, the system automatically creates a document namespace for each objective
        using the objective's episodic_key as the external_id, allowing the agent to
        store and retrieve documents specific to that episode.

      - `episodicMemoryTtl: optional number`

        How long episodic memories should be retained.
        After this duration, episodic document namespaces can be automatically cleaned up.
        If not set, episodic memories are retained indefinitely.

      - `modelConfig: optional object { modelId, temperature }`

        ModelConfig defines the model configuration for a variation

        - `modelId: optional string`

          The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

        - `temperature: optional number`

          Sampling temperature for model inference (0.0 to 1.0)
          Lower values produce more deterministic outputs, higher values increase randomness

      - `progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }`

        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.

        - `hints: optional array of string`

        - `maxTools: optional number`

        - `rerankThreshold: optional number`

          Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
          which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
          the tool very closely match the query the tool search performed.

      - `prompt: optional string`

        The system prompt for this variation

      - `weight: optional number`

        Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
        Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

    - `info: optional object { assignments, createdBy, feedbackCount, 7 more }`

      AgentVariationInfo provides read-only summary information about a variation

      - `assignments: optional array of 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.

        - `id: optional string`

        - `agent: optional object { id, name }`

          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: optional string`

          - `name: optional 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).

        - `tool: optional object { id, name }`

          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: optional string`

          - `name: optional 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).

        - `toolSet: optional object { id, name }`

          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: optional string`

          - `name: optional 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).

      - `createdBy: optional object { metadata, spec }`

        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: object { id, accountId, name, 3 more }`

          AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

          - `id: string`

            Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

          - `accountId: string`

            Account this resource belongs to for multi-tenant isolation (prefixed ULID)

          - `name: string`

            Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
            Required for resources that users interact with directly

          - `profileId: string`

          - `externalId: optional string`

            External ID for the resource (e.g., a workflow ID from an external system)

          - `labels: optional map[string]`

            Arbitrary key-value pairs for categorization and filtering
            Examples: {"environment": "production", "team": "platform", "version": "v2"}

        - `spec: object { type, email, name }`

          Configuration for a profile.

          - `type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"`

            Whether this profile represents a human user, an API key, or a system
            principal.

            - `"PROFILE_TYPE_UNSPECIFIED"`

            - `"PROFILE_TYPE_USER"`

            - `"PROFILE_TYPE_API_KEY"`

            - `"PROFILE_TYPE_SYSTEM"`

          - `email: optional string`

            Email address of the profile. Required and unique within an account for
            user profiles.

          - `name: optional string`

            Display name (e.g., "Bobby Tables").

      - `feedbackCount: optional number`

        Total number of objective feedbacks received for this variation

      - `memoryLayerAssignments: optional array of VariationMemoryLayerAssignment`

        Read-only list of memory layer assignments for this variation,
        returned in ascending `position` (bottom → top). Capped at 10 entries.

        - `id: optional string`

          Assignment row id — handle for removing the assignment. Distinct
          from the referenced memory layer's id.

        - `memoryLayer: optional object { id, name }`

          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: optional string`

          - `name: optional 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: optional number`

          Position in the variation's baseline stack. Lower values sit lower;
          the highest-position assignment is on top of the variation's
          baseline. 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: optional number`

        Count of memory layer assignments.

      - `model: optional object { id, accountId, createdAt, 6 more }`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: string`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `accountId: string`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `createdAt: string`

          Timestamp when this resource was created

        - `name: string`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profileId: string`

          ID of the actor (user or service account) that created this resource

        - `workspaceId: string`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundleKey: optional string`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `externalId: optional string`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: optional map[string]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `score: optional number`

        Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
        Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

      - `subAgentCount: optional number`

        Number of sub-agents assigned to this variation

      - `toolCount: optional number`

        Number of individual tools assigned to this variation

      - `toolSetCount: optional number`

        Number of tool sets assigned to this variation

  - `pagination: optional object { nextCursor, total }`

    - `nextCursor: optional string`

    - `total: optional number`

### Example

```cli
cadenya agents:variations list \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId
```

#### Response

```json
{
  "items": [
    {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "compactionConfig": {
          "summarization": {
            "instructions": "instructions"
          },
          "toolResultClearing": {
            "preserveRecentResults": 0
          },
          "triggerThreshold": 0
        },
        "constraints": {
          "maxSubObjectives": 0,
          "maxToolCalls": 0
        },
        "description": "description",
        "enableEpisodicMemory": true,
        "episodicMemoryTtl": 0,
        "modelConfig": {
          "modelId": "modelId",
          "temperature": 0
        },
        "progressiveDiscovery": {
          "hints": [
            "string"
          ],
          "maxTools": 0,
          "rerankThreshold": 0
        },
        "prompt": "prompt",
        "weight": 0
      },
      "info": {
        "assignments": [
          {
            "id": "id",
            "agent": {
              "id": "id",
              "name": "name"
            },
            "tool": {
              "id": "id",
              "name": "name"
            },
            "toolSet": {
              "id": "id",
              "name": "name"
            }
          }
        ],
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "feedbackCount": 0,
        "memoryLayerAssignments": [
          {
            "id": "id",
            "memoryLayer": {
              "id": "id",
              "name": "name"
            },
            "position": 0
          }
        ],
        "memoryLayerCount": 0,
        "model": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "score": 0,
        "subAgentCount": 0,
        "toolCount": 0,
        "toolSetCount": 0
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Create a new variation

`$ cadenya agents:variations create`

**post** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations`

Creates a new variation for an agent

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--metadata: object { name, bundleKey, externalId, labels }`

  CreateResourceMetadata contains the user-provided fields for creating
  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.

- `--spec: object { compactionConfig, constraints, description, 6 more }`

  AgentVariationSpec defines the operational configuration for a variation

### Returns

- `agent_variation: object { metadata, spec, info }`

  AgentVariation resource

  - `metadata: object { id, accountId, createdAt, 6 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundleKey: optional string`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: object { compactionConfig, constraints, description, 6 more }`

    AgentVariationSpec defines the operational configuration for a variation

    - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `summarization: optional object { instructions }`

        SummarizationStrategy configures LLM-powered summarization of older conversation turns.

        - `instructions: optional 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: optional object { preserveRecentResults }`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserveRecentResults: optional number`

          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

      - `triggerThreshold: optional number`

        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%)

    - `constraints: optional object { maxSubObjectives, maxToolCalls }`

      Execution constraints

      - `maxSubObjectives: optional number`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `maxToolCalls: optional number`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: optional string`

      Human-readable description of what this variation does or when it should be used

    - `enableEpisodicMemory: optional boolean`

      Enable episodic memory for objectives using this variation.
      When true, the system automatically creates a document namespace for each objective
      using the objective's episodic_key as the external_id, allowing the agent to
      store and retrieve documents specific to that episode.

    - `episodicMemoryTtl: optional number`

      How long episodic memories should be retained.
      After this duration, episodic document namespaces can be automatically cleaned up.
      If not set, episodic memories are retained indefinitely.

    - `modelConfig: optional object { modelId, temperature }`

      ModelConfig defines the model configuration for a variation

      - `modelId: optional string`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: optional number`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }`

      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.

      - `hints: optional array of string`

      - `maxTools: optional number`

      - `rerankThreshold: optional number`

        Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
        which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
        the tool very closely match the query the tool search performed.

    - `prompt: optional string`

      The system prompt for this variation

    - `weight: optional number`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: optional object { assignments, createdBy, feedbackCount, 7 more }`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: optional array of 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.

      - `id: optional string`

      - `agent: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `tool: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `toolSet: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

    - `createdBy: optional object { metadata, spec }`

      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: object { id, accountId, name, 3 more }`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: string`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `accountId: string`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: string`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profileId: string`

        - `externalId: optional string`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: optional map[string]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: object { type, email, name }`

        Configuration for a profile.

        - `type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `"PROFILE_TYPE_UNSPECIFIED"`

          - `"PROFILE_TYPE_USER"`

          - `"PROFILE_TYPE_API_KEY"`

          - `"PROFILE_TYPE_SYSTEM"`

        - `email: optional string`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: optional string`

          Display name (e.g., "Bobby Tables").

    - `feedbackCount: optional number`

      Total number of objective feedbacks received for this variation

    - `memoryLayerAssignments: optional array of VariationMemoryLayerAssignment`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: optional string`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memoryLayer: optional object { id, name }`

        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: optional string`

        - `name: optional 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: optional number`

        Position in the variation's baseline stack. Lower values sit lower;
        the highest-position assignment is on top of the variation's
        baseline. 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: optional number`

      Count of memory layer assignments.

    - `model: optional object { id, accountId, createdAt, 6 more }`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: string`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `accountId: string`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `createdAt: string`

        Timestamp when this resource was created

      - `name: string`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profileId: string`

        ID of the actor (user or service account) that created this resource

      - `workspaceId: string`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundleKey: optional string`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `externalId: optional string`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: optional map[string]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `score: optional number`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `subAgentCount: optional number`

      Number of sub-agents assigned to this variation

    - `toolCount: optional number`

      Number of individual tools assigned to this variation

    - `toolSetCount: optional number`

      Number of tool sets assigned to this variation

### Example

```cli
cadenya agents:variations create \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --metadata '{name: name}' \
  --spec '{}'
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "compactionConfig": {
      "summarization": {
        "instructions": "instructions"
      },
      "toolResultClearing": {
        "preserveRecentResults": 0
      },
      "triggerThreshold": 0
    },
    "constraints": {
      "maxSubObjectives": 0,
      "maxToolCalls": 0
    },
    "description": "description",
    "enableEpisodicMemory": true,
    "episodicMemoryTtl": 0,
    "modelConfig": {
      "modelId": "modelId",
      "temperature": 0
    },
    "progressiveDiscovery": {
      "hints": [
        "string"
      ],
      "maxTools": 0,
      "rerankThreshold": 0
    },
    "prompt": "prompt",
    "weight": 0
  },
  "info": {
    "assignments": [
      {
        "id": "id",
        "agent": {
          "id": "id",
          "name": "name"
        },
        "tool": {
          "id": "id",
          "name": "name"
        },
        "toolSet": {
          "id": "id",
          "name": "name"
        }
      }
    ],
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "feedbackCount": 0,
    "memoryLayerAssignments": [
      {
        "id": "id",
        "memoryLayer": {
          "id": "id",
          "name": "name"
        },
        "position": 0
      }
    ],
    "memoryLayerCount": 0,
    "model": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "score": 0,
    "subAgentCount": 0,
    "toolCount": 0,
    "toolSetCount": 0
  }
}
```

## Get a variation by ID

`$ cadenya agents:variations retrieve`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}`

Retrieves a variation by ID from an agent

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

### Returns

- `agent_variation: object { metadata, spec, info }`

  AgentVariation resource

  - `metadata: object { id, accountId, createdAt, 6 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundleKey: optional string`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: object { compactionConfig, constraints, description, 6 more }`

    AgentVariationSpec defines the operational configuration for a variation

    - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `summarization: optional object { instructions }`

        SummarizationStrategy configures LLM-powered summarization of older conversation turns.

        - `instructions: optional 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: optional object { preserveRecentResults }`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserveRecentResults: optional number`

          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

      - `triggerThreshold: optional number`

        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%)

    - `constraints: optional object { maxSubObjectives, maxToolCalls }`

      Execution constraints

      - `maxSubObjectives: optional number`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `maxToolCalls: optional number`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: optional string`

      Human-readable description of what this variation does or when it should be used

    - `enableEpisodicMemory: optional boolean`

      Enable episodic memory for objectives using this variation.
      When true, the system automatically creates a document namespace for each objective
      using the objective's episodic_key as the external_id, allowing the agent to
      store and retrieve documents specific to that episode.

    - `episodicMemoryTtl: optional number`

      How long episodic memories should be retained.
      After this duration, episodic document namespaces can be automatically cleaned up.
      If not set, episodic memories are retained indefinitely.

    - `modelConfig: optional object { modelId, temperature }`

      ModelConfig defines the model configuration for a variation

      - `modelId: optional string`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: optional number`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }`

      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.

      - `hints: optional array of string`

      - `maxTools: optional number`

      - `rerankThreshold: optional number`

        Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
        which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
        the tool very closely match the query the tool search performed.

    - `prompt: optional string`

      The system prompt for this variation

    - `weight: optional number`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: optional object { assignments, createdBy, feedbackCount, 7 more }`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: optional array of 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.

      - `id: optional string`

      - `agent: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `tool: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `toolSet: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

    - `createdBy: optional object { metadata, spec }`

      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: object { id, accountId, name, 3 more }`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: string`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `accountId: string`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: string`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profileId: string`

        - `externalId: optional string`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: optional map[string]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: object { type, email, name }`

        Configuration for a profile.

        - `type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `"PROFILE_TYPE_UNSPECIFIED"`

          - `"PROFILE_TYPE_USER"`

          - `"PROFILE_TYPE_API_KEY"`

          - `"PROFILE_TYPE_SYSTEM"`

        - `email: optional string`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: optional string`

          Display name (e.g., "Bobby Tables").

    - `feedbackCount: optional number`

      Total number of objective feedbacks received for this variation

    - `memoryLayerAssignments: optional array of VariationMemoryLayerAssignment`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: optional string`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memoryLayer: optional object { id, name }`

        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: optional string`

        - `name: optional 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: optional number`

        Position in the variation's baseline stack. Lower values sit lower;
        the highest-position assignment is on top of the variation's
        baseline. 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: optional number`

      Count of memory layer assignments.

    - `model: optional object { id, accountId, createdAt, 6 more }`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: string`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `accountId: string`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `createdAt: string`

        Timestamp when this resource was created

      - `name: string`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profileId: string`

        ID of the actor (user or service account) that created this resource

      - `workspaceId: string`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundleKey: optional string`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `externalId: optional string`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: optional map[string]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `score: optional number`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `subAgentCount: optional number`

      Number of sub-agents assigned to this variation

    - `toolCount: optional number`

      Number of individual tools assigned to this variation

    - `toolSetCount: optional number`

      Number of tool sets assigned to this variation

### Example

```cli
cadenya agents:variations retrieve \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --id id
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "compactionConfig": {
      "summarization": {
        "instructions": "instructions"
      },
      "toolResultClearing": {
        "preserveRecentResults": 0
      },
      "triggerThreshold": 0
    },
    "constraints": {
      "maxSubObjectives": 0,
      "maxToolCalls": 0
    },
    "description": "description",
    "enableEpisodicMemory": true,
    "episodicMemoryTtl": 0,
    "modelConfig": {
      "modelId": "modelId",
      "temperature": 0
    },
    "progressiveDiscovery": {
      "hints": [
        "string"
      ],
      "maxTools": 0,
      "rerankThreshold": 0
    },
    "prompt": "prompt",
    "weight": 0
  },
  "info": {
    "assignments": [
      {
        "id": "id",
        "agent": {
          "id": "id",
          "name": "name"
        },
        "tool": {
          "id": "id",
          "name": "name"
        },
        "toolSet": {
          "id": "id",
          "name": "name"
        }
      }
    ],
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "feedbackCount": 0,
    "memoryLayerAssignments": [
      {
        "id": "id",
        "memoryLayer": {
          "id": "id",
          "name": "name"
        },
        "position": 0
      }
    ],
    "memoryLayerCount": 0,
    "model": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "score": 0,
    "subAgentCount": 0,
    "toolCount": 0,
    "toolSetCount": 0
  }
}
```

## Delete a variation

`$ cadenya agents:variations delete`

**delete** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}`

Deletes a variation from an agent

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

### Example

```cli
cadenya agents:variations delete \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --id id
```

## Update a variation

`$ cadenya agents:variations update`

**patch** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}`

Updates a variation for an agent

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

- `--metadata: optional object { name, bundleKey, externalId, labels }`

  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.

- `--spec: optional object { compactionConfig, constraints, description, 6 more }`

  AgentVariationSpec defines the operational configuration for a variation

- `--update-mask: optional string`

  Fields to update

### Returns

- `agent_variation: object { metadata, spec, info }`

  AgentVariation resource

  - `metadata: object { id, accountId, createdAt, 6 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundleKey: optional string`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: object { compactionConfig, constraints, description, 6 more }`

    AgentVariationSpec defines the operational configuration for a variation

    - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `summarization: optional object { instructions }`

        SummarizationStrategy configures LLM-powered summarization of older conversation turns.

        - `instructions: optional 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: optional object { preserveRecentResults }`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserveRecentResults: optional number`

          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

      - `triggerThreshold: optional number`

        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%)

    - `constraints: optional object { maxSubObjectives, maxToolCalls }`

      Execution constraints

      - `maxSubObjectives: optional number`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `maxToolCalls: optional number`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: optional string`

      Human-readable description of what this variation does or when it should be used

    - `enableEpisodicMemory: optional boolean`

      Enable episodic memory for objectives using this variation.
      When true, the system automatically creates a document namespace for each objective
      using the objective's episodic_key as the external_id, allowing the agent to
      store and retrieve documents specific to that episode.

    - `episodicMemoryTtl: optional number`

      How long episodic memories should be retained.
      After this duration, episodic document namespaces can be automatically cleaned up.
      If not set, episodic memories are retained indefinitely.

    - `modelConfig: optional object { modelId, temperature }`

      ModelConfig defines the model configuration for a variation

      - `modelId: optional string`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: optional number`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }`

      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.

      - `hints: optional array of string`

      - `maxTools: optional number`

      - `rerankThreshold: optional number`

        Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
        which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
        the tool very closely match the query the tool search performed.

    - `prompt: optional string`

      The system prompt for this variation

    - `weight: optional number`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: optional object { assignments, createdBy, feedbackCount, 7 more }`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: optional array of 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.

      - `id: optional string`

      - `agent: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `tool: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `toolSet: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

    - `createdBy: optional object { metadata, spec }`

      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: object { id, accountId, name, 3 more }`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: string`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `accountId: string`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: string`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profileId: string`

        - `externalId: optional string`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: optional map[string]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: object { type, email, name }`

        Configuration for a profile.

        - `type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `"PROFILE_TYPE_UNSPECIFIED"`

          - `"PROFILE_TYPE_USER"`

          - `"PROFILE_TYPE_API_KEY"`

          - `"PROFILE_TYPE_SYSTEM"`

        - `email: optional string`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: optional string`

          Display name (e.g., "Bobby Tables").

    - `feedbackCount: optional number`

      Total number of objective feedbacks received for this variation

    - `memoryLayerAssignments: optional array of VariationMemoryLayerAssignment`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: optional string`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memoryLayer: optional object { id, name }`

        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: optional string`

        - `name: optional 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: optional number`

        Position in the variation's baseline stack. Lower values sit lower;
        the highest-position assignment is on top of the variation's
        baseline. 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: optional number`

      Count of memory layer assignments.

    - `model: optional object { id, accountId, createdAt, 6 more }`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: string`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `accountId: string`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `createdAt: string`

        Timestamp when this resource was created

      - `name: string`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profileId: string`

        ID of the actor (user or service account) that created this resource

      - `workspaceId: string`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundleKey: optional string`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `externalId: optional string`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: optional map[string]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `score: optional number`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `subAgentCount: optional number`

      Number of sub-agents assigned to this variation

    - `toolCount: optional number`

      Number of individual tools assigned to this variation

    - `toolSetCount: optional number`

      Number of tool sets assigned to this variation

### Example

```cli
cadenya agents:variations update \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --id id
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "compactionConfig": {
      "summarization": {
        "instructions": "instructions"
      },
      "toolResultClearing": {
        "preserveRecentResults": 0
      },
      "triggerThreshold": 0
    },
    "constraints": {
      "maxSubObjectives": 0,
      "maxToolCalls": 0
    },
    "description": "description",
    "enableEpisodicMemory": true,
    "episodicMemoryTtl": 0,
    "modelConfig": {
      "modelId": "modelId",
      "temperature": 0
    },
    "progressiveDiscovery": {
      "hints": [
        "string"
      ],
      "maxTools": 0,
      "rerankThreshold": 0
    },
    "prompt": "prompt",
    "weight": 0
  },
  "info": {
    "assignments": [
      {
        "id": "id",
        "agent": {
          "id": "id",
          "name": "name"
        },
        "tool": {
          "id": "id",
          "name": "name"
        },
        "toolSet": {
          "id": "id",
          "name": "name"
        }
      }
    ],
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "feedbackCount": 0,
    "memoryLayerAssignments": [
      {
        "id": "id",
        "memoryLayer": {
          "id": "id",
          "name": "name"
        },
        "position": 0
      }
    ],
    "memoryLayerCount": 0,
    "model": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "score": 0,
    "subAgentCount": 0,
    "toolCount": 0,
    "toolSetCount": 0
  }
}
```

## Add an assignment to a variation

`$ cadenya agents:variations add-assignment`

**post** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/assignments`

Assigns a tool, tool set, or sub-agent to a variation. Exactly one target ID must be set.

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--variation-id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

- `--sub-agent-id: optional string`

- `--tool-id: optional string`

- `--tool-set-id: optional string`

### Returns

- `variation_assignment: object { id, agent, tool, toolSet }`

  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`.

  - `id: optional string`

  - `agent: optional object { id, name }`

    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: optional string`

    - `name: optional 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).

  - `tool: optional object { id, name }`

    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: optional string`

    - `name: optional 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).

  - `toolSet: optional object { id, name }`

    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: optional string`

    - `name: optional 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).

### Example

```cli
cadenya agents:variations add-assignment \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --variation-id variationId
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "id",
    "name": "name"
  },
  "tool": {
    "id": "id",
    "name": "name"
  },
  "toolSet": {
    "id": "id",
    "name": "name"
  }
}
```

## Remove an assignment from a variation

`$ cadenya agents:variations remove-assignment`

**delete** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/assignments/{id}`

Detaches an assignment from a variation, identified by the assignment ID returned when it was added.

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--variation-id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

- `--id: string`

### Example

```cli
cadenya agents:variations remove-assignment \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --variation-id variationId \
  --id id
```

## Attach a memory layer to a variation

`$ cadenya agents:variations add-memory-layer`

**post** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments`

Attaches a memory layer to a variation at a given position in the variation's baseline memory stack.

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--variation-id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

- `--memory-layer-id: optional string`

  Layer to attach. Accepts the canonical `memlyr_…` form or the `external_id:<value>` form.

- `--position: optional number`

  Position in the stack. If omitted, server appends
  (max existing position + 1).

### Returns

- `variation_memory_layer_assignment: object { id, memoryLayer, position }`

  VariationMemoryLayerAssignment attaches a single MemoryLayer to a
  variation at a given position in the variation's baseline memory
  stack. A variation has at most one assignment per memory_layer_id.

  Variations only support whole-layer attachments — entry pinning is an
  objective-level capability.

  - `id: optional string`

    Assignment row id — handle for removing the assignment. Distinct
    from the referenced memory layer's id.

  - `memoryLayer: optional object { id, name }`

    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: optional string`

    - `name: optional 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: optional number`

    Position in the variation's baseline stack. Lower values sit lower;
    the highest-position assignment is on top of the variation's
    baseline. 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.

### Example

```cli
cadenya agents:variations add-memory-layer \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --variation-id variationId
```

#### Response

```json
{
  "id": "id",
  "memoryLayer": {
    "id": "id",
    "name": "name"
  },
  "position": 0
}
```

## Update a variation's memory layer assignment

`$ cadenya agents:variations update-memory-layer`

**patch** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments/{id}`

Updates the position of a memory layer assignment on a variation.

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--variation-id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

- `--id: string`

- `--position: optional number`

  New position. Only field currently updatable on an assignment.

### Returns

- `variation_memory_layer_assignment: object { id, memoryLayer, position }`

  VariationMemoryLayerAssignment attaches a single MemoryLayer to a
  variation at a given position in the variation's baseline memory
  stack. A variation has at most one assignment per memory_layer_id.

  Variations only support whole-layer attachments — entry pinning is an
  objective-level capability.

  - `id: optional string`

    Assignment row id — handle for removing the assignment. Distinct
    from the referenced memory layer's id.

  - `memoryLayer: optional object { id, name }`

    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: optional string`

    - `name: optional 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: optional number`

    Position in the variation's baseline stack. Lower values sit lower;
    the highest-position assignment is on top of the variation's
    baseline. 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.

### Example

```cli
cadenya agents:variations update-memory-layer \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --variation-id variationId \
  --id id
```

#### Response

```json
{
  "id": "id",
  "memoryLayer": {
    "id": "id",
    "name": "name"
  },
  "position": 0
}
```

## Remove a memory layer assignment from a variation

`$ cadenya agents:variations remove-memory-layer`

**delete** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments/{id}`

Detaches a memory layer assignment from a variation, identified by the assignment id.

### Parameters

- `--workspace-id: string`

  Workspace ID.

- `--agent-id: string`

  Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

- `--variation-id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

- `--id: string`

### Example

```cli
cadenya agents:variations remove-memory-layer \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --variation-id variationId \
  --id id
```

## Domain Types

### Agent Variation

- `agent_variation: object { metadata, spec, info }`

  AgentVariation resource

  - `metadata: object { id, accountId, createdAt, 6 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundleKey: optional string`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: object { compactionConfig, constraints, description, 6 more }`

    AgentVariationSpec defines the operational configuration for a variation

    - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `summarization: optional object { instructions }`

        SummarizationStrategy configures LLM-powered summarization of older conversation turns.

        - `instructions: optional 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: optional object { preserveRecentResults }`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserveRecentResults: optional number`

          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

      - `triggerThreshold: optional number`

        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%)

    - `constraints: optional object { maxSubObjectives, maxToolCalls }`

      Execution constraints

      - `maxSubObjectives: optional number`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `maxToolCalls: optional number`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: optional string`

      Human-readable description of what this variation does or when it should be used

    - `enableEpisodicMemory: optional boolean`

      Enable episodic memory for objectives using this variation.
      When true, the system automatically creates a document namespace for each objective
      using the objective's episodic_key as the external_id, allowing the agent to
      store and retrieve documents specific to that episode.

    - `episodicMemoryTtl: optional number`

      How long episodic memories should be retained.
      After this duration, episodic document namespaces can be automatically cleaned up.
      If not set, episodic memories are retained indefinitely.

    - `modelConfig: optional object { modelId, temperature }`

      ModelConfig defines the model configuration for a variation

      - `modelId: optional string`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: optional number`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }`

      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.

      - `hints: optional array of string`

      - `maxTools: optional number`

      - `rerankThreshold: optional number`

        Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
        which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
        the tool very closely match the query the tool search performed.

    - `prompt: optional string`

      The system prompt for this variation

    - `weight: optional number`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: optional object { assignments, createdBy, feedbackCount, 7 more }`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: optional array of 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.

      - `id: optional string`

      - `agent: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `tool: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

      - `toolSet: optional object { id, name }`

        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: optional string`

        - `name: optional 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).

    - `createdBy: optional object { metadata, spec }`

      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: object { id, accountId, name, 3 more }`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: string`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `accountId: string`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: string`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profileId: string`

        - `externalId: optional string`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: optional map[string]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: object { type, email, name }`

        Configuration for a profile.

        - `type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `"PROFILE_TYPE_UNSPECIFIED"`

          - `"PROFILE_TYPE_USER"`

          - `"PROFILE_TYPE_API_KEY"`

          - `"PROFILE_TYPE_SYSTEM"`

        - `email: optional string`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: optional string`

          Display name (e.g., "Bobby Tables").

    - `feedbackCount: optional number`

      Total number of objective feedbacks received for this variation

    - `memoryLayerAssignments: optional array of VariationMemoryLayerAssignment`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: optional string`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memoryLayer: optional object { id, name }`

        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: optional string`

        - `name: optional 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: optional number`

        Position in the variation's baseline stack. Lower values sit lower;
        the highest-position assignment is on top of the variation's
        baseline. 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: optional number`

      Count of memory layer assignments.

    - `model: optional object { id, accountId, createdAt, 6 more }`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: string`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `accountId: string`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `createdAt: string`

        Timestamp when this resource was created

      - `name: string`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profileId: string`

        ID of the actor (user or service account) that created this resource

      - `workspaceId: string`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundleKey: optional string`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `externalId: optional string`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: optional map[string]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `score: optional number`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `subAgentCount: optional number`

      Number of sub-agents assigned to this variation

    - `toolCount: optional number`

      Number of individual tools assigned to this variation

    - `toolSetCount: optional number`

      Number of tool sets assigned to this variation

### Agent Variation Info

- `agent_variation_info: object { assignments, createdBy, feedbackCount, 7 more }`

  AgentVariationInfo provides read-only summary information about a variation

  - `assignments: optional array of 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.

    - `id: optional string`

    - `agent: optional object { id, name }`

      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: optional string`

      - `name: optional 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).

    - `tool: optional object { id, name }`

      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: optional string`

      - `name: optional 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).

    - `toolSet: optional object { id, name }`

      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: optional string`

      - `name: optional 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).

  - `createdBy: optional object { metadata, spec }`

    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: object { id, accountId, name, 3 more }`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: string`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `accountId: string`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: string`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profileId: string`

      - `externalId: optional string`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: optional map[string]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: object { type, email, name }`

      Configuration for a profile.

      - `type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `"PROFILE_TYPE_UNSPECIFIED"`

        - `"PROFILE_TYPE_USER"`

        - `"PROFILE_TYPE_API_KEY"`

        - `"PROFILE_TYPE_SYSTEM"`

      - `email: optional string`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: optional string`

        Display name (e.g., "Bobby Tables").

  - `feedbackCount: optional number`

    Total number of objective feedbacks received for this variation

  - `memoryLayerAssignments: optional array of VariationMemoryLayerAssignment`

    Read-only list of memory layer assignments for this variation,
    returned in ascending `position` (bottom → top). Capped at 10 entries.

    - `id: optional string`

      Assignment row id — handle for removing the assignment. Distinct
      from the referenced memory layer's id.

    - `memoryLayer: optional object { id, name }`

      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: optional string`

      - `name: optional 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: optional number`

      Position in the variation's baseline stack. Lower values sit lower;
      the highest-position assignment is on top of the variation's
      baseline. 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: optional number`

    Count of memory layer assignments.

  - `model: optional object { id, accountId, createdAt, 6 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundleKey: optional string`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `score: optional number`

    Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
    Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

  - `subAgentCount: optional number`

    Number of sub-agents assigned to this variation

  - `toolCount: optional number`

    Number of individual tools assigned to this variation

  - `toolSetCount: optional number`

    Number of tool sets assigned to this variation

### Agent Variation Spec

- `agent_variation_spec: object { compactionConfig, constraints, description, 6 more }`

  AgentVariationSpec defines the operational configuration for a variation

  - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }`

    CompactionConfig defines how context window compaction behaves for objectives using this variation.

    - `summarization: optional object { instructions }`

      SummarizationStrategy configures LLM-powered summarization of older conversation turns.

      - `instructions: optional 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: optional object { preserveRecentResults }`

      ToolResultClearingStrategy configures clearing of older tool result content.

      - `preserveRecentResults: optional number`

        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

    - `triggerThreshold: optional number`

      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%)

  - `constraints: optional object { maxSubObjectives, maxToolCalls }`

    Execution constraints

    - `maxSubObjectives: optional number`

      The maximum number of sub-objectives that can be created. 0 means no limit.

    - `maxToolCalls: optional number`

      The maximum number of tool calls that can be made. 0 means no limit.

  - `description: optional string`

    Human-readable description of what this variation does or when it should be used

  - `enableEpisodicMemory: optional boolean`

    Enable episodic memory for objectives using this variation.
    When true, the system automatically creates a document namespace for each objective
    using the objective's episodic_key as the external_id, allowing the agent to
    store and retrieve documents specific to that episode.

  - `episodicMemoryTtl: optional number`

    How long episodic memories should be retained.
    After this duration, episodic document namespaces can be automatically cleaned up.
    If not set, episodic memories are retained indefinitely.

  - `modelConfig: optional object { modelId, temperature }`

    ModelConfig defines the model configuration for a variation

    - `modelId: optional string`

      The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

    - `temperature: optional number`

      Sampling temperature for model inference (0.0 to 1.0)
      Lower values produce more deterministic outputs, higher values increase randomness

  - `progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }`

    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.

    - `hints: optional array of string`

    - `maxTools: optional number`

    - `rerankThreshold: optional number`

      Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
      which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
      the tool very closely match the query the tool search performed.

  - `prompt: optional string`

    The system prompt for this variation

  - `weight: optional number`

    Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
    Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

### Agent Variation Spec Compaction Config

- `agent_variation_spec_compaction_config: object { summarization, toolResultClearing, triggerThreshold }`

  CompactionConfig defines how context window compaction behaves for objectives using this variation.

  - `summarization: optional object { instructions }`

    SummarizationStrategy configures LLM-powered summarization of older conversation turns.

    - `instructions: optional 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: optional object { preserveRecentResults }`

    ToolResultClearingStrategy configures clearing of older tool result content.

    - `preserveRecentResults: optional number`

      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

  - `triggerThreshold: optional number`

    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%)

### Agent Variation Spec Constraints

- `agent_variation_spec_constraints: object { maxSubObjectives, maxToolCalls }`

  - `maxSubObjectives: optional number`

    The maximum number of sub-objectives that can be created. 0 means no limit.

  - `maxToolCalls: optional number`

    The maximum number of tool calls that can be made. 0 means no limit.

### Agent Variation Spec Model Config

- `agent_variation_spec_model_config: object { modelId, temperature }`

  ModelConfig defines the model configuration for a variation

  - `modelId: optional string`

    The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

  - `temperature: optional number`

    Sampling temperature for model inference (0.0 to 1.0)
    Lower values produce more deterministic outputs, higher values increase randomness

### Agent Variation Spec Progressive Discovery

- `agent_variation_spec_progressive_discovery: object { hints, maxTools, rerankThreshold }`

  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.

  - `hints: optional array of string`

  - `maxTools: optional number`

  - `rerankThreshold: optional number`

    Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
    which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
    the tool very closely match the query the tool search performed.

### Compaction Config Summarization Strategy

- `compaction_config_summarization_strategy: object { instructions }`

  SummarizationStrategy configures LLM-powered summarization of older conversation turns.

  - `instructions: optional 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."

### Compaction Config Tool Result Clearing Strategy

- `compaction_config_tool_result_clearing_strategy: object { preserveRecentResults }`

  ToolResultClearingStrategy configures clearing of older tool result content.

  - `preserveRecentResults: optional number`

    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

### Variation Assignment

- `variation_assignment: object { id, agent, tool, toolSet }`

  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`.

  - `id: optional string`

  - `agent: optional object { id, name }`

    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: optional string`

    - `name: optional 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).

  - `tool: optional object { id, name }`

    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: optional string`

    - `name: optional 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).

  - `toolSet: optional object { id, name }`

    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: optional string`

    - `name: optional 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).

### Variation Memory Layer Assignment

- `variation_memory_layer_assignment: object { id, memoryLayer, position }`

  VariationMemoryLayerAssignment attaches a single MemoryLayer to a
  variation at a given position in the variation's baseline memory
  stack. A variation has at most one assignment per memory_layer_id.

  Variations only support whole-layer attachments — entry pinning is an
  objective-level capability.

  - `id: optional string`

    Assignment row id — handle for removing the assignment. Distinct
    from the referenced memory layer's id.

  - `memoryLayer: optional object { id, name }`

    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: optional string`

    - `name: optional 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: optional number`

    Position in the variation's baseline stack. Lower values sit lower;
    the highest-position assignment is on top of the variation's
    baseline. 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.