Agents

An agent gives a role a stable identity in Cadenya. Its Agent Variations define the behavior, model, prompts, tools, and other settings. Create several variations to test different configurations without replacing the agent.

Agent settings

An agent is a lightweight container for one or more Agent Variations. The agent itself holds a few settings worth understanding before you configure its variations.

Use an external ID

When you integrate with the Cadenya API, you can identify an agent by its Cadenya ID, such as agent_01M0EAKDT9ENHRAZZFQ4HVN3AY, or by an externalId. Use an external ID when you have one. It can be anything you want. As long as it’s alphanumeric. Ok so maybe not anything you want. An external ID lets your API calls use an identifier from your own system, so you do not need to store Cadenya’s generated ID. Set the external ID when you create the agent, then use the same value in later requests. Without an external ID:

https://api.cadenya.com/v1/workspaces/workspace_01M0EAKDT9ENHRAZZFQ4HVN3AY/agents/agent_01M0EAKDT9ENHRAZZFQ4HVN3AY

With external IDs:

https://api.cadenya.com/v1/workspaces/external_id:production/agents/external_id:support-bot

You can also use an external ID in place of a workspace ID.

Variations

Cadenya is designed to make switching between models, prompts, and tools easy with variations. Because your code and widgets are pointed at an “Agent” - Cadenya can then select which Variation to run on your behalf. You can, of course, provide an agent variation ID, too.

Model Selection

Variations are where you select which model to use for a given agent. Depending on the AI Provider’s configured in your workspace, you may have access to multiple models.

Prompts

There are two prompts you have control over:

System Prompt
First User Message Prompt

These fields accept Liquid templating to interpolate additional data into your prompts as well. Prompts are what steer your agent when it is dispatched. You can use multiple variations of your agent to test different prompts.

Structured Prompt Data

Your prompts have access to the objective’s systemPromptData and firstUserMessageData keys that can store arbitrary JSON objects. This feature is useful when you want to provide structured data to your objective, and manage the prompt rendering in Cadenya. For example, you can write a prompt like:

You are a {{ system_prompt_data.role }} assistant helping with {{ system_prompt_data.task }}.

Run the {{ first_user_message_data.cadence }} report for {{ first_user_message_data.region }}.

curl -X POST 'http://localhost:8080/v1/workspaces/production/objectives' \
  -H 'Authorization: Bearer $CADENYA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "faux-real",
    "system_prompt_data": {
      "role": "coding",
      "task": "debugging"
    },
    "first_user_message_data": {
      "cadence": "daily",
      "region": "EMEA"
    }
  }'

Assigning Tools

Variations can have Tool Sets, individual tools, and even other Agents assigned as tools. When an objective is dispatched for the agent, all of the tools assigned in the variation are loaded into the context for the LLM to use. That is, unless of course, you enable Progressive Discvoery. If you’ve read the Tool Sets guide, you know about Cadenya’s ability to filter tools with simple conditions. When a tool set is assigned to a variation, only the available tools are loaded into the objective. This helps manage context windows by reducing unnecessary input tokens.

Receive webhooks

Set a webhook endpoint on an agent to receive every event from its objectives. Cadenya sends events such as Tool Called and Approval Requested to the configured endpoint.

Use Svix Playground to test your webhook endpoint before you deploy it to production.

Signing and verification

Cadenya webhooks follow the Standard Webhooks specification. Each Cadenya SDK provides methods to verify and unwrap an incoming webhook. Find your HMAC secret in Account Admin.

Example events

Webhook events include:

objective_event.user_message: Cadenya sends this event when an objective receives its first user message or a later user message.
objective_event.tool_called: Cadenya sends this event when an objective calls a tool.
objective_event.tool_approval_requested: Cadenya sends this event when a tool call requires approval.

The webhooks guide walks through configuration, signature verification, event routing, and delivery troubleshooting. See the full payload list in the webhook events reference.

Structured output

Extraction

Use structured output for agents with one purpose: return a JSON object to your application. It works well for classification, extraction, and other structured-data tasks. Cadenya stores the output on the objective so you can retrieve it through the API without callbacks or tools.

Structured output requires a valid JSON Schema definition.

If you have a JSON object that shows the output you want, paste it into the input. Cadenya converts it to JSON Schema for you.

When an objective finishes with structured output, its final log event has the STATE_FINALIZED state.

Retrieve output

After an objective reaches STATE_FINALIZED, its result appears in the objective record’s output field. Use the Retrieve Objective API with your API key to access it from your code.

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya();
const objective = await client.objectives.retrieve('obj_01M0XTZWC2THMMCE7SCGBY9D8Q');

console.log(objective.output) // => {"name": "Kareem Wuckert"}

package main

import (
	"context"
	"fmt"
	"log"

	cadenya "go.cadenya.com/cadenya-go"
)

func main() {
	client, err := cadenya.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()
	params := &cadenya.ObjectiveRetrieveParams{}
	result, err := client.Objectives().Retrieve(ctx, "obj_01M0XTZWC2THMMCE7SCGBY9D8Q", params)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", result.Output)
}

require "cadenya"

client = Cadenya::Client.new
result = client.objectives.retrieve("obj_01M0XTZWC2THMMCE7SCGBY9D8Q")
puts result.output

Episodic memory

Agent amnesia, begone.

How it works

Episodic memory lets an agent remember information across objectives that share an episodic_key. Cadenya stores those entries in a system-managed Memory Layer. Your Agent Variation’s system prompt influences which memories the agent creates or skips. You can set a time to live (TTL) for episodic memory. Each new objective with the same key moves the expiration time forward. For example, you might create an objective with an episodic key like so:

curl -X POST https://api.cadenya.com/v1/workspaces/production/objectives \
  -H "Authorization: Bearer $CADENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
    "systemPromptData": {
      "customer_name": "Acme Corp"
    },
    "firstUserMessage": "What do we know about this customer so far?",
    "episodicMemory": {
      "key": "customer-details-123ABC"
    }
  }'

How an agent remembers

When you enable episodic memory, Cadenya gives your agent the built-in store_memory, get_memory, and search_memory tools. The agent stores entries in the Memory Layer for the episodic key and reads them on demand through the memory cascade. You can see calls to store_memory in an objective’s event log, like any other tool call.

Use your Agent Variation’s system prompt to direct when it should and should not store memory.

Reset memory

To reset an agent’s episodic memory, delete its Memory Layer or selected entries from the layer.

Getting Started

The Basics

Agent settings

Use an external ID

Variations

Model Selection

Prompts

Structured Prompt Data

Assigning Tools

Receive webhooks

Signing and verification

Example events

Structured output

Extraction

Retrieve output

Episodic memory

How it works

How an agent remembers

Reset memory

​Agent settings

​Use an external ID

​Variations

​Model Selection

​Prompts

​Structured Prompt Data

​Assigning Tools

​Receive webhooks

​Signing and verification

​Example events

​Structured output

​Extraction

​Retrieve output

​Episodic memory

​How it works

​How an agent remembers

​Reset memory

Agent settings

Use an external ID

Variations

Model Selection

Prompts

Structured Prompt Data

Assigning Tools

Receive webhooks

Signing and verification

Example events

Structured output

Extraction

Retrieve output

Episodic memory

How it works

How an agent remembers

Reset memory