# Agent Variations ## List variations `$ cadenya agent-variations list` **get** `/v1/agents/{agentId}/variations` Lists all variations for an agent ### Parameters - `--agent-id: string` Agent ID (from path) - `--cursor: optional string` Pagination cursor from previous response - `--include-info: optional boolean` When set to true you may use more of your alloted API 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, 5 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) - `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 - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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` - `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, 5 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 }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `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 }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { id, accountId, createdAt, 5 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) - `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 agent-variations list \ --api-key 'My API Key' \ --agent-id agentId ``` #### Response ```json { "items": [ { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "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 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "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_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Create a new variation `$ cadenya agent-variations create` **post** `/v1/agents/{agentId}/variations` Creates a new variation for an agent ### Parameters - `--agent-id: string` Agent ID (from path) - `--metadata: object { name, 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, 5 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) - `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 - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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` - `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, 5 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 }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `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 }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { id, accountId, createdAt, 5 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) - `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 agent-variations create \ --api-key 'My API Key' \ --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", "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 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "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_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } ``` ## Get a variation by ID `$ cadenya agent-variations retrieve` **get** `/v1/agents/{agentId}/variations/{id}` Retrieves a variation by ID from an agent ### Parameters - `--agent-id: string` Agent ID (from path) - `--id: string` Variation ID ### Returns - `agent_variation: object { metadata, spec, info }` AgentVariation resource - `metadata: object { id, accountId, createdAt, 5 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) - `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 - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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` - `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, 5 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 }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `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 }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { id, accountId, createdAt, 5 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) - `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 agent-variations retrieve \ --api-key 'My API Key' \ --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", "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 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "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_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } ``` ## Delete a variation `$ cadenya agent-variations delete` **delete** `/v1/agents/{agentId}/variations/{id}` Deletes a variation from an agent ### Parameters - `--agent-id: string` Agent ID (from path) - `--id: string` Variation ID ### Example ```cli cadenya agent-variations delete \ --api-key 'My API Key' \ --agent-id agentId \ --id id ``` ## Update a variation `$ cadenya agent-variations update` **patch** `/v1/agents/{agentId}/variations/{id}` Updates a variation for an agent ### Parameters - `--agent-id: string` Agent ID (from path) - `--id: string` Variation ID (from path) - `--metadata: optional object { name, 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, 5 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) - `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 - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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` - `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, 5 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 }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `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 }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { id, accountId, createdAt, 5 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) - `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 agent-variations update \ --api-key 'My API Key' \ --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", "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 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "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_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } ``` ## Add an assignment to a variation `$ cadenya agent-variations add-assignment` **post** `/v1/agent_variations/{agentVariationId}/assignments` Assigns a tool, tool set, or sub-agent to a variation. Exactly one target ID must be set. ### Parameters - `--agent-variation-id: string` - `--sub-agent-id: optional string` - `--tool-id: optional string` - `--tool-set-id: optional string` ### Returns - `variation_assignment: object { id, agent, tool, toolSet }` VariationAssignment is a read-only reference to a single tool, tool set, or sub-agent attached to a variation. Clients read the full set of assignments via `AgentVariationInfo.assignments`; mutations go through the dedicated add/remove assignment endpoints under /v1/agent_variations/{id}/assignments. The `id` identifies the assignment row 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 agent-variations add-assignment \ --api-key 'My API Key' \ --agent-variation-id agentVariationId ``` #### 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 agent-variations remove-assignment` **delete** `/v1/agent_variations/{agentVariationId}/assignments/{id}` Detaches an assignment from a variation, identified by the assignment ID returned when it was added. ### Parameters - `--agent-variation-id: string` - `--id: string` ### Example ```cli cadenya agent-variations remove-assignment \ --api-key 'My API Key' \ --agent-variation-id agentVariationId \ --id id ``` ## Domain Types ### Agent Variation - `agent_variation: object { metadata, spec, info }` AgentVariation resource - `metadata: object { id, accountId, createdAt, 5 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) - `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 - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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` - `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, 5 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 }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `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 }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { id, accountId, createdAt, 5 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) - `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, 5 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 }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `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 }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { id, accountId, createdAt, 5 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) - `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 - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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` - `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 Tool Selection - `agent_variation_spec_tool_selection: object { assignedTools, autoDiscovery }` - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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` ### 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 ### Tool Selection Assigned Tools - `tool_selection_assigned_tools: object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` ### Tool Selection Auto Discovery - `tool_selection_auto_discovery: object { hints, maxTools }` AutoDiscovery 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. 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` ### Variation Assignment - `variation_assignment: object { id, agent, tool, toolSet }` VariationAssignment is a read-only reference to a single tool, tool set, or sub-agent attached to a variation. Clients read the full set of assignments via `AgentVariationInfo.assignments`; mutations go through the dedicated add/remove assignment endpoints under /v1/agent_variations/{id}/assignments. The `id` identifies the assignment row 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).