JavaScript
Agent Variations
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.
POST
JavaScript
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
Summarization always runs. It condenses older turns into a summary carried into the fresh window, using the variation’s own model.
See Preventing tool bloat for the full treatment.
spec is optional. A variation with nothing but a model is valid, and a variation with nothing at all is too.
The whole surface
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 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.maxSubObjectives is gentler: a sub-agent 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 pasttriggerThreshold (a fraction of the model’s limit, default 0.75), Cadenya compacts rather than failing. Two strategies, and they compose.
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
SetprogressiveDiscovery 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.
Neither
maxTools nor rerankThreshold declares its bounds in the OpenAPI schema, but both are enforced.Variations compete
A variation is a candidate, not a config file. Create several, let weighted selection route traffic, and score the objectives 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, and memory layers withmemory_layer_assignments, both of which are separate calls after this one.
Related
Agents and variations
The lifecycle in code, from create to a running objective.
Preventing tool bloat
Progressive discovery, include filters, and how they partner.
Compaction
What happens to a conversation when the window fills.
Build an agent that improves
Two variations, live feedback, and traffic shifting to the winner.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.
Example:
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"
Body
application/json
Create agent variation request
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 defines the operational configuration for a variation