Skip to main content
POST
JavaScript
An agent is the stable thing your application names. Its variations carry the prompt and the model, and they come and go. The agent carries the contract. Only 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.
Agents are born 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.
The same value rides on the finalized event, at finalized.output, so a webhook or stream consumer never has to fetch the objective.
If you are polling for a terminal state and your agent has no 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.
Reach for this. Prompt data flows into a Liquid template, and a missing key renders as an empty string rather than an error, so the agent runs with a hole in its prompt and answers anyway. A schema is what turns that silent failure into a 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_RANDOM picks uniformly at random, forever. The default.
  • VARIATION_SELECTION_MODE_WEIGHTED learns. 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.
With one variation the mode is moot. Set WEIGHTED anyway, since the second variation is the reason the field exists.

The lifecycle

Published agents take objectives and fire schedules. Draft agents take edits. Archived agents take neither, but their objectives and feedback stay queryable.
Deleting an agent clears its variations’ assignments, so the tool sets and memory layers it referenced stay deletable. Delete discards the variations’ feedback history; archive keeps it.

Agents and variations

The lifecycle in code, in four languages.

Create a variation

Prompt, model, compaction, and the constraints that bound a run.

Get structured output

The hands-on lesson for outputDefinition.

Memory layers

What enableEpisodicMemory switches on.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Body

application/json

Create agent request

metadata
object
required

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
object
required

Agent specification (user-provided configuration)

defaultVariation
object

Optional default variation to add to the agent on create

Response

OK

Agent resource

metadata
object
required

Resource metadata

spec
object
required

Agent specification

state
enum<string>
required
read-only

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.

Available options:
STATE_UNSPECIFIED,
STATE_DRAFT,
STATE_PUBLISHED,
STATE_ARCHIVED
info
object

Agent information