Variations
Manage variations of an agent and their tool, sub-agent, and memory layer assignments.
List variations
Create a new variation
Get a variation by ID
Delete a variation
Update a variation
Add an assignment to a variation
Remove an assignment from a variation
Attach a memory layer to a variation
Update a variation's memory layer assignment
Remove a memory layer assignment from a variation
ModelsExpand Collapse
agent_variation: object { metadata, spec, info }
AgentVariation resource
metadata: object { id, accountId, createdAt, 6 more }
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
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.
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
progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
rerankThreshold: optional number
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
info: optional object { assignments, createdBy, feedbackCount, 7 more }
AgentVariationInfo provides read-only summary information about a variation
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.
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.
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.
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.
createdBy: optional object { metadata, spec }
A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
metadata: object { id, accountId, name, 3 more }
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
memoryLayerAssignments: optional array of 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: optional string
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
memoryLayer: optional object { id, name }
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
position: optional number
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
model: optional object { id, accountId, createdAt, 6 more }
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
agent_variation_info: object { assignments, createdBy, feedbackCount, 7 more }
AgentVariationInfo provides read-only summary information about a variation
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.
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.
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.
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.
createdBy: optional object { metadata, spec }
A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
metadata: object { id, accountId, name, 3 more }
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
memoryLayerAssignments: optional array of 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: optional string
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
memoryLayer: optional object { id, name }
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
position: optional number
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
model: optional object { id, accountId, createdAt, 6 more }
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
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.
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
progressiveDiscovery: optional object { hints, maxTools, rerankThreshold }
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
rerankThreshold: optional number
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
agent_variation_spec_compaction_config: object { summarization, toolResultClearing, triggerThreshold }
CompactionConfig defines how context window compaction behaves for objectives using this variation.
agent_variation_spec_progressive_discovery: object { hints, maxTools, rerankThreshold }
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
rerankThreshold: optional number
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
variation_assignment: object { id, agent, tool, toolSet }
A read-only reference to a single tool, tool set, or sub-agent attached to
a variation. Read the full set of assignments via AgentVariationInfo.assignments;
mutations go through the dedicated add/remove assignment endpoints.
The id identifies the assignment itself (not the referenced resource) and
is the handle used to remove the assignment. It is returned by the add
endpoint and present on every entry in AgentVariationInfo.assignments.
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.
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.
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.
variation_memory_layer_assignment: object { id, memoryLayer, position }
VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a given position in the variation’s baseline memory stack. A variation has at most one assignment per memory_layer_id.
Variations only support whole-layer attachments — entry pinning is an objective-level capability.
id: optional string
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
memoryLayer: optional object { id, name }
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
position: optional number
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.