Skip to main content
GET
JavaScript
An agent is the role. This returns the role’s outline, not its substance: the substance lives in the variations, which you read separately.

What the shell holds

spec is short by design: description, variationSelectionMode, enableEpisodicMemory, and outputDefinition when the agent has one. No prompt, no model, no tools. Those are per-variation, because an agent runs several variations and lets the strong one win. info carries variationCount and createdBy, and it returns on every read: includeInfo is a no-op here, as on the other agent-family reads. So one call tells you the agent exists, whether it can run (state), how it picks a variation, and how many it has to pick from.

The three states

state is the field to check before you create an objective. A draft agent, or one you archived, refuses new work. See publish for the lifecycle.

Fetch by your own ID

Agents take an external ID, so a support-bot slug from your system fetches the agent without you storing a Cadenya ID:
A missing ID, in either form, is a 404.

List variations

The real configuration, and the score that ranks them.

Publish an agent

What moves state from DRAFT to PUBLISHED.

Create an agent

variationSelectionMode, outputDefinition, and episodic memory.

Create an objective

What a published agent can finally do.

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"

id
string
required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

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