> ## Documentation Index > Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a variation > A variation is one concrete setup of an agent: model, prompt, tools, compaction, and the limits that keep a runaway objective from running forever. The agent is the role. The variation is the resume. Everything that decides how an objective runs lives here: which model, which prompt, how the context window is kept from filling, and how much the agent is allowed to do before you pull the cord. Every field on `spec` is optional. A variation with nothing but a model is valid, and a variation with nothing at all is too. ## The whole surface ```typescript TypeScript theme={null} const variation = await client.agents.variations.create(agentId, { workspaceId, metadata: { name: 'Tuned', externalId: 'tuned' }, spec: { systemPromptTemplate: 'You triage tickets for {{ system_prompt_data.company }}.', firstUserMessageTemplate: 'Ticket {{ first_user_message_data.id }}', modelConfig: { modelId: 'external_id:claude-sonnet-4-6', temperature: 0.3 }, constraints: { maxToolCalls: 25, maxSubObjectives: 3, inactivityTimeout: '7200s', }, compactionConfig: { triggerThreshold: 0.8, toolResultClearing: { preserveRecentResults: 5 }, summarization: { instructions: 'Keep decisions and open questions.' }, }, progressiveDiscovery: { maxTools: 10, hints: ['prefer read-only tools'], }, }, }); ``` ```go Go theme={null} variation, err := client.Agents.Variations.New(ctx, agentID, cadenya.AgentVariationNewParams{ WorkspaceID: cadenya.String(workspaceID), Metadata: shared.CreateResourceMetadataParam{ Name: "Tuned", ExternalID: cadenya.String("tuned"), }, Spec: cadenya.AgentVariationSpecParam{ SystemPromptTemplate: cadenya.String("You triage tickets for {{ system_prompt_data.company }}."), FirstUserMessageTemplate: cadenya.String("Ticket {{ first_user_message_data.id }}"), ModelConfig: cadenya.AgentVariationSpecModelConfigParam{ ModelID: cadenya.String("external_id:claude-sonnet-4-6"), Temperature: cadenya.Float(0.3), }, Constraints: cadenya.AgentVariationSpecConstraintsParam{ MaxToolCalls: cadenya.Int(25), MaxSubObjectives: cadenya.Int(3), InactivityTimeout: cadenya.String("7200s"), }, CompactionConfig: cadenya.AgentVariationSpecCompactionConfigParam{ TriggerThreshold: cadenya.Float(0.8), ToolResultClearing: cadenya.CompactionConfigToolResultClearingStrategyParam{ PreserveRecentResults: cadenya.Int(5), }, Summarization: cadenya.CompactionConfigSummarizationStrategyParam{ Instructions: cadenya.String("Keep decisions and open questions."), }, }, ProgressiveDiscovery: cadenya.AgentVariationSpecProgressiveDiscoveryParam{ MaxTools: cadenya.Int(10), Hints: []string{"prefer read-only tools"}, }, }, }) ``` ```ruby Ruby theme={null} variation = cadenya.agents.variations.create( agent_id, workspace_id: workspace_id, metadata: {name: "Tuned", externalId: "tuned"}, spec: { systemPromptTemplate: "You triage tickets for {{ system_prompt_data.company }}.", firstUserMessageTemplate: "Ticket {{ first_user_message_data.id }}", modelConfig: {modelId: "external_id:claude-sonnet-4-6", temperature: 0.3}, constraints: { maxToolCalls: 25, maxSubObjectives: 3, inactivityTimeout: "7200s" }, compactionConfig: { triggerThreshold: 0.8, toolResultClearing: {preserveRecentResults: 5}, summarization: {instructions: "Keep decisions and open questions."} }, progressiveDiscovery: { maxTools: 10, hints: ["prefer read-only tools"] } } ) ``` ```bash cURL theme={null} curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/agents/${AGENT_ID}/variations" \ -H "Authorization: Bearer ${CADENYA_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "name": "Tuned", "externalId": "tuned" }, "spec": { "systemPromptTemplate": "You triage tickets for {{ system_prompt_data.company }}.", "firstUserMessageTemplate": "Ticket {{ first_user_message_data.id }}", "modelConfig": { "modelId": "external_id:claude-sonnet-4-6", "temperature": 0.3 }, "constraints": { "maxToolCalls": 25, "maxSubObjectives": 3, "inactivityTimeout": "7200s" }, "compactionConfig": { "triggerThreshold": 0.8, "toolResultClearing": { "preserveRecentResults": 5 }, "summarization": { "instructions": "Keep decisions and open questions." } }, "progressiveDiscovery": { "maxTools": 10, "hints": ["prefer read-only tools"] } } }' ``` `modelId` takes a canonical `model_...` ID or the `external_id:` form. Cadenya resolves it and stores the canonical ID, so reading the variation back shows `model_01KWDY...` where you wrote `external_id:claude-sonnet-4-6`. Browse [List models](/docs/api-reference/modelservice/list-models) for what your workspace has. Both prompt fields are Liquid templates. The data roots are not optional: `systemPromptTemplate` reads `system_prompt_data.*` and `firstUserMessageTemplate` reads `first_user_message_data.*`. A bare `{{ company }}` renders as an empty string, with no error. ## Constraints are real These are not advisory. Each one is enforced at run time, and each one fails differently, which matters when you are deciding what to set. | Constraint | Bounds | What happens when it trips | | ------------------- | ------------------ | ------------------------------------------------------- | | `maxToolCalls` | `0` means no limit | The objective **fails**. | | `maxSubObjectives` | `0` means no limit | The spawn is refused. The agent is told and carries on. | | `inactivityTimeout` | `60s` to `86400s` | The objective is finalized as `STATE_TIMED_OUT`. | `maxToolCalls` is a kill switch, not a brake. Cross it and the objective moves to `STATE_FAILED` mid-task, losing whatever it was doing. Set it as a runaway backstop well above what a healthy run needs, not as a budget you expect to reach. `maxSubObjectives` is gentler: a [sub-agent](/docs/guides/delegate-to-sub-agents) spawn past the cap is rejected as a tool error and the parent keeps working. It is also best-effort, since two parallel spawns can both pass the check, so treat it as a cost guardrail rather than a hard invariant. `inactivityTimeout` counts silence, not runtime: no user messages, no model calls. Leave it unset and objectives are still swept at a system-wide 24-hour maximum, so nothing runs forever. ## Compaction keeps a long objective alive When an objective's context window fills past `triggerThreshold` (a fraction of the model's limit, default `0.75`), Cadenya compacts rather than failing. Two strategies, and they compose. ```typescript theme={null} compactionConfig: { triggerThreshold: 0.8, toolResultClearing: { preserveRecentResults: 5 }, summarization: { instructions: 'Keep decisions and open questions.' }, } ``` **Summarization always runs.** It condenses older turns into a summary carried into the fresh window, using the variation's own model. `instructions` replaces the default summarization prompt entirely, so it is your lever on what survives. Omit `compactionConfig` and you still get summarization at `0.75`. **Tool result clearing is the optional one.** It replaces the body of older tool results with `[result cleared]`, keeping the assistant's call itself (the function name and arguments) so the agent still remembers what it asked. `preserveRecentResults` is how many recent results survive intact, defaulting to `2`. Set both and they run in order: tool results are cleared first, then what remains is summarized. There is no compaction path that skips the model. Setting only `toolResultClearing` clears the results and **then still summarizes**, which is a billed model call. Reach for clearing when your tools return large payloads and the agent only needs to know a call happened; it shrinks what the summarizer has to read, not whether it runs. `triggerThreshold` must be greater than `0` and at most `1.0`, so there is no way to turn compaction off. If the model record carries no `maxInputTokens`, compaction never fires at all. ## Progressive discovery, briefly Set `progressiveDiscovery` and no tools are loaded up front. The agent gets a `tool_search` tool and a list of candidate tool names in its system prompt, then loads what it needs by **exact name**. A thousand assigned tools cost almost nothing until they are used. Despite the name, `tool_search` does not search. It takes `tool_names` and registers them, so the model picks from the names in its prompt. `hints` are prose appended to that list to steer the model's choice, up to five of them. `maxTools` caps how many names one `tool_search` call may request, from `1` to `10`. Ask for more and the call returns an error telling the model to retry in smaller batches; it does not silently truncate. The agent can call `tool_search` again, so this is not a ceiling on tools in the window. `rerankThreshold` does nothing. It is validated on write (values outside `0` to `1` are a `400`) and echoed back on read, and no execution path reads it. There is no reranker. Neither `maxTools` nor `rerankThreshold` declares its bounds in the OpenAPI schema, but both are enforced. See [Preventing tool bloat](/docs/guides/preventing-tool-bloat) for the full treatment. ## Variations compete A variation is a candidate, not a config file. Create several, let [weighted selection](/docs/guides/sdk/agents#let-variations-compete) route traffic, and [score the objectives](/docs/api-reference/objectiveservice/submit-feedback-for-an-objective) so the better prompt wins on evidence. That is the reason variations exist at all. One variation is a setting. Two is an experiment. Give a variation tools with [assignments](/docs/guides/sdk/agents#assignments-tools-sub-agents-memory), and memory layers with `memory_layer_assignments`, both of which are separate calls after this one. ## Related The lifecycle in code, from create to a running objective. Progressive discovery, include filters, and how they partner. What happens to a conversation when the window fills. Two variations, live feedback, and traffic shifting to the winner. ## OpenAPI ````yaml post /v1/workspaces/{workspaceId}/agents/{agentId}/variations openapi: 3.1.0 info: title: Cadenya API description: API for the Cadenya Agent Runtime platform. version: '1.0' servers: - url: https://api.cadenya.com description: Production server security: - bearerAuth: [] tags: - name: AIProviderKeyService - name: APIKeyService description: |- Issue, rotate, disable, and revoke a workspace's API keys. Every key belongs to exactly one workspace; the system-managed global account key is managed via GlobalAPIKeyService instead. - name: AccountService description: >- Manage the authenticated account. Accounts are the top-level organizational unit and contain one or more workspaces. - name: AgentScheduleService description: >- Manage recurring schedules attached to agents. Schedules trigger objectives on a cadence defined by AgentScheduleSpec.Schedule. - name: AgentService description: >- Manage AI agents within a workspace. Agents define AI behavior and tool access. - name: AgentVariationService description: >- Manage variations of an agent and their tool, sub-agent, and memory layer assignments. - name: GlobalAPIKeyService description: |- Manage the account's system-provisioned global API key. The global key is the only key that spans every workspace; it is created by the system and cannot be deleted, so the surface is retrieve, rotate, and the disable/enable kill switch. - name: MemoryService description: >- Manage memory layers and their entries. Layers are named containers that can be composed into an objective's memory cascade; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API. - name: ModelService description: |- Manage LLM models available to a workspace. Models represent provider and family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded with the supported models and you can enable or disable each one. - name: ObjectiveEventStreamsService - name: ObjectiveService - name: ProfilesService description: |- Operations on profiles, the account-level principals (users, API keys, system) that authenticate against the API. - name: SearchService - name: TenantService description: >- Read and erase tenants and the subjects under them. Tenants and subjects are created by assertion — on objective creation or widget session mint — never directly, so this service has no create or update: it exists to enumerate what assertions have produced, and to destroy it on request. - name: ToolService description: >- Manage tool sets and the tools they contain. Tool sets group related tools, and tools define specific capabilities available to agents. When a tool set is managed, only API key actors can modify its tools; human (profile) actors cannot. - name: UploadService description: |- Issue short-lived presigned URLs for direct client-to-object-storage uploads. Created uploads can be referenced by id when creating or updating resources that accept binary content (e.g., MemoryEntry). - name: WidgetService description: |- Manage embeddable chat widgets. A widget binds an agent to a globally unique hostname with a per-widget origin allowlist; browsers reach it with session tokens minted via WidgetSessionService. - name: WidgetSessionService description: >- Mint and manage widget sessions. Session creation is server-to-server only: the customer's backend authenticates its visitor, asserts tenant/subject context, attaches any per-visitor secrets, and receives a short-lived bearer token the browser uses against the widget host. - name: WorkspaceAdminService description: >- Administer workspaces across the account: create and archive workspaces and manage their membership. These operations are account-scoped and require the admin role (a token whose profile holds the WorkOS admin role); they live under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces tree so an admin can manage any workspace in the account, including ones they are not themselves a member of. - name: WorkspaceSecretService - name: WorkspaceService description: |- Manage workspaces within an account. Workspaces provide organizational grouping and isolation for resources such as agents, tools, and API keys. This is the workspace-scoped, end-user surface. Administrative operations (create / archive workspaces, manage members) live in WorkspaceAdminService under /v1/account/workspaces and require the admin role. paths: /v1/workspaces/{workspaceId}/agents/{agentId}/variations: post: tags: - AgentVariationService - Agent Variations summary: Create a new variation description: Creates a new variation for an agent operationId: AgentVariationService_CreateAgentVariation parameters: - name: workspaceId in: path description: Workspace ID. required: true schema: type: string example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q - name: agentId in: path description: >- Agent ID. Accepts the canonical `agent_…` form or the `external_id:` form. required: true schema: example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentVariationRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgentVariation' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: JavaScript source: >- import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); const agentVariation = await client.agents.variations.create('agent_01HXKD2E5NQM3T9AYWCFMGWT9Y', { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q', metadata: { name: 'name' }, spec: {}, }); console.log(agentVariation.metadata); - lang: Python source: |- import os from cadenya import Cadenya client = Cadenya( api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted ) agent_variation = client.agents.variations.create( agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y", workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q", metadata={ "name": "name" }, spec={}, ) print(agent_variation.metadata) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n\t\"go.cadenya.com/cadenya-go/shared\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tagentVariation, err := client.Agents.Variations.New(\n\t\tcontext.TODO(),\n\t\t\"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y\",\n\t\tcadenya.AgentVariationNewParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t\tMetadata: shared.CreateResourceMetadataParam{\n\t\t\t\tName: \"name\",\n\t\t\t},\n\t\t\tSpec: cadenya.AgentVariationSpecParam{},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", agentVariation.Metadata)\n}\n" - lang: Ruby source: |- require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") agent_variation = cadenya.agents.variations.create( "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y", workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q", metadata: {name: "name"}, spec: {} ) puts(agent_variation) - lang: CLI source: |- cadenya agents:variations create \ --api-key 'My API Key' \ --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \ --agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \ --metadata '{name: name}' \ --spec '{}' components: schemas: CreateAgentVariationRequest: required: - metadata - spec type: object properties: workspaceId: readOnly: true example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q type: string description: Workspace ID. agentId: readOnly: true example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y type: string description: >- Agent ID. Accepts the canonical `agent_…` form or the `external_id:` form. metadata: $ref: '#/components/schemas/CreateResourceMetadata' spec: $ref: '#/components/schemas/AgentVariationSpec' description: Create agent variation request AgentVariation: required: - metadata - spec type: object properties: metadata: allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Resource metadata spec: allOf: - $ref: '#/components/schemas/AgentVariationSpec' description: Variation specification info: readOnly: true allOf: - $ref: '#/components/schemas/AgentVariationInfo' description: Read-only summary information description: AgentVariation resource Status: type: object properties: code: type: integer description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: $ref: '#/components/schemas/GoogleProtobufAny' description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). CreateResourceMetadata: required: - name type: object properties: name: type: string description: >- Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") externalId: type: string description: >- External ID for the resource (e.g., a workflow ID from an external system) labels: type: object additionalProperties: type: string description: |- Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} description: |- 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. AgentVariationSpec: type: object properties: systemPromptTemplate: type: string description: >- Liquid template for the system prompt of objectives using this variation. Rendered with CreateObjectiveRequest.system_prompt_data into Objective.system_prompt. progressiveDiscovery: allOf: - $ref: '#/components/schemas/AgentVariationSpec_ProgressiveDiscovery' description: >- ProgressiveDiscovery is an optional config that, when set, will load a Cadenya provided tool that can search for tools in the assigned tool sets or tools. Note: Sub-agents are always loaded as a tool regardless of this value. constraints: allOf: - $ref: '#/components/schemas/AgentVariationSpec_Constraints' description: Execution constraints description: type: string description: >- Human-readable description of what this variation does or when it should be used modelConfig: allOf: - $ref: '#/components/schemas/AgentVariationSpec_ModelConfig' description: Model configuration for this variation compactionConfig: allOf: - $ref: '#/components/schemas/AgentVariationSpec_CompactionConfig' description: >- Compaction configuration for managing context window limits during long-running objectives. When not set, the system uses a default summarization strategy at 75% context window usage. firstUserMessageTemplate: type: string description: >- Liquid template for the first user message of objectives using this variation. Rendered with CreateObjectiveRequest.first_user_message_data into Objective.first_user_message, the first user message in the LLM chat history. CreateObjectiveRequest.first_user_message, when set, overrides the rendered result. If neither this template nor first_user_message is present, objective creation is rejected with InvalidArgument. description: AgentVariationSpec defines the operational configuration for a variation ResourceMetadata: required: - id - accountId - workspaceId - name - profileId - createdAt type: object properties: id: readOnly: true type: string description: >- Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") accountId: readOnly: true example: account_01HXKD2E5NQM3T9AYWCFTJHJVF type: string description: >- Account this resource belongs to for multi-tenant isolation (prefixed ULID) workspaceId: readOnly: true example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q type: string description: >- Workspace this resource belongs to for organizational grouping (prefixed ULID) name: type: string description: >- Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly externalId: type: string description: >- External ID for the resource (e.g., a workflow ID from an external system) labels: type: object additionalProperties: type: string description: |- Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} profileId: readOnly: true example: profile_01HXKD2E5NQM3T9AYWCFS0AP08 type: string description: ID of the actor (user or service account) that created this resource createdAt: readOnly: true type: string description: Timestamp when this resource was created format: date-time updatedAt: readOnly: true type: string description: Timestamp when this resource was last updated format: date-time description: >- Standard metadata for persistent, named resources (e.g., agents, tools, prompts) AgentVariationInfo: type: object properties: toolCount: readOnly: true type: integer description: Number of individual tools assigned to this variation format: int32 toolSetCount: readOnly: true type: integer description: Number of tool sets assigned to this variation format: int32 subAgentCount: readOnly: true type: integer description: Number of sub-agents assigned to this variation format: int32 createdBy: $ref: '#/components/schemas/Profile' model: readOnly: true allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Metadata for the model assigned to this variation score: type: number description: |- Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. format: float feedbackCount: type: integer description: Total number of objective feedbacks received for this variation format: int32 assignments: readOnly: true type: array items: $ref: '#/components/schemas/VariationAssignment' description: |- 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. memoryLayerAssignments: readOnly: true type: array items: $ref: '#/components/schemas/VariationMemoryLayerAssignment' description: |- Read-only list of memory layer assignments for this variation, returned in ascending `position` (most specific first — resolution order). Capped at 10 entries. memoryLayerCount: readOnly: true type: integer description: Count of memory layer assignments. format: int32 description: >- AgentVariationInfo provides read-only summary information about a variation GoogleProtobufAny: type: object properties: '@type': type: string description: The type of the serialized message. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. AgentVariationSpec_ProgressiveDiscovery: type: object properties: maxTools: type: integer description: >- The most tool names tool_search will load in a single call. Requesting more than this returns an error telling the model to retry in smaller batches -- it is a per-call batch limit, not a ceiling on how many tools an objective may end up with. format: int32 hints: type: array items: type: string description: >- Free-text guidance appended to the discoverable-tools appendix in the system prompt. Hints steer the model's choice of tool names; they do not filter or rank anything, because tool_search matches names exactly rather than searching. description: >- 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. AgentVariationSpec_Constraints: type: object properties: maxToolCalls: type: integer description: The maximum number of tool calls that can be made. 0 means no limit. format: int32 maxSubObjectives: type: integer description: >- The maximum number of sub-objectives that can be created. 0 means no limit. format: int32 inactivityTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: |- How long an objective may sit with no activity (no user messages, no LLM calls) before it is finalized as timed out. Between 1 minute and 24 hours, expressed as a duration string in seconds (e.g. "7200s"). When not set, objectives are still swept at the system-wide 24 hour maximum — every objective eventually reaches a terminal state. Note: no gnostic integer hint here on purpose. The Envoy gRPC-JSON transcoder only accepts the canonical protobuf JSON form for Durations — a "s" string — so the SDKs must type this as a string (like AgentScheduleSpec.every), not an integer. AgentVariationSpec_ModelConfig: type: object properties: modelId: example: claude/opus-4.6 type: string description: >- The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") temperature: type: number description: |- Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness format: float description: ModelConfig defines the model configuration for a variation AgentVariationSpec_CompactionConfig: type: object properties: triggerThreshold: type: number description: >- 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%) format: float summarization: allOf: - $ref: '#/components/schemas/CompactionConfig_SummarizationStrategy' description: >- Strategies — set one or more. When multiple are set, they execute in order: tool_result_clearing → summarization. When none are set, defaults to summarization with the system default prompt. toolResultClearing: $ref: '#/components/schemas/CompactionConfig_ToolResultClearingStrategy' description: >- CompactionConfig defines how context window compaction behaves for objectives using this variation. Profile: required: - metadata - spec type: object properties: metadata: $ref: '#/components/schemas/AccountResourceMetadata' spec: $ref: '#/components/schemas/ProfileSpec' description: |- 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. VariationAssignment: oneOf: - $ref: '#/components/schemas/VariationAssignment_Tool' - $ref: '#/components/schemas/VariationAssignment_ToolSet' - $ref: '#/components/schemas/VariationAssignment_Agent' discriminator: propertyName: type mapping: tool: $ref: '#/components/schemas/VariationAssignment_Tool' toolSet: $ref: '#/components/schemas/VariationAssignment_ToolSet' agent: $ref: '#/components/schemas/VariationAssignment_Agent' description: >- 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`. VariationMemoryLayerAssignment: type: object properties: id: readOnly: true example: avml_01HXKD2E5NQM3T9AYWCFX8AF59 type: string description: |- Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer's id. memoryLayer: allOf: - $ref: '#/components/schemas/BareMetadata' description: The attached memory layer. position: type: integer description: |- Position in the variation's baseline cascade. Position is specificity, CSS-style: a LOWER position is more specific and is consulted first; the highest-position assignment is the most general fallback. 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. format: int32 description: |- VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a given position in the variation's baseline memory cascade. A variation has at most one assignment per memory_layer_id. Variations only support whole-layer attachments — entry pinning is an objective-level capability. CompactionConfig_SummarizationStrategy: type: object properties: instructions: type: string description: |- Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." description: >- SummarizationStrategy configures LLM-powered summarization of older conversation turns. CompactionConfig_ToolResultClearingStrategy: type: object properties: preserveRecentResults: type: integer description: |- 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 format: int32 description: >- ToolResultClearingStrategy configures clearing of older tool result content. AccountResourceMetadata: required: - id - accountId - name - profileId type: object properties: id: readOnly: true type: string description: >- Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") accountId: readOnly: true example: account_01HXKD2E5NQM3T9AYWCFTJHJVF type: string description: >- Account this resource belongs to for multi-tenant isolation (prefixed ULID) name: type: string description: >- Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly externalId: type: string description: >- External ID for the resource (e.g., a workflow ID from an external system) labels: type: object additionalProperties: type: string description: |- Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} profileId: readOnly: true example: profile_01HXKD2E5NQM3T9AYWCFS0AP08 type: string createdAt: readOnly: true type: string format: date-time description: >- AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. ProfileSpec: required: - type type: object properties: email: type: string description: >- Email address of the profile. Required and unique within an account for user profiles. name: type: string description: Display name (e.g., "Bobby Tables"). type: enum: - PROFILE_TYPE_UNSPECIFIED - PROFILE_TYPE_USER - PROFILE_TYPE_API_KEY - PROFILE_TYPE_SYSTEM type: string description: >- Whether this profile represents a human user, an API key, or a system principal. format: enum description: Configuration for a profile. VariationAssignment_Tool: type: object required: - type - tool properties: type: type: string enum: - tool tool: $ref: '#/components/schemas/BareMetadata' id: readOnly: true example: avt_01HXKD2E5NQM3T9AYWCFJE6K89 type: string VariationAssignment_ToolSet: type: object required: - type - toolSet properties: type: type: string enum: - toolSet toolSet: $ref: '#/components/schemas/BareMetadata' id: readOnly: true example: avt_01HXKD2E5NQM3T9AYWCFJE6K89 type: string VariationAssignment_Agent: type: object required: - type - agent properties: type: type: string enum: - agent agent: $ref: '#/components/schemas/BareMetadata' id: readOnly: true example: avt_01HXKD2E5NQM3T9AYWCFJE6K89 type: string BareMetadata: type: object properties: id: readOnly: true type: string name: readOnly: true type: string description: >- 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). description: |- 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. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````