Create an agent
The role, not the resume. An agent holds the contract its objectives obey: input schema, output schema, memory, and how variations compete.
metadata.name and spec.variationSelectionMode are required.
Create the agent and its first variation in one call
An agent cannot publish without a variation, so the API lets you supply one inline. This is the shortest path from nothing to a running agent.STATE_DRAFT and refuse objectives until published. publish, unpublish, archive, and unarchive are dedicated actions; state is read-only and a PATCH cannot set it.
outputDefinition decides whether an objective ever ends
This is the most consequential field on the spec, and the least obvious.
Without an outputDefinition, an objective answers and parks in STATE_WAITING, holding its context window open for your next turn. It never finalizes on its own. That is right for a chat agent and surprising for everything else.
With an outputDefinition, Cadenya runs an extraction pass once the agent stops working, validates the result against your schema, and moves the objective to STATE_FINALIZED with the result on output.
finalized event, at finalized.output, so a webhook or stream consumer never has to fetch the objective.
outputDefinition, you are waiting for something that never arrives. Either add the schema, or treat STATE_WAITING as done.systemPromptDataSchema catches bad data at the door
Declare a JSON Schema and every objective’s systemPromptData is validated against it before the run starts.
400 on the call that caused it.
It validates the data, not the template. A typo in {{ system_prompt_data.compnay }} still renders empty.
Memory and webhooks
enableEpisodicMemory turns the agent into one that remembers across runs. Once set, every objective must carry an episodicMemory.key, and omitting it is a 400. Objectives sharing a key share one system-managed memory layer. episodicMemoryTtl slides that layer’s expiry forward on each new objective; leave it unset and memories persist indefinitely.
Memory is agent-level, so every variation reads and writes the same memories, and a learning survives a variation swap.
webhookEventsUrl sends every objective event for this agent to your endpoint. It must be https, and deliveries are recorded in webhook deliveries.
variationSelectionMode
VARIATION_SELECTION_MODE_RANDOMpicks uniformly at random, forever. The default.VARIATION_SELECTION_MODE_WEIGHTEDlearns. Cadenya runs Thompson Sampling over each variation’s feedback, so variations that score well get picked more often while every variation keeps a shrinking chance to prove itself.
WEIGHTED anyway, since the second variation is the reason the field exists.
The lifecycle
Related
Agents and variations
Create a variation
Get structured output
outputDefinition.Memory layers
enableEpisodicMemory switches on.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Body
Create agent 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.
Agent specification (user-provided configuration)
Optional default variation to add to the agent on create
Response
OK
Agent resource
Resource metadata
Agent specification
The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states.
STATE_UNSPECIFIED, STATE_DRAFT, STATE_PUBLISHED, STATE_ARCHIVED Agent information