TypeScript SDK
Complete reference for the Tensile TypeScript SDK: init, begin, end, track, identify, setProperty, and conversation grouping, with runnable examples.
The TypeScript SDK instruments your agent from application code. Install it with npm install @asymmetric-ai/hone and configure it once at startup.
init
Configure the SDK with your API key. Call it once, early, before any other Tensile call.
import { init } from "@asymmetric-ai/hone";
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" });Deployment stage (dev / staging / prod)
Tag every event from a process with its deployment stage so the dashboard can separate real production traffic from dev and staging. The Stage filter on the reliability scorecard, cost views, and triage all read it, and the scorecard defaults to production so dev noise never skews your reliability numbers.
Set it once at init, or per-deploy from the HONE_ENV environment variable:
init("sk_your_key_here", { environment: "production" });
// or, per-deploy, from the environment:
// HONE_ENV=staging| Option | Environment | Default |
|---|---|---|
init(key, { environment }) | HONE_ENV | — (no stage tag) |
The value is written to metadata.environment on every event and canonicalized case-insensitively at write time: prod / PROD / prd → production, stg → staging, local / development → dev. Any other value is kept as-is (lowercased), so a custom stage like qa is never folded into the wrong bucket. The explicit init option wins over HONE_ENV.
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 "@asymmetric-ai/hone";
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. |
customerId | string | No | Downstream tenant when one agent serves several of your customers — see Multi-tenant. |
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 "@asymmetric-ai/hone";
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. |
customerId | string | No | Downstream tenant when one agent serves several of your customers — see Multi-tenant. |
Multi-tenant (customerId)
When one agent serves several of your own customers, pass customerId so each session and event is scoped to the downstream tenant it belongs to. The end-user's identity becomes the pair (customerId, userId), and the dashboard can filter and roll up per customer.
// On an explicit turn:
const interaction = begin({
userId: "user-123",
agentName: "support-bot",
input: "How do I reset my password?",
customerId: "acme-corp",
});
interaction.end("Head to Settings → Security.");
// Or in one shot:
track({
userId: "user-123",
input: "How do I reset my password?",
output: "Head to Settings → Security.",
agentName: "support-bot",
customerId: "acme-corp",
});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 "@asymmetric-ai/hone";
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 "@asymmetric-ai/hone";
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 });