arkna

Official Node.js SDK for ARKNA — AI agent observability and incident intelligence.

ARKNA records every run, step, and tool call your AI agents make, with full context and hash-chained integrity. When something goes wrong, replay the exact run and see what the agent knew at each step.

Installation

npm install arkna

Quick Start

Auto-instrumentation (recommended)

One line. All OpenAI and Anthropic calls are captured automatically.

import { init } from 'arkna';

init({ apiKey: 'ark_live_...', agentName: 'my-agent' });

// Your existing code — no changes needed
import OpenAI from 'openai';
const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }],
});
// ^ This call is automatically recorded by ARKNA

Or zero-code via environment variables:

ARKNA_API_KEY=ark_live_... ARKNA_AGENT_NAME=my-agent NODE_OPTIONS="--require arkna/dist/init" node app.js

Manual instrumentation

For full control over what gets recorded:

import { ArknaClient } from 'arkna';

const arkna = new ArknaClient({
  apiKey: 'ark_live_...',
  agentName: 'my-agent',
});

const run = await arkna.startRun({ triggerType: 'api' });

await arkna.recordStep(run.id, {
  stepType: 'reasoning',
  input: 'User asked about refund policy',
  output: 'Found 3 relevant documents',
});

await arkna.recordToolCall(run.id, {
  toolName: 'search_docs',
  input: { query: 'refund' },
  output: { results: 3 },
  status: 'success',
});

await arkna.completeRun(run.id, { status: 'completed' });

Framework Integrations

LangChain

import { init, ArknaLangChainHandler } from 'arkna';

init({ apiKey: 'ark_live_...', agentName: 'my-langchain-agent' });
const handler = new ArknaLangChainHandler();

const result = await chain.invoke({ input: 'hello' }, { callbacks: [handler] });

Vercel AI SDK

import { init, wrapVercelAI } from 'arkna';

init({ apiKey: 'ark_live_...', agentName: 'my-vercel-agent' });
const ai = wrapVercelAI();

Configuration

| Environment Variable | Description | |---------------------|-------------| | ARKNA_API_KEY | API key (ark_live_...) | | ARKNA_AGENT_NAME | Agent name for identification | | ARKNA_BASE_URL | API endpoint (default: https://api.arkna.com.au) |

Requirements

• Node.js >= 18.0.0
• Zero runtime dependencies (uses built-in fetch)

License

MIT