TypeScript SDK

The TypeScript SDK instruments your agent from application code. Install it with npm install @hone/sdk and configure it once at startup.

init

Configure the SDK with your API key. Call it once, early, before any other Hone call.

import { init } from "@hone/sdk";

init("sk_your_key_here");

Pass an endpoint to target a non-default base URL, such as a local stack:

init("sk_your_key_here", { endpoint: "http://localhost:8080" });

Load the key from the environment rather than hard-coding it: init(process.env.HONE_API_KEY!). See Authentication.

begin and end

begin() opens an interaction for a single agent turn and returns an object you close with end(). Latency is captured automatically from the time between the two calls.

import { begin } from "@hone/sdk";

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

const reply = await runAgent("How do I reset my password?");

interaction.end(reply, { success: true });

begin options

Option	Type	Required	Description
`userId`	string	Yes	Pseudonymous identifier for the end user.
`agentName`	string	Yes	Name of the agent handling this turn.
`input`	string	Yes	The user’s message for this turn.

end arguments

Argument	Type	Required	Description
`output`	string	Yes	The agent’s reply.
`success`	boolean	No	Whether the turn succeeded. Defaults to `true`.

Mark a failed turn so it surfaces in error analytics:

try {
  const reply = await runAgent(userInput);
  interaction.end(reply, { success: true });
} catch (err) {
  interaction.end(String(err), { success: false });
}

track

track() records a completed turn in a single call. Reach for it when you already have both the input and the output and do not need to hold an interaction open.

import { track } from "@hone/sdk";

track({
  userId: "user_8f21",
  input: "How do I reset my password?",
  output: "Head to Settings, then Security, and choose Reset password.",
  agentName: "support-bot",
  conversationId: "conv_5c19",
});

Options

Option	Type	Required	Description
`userId`	string	Yes	Pseudonymous end-user identifier.
`input`	string	Yes	The user’s message.
`output`	string	Yes	The agent’s reply.
`agentName`	string	No	Name of the agent.
`conversationId`	string	No	Groups related turns into one conversation.

Conversation grouping

A conversation is a series of turns between one user and your agent. Pass the same conversationId across track() calls to thread them together, so the dashboard shows them as one exchange under User Stories.

const conversationId = "conv_5c19";

track({
  userId: "user_8f21",
  input: "How do I reset my password?",
  output: "Head to Settings, then Security, and choose Reset password.",
  conversationId,
});

track({
  userId: "user_8f21",
  input: "I don't see a Security tab.",
  output: "It's under your profile menu on the top right.",
  conversationId,
});

Generate a fresh id when a new conversation starts, and reuse it for every follow-up turn in that exchange.

identify

identify() attaches traits to a user id. Traits enrich the user profile in the dashboard and become dimensions you can filter and segment on. Keep the id pseudonymous.

import { identify } from "@hone/sdk";

identify("user_8f21", {
  plan: "enterprise",
  signupCohort: "2026-Q2",
  region: "eu-west",
});

setProperty and setProperties

Within an open interaction, attach custom properties such as the model used, token counts, or cost. These ride along on the event and power metadata-driven charts and filters.

const interaction = begin({
  userId: "user_8f21",
  agentName: "support-bot",
  input: "Summarize this thread.",
});

interaction.setProperty("model", "claude-sonnet-4");

interaction.setProperties({
  inputTokens: 1840,
  outputTokens: 220,
  costUsd: 0.0142,
});

interaction.end(reply, { success: true });

Use setProperty for a single key and setProperties to attach several at once. Define the corresponding keys under Settings → Metadata Keys so they become selectable dimensions in the dashboard.

Full example

import { init, begin, identify } from "@hone/sdk";

init(process.env.HONE_API_KEY!);

identify("user_8f21", { plan: "enterprise", region: "eu-west" });

const interaction = begin({
  userId: "user_8f21",
  agentName: "support-bot",
  input: "How do I export my data?",
});

interaction.setProperty("model", "claude-sonnet-4");

const reply = "Open Settings, choose Export, and pick a format. We'll email a link.";
interaction.setProperties({ outputTokens: 96, costUsd: 0.0031 });

interaction.end(reply, { success: true });

To capture MCP tool, resource, and prompt calls automatically, see MCP.

​init

​begin and end

​track

​Conversation grouping

​identify

​setProperty and setProperties

​Full example

init

begin and end

track

Conversation grouping

identify

setProperty and setProperties

Full example