@owlai/agent-sdk

Record the production AI agent you already run. Owl AI (withowl.ai) stores each conversation as an agent session — intents, tool calls, outcomes, traces, evals, and shadow clones.

Owl never hosts or runs the agent. Prompts stay in your repo. This is not a prompt CMS, and it is not CAMEL-AI OWL (the open-source multi-agent framework).

This is not the browser session-replay package (@owlai/sdk). Install this in the process that already runs the agent.

Install

npm install @owlai/agent-sdk

Get your public key from Settings → Integrations → Owl Agent SDK in the Owl dashboard. The same owl_pk_… key used by the web SDK works here. Keys are safe to ship in server code:

owl_pk_<env>_<random>

Usage

import { init } from "@owlai/agent-sdk";

const owl = init({
  publicKey: "owl_pk_prod_xxxxxxxx",
  baseUrl: "https://app.withowl.ai/api/v1",
});

const sessionId = owl.session({
  sourceSessionId: "conv_123",
  agentModel: "gpt-4o",
  agentFramework: "langchain",
});
owl.interaction(sessionId, { seq: 1, type: "intent", target: "refund" });
owl.outcome(sessionId, { status: "completed", outcomeStatus: "success" });
await owl.flush();

flush() POSTs to {baseUrl}/sdk/agents/ingest with X-Owl-Public-Key. baseUrl is required outside the Owl app (the default /api/v1 is relative).

Local Owl backend: baseUrl: "http://localhost:8000/api/v1".

API

const owl = init({ publicKey, baseUrl? });

owl.session({ sourceSessionId, agentModel?, agentFramework?, … });
owl.interaction(sessionId, { seq, type, target?, … });
owl.outcome(sessionId, { status, outcomeStatus?, … });
await owl.flush();

Traces show up in the dashboard under Agent Sessions.

Shadow clones

Owl never runs your agent. After a production turn, ask whether to clone it, then apply the variant Owl returns. If the experiment swaps tools, RAG, or voice and you do not apply those fields, the clone is a label only — the SDK throws instead of pretending.

import { applyShadowVariant, init } from "@owlai/agent-sdk";

const decision = await owl.shadow.shouldRun({
  sourceSessionId,
  agentModel,
  experimentKey: "tools-search-only",
});
if (!decision.run) return;

await applyShadowVariant(decision.variant, {
  model: ({ id }) => {
    model = id;
  },
  prompt: (prompt) => {
    system = prompt.snapshot ?? loadPrompt(prompt.ref);
  },
  tools: (tools) => {
    bindTools(tools);
  },
  rag: (rag) => {
    retriever = rag;
  },
  voice: (voice) => {
    realtime = voice;
  },
});

Pass a handler for every dimension present on decision.variant. Missing handlers throw ShadowCloneError. resolveCloneConfig(primary, variant) merges the variant onto your current runtime (enable/disable tools, overlay RAG/voice) when you want the object instead of side effects.

enroll() still defaults to { model: "claude-sonnet-5" }. Send only the dimensions the experiment should swap.

Not these other Owls

This is Owl AI at withowl.ai. Not owl.co (insurance), owl-ai.com (courses), aiowl.org, the OwlAIProject repo, or CAMEL-AI OWL.

Links

• Brand — https://www.withowl.ai/
• Try Owl — https://www.withowl.ai/from/ai
• vs LangSmith / Braintrust — https://www.withowl.ai/vs/langsmith
• Dashboard — https://app.withowl.ai
• Browser session replay — @owlai/sdk

MIT © Owl