agentdock-sdk

Node.js SDK that wraps the Anthropic SDK to automatically report token usage, tool calls, and session lifecycle events to your AgentDock dashboard.

Installation

npm install agentdock-sdk @anthropic-ai/sdk

Quick start

import Anthropic from "@anthropic-ai/sdk";
import { AgentDock } from "agentdock-sdk";

const hub = new AgentDock({
  apiKey: process.env.AGENTDOCK_API_KEY!,
  // baseUrl defaults to AGENTDOCK_BASE_URL env var, then http://localhost:3000
});

const client = hub.wrapAnthropic(new Anthropic());

// 1. Start a session
await client.withSession({
  agentType: "coding-agent",
  name: "Task: fix auth bug",
  model: "claude-sonnet-4-6", // optional; auto-detected from responses
});

// 2. Make message calls as usual — usage + tool events are reported automatically
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});

// 3. End the session
await client.endSession({ status: "done" });

Constructor options

AgentDock(opts)

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your AgentDock project API key. | | baseUrl | string | AGENTDOCK_BASE_URL env → http://localhost:3000 | Base URL of your AgentDock instance. | | requireApproval | boolean | false | If true, calls to file-write tools (Write, Edit, MultiEdit, Bash) are held until a human approves or rejects them in the dashboard. The SDK throws an Error if rejected. |

API

hub.wrapAnthropic(client: Anthropic): WrappedAnthropic

Returns a WrappedAnthropic instance. All messages.create calls on this instance are automatically instrumented.

client.withSession(opts?): Promise<void>

Creates a new session on AgentDock. Should be called once before making message requests.

| Option | Type | Description | |---|---|---| | agentType | string | Identifies the kind of agent running (e.g. "coding-agent", "research"). | | name | string | Human-readable session name (e.g. "Task: fix auth bug"). | | model | string | Starting model (optional; auto-detected from responses). |

client.endSession(opts?): Promise<void>

Marks the current session as finished.

| Option | Type | Description | |---|---|---| | status | "done" \| "failed" \| "terminated" | Final status. Defaults to "terminated". | | error | string | Error message (used when status is "failed"). |

client.messages.create(params, options?): Promise<Anthropic.Message>

Drop-in replacement for client.messages.create. After every successful call:

1. Token usage (input_tokens, output_tokens) is posted to AgentDock as a cost_recorded event.
2. Any tool_use block whose name is Write, Edit, MultiEdit, or Bash is reported as a file_write event.
3. If requireApproval is true, the SDK blocks until a human approves or rejects the tool call in the dashboard. Rejected calls throw an Error.

Human approval flow

Enable requireApproval: true to pause agent execution whenever a file-write tool is called:

const hub = new AgentDock({
  apiKey: process.env.AGENTDOCK_API_KEY!,
  requireApproval: true,
});

const client = hub.wrapAnthropic(new Anthropic());
await client.withSession({ agentType: "coding-agent" });

try {
  // If the model calls Write/Edit/Bash, execution blocks here until approved
  const response = await client.messages.create({ ... });
} catch (err) {
  // err.message starts with "[AgentDock]" when a reviewer rejected the change
  console.error(err.message);
}

The SDK polls /api/v1/sessions/:sessionId/pending-change then /api/v1/changes/:changeId every 2 seconds. It times out after 5 minutes and logs a warning (without throwing) if no decision is received.

Error handling

The SDK is designed to be non-fatal: if AgentDock is unreachable or returns an error, a warning is written to stderr and the original Anthropic response is still returned to the caller. The only exception is an explicit rejection from a human reviewer when requireApproval is true.

Environment variables

| Variable | Description | |---|---| | AGENTDOCK_API_KEY | Project API key (can be passed as opts.apiKey instead). | | AGENTDOCK_BASE_URL | Base URL of your AgentDock instance (can be passed as opts.baseUrl instead). |

Building from source

npm install
npm run build   # outputs to dist/

TypeScript declarations are emitted alongside compiled JS, so consumers get full type support.

License

MIT — see LICENSE.