# Agent Variations ## List variations `client.AgentVariations.List(ctx, agentID, query) (*CursorPagination[AgentVariation], error)` **get** `/v1/agents/{agentId}/variations` Lists all variations for an agent ### Parameters - `agentID string` - `query AgentVariationListParams` - `Cursor param.Field[string]` Pagination cursor from previous response - `IncludeInfo param.Field[bool]` When set to true you may use more of your alloted API rate-limit - `Limit param.Field[int64]` Maximum number of results to return - `SortOrder param.Field[string]` Sort order for results (asc or desc by creation time) ### Returns - `type AgentVariation struct{…}` AgentVariation resource - `Metadata ResourceMetadata` 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 Time` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec AgentVariationSpec` AgentVariationSpec defines the operational configuration for a variation - `CompactionConfig AgentVariationSpecCompactionConfig` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `Summarization CompactionConfigSummarizationStrategy` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `ToolResultClearing CompactionConfigToolResultClearingStrategy` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 float64` 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 AgentVariationSpecConstraints` Execution constraints - `MaxSubObjectives int64` The maximum number of sub-objectives that can be created. 0 means no limit. - `MaxToolCalls int64` The maximum number of tool calls that can be made. 0 means no limit. - `Description string` Human-readable description of what this variation does or when it should be used - `EnableEpisodicMemory bool` 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 int64` How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely. - `ModelConfig AgentVariationSpecModelConfig` ModelConfig defines the model configuration for a variation - `ModelID string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `Temperature float64` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `Prompt string` The system prompt for this variation - `ToolSelection AgentVariationSpecToolSelection` Tool selection strategy - `AssignedTools ToolSelectionAssignedTools` 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 bool` - `AutoDiscovery ToolSelectionAutoDiscovery` 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 []string` - `MaxTools int64` - `Weight int64` 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 AgentVariationInfo` AgentVariationInfo provides read-only summary information about a variation - `Assignments []VariationAssignment` All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation's full assignment list without calling the add/remove endpoints just to enumerate. - `ID string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `CreatedBy Profile` 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 AccountResourceMetadata` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec ProfileSpec` ProfileSpec contains the profile-specific fields - `Type ProfileSpecType` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"` - `const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"` - `const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"` - `Email string` Email address of the user (required, unique per account) - `Name string` Display name for the user (e.g., "Bobby Tables") - `FeedbackCount int64` Total number of objective feedbacks received for this variation - `Model ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `Score float64` 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 int64` Number of sub-agents assigned to this variation - `ToolCount int64` Number of individual tools assigned to this variation - `ToolSetCount int64` Number of tool sets assigned to this variation ### Example ```go package main import ( "context" "fmt" "github.com/cadenya/cadenya-go" "github.com/cadenya/cadenya-go/option" ) func main() { client := cadenya.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.AgentVariations.List( context.TODO(), "agentId", cadenya.AgentVariationListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 `client.AgentVariations.New(ctx, agentID, body) (*AgentVariation, error)` **post** `/v1/agents/{agentId}/variations` Creates a new variation for an agent ### Parameters - `agentID string` - `body AgentVariationNewParams` - `Metadata param.Field[CreateResourceMetadata]` 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 param.Field[AgentVariationSpec]` AgentVariationSpec defines the operational configuration for a variation ### Returns - `type AgentVariation struct{…}` AgentVariation resource - `Metadata ResourceMetadata` 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 Time` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec AgentVariationSpec` AgentVariationSpec defines the operational configuration for a variation - `CompactionConfig AgentVariationSpecCompactionConfig` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `Summarization CompactionConfigSummarizationStrategy` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `ToolResultClearing CompactionConfigToolResultClearingStrategy` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 float64` 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 AgentVariationSpecConstraints` Execution constraints - `MaxSubObjectives int64` The maximum number of sub-objectives that can be created. 0 means no limit. - `MaxToolCalls int64` The maximum number of tool calls that can be made. 0 means no limit. - `Description string` Human-readable description of what this variation does or when it should be used - `EnableEpisodicMemory bool` 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 int64` How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely. - `ModelConfig AgentVariationSpecModelConfig` ModelConfig defines the model configuration for a variation - `ModelID string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `Temperature float64` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `Prompt string` The system prompt for this variation - `ToolSelection AgentVariationSpecToolSelection` Tool selection strategy - `AssignedTools ToolSelectionAssignedTools` 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 bool` - `AutoDiscovery ToolSelectionAutoDiscovery` 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 []string` - `MaxTools int64` - `Weight int64` 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 AgentVariationInfo` AgentVariationInfo provides read-only summary information about a variation - `Assignments []VariationAssignment` All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation's full assignment list without calling the add/remove endpoints just to enumerate. - `ID string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `CreatedBy Profile` 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 AccountResourceMetadata` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec ProfileSpec` ProfileSpec contains the profile-specific fields - `Type ProfileSpecType` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"` - `const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"` - `const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"` - `Email string` Email address of the user (required, unique per account) - `Name string` Display name for the user (e.g., "Bobby Tables") - `FeedbackCount int64` Total number of objective feedbacks received for this variation - `Model ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `Score float64` 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 int64` Number of sub-agents assigned to this variation - `ToolCount int64` Number of individual tools assigned to this variation - `ToolSetCount int64` Number of tool sets assigned to this variation ### Example ```go package main import ( "context" "fmt" "github.com/cadenya/cadenya-go" "github.com/cadenya/cadenya-go/option" "github.com/cadenya/cadenya-go/shared" ) func main() { client := cadenya.NewClient( option.WithAPIKey("My API Key"), ) agentVariation, err := client.AgentVariations.New( context.TODO(), "agentId", cadenya.AgentVariationNewParams{ Metadata: cadenya.F(shared.CreateResourceMetadataParam{ Name: cadenya.F("name"), }), Spec: cadenya.F(cadenya.AgentVariationSpecParam{ }), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", agentVariation.Metadata) } ``` #### 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 `client.AgentVariations.Get(ctx, agentID, id) (*AgentVariation, error)` **get** `/v1/agents/{agentId}/variations/{id}` Retrieves a variation by ID from an agent ### Parameters - `agentID string` - `id string` ### Returns - `type AgentVariation struct{…}` AgentVariation resource - `Metadata ResourceMetadata` 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 Time` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec AgentVariationSpec` AgentVariationSpec defines the operational configuration for a variation - `CompactionConfig AgentVariationSpecCompactionConfig` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `Summarization CompactionConfigSummarizationStrategy` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `ToolResultClearing CompactionConfigToolResultClearingStrategy` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 float64` 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 AgentVariationSpecConstraints` Execution constraints - `MaxSubObjectives int64` The maximum number of sub-objectives that can be created. 0 means no limit. - `MaxToolCalls int64` The maximum number of tool calls that can be made. 0 means no limit. - `Description string` Human-readable description of what this variation does or when it should be used - `EnableEpisodicMemory bool` 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 int64` How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely. - `ModelConfig AgentVariationSpecModelConfig` ModelConfig defines the model configuration for a variation - `ModelID string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `Temperature float64` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `Prompt string` The system prompt for this variation - `ToolSelection AgentVariationSpecToolSelection` Tool selection strategy - `AssignedTools ToolSelectionAssignedTools` 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 bool` - `AutoDiscovery ToolSelectionAutoDiscovery` 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 []string` - `MaxTools int64` - `Weight int64` 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 AgentVariationInfo` AgentVariationInfo provides read-only summary information about a variation - `Assignments []VariationAssignment` All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation's full assignment list without calling the add/remove endpoints just to enumerate. - `ID string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `CreatedBy Profile` 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 AccountResourceMetadata` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec ProfileSpec` ProfileSpec contains the profile-specific fields - `Type ProfileSpecType` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"` - `const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"` - `const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"` - `Email string` Email address of the user (required, unique per account) - `Name string` Display name for the user (e.g., "Bobby Tables") - `FeedbackCount int64` Total number of objective feedbacks received for this variation - `Model ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `Score float64` 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 int64` Number of sub-agents assigned to this variation - `ToolCount int64` Number of individual tools assigned to this variation - `ToolSetCount int64` Number of tool sets assigned to this variation ### Example ```go package main import ( "context" "fmt" "github.com/cadenya/cadenya-go" "github.com/cadenya/cadenya-go/option" ) func main() { client := cadenya.NewClient( option.WithAPIKey("My API Key"), ) agentVariation, err := client.AgentVariations.Get( context.TODO(), "agentId", "id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", agentVariation.Metadata) } ``` #### 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 `client.AgentVariations.Delete(ctx, agentID, id) error` **delete** `/v1/agents/{agentId}/variations/{id}` Deletes a variation from an agent ### Parameters - `agentID string` - `id string` ### Example ```go package main import ( "context" "github.com/cadenya/cadenya-go" "github.com/cadenya/cadenya-go/option" ) func main() { client := cadenya.NewClient( option.WithAPIKey("My API Key"), ) err := client.AgentVariations.Delete( context.TODO(), "agentId", "id", ) if err != nil { panic(err.Error()) } } ``` ## Update a variation `client.AgentVariations.Update(ctx, agentID, id, body) (*AgentVariation, error)` **patch** `/v1/agents/{agentId}/variations/{id}` Updates a variation for an agent ### Parameters - `agentID string` - `id string` - `body AgentVariationUpdateParams` - `Metadata param.Field[UpdateResourceMetadata]` UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server. - `Spec param.Field[AgentVariationSpec]` AgentVariationSpec defines the operational configuration for a variation - `UpdateMask param.Field[string]` Fields to update ### Returns - `type AgentVariation struct{…}` AgentVariation resource - `Metadata ResourceMetadata` 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 Time` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec AgentVariationSpec` AgentVariationSpec defines the operational configuration for a variation - `CompactionConfig AgentVariationSpecCompactionConfig` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `Summarization CompactionConfigSummarizationStrategy` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `ToolResultClearing CompactionConfigToolResultClearingStrategy` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 float64` 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 AgentVariationSpecConstraints` Execution constraints - `MaxSubObjectives int64` The maximum number of sub-objectives that can be created. 0 means no limit. - `MaxToolCalls int64` The maximum number of tool calls that can be made. 0 means no limit. - `Description string` Human-readable description of what this variation does or when it should be used - `EnableEpisodicMemory bool` 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 int64` How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely. - `ModelConfig AgentVariationSpecModelConfig` ModelConfig defines the model configuration for a variation - `ModelID string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `Temperature float64` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `Prompt string` The system prompt for this variation - `ToolSelection AgentVariationSpecToolSelection` Tool selection strategy - `AssignedTools ToolSelectionAssignedTools` 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 bool` - `AutoDiscovery ToolSelectionAutoDiscovery` 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 []string` - `MaxTools int64` - `Weight int64` 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 AgentVariationInfo` AgentVariationInfo provides read-only summary information about a variation - `Assignments []VariationAssignment` All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation's full assignment list without calling the add/remove endpoints just to enumerate. - `ID string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `CreatedBy Profile` 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 AccountResourceMetadata` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec ProfileSpec` ProfileSpec contains the profile-specific fields - `Type ProfileSpecType` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"` - `const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"` - `const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"` - `Email string` Email address of the user (required, unique per account) - `Name string` Display name for the user (e.g., "Bobby Tables") - `FeedbackCount int64` Total number of objective feedbacks received for this variation - `Model ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `Score float64` 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 int64` Number of sub-agents assigned to this variation - `ToolCount int64` Number of individual tools assigned to this variation - `ToolSetCount int64` Number of tool sets assigned to this variation ### Example ```go package main import ( "context" "fmt" "github.com/cadenya/cadenya-go" "github.com/cadenya/cadenya-go/option" ) func main() { client := cadenya.NewClient( option.WithAPIKey("My API Key"), ) agentVariation, err := client.AgentVariations.Update( context.TODO(), "agentId", "id", cadenya.AgentVariationUpdateParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", agentVariation.Metadata) } ``` #### 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 `client.AgentVariations.AddAssignment(ctx, agentVariationID, body) (*VariationAssignment, error)` **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 - `agentVariationID string` - `body AgentVariationAddAssignmentParams` - `SubAgentID param.Field[string]` - `ToolID param.Field[string]` - `ToolSetID param.Field[string]` ### Returns - `type VariationAssignment struct{…}` 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 string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. ### Example ```go package main import ( "context" "fmt" "github.com/cadenya/cadenya-go" "github.com/cadenya/cadenya-go/option" ) func main() { client := cadenya.NewClient( option.WithAPIKey("My API Key"), ) variationAssignment, err := client.AgentVariations.AddAssignment( context.TODO(), "agentVariationId", cadenya.AgentVariationAddAssignmentParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", variationAssignment.ID) } ``` #### 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 `client.AgentVariations.RemoveAssignment(ctx, agentVariationID, id) error` **delete** `/v1/agent_variations/{agentVariationId}/assignments/{id}` Detaches an assignment from a variation, identified by the assignment ID returned when it was added. ### Parameters - `agentVariationID string` - `id string` ### Example ```go package main import ( "context" "github.com/cadenya/cadenya-go" "github.com/cadenya/cadenya-go/option" ) func main() { client := cadenya.NewClient( option.WithAPIKey("My API Key"), ) err := client.AgentVariations.RemoveAssignment( context.TODO(), "agentVariationId", "id", ) if err != nil { panic(err.Error()) } } ``` ## Domain Types ### Agent Variation - `type AgentVariation struct{…}` AgentVariation resource - `Metadata ResourceMetadata` 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 Time` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec AgentVariationSpec` AgentVariationSpec defines the operational configuration for a variation - `CompactionConfig AgentVariationSpecCompactionConfig` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `Summarization CompactionConfigSummarizationStrategy` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `ToolResultClearing CompactionConfigToolResultClearingStrategy` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 float64` 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 AgentVariationSpecConstraints` Execution constraints - `MaxSubObjectives int64` The maximum number of sub-objectives that can be created. 0 means no limit. - `MaxToolCalls int64` The maximum number of tool calls that can be made. 0 means no limit. - `Description string` Human-readable description of what this variation does or when it should be used - `EnableEpisodicMemory bool` 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 int64` How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely. - `ModelConfig AgentVariationSpecModelConfig` ModelConfig defines the model configuration for a variation - `ModelID string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `Temperature float64` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `Prompt string` The system prompt for this variation - `ToolSelection AgentVariationSpecToolSelection` Tool selection strategy - `AssignedTools ToolSelectionAssignedTools` 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 bool` - `AutoDiscovery ToolSelectionAutoDiscovery` 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 []string` - `MaxTools int64` - `Weight int64` 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 AgentVariationInfo` AgentVariationInfo provides read-only summary information about a variation - `Assignments []VariationAssignment` All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation's full assignment list without calling the add/remove endpoints just to enumerate. - `ID string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `CreatedBy Profile` 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 AccountResourceMetadata` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec ProfileSpec` ProfileSpec contains the profile-specific fields - `Type ProfileSpecType` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"` - `const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"` - `const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"` - `Email string` Email address of the user (required, unique per account) - `Name string` Display name for the user (e.g., "Bobby Tables") - `FeedbackCount int64` Total number of objective feedbacks received for this variation - `Model ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `Score float64` 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 int64` Number of sub-agents assigned to this variation - `ToolCount int64` Number of individual tools assigned to this variation - `ToolSetCount int64` Number of tool sets assigned to this variation ### Agent Variation Info - `type AgentVariationInfo struct{…}` AgentVariationInfo provides read-only summary information about a variation - `Assignments []VariationAssignment` All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation's full assignment list without calling the add/remove endpoints just to enumerate. - `ID string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `CreatedBy Profile` 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 AccountResourceMetadata` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Spec ProfileSpec` ProfileSpec contains the profile-specific fields - `Type ProfileSpecType` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"` - `const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"` - `const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"` - `Email string` Email address of the user (required, unique per account) - `Name string` Display name for the user (e.g., "Bobby Tables") - `FeedbackCount int64` Total number of objective feedbacks received for this variation - `Model ResourceMetadata` 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 Time` 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 string` External ID for the resource (e.g., a workflow ID from an external system) - `Labels map[string, string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `Score float64` 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 int64` Number of sub-agents assigned to this variation - `ToolCount int64` Number of individual tools assigned to this variation - `ToolSetCount int64` Number of tool sets assigned to this variation ### Agent Variation Spec - `type AgentVariationSpec struct{…}` AgentVariationSpec defines the operational configuration for a variation - `CompactionConfig AgentVariationSpecCompactionConfig` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `Summarization CompactionConfigSummarizationStrategy` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `ToolResultClearing CompactionConfigToolResultClearingStrategy` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 float64` 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 AgentVariationSpecConstraints` Execution constraints - `MaxSubObjectives int64` The maximum number of sub-objectives that can be created. 0 means no limit. - `MaxToolCalls int64` The maximum number of tool calls that can be made. 0 means no limit. - `Description string` Human-readable description of what this variation does or when it should be used - `EnableEpisodicMemory bool` 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 int64` How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely. - `ModelConfig AgentVariationSpecModelConfig` ModelConfig defines the model configuration for a variation - `ModelID string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `Temperature float64` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `Prompt string` The system prompt for this variation - `ToolSelection AgentVariationSpecToolSelection` Tool selection strategy - `AssignedTools ToolSelectionAssignedTools` 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 bool` - `AutoDiscovery ToolSelectionAutoDiscovery` 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 []string` - `MaxTools int64` - `Weight int64` 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 - `type AgentVariationSpecCompactionConfig struct{…}` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `Summarization CompactionConfigSummarizationStrategy` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `ToolResultClearing CompactionConfigToolResultClearingStrategy` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 float64` 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 - `type AgentVariationSpecConstraints struct{…}` - `MaxSubObjectives int64` The maximum number of sub-objectives that can be created. 0 means no limit. - `MaxToolCalls int64` The maximum number of tool calls that can be made. 0 means no limit. ### Agent Variation Spec Model Config - `type AgentVariationSpecModelConfig struct{…}` ModelConfig defines the model configuration for a variation - `ModelID string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `Temperature float64` 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 - `type AgentVariationSpecToolSelection struct{…}` - `AssignedTools ToolSelectionAssignedTools` 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 bool` - `AutoDiscovery ToolSelectionAutoDiscovery` 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 []string` - `MaxTools int64` ### Compaction Config Summarization Strategy - `type CompactionConfigSummarizationStrategy struct{…}` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `Instructions string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." ### Compaction Config Tool Result Clearing Strategy - `type CompactionConfigToolResultClearingStrategy struct{…}` ToolResultClearingStrategy configures clearing of older tool result content. - `PreserveRecentResults int64` 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 - `type ToolSelectionAssignedTools struct{…}` 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 bool` ### Tool Selection Auto Discovery - `type ToolSelectionAutoDiscovery struct{…}` 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 []string` - `MaxTools int64` ### Variation Assignment - `type VariationAssignment struct{…}` 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 string` - `Agent BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ID string` - `Name string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `Tool BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `ToolSet BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.