Skip to main content
By the end of this page you’ll have the calado SDK wired into your app, sent your first conversation, seen it appear in the dashboard, and kicked off analysis to get findings.
Capturing a conversation takes a few seconds. Findings (patterns, severity, tiered evidence) only appear after you click Run Analysis on the agent page — calado doesn’t start LLM classification automatically on ingest, so you stay in control of when analysis cost is incurred.

​
Prerequisites

Before you start, you need:
  • A calado account with access to at least one organization.
  • An existing Anthropic or OpenAI client in your app — calado wraps it, it doesn’t replace it.
  • Node.js 18+.

​
1. Create an agent and grab your API key

1

Sign in

Open the calado dashboard and sign in to your organization.
2

Create an agent

Click New agent from the dashboard. Give it a name that matches the agent you’re monitoring.
3

Generate an API key

Open your agent’s Settings page and click Generate key. You’ll see the plaintext key once. Copy it now, it won’t be shown again.API keys are prefixed with cl_. Store the key in a secret manager or a .env file, never in source control.

​
2. Install the SDK

npm install calado
Also works with pnpm add calado and yarn add calado.

​
3. Wrap your client

calado works by returning a Proxy over your existing Anthropic or OpenAI client. No code changes beyond two lines. 
import Anthropic from "@anthropic-ai/sdk";
import { calado } from "calado";

calado.init(process.env.CALADO_API_KEY!);
const anthropic = calado.wrap(new Anthropic());

// Use the client exactly as before. calado captures in the background.
await anthropic.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  system: "You are a helpful assistant.",
  messages: [{ role: "user", content: "hello" }],
});

await calado.flush();
That’s it. Every subsequent call on the wrapped client is queued, batched, and sent to calado. flush() forces the queue to send now — important in scripts and serverless, harmless in long-running servers.
Running in a serverless environment? Functions freeze between invocations, so you need to flush explicitly before returning. See Serverless patterns.

​
4. See your conversation in the dashboard

The SDK batches events and flushes every 5 seconds by default. After your first call, wait a few seconds, then open your agent in the dashboard. You’ll see your conversation appear under the agent’s conversations list with a pending classification status. It’s stored, but no classification or findings will appear until you trigger analysis in the next step — calado never runs LLM classification on ingest. If nothing shows up, call await calado.flush() manually to force a send, or check calado.status() for transport errors.

​
5. Run analysis to get findings

Ingestion and analysis are intentionally decoupled. Calado stores conversations immediately but waits for you to trigger analysis so you decide when LLM cost is incurred.
1

Open your agent

Go to your agent page in the dashboard.
2

Click Run Analysis

Use the Run Analysis button on the agent page. This queues Stage 0 (spec assessment) and Stage 1 (per-conversation triage), then cascades to Stage 2 pattern synthesis.
3

Wait for the run to complete

Analysis runs in the background and takes minutes, not seconds, depending on conversation volume. Track progress under the agent’s Analysis runs section. Findings appear once there’s enough data to group into patterns.
You’ll need to click Run Analysis again after ingesting new conversations or updating agent definitions to re-classify against the new state.

​
Next steps

Full SDK guide

Conversation context, streaming, configuration, runtime behavior.

Serverless patterns

Flush the queue before your function freezes.

Direct API

Raw HTTP contract for when you can’t use the SDK.

Troubleshooting

Common issues and how to fix them.