> ## 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.

# Setup

> Setup The Context Company custom instrumentation for Python

## Set TCC environment variables

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

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

## Install the SDK

### Step 1: Install dependencies

<CodeGroup>
  ```Title pip theme={null}
  pip install contextcompany
  ```

  ```Title poetry theme={null}
  poetry add contextcompany
  ```
</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 `tcc.run()`. A run requires a **prompt** before calling `.end()`. The **response** is optional. Calling `.end()` will export the finalized run with all its parameters.

```python main.py theme={null}
import contextcompany as tcc

r = tcc.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
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/python/runs) for more details.

| Method                                | Required | Description                                              |
| ------------------------------------- | -------- | -------------------------------------------------------- |
| `.prompt(user_prompt, system_prompt)` | **Yes**  | The user input (and optional system prompt) to the agent |
| `.response(text)`                     | No       | The final response from the agent                        |
| `.metadata(data, **kwargs)`           | No       | Custom key-value metadata for filtering                  |
| `.feedback(score, text)`              | No       | Submit user feedback for this run                        |
| `.status(code, message)`              | No       | Set a status code and message                            |
| `.error(status_message)`              | No       | Mark the run as failed                                   |
| `.step(step_id)`                      | No       | Create a step within the run                             |
| `.tool_call(tool_name, tool_call_id)` | 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()`.

```python main.py theme={null}
import contextcompany as tcc

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

# --- Your agent loop ---
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(requested="gpt-4", used="gpt-4-0613")
s.end()
# --- End of agent loop ---

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

#### Step methods

The following methods are available on a step. See [Step Usage](/frameworks/custom-instrumentation/python/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(requested, used)`                             | No       | The model requested and actually used |
| `.tokens(prompt_uncached, prompt_cached, completion)` | No       | Token counts for the step             |
| `.cost(real_total)`                                   | No       | Cost of the step                      |
| `.finish_reason(reason)`                              | No       | Finish reason from the LLM            |
| `.tool_definitions(definitions)`                      | No       | Tool definitions available to the LLM |
| `.status(code, message)`                              | No       | Set a status code and message         |
| `.error(status_message)`                              | No       | Mark the step as failed               |
| `.end()`                                              | **Yes**  | End the step and export it            |

## Maximize observability

Once instrumented, you can enrich your data with additional context:

* **Optional run data:** response and error handling
* **Optional step data:** model, token usage, cost, finish reason, tool definitions, and error handling
* **Custom metadata:** tie agent runs to your business logic (user, organization, feature, etc.)
* **User feedback:** collect thumbs up/down scores and text feedback from end users
* **Agent sessions:** group related runs into sessions to track full conversations
* **Debug mode:** log payloads as they are created and sent

See the [Run Usage](/frameworks/custom-instrumentation/python/runs), [Step Usage](/frameworks/custom-instrumentation/python/steps), and [Tool Call Usage](/frameworks/custom-instrumentation/python/tool-calls) guides for detailed examples.