Create a new variation

client.agents.variations.create(, , ?): AgentVariation { metadata, spec, info }

POST/v1/workspaces/{workspaceId}/agents/{agentId}/variations

Creates a new variation for an agent

ParametersExpand Collapse

agentID: string

params: VariationCreateParams { workspaceId, metadata, spec }

workspaceId: string

Path param: Workspace ID.

metadata: CreateResourceMetadata { name, bundleKey, externalId, labels }

Body param: 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.

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”)

bundleKey?: string

Optional bundle ownership key. See ResourceMetadata.bundle_key.

externalId?: string

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

labels?: Record<string, string>

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

spec: AgentVariationSpec { compactionConfig, constraints, description, 6 more }

Body param: AgentVariationSpec defines the operational configuration for a variation

compactionConfig?: AgentVariationSpecCompactionConfig { summarization, toolResultClearing, triggerThreshold }

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

summarization?: CompactionConfigSummarizationStrategy { instructions }

SummarizationStrategy configures LLM-powered summarization of older conversation turns.

instructions?: string

Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: “Preserve all code snippets, variable names, and technical decisions.”

toolResultClearing?: CompactionConfigToolResultClearingStrategy { preserveRecentResults }

ToolResultClearingStrategy configures clearing of older tool result content.

preserveRecentResults?: 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

formatint32

triggerThreshold?: 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%)

formatfloat

constraints?: AgentVariationSpecConstraints { maxSubObjectives, maxToolCalls }

Execution constraints

maxSubObjectives?: number

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

formatint32

maxToolCalls?: number

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

formatint32

description?: string

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

enableEpisodicMemory?: 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?: 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?: AgentVariationSpecModelConfig { modelId, temperature }

ModelConfig defines the model configuration for a variation

modelId?: string

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

temperature?: number

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

formatfloat

progressiveDiscovery?: AgentVariationSpecProgressiveDiscovery { 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?: Array<string>

maxTools?: number

rerankThreshold?: 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.

formatfloat

prompt?: string

The system prompt for this variation

weight?: 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.

formatint32

ReturnsExpand Collapse

AgentVariation { metadata, spec, info }

AgentVariation resource

metadata: ResourceMetadata { 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

formatdate-time

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?: 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?: string

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

labels?: Record<string, string>

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

spec: AgentVariationSpec { compactionConfig, constraints, description, 6 more }

AgentVariationSpec defines the operational configuration for a variation

compactionConfig?: AgentVariationSpecCompactionConfig { summarization, toolResultClearing, triggerThreshold }

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

summarization?: CompactionConfigSummarizationStrategy { instructions }

SummarizationStrategy configures LLM-powered summarization of older conversation turns.

instructions?: string

Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: “Preserve all code snippets, variable names, and technical decisions.”

toolResultClearing?: CompactionConfigToolResultClearingStrategy { preserveRecentResults }

ToolResultClearingStrategy configures clearing of older tool result content.

preserveRecentResults?: number

formatint32

triggerThreshold?: 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%)

formatfloat

constraints?: AgentVariationSpecConstraints { maxSubObjectives, maxToolCalls }

Execution constraints

maxSubObjectives?: number

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

formatint32

maxToolCalls?: number

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

formatint32

description?: string

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

enableEpisodicMemory?: boolean

episodicMemoryTtl?: 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?: AgentVariationSpecModelConfig { modelId, temperature }

ModelConfig defines the model configuration for a variation

modelId?: string

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

temperature?: number

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

formatfloat

progressiveDiscovery?: AgentVariationSpecProgressiveDiscovery { hints, maxTools, rerankThreshold }

hints?: Array<string>

maxTools?: number

rerankThreshold?: number

formatfloat

prompt?: string

The system prompt for this variation

weight?: number

formatint32

info?: AgentVariationInfo { assignments, createdBy, feedbackCount, 7 more }

AgentVariationInfo provides read-only summary information about a variation

assignments?: Array<VariationAssignment { id, agent, tool, toolSet } >

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?: string

agent?: BareMetadata { 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?: string

name?: string

Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).

tool?: BareMetadata { id, name }

id?: string

name?: string

Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).

toolSet?: BareMetadata { id, name }

id?: string

name?: string

Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).

createdBy?: Profile { 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: AccountResourceMetadata { 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)

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

profileId: string

externalId?: string

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

labels?: Record<string, string>

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

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" | "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

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

formatenum

One of the following:

"PROFILE_TYPE_UNSPECIFIED"

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email?: string

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

name?: string

Display name (e.g., “Bobby Tables”).

feedbackCount?: number

Total number of objective feedbacks received for this variation

formatint32

memoryLayerAssignments?: Array<VariationMemoryLayerAssignment { id, memoryLayer, position } >

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

id?: string

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

memoryLayer?: BareMetadata { id, name }

id?: string

name?: string

Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).

position?: 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.

formatint32

memoryLayerCount?: number

Count of memory layer assignments.

formatint32

model?: ResourceMetadata { 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

formatdate-time

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?: string

externalId?: string

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

labels?: Record<string, string>

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

score?: 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.

formatfloat

subAgentCount?: number

Number of sub-agents assigned to this variation

formatint32

toolCount?: number

Number of individual tools assigned to this variation

formatint32

toolSetCount?: number

Number of tool sets assigned to this variation

formatint32

Create a new variation

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const agentVariation = await client.agents.variations.create('agentId', {
  workspaceId: 'workspaceId',
  metadata: { name: 'name' },
  spec: {},
});

console.log(agentVariation.metadata);

{
  "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
  }
}

Returns Examples

{
  "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
  }
}