New

Cairn 3.0 — multi-agent handoffs, eval suites and a rebuilt trace viewer

Read the changelog

New

Cairn 3.0 — multi-agent handoffs, eval suites and a rebuilt trace viewer

Docs · Getting started

Quickstart: your first agent in production.

Set up a workspace, connect a tool and ship a shadow-mode agent in about 30 minutes. Each step works from the UI or the CLI.

Overview

Cairn agents read a trigger, gather context from your tools, decide what to do and act through scoped permissions — leaving a trace of every step. In this guide you’ll build a refund agent for a support team and run it safely before it touches a real customer.

You’ll need a Cairn workspace on any plan, admin access to one support tool such as Zendesk or Intercom, and about 30 minutes.

New to agents?

Start with the Key concepts section below — five definitions cover everything this guide uses.

1. Create a workspace

Workspaces hold your agents, connections and traces. Pick the region where your data should live — you can’t move a workspace between regions later.

Terminal

npm install -g @cairn/cli
cairn login
cairn workspaces create --name "Support Ops" --region

2. Connect a tool

Connections use OAuth where the tool supports it. Start with read-only scopes; you’ll grant write access per action when the agent is ready to act.

Terminal

cairn integrations connect zendesk --scopes tickets:read
cairn integrations connect shopify --scopes

3. Create an agent

Describe the job in plain language, list the tools the agent may use and set the conditions that require a person. You can do the same thing in the visual builder.

create-agent.ts

import { Cairn } from "@cairn/sdk";

const cairn = new Cairn({ apiKey: process.env.CAIRN_API_KEY });

await cairn.agents.create({
  name: "Refund Resolver",
  trigger: { app: "zendesk", on: "ticket.created" },
  instructions: "Refund damaged items up to $150.",
  tools: ["shopify.orders.read", "stripe.refunds.create"],
  approvals: [{ when: "amount > 150", in: "#finance-ops" }],
  mode: "shadow",
});

4. Run in shadow mode

Shadow mode runs the full workflow but never writes to your tools. Replay recent tickets to see what the agent would have done, then compare its decisions with your team’s.

Terminal

cairn runs replay --agent refund-resolver --since 2026-09-01 --limit 200
cairn evals create --from-runs refund-resolver --name "refunds-v1"

Nothing leaves shadow mode by accident

Every proposed action is recorded in the trace with its evidence. Promotion to live is a separate, audited step.

5. Go live

When the eval suite passes and your team agrees with the agent’s decisions, promote it. Keep approval gates on anything above your thresholds.

Set approval thresholds for refunds and anything irreversible
Add the eval suite to the agent’s release checks
Switch the trigger from replay to live
Review the first 50 runs in the trace viewer

Terminal

cairn agents promote refund-resolver --env production --approval "amount > 150"

Key concepts

Agent

A job description with instructions, tools, knowledge and guardrails. Versioned like code.

Run

One execution of an agent or workflow, from trigger to result.

Trace

The record of a run: every input, tool call, decision, approval and output.

Approval gate

A condition that pauses a run until a person approves, edits or rejects the action.

Eval suite

Test cases built from real runs that score an agent’s decisions on every change.

Next steps

Start from a template

Twelve production-tested workflows.

Browse integrations

Scopes, triggers and actions for 120+ tools.

Review security

Permissions, audit logs and data residency.

Get help

Talk to an engineer about your setup.

Stuck on a step?

Pair with an engineer for 30 minutes.

We’ll set up your workspace together, connect your first tool and get a shadow-mode agent running on your data.

Book a session

Contact support

Free for every plan, including Starter

Stuck on a step?

Pair with an engineer for 30 minutes.

We’ll set up your workspace together, connect your first tool and get a shadow-mode agent running on your data.

Book a session

Contact support

Free for every plan, including Starter