hone (TypeScript SDK)

Send AI-agent conversations and MCP tool calls to Hone, an observability platform for AI agents. The SDK is ESM, has zero runtime dependencies (it uses the global fetch), and never throws capture failures into your application by default.

Install

npm install @asymmetric-ai/hone

Node 22+ is required (global fetch, crypto.randomUUID).

Configure

Set an API key and, optionally, an endpoint. Both can come from the environment or from init:

import { init } from "@asymmetric-ai/hone";

init("sk_your_key", { endpoint: "https://api.hone.dev" });

| Value | Source | | ---------- | ----------------------------------------------- | | API key | init(apiKey) or HONE_API_KEY | | Endpoint | init(_, { endpoint }) or HONE_ENDPOINT | | Default | https://api.hone.dev (local: http://localhost:8080) |

Auth is sent as the x-api-key: sk_<hex> header. A 401 means the key is invalid.

Capture a turn with begin / end

begin opens a new conversation (a fresh session_id) and records the start time. end posts the session once, then the event with a computed latency.

import { begin } from "@asymmetric-ai/hone";

const interaction = begin({
  userId: "user-42",
  agentName: "support-bot",
  input: "How do I reset my password?",
});

interaction.setProperty("model", "opus");
interaction.setProperties({ promptTokens: 128, cached: false });

const answer = await runYourAgent();
await interaction.end(answer, { success: true });

One-shot capture with track

For a fully-formed turn, track posts the session and event in one call. Pass conversationId to group several turns under a single session:

import { track } from "@asymmetric-ai/hone";

await track({
  userId: "user-42",
  agentName: "support-bot",
  input: "Hi",
  output: "Hello! How can I help?",
  conversationId: "thread-abc", // optional; groups turns
});

identify

Attach traits to the next session for a user. Traits are string key/values and are consumed once:

import { identify } from "@asymmetric-ai/hone";

identify("user-42", { plan: "pro", region: "us-east" });

MCP tool calls with trackMCP

Wrap an MCP server so every tool invocation becomes a PRIMITIVE_TYPE_TOOL event (primitive_name is the tool name). The @modelcontextprotocol/sdk package is an optional peer dependency — if it is absent, trackMCP simply does nothing.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { trackMCP } from "@asymmetric-ai/hone";

const server = new McpServer({ name: "my-server", version: "1.0.0" });
trackMCP(server); // wrap before registering tools

server.tool("add", async ({ a, b }) => ({
  content: [{ type: "text", text: String(a + b) }],
}));

Options let you drop sensitive payloads:

trackMCP(server, "sk_scoped_key", { disableInput: true, disableOutput: true });

Error handling

Capture failures are logged and swallowed by default so observability never breaks the host app. For tests (or strict environments) enable throwOnError:

init("sk_test", { throwOnError: true });

API summary

| Export | Purpose | | ------------------------------ | --------------------------------------------------- | | init(apiKey?, options?) | Module-level config (falls back to env). | | begin(args) → Interaction | Open a conversation; end, setProperty(-ies). | | track(args) → Promise<void> | One-shot turn capture; conversationId groups them.| | identify(userId, traits) | Traits for the next session. | | trackMCP(server, key?, opts?)| Instrument an MCP server's tool calls. | | HoneTransportError | Error thrown under throwOnError. |