API Reference

Agents

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create a new agent

agents.create(workspace_id, **kwargs) -> Agent { metadata, spec, info }

POST/v1/workspaces/{workspaceId}/agents

Creates a new agent in the workspace

ParametersExpand Collapse

workspace_id: String

metadata: CreateResourceMetadata { name, bundle_key, external_id, labels }

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.

name: String

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”)

bundle_key: String

Optional bundle ownership key. See ResourceMetadata.bundle_key.

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: AgentSpec { status, variation_selection_mode, description, 3 more }

Agent specification (user-provided configuration)

status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED

Status of the agent

formatenum

One of the following:

:AGENT_STATUS_UNSPECIFIED

:AGENT_STATUS_DRAFT

:AGENT_STATUS_PUBLISHED

:AGENT_STATUS_ARCHIVED

variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED

Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified

formatenum

One of the following:

:VARIATION_SELECTION_MODE_UNSPECIFIED

:VARIATION_SELECTION_MODE_RANDOM

:VARIATION_SELECTION_MODE_WEIGHTED

description: String

Description of the agent’s purpose

input_data_schema: Hash[Symbol, untyped]

InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool’s input parameter schema. If omitted, the sub-agent schema will be loaded with a simple “prompt” free text string as its schema.

output_definition: Hash[Symbol, untyped]

Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives.

webhook_events_url: String

The URL that Cadenya will send events for any objective assigned to the agent.

default_variation: DefaultVariation{ metadata, spec, agent_id, workspace_id}

Create agent variation request

metadata: CreateResourceMetadata { name, bundle_key, external_id, labels }

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.

name: String

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”)

bundle_key: String

Optional bundle ownership key. See ResourceMetadata.bundle_key.

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: AgentVariationSpec { compaction_config, constraints, description, 6 more }

AgentVariationSpec defines the operational configuration for a variation

compaction_config: AgentVariationSpecCompactionConfig { summarization, tool_result_clearing, trigger_threshold }

CompactionConfig defines how context window compaction behaves for objectives using this variation.

summarization: CompactionConfigSummarizationStrategy { instructions }

SummarizationStrategy configures LLM-powered summarization of older conversation turns.

instructions: String

Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: “Preserve all code snippets, variable names, and technical decisions.”

tool_result_clearing: CompactionConfigToolResultClearingStrategy { preserve_recent_results }

ToolResultClearingStrategy configures clearing of older tool result content.

preserve_recent_results: Integer

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

formatint32

trigger_threshold: Float

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%)

formatfloat

constraints: AgentVariationSpecConstraints { max_sub_objectives, max_tool_calls }

Execution constraints

max_sub_objectives: Integer

The maximum number of sub-objectives that can be created. 0 means no limit.

formatint32

max_tool_calls: Integer

The maximum number of tool calls that can be made. 0 means no limit.

formatint32

description: String

Human-readable description of what this variation does or when it should be used

enable_episodic_memory: bool

Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.

episodic_memory_ttl: Integer

How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.

model_config: AgentVariationSpecModelConfig { model_id, temperature }

ModelConfig defines the model configuration for a variation

model_id: String

The model identifier in family/model format (e.g., “claude/opus-4.6”, “claude/sonnet-4.5”)

temperature: Float

Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness

formatfloat

progressive_discovery: AgentVariationSpecProgressiveDiscovery { hints, max_tools, rerank_threshold }

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.

hints: Array[String]

max_tools: Integer

rerank_threshold: Float

Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.

formatfloat

prompt: String

The system prompt for this variation

weight: Integer

Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights). Only used when the agent’s variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

formatint32

agent_id: String

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

workspace_id: String

Workspace ID.

ReturnsExpand Collapse

class Agent { metadata, spec, info }

Agent resource

metadata: ResourceMetadata { id, account_id, created_at, 6 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: String

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

created_at: Time

Timestamp when this resource was created

formatdate-time

name: String

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

ID of the actor (user or service account) that created this resource

workspace_id: String

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundle_key: String

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: AgentSpec { status, variation_selection_mode, description, 3 more }

Agent specification (user-provided configuration)

status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED

Status of the agent

formatenum

One of the following:

:AGENT_STATUS_UNSPECIFIED

:AGENT_STATUS_DRAFT

:AGENT_STATUS_PUBLISHED

:AGENT_STATUS_ARCHIVED

variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED

Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified

formatenum

One of the following:

:VARIATION_SELECTION_MODE_UNSPECIFIED

:VARIATION_SELECTION_MODE_RANDOM

:VARIATION_SELECTION_MODE_WEIGHTED

description: String

Description of the agent’s purpose

input_data_schema: Hash[Symbol, untyped]

InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool’s input parameter schema. If omitted, the sub-agent schema will be loaded with a simple “prompt” free text string as its schema.

output_definition: Hash[Symbol, untyped]

Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives.

webhook_events_url: String

The URL that Cadenya will send events for any objective assigned to the agent.

info: AgentInfo { created_by, variation_count }

AgentInfo contains simple information about an agent for display or quick reference

created_by: Profile { metadata, spec }

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.

metadata: AccountResourceMetadata { id, account_id, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: String

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: String

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

:PROFILE_TYPE_UNSPECIFIED

:PROFILE_TYPE_USER

:PROFILE_TYPE_API_KEY

:PROFILE_TYPE_SYSTEM

email: String

Email address of the profile. Required and unique within an account for user profiles.

name: String

Display name (e.g., “Bobby Tables”).

variation_count: Integer

Create a new agent

Ruby

HTTP

TypeScript

Go

Ruby

CLI Tool

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent = cadenya.agents.create(
  "workspaceId",
  metadata: {name: "name"},
  spec: {status: :AGENT_STATUS_UNSPECIFIED, variationSelectionMode: :VARIATION_SELECTION_MODE_UNSPECIFIED}
)

puts(agent)

200 example

{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "status": "AGENT_STATUS_UNSPECIFIED",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
    "description": "description",
    "inputDataSchema": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "webhookEventsUrl": "webhookEventsUrl"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "variationCount": 0
  }
}

Returns Examples

200 example

{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "status": "AGENT_STATUS_UNSPECIFIED",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
    "description": "description",
    "inputDataSchema": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "webhookEventsUrl": "webhookEventsUrl"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "variationCount": 0
  }
}