Introduction

Before you start, you need:

A Cadenya account
About 15 minutes and a positive attitude

If videos are your thing, here’s Robert with a ~10 minute video end-to-end configuring an agent and dispatching an objective for it.

Create An Account

If you haven’t, create an account at https://app.cadenya.com/signup. After signing up and paying your initial monthly fee, you’ll gain access to the Cadenya platform and API. There’s no waiting.

Cadenya does not have a free plan. The level of effort to abuse free accounts has been greatly reduced in the past few years, and we avoid playing free tier whack-a-mole by requiring a minimum fee of $20.00 USD for all accounts.

Your account will be created with two workspaces: Development and Production. Workspaces are isolated from each other in Cadenya, so you can configure them independently. Cadenya provisions an OpenRouter key for you with a max budget of $5 to immediately try the product. After that, you need to grant Cadenya access to your own LLM provider. Cadenya does not provide inference.

Install Cadenya’s Skills

Cadenya comes with multiple skills for your coding agents to make use of. You can install them with:

npx skills add https://cadenya.com/docs

Install the CLI

brew install cadenya/tools/cadenya

choco install cadenya

Cadenya’s CLI is notarized for MacOS installations so you know it’s from us. It was a pain to do, and we can’t go through that without humble bragging.

This guide assumes you’re using a coding assistant such as Claude Code or OpenAI’s Codex. Cadenya can be fully driven via our user interface, but leveraging the CLI makes getting started much faster. Once installed, you can initialize the account pairing with:

cadenya auth login

Authorize the workspace

A browser window should open to an authorization page which will allow you to select which workspaces to give the CLI access to. Select your Development workspace. You can add others later by going through the same process.

Test the CLI

Once you’ve authorized your workspace, you may close the window. The CLI in your terminal should show a successful authorization.Try the CLI with:

cadenya auth status

You should see something like:

~/Code/cadenya.com % cadenya auth status
Profile "default": logged in.
  workspace: workspace_01KZ950VTH0TJ2ZKF503VX1QPN

Self-five yourself

You may now self-five yourself while no one is looking. 🙏

Nomenclature

Cadenya has a few terms that you’ll see everywhere. You’ll understand them more as you use the product, but in general:

Tool Sets	Configures a group of OpenAPI, MCP, HTTP, or Bare tools. Handles tool filtering, approval rules, and overlays to manage context from tool calls an LLM makes.
Agents	Agents have at-least-one variation that can be assigned an objective. Variations can be given Tool Sets, tools, or other agents for the behavior.
Objectives	Objectives are dispatched from your code (or schedules) using the Cadenya SDK and will initiate your agentic loop with the assigned tools. Compaction, approvals, and more are tied to objectives. Some products call this a session. We like objective.
Memory Layers	Memory layers are optional types that can be assigned to agent variations and be used to store documents, skills, or other facts. Memories can be created by an agent that has episodic memory enabled.
Widgets	Widgets are how you can use your Agents in Cadenya in your own webapp with minimal backend interaction. Custom domains. CORS. And React Components. All pre-built.

Your First Tool Set, Agent, and Objective

There are two flavors to the rest of this guide. You either are here to see what Cadenya is all about, or you’ve created your account and you’re ready to rock and roll with the CLI. Here’s how you can decide:

CLI Docs - You’re here to speed run to dispatching an objective.
UI Docs - You’re here to visualize Cadenya before buying.

CLI Docs
UI Docs

Create the Tool Set

With your CLI authenticated, we can now use it to create a Tool Set.

cadenya tool-sets create --display extended \
  --workspace-id "development" \
  --metadata '{"name":"Petstore","externalId":"petstore"}' \
  --spec '{
    "description": "Swagger Petstore v3",
    "adapter": {
      "type": "openapi",
      "openapi": {
        "type": "url",
        "url": "https://petstore3.swagger.io/api/v3/openapi.json",
        "baseUrl": "https://petstore3.swagger.io/api/v3"
      }
    }
  }'

You should see something like this in your stdout

-[ RECORD 1 ]-
ID      | toolset_01M08DTBR03YX7CH93WYHF13S3
NAME    | Petstore
CREATED | 2026-08-17T17:55:26.080514869Z
STATE   | STATE_ACTIVE

Create an Agent

Now we can create an Agent

cadenya agents create --display extended \
  --workspace-id "development" \
  --metadata '{"name":"Petstore Agent","externalId":"petstore-agent"}' \
  --spec '{
    "description": "Answers questions about pets in the Swagger Petstore",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_RANDOM"
  }'

Attach a variation

Now we can give our Agent a new variation that assigns the model and default prompts.

cadenya agents variations create petstore-agent \
  --display extended \
  --workspace-id "development" \
  --metadata '{"name":"default","externalId":"petstore-agent-default"}' \
  --spec '{
    "description": "Haiku-backed default variation",
    "systemPromptTemplate": "You are a helpful assistant for the Swagger Petstore. Use the available tools to look up pets, inventory, and orders. Do not invent pet data.",
    "firstUserMessageTemplate": "List inventory",
    "modelConfig": {
      "modelId": "getting-started-key.anthropic-claude-haiku-latest",
      "temperature": 0.2
    },
    "constraints": {
      "maxToolCalls": 25,
      "inactivityTimeout": "3600s"
    }
  }'

And we can compose our new variation with our Tool Set from earlier (The one that actually defines the Petstore tools).

cadenya agents variations add-assignment \
  petstore-agent \
  petstore-agent-default \
  --workspace-id "development" \
  --tool-set-id petstore \
  --display json

Before an Agent can be used to dispatch an Objective, we need to mark it as published.

cadenya agents publish petstore-agent \
  --display extended \
  --workspace-id "development"

Now let’s kick off an Objective.

Dispatch an objective

Now you have a Tool Set, an Agent, and an Agent Variation. Last stop: Objective town.

cadenya objectives create \
  --agent-id petstore-agent \
  --metadata '{"externalId":"petstore-run-001","labels":{"source":"cli"}}' \
  --system-prompt-data '{}' \
  --first-user-message 'Find all pets with status available and summarize them by category.'

You should see:

ID                              CREATED                         STATE
obj_01M08HAWG66MQ3M0P4DDFH6PS0  2026-08-17T18:56:53.254341617Z  STATE_PENDING

See the event log

Now that you have an objective, you can list its events as well. There are endpoints for streaming events, too. But for quick-start purposes we’re going to skip those for now.

cadenya objectives list-events petstore-agent

Copy the spec

https://free.cadenya.com/faker-mcp

Create a Tool Set

Navigate to Tool Sets in your workspaces navigation.
Click “Create Tool Set”
Fill in the name “Faker MCP”
Select “MCP” for the adapter type
Set the URL to https://free.cadenya.com/faker-mcp (from your clipboard if you copied it)
Disable “Just-in-time” loading (for now, you’ll use it later)
Save the Tool Set

Go to Agents

Getting Started

The Basics

Create An Account

Install Cadenya’s Skills

Install the CLI

Nomenclature

Your First Tool Set, Agent, and Objective

​Create An Account

​Install Cadenya’s Skills

​Install the CLI

​Login with the CLI

​Nomenclature

​Your First Tool Set, Agent, and Objective

Create An Account

Install Cadenya’s Skills

Install the CLI

Login with the CLI

Nomenclature

Your First Tool Set, Agent, and Objective