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

# Step usage

> Using steps with The Context Company custom instrumentation for TypeScript

A [step](/concepts#steps) represents a single request to an LLM and its response within an [agent run](/concepts#agent-runs). A step requires both a **prompt** and a **response** before calling `.end()`.

All setter methods return `this`, so you can chain calls:

```typescript theme={null}
s.prompt("Hello").response("World").model("gpt-4o").end();
```

## Required

### Create step

Create a step from a run:

```typescript theme={null}
const s = r.step();
```

| Parameter | Required | Description                                                         |
| --------- | -------- | ------------------------------------------------------------------- |
| `stepId`  | No       | Custom step ID. If not provided, a UUID is automatically generated. |

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

const r = run();
const s = r.step();
// or with custom ID
const s2 = r.step("custom-step-id");
```

### Set prompt

The prompt is **required** before calling `.end()`.

```typescript theme={null}
s.prompt(text);
```

| Parameter | Required | Description                |
| --------- | -------- | -------------------------- |
| `text`    | **Yes**  | The prompt sent to the LLM |

```typescript theme={null}
s.prompt("You are a weather agent. The user asked: What is the weather in London?");
```

### Set response

The response is **required** before calling `.end()`.

```typescript theme={null}
s.response(text);
```

| Parameter | Required | Description                      |
| --------- | -------- | -------------------------------- |
| `text`    | **Yes**  | The response returned by the LLM |

```typescript theme={null}
s.response("The weather in London is 15°C and cloudy.");
```

### End step

End the step. A step must have both a **prompt** and a **response** set before calling `.end()`. The step cannot be modified after calling `.end()`.

```typescript theme={null}
const s = r.step();
s.prompt("You are a weather agent. The user asked: What is the weather in London?");

// --- Your LLM call ---
// ...
// --- End of LLM call ---

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

***

## Optional step data

### Set model

Track which model was used. You can use the shorthand or provide both requested and used models.

```typescript theme={null}
s.model(name);
// or
s.model({ requested, used });
```

| Parameter   | Required | Description                      |
| ----------- | -------- | -------------------------------- |
| `name`      | No       | The model name (shorthand)       |
| `requested` | No       | The model that was requested     |
| `used`      | No       | The model that was actually used |

```typescript theme={null}
// Shorthand
s.model("gpt-4o");

// With requested and used
s.model({ requested: "gpt-4o", used: "gpt-4o-2024-08-06" });
```

### Set token usage

Track token counts for the step.

```typescript theme={null}
s.tokens({ uncached, cached, completion });
```

| Parameter    | Required | Description                      |
| ------------ | -------- | -------------------------------- |
| `uncached`   | No       | Number of uncached prompt tokens |
| `cached`     | No       | Number of cached prompt tokens   |
| `completion` | No       | Number of completion tokens      |

```typescript theme={null}
s.tokens({
  uncached: 150,
  cached: 50,
  completion: 25,
});
```

### Set cost

Track the cost of the step in USD.

```typescript theme={null}
s.cost(amount);
```

| Parameter | Required | Description                       |
| --------- | -------- | --------------------------------- |
| `amount`  | **Yes**  | The total cost of the step in USD |

```typescript theme={null}
s.cost(0.0035);
```

### Set finish reason

Set the finish reason returned by the LLM.

```typescript theme={null}
s.finishReason(reason);
```

| Parameter | Required | Description                                                          |
| --------- | -------- | -------------------------------------------------------------------- |
| `reason`  | **Yes**  | The finish reason returned by the LLM (e.g. `"stop"`, `"tool_call"`) |

```typescript theme={null}
s.finishReason("stop");
```

### Set tool definitions

Set the tool definitions available to the LLM for this step.

```typescript theme={null}
s.toolDefinitions(definitions);
```

| Parameter     | Required | Description                                                 |
| ------------- | -------- | ----------------------------------------------------------- |
| `definitions` | **Yes**  | The tool definitions available to the LLM (string or array) |

```typescript theme={null}
s.toolDefinitions('[{"name": "get_weather", "description": "Get the weather for a location"}]');

// Or as an array
s.toolDefinitions([
  { name: "get_weather", description: "Get the weather for a location" },
]);
```

### Mark step as failed

Sets the status code to error. The step cannot be modified after calling `.error()`. Unlike `.end()`, calling `.error()` does not require a prompt or response to be set.

```typescript theme={null}
s.error(statusMessage?);
```

| Parameter       | Required | Description                |
| --------------- | -------- | -------------------------- |
| `statusMessage` | No       | A description of the error |

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

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

const s = r.step();
s.prompt("Calling weather API...");

try {
  const result = await callWeatherApi();
  s.response(result);
  s.end();
} catch (e) {
  s.error(String(e));
}

// Run still ends successfully even if a step fails
await r.end();
```

***

## Factory pattern

If you have all step data available upfront, use the `sendStep` function:

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

await sendStep({
  runId: "run_abc",
  prompt: JSON.stringify(messages),
  response: assistantContent,
  model: { requested: "gpt-4o", used: "gpt-4o-2024-08-06" },
  tokens: { uncached: 120, cached: 30, completion: 45 },
  cost: 0.0042,
  startTime: new Date(),
  endTime: new Date(),
});
```