Skip to main content

​
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

​
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.
MethodRequiredDescription
.prompt(text)YesThe user input to the agent. Pass a string or { user_prompt, system_prompt? }.
.response(text)NoThe final response from the agent
.metadata({ key: "val" })NoCustom key-value metadata for filtering
.status(code, message?)NoSet a status code and message
.error(message?)NoMark the run as failed
.step(idOrOptions?)NoCreate a step within the run
.toolCall(nameOrOptions?)NoCreate a tool call within the run
.end()YesEnd 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.
MethodRequiredDescription
.prompt(text)YesThe prompt sent to the LLM
.response(text)YesThe response returned by the LLM
.model(name)NoThe model name (shorthand)
.model({ requested, used })NoThe model requested and actually used
.tokens({ uncached, cached, completion })NoToken counts for the step
.cost(amount)NoCost of the step in USD
.finishReason(reason)NoFinish reason from the LLM
.toolDefinitions(definitions)NoTool definitions available to the LLM
.status(code, message?)NoSet a status code and message
.error(message?)NoMark the step as failed
.end()YesEnd 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

MethodRequiredDescription
.name(toolName)YesThe name of the tool
.args(value)NoArguments passed to the tool (string or object)
.result(value)NoResult returned by the tool (string or object)
.status(code, message?)NoSet a status code and message
.error(message?)NoMark the tool call as failed
.end()YesEnd 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 });