> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecontext.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Setup The Context Company custom instrumentation for TypeScript

## Set TCC environment variables

<Tip>Our SDKs default to using the `TCC_API_KEY` environment variable.</Tip>

```typescript .env theme={null}
TCC_API_KEY="your-api-key"
```

## Install the SDK

### Step 1: Install dependencies

<CodeGroup>
  ```Title pnpm theme={null}
  pnpm add @contextcompany/custom
  ```

  ```Title npm theme={null}
  npm i @contextcompany/custom
  ```

  ```Title bun theme={null}
  bun add @contextcompany/custom
  ```
</CodeGroup>

### Step 2: Create an agent run

An [agent run](/concepts#agent-runs) 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.

```typescript main.ts theme={null}
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](/frameworks/custom-instrumentation/typescript/runs) 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](/concepts#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()`.

```typescript main.ts theme={null}
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](/frameworks/custom-instrumentation/typescript/steps) 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](/concepts#tool-calls) represent individual tool executions within an agent run.

A tool call requires a **name** before calling `.end()`.

```typescript main.ts theme={null}
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.

```bash theme={null}
TCC_DEBUG=true node main.js
```

Or configure programmatically:

```typescript theme={null}
import { configure } from "@contextcompany/custom";

configure({ debug: true });
```