Setup

Set TCC environment variables

Our SDKs default to using the TCC_API_KEY environment variable.

.env

TCC_API_KEY="your-api-key"

Install the SDK

Step 1: Install dependencies

pnpm add @contextcompany/custom

npm i @contextcompany/custom

bun add @contextcompany/custom

Step 2: Create an agent run

An agent run represents a single execution of your agent, from the moment it receives a user input to the final response. Create a run before your agent loop begins, and end it after your agent loop completes. Initialize a run with run(). A run requires a prompt before calling .end(). The response is optional. Calling .end() will export the finalized run with all its parameters.

main.ts

import { run } from "@contextcompany/custom";

const r = run();
r.prompt("What is the weather in London?"); // required

// --- Your agent loop ---
// ...
// --- End of agent loop ---

r.response("The weather in London is 15°C and cloudy."); // optional
await r.end(); // required

That’s it! Your agent run will now be tracked and viewable in the dashboard.

Run methods

The following methods are available on a run. See Run usage for more details.

Method	Required	Description
`.prompt(text)`	Yes	The user input to the agent. Pass a string or `{ user_prompt, system_prompt? }`.
`.response(text)`	No	The final response from the agent
`.metadata({ key: "val" })`	No	Custom key-value metadata for filtering
`.status(code, message?)`	No	Set a status code and message
`.error(message?)`	No	Mark the run as failed
`.step(idOrOptions?)`	No	Create a step within the run
`.toolCall(nameOrOptions?)`	No	Create a tool call within the run
`.end()`	Yes	End the run and export it

Step 3: Add steps to your run

Steps represent individual LLM calls within an agent run. Use them to track the reasoning flow of your agent. A step requires both a prompt and a response before calling .end().

main.ts

import { run } from "@contextcompany/custom";

const r = run();
r.prompt("What is the weather in London?");

// --- Your agent loop ---
const s = r.step();
s.prompt("You are a weather agent. The user asked: What is the weather in London?"); // required
s.response("The weather in London is 15°C and cloudy."); // required
s.model("gpt-4o");
s.end();
// --- End of agent loop ---

r.response("The weather in London is 15°C and cloudy.");
await r.end();

Step methods

The following methods are available on a step. See Step usage for more details.

Method	Required	Description
`.prompt(text)`	Yes	The prompt sent to the LLM
`.response(text)`	Yes	The response returned by the LLM
`.model(name)`	No	The model name (shorthand)
`.model({ requested, used })`	No	The model requested and actually used
`.tokens({ uncached, cached, completion })`	No	Token counts for the step
`.cost(amount)`	No	Cost of the step in USD
`.finishReason(reason)`	No	Finish reason from the LLM
`.toolDefinitions(definitions)`	No	Tool definitions available to the LLM
`.status(code, message?)`	No	Set a status code and message
`.error(message?)`	No	Mark the step as failed
`.end()`	Yes	End the step

Step 4: Add tool calls to your run

Tool calls represent individual tool executions within an agent run. A tool call requires a name before calling .end().

main.ts

import { run } from "@contextcompany/custom";

const r = run();
r.prompt("What is the weather in London?");

// --- Your agent loop ---
const tc = r.toolCall("get_weather");
tc.args({ city: "London" });
tc.result({ temp: 15, unit: "C", condition: "cloudy" });
tc.end();
// --- End of agent loop ---

r.response("The weather in London is 15°C and cloudy.");
await r.end();

Tool call methods

Method	Required	Description
`.name(toolName)`	Yes	The name of the tool
`.args(value)`	No	Arguments passed to the tool (string or object)
`.result(value)`	No	Result returned by the tool (string or object)
`.status(code, message?)`	No	Set a status code and message
`.error(message?)`	No	Mark the tool call as failed
`.end()`	Yes	End the tool call

Debug mode

You can enable debug mode by setting the TCC_DEBUG environment variable, which will log payloads as they are created and sent.

TCC_DEBUG=true node main.js

Or configure programmatically:

import { configure } from "@contextcompany/custom";

configure({ debug: true });

Getting started

Supported frameworks

Custom Instrumentation

Monitoring

Integrations

Security

Set TCC environment variables

Install the SDK

Step 1: Install dependencies

Step 2: Create an agent run

Run methods

Step 3: Add steps to your run

Step methods

Step 4: Add tool calls to your run

Tool call methods

Debug mode

​Set TCC environment variables

​Install the SDK

​Step 1: Install dependencies

​Step 2: Create an agent run

​Run methods

​Step 3: Add steps to your run

​Step methods

​Step 4: Add tool calls to your run

​Tool call methods

​Debug mode

Set TCC environment variables

Install the SDK

Step 1: Install dependencies

Step 2: Create an agent run

Run methods

Step 3: Add steps to your run

Step methods

Step 4: Add tool calls to your run

Tool call methods

Debug mode