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

# Run Usage

> Using runs with The Context Company custom instrumentation for Python

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.

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

```python theme={null}
r.prompt("What is the weather in London?").metadata(userId="user-123").response("15°C and cloudy.").end()
```

## Required

### Initialize run

```python theme={null}
r = tcc.run()
```

| Parameter        | Required | Description                                                                                                               |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `run_id`         | No       | Custom run ID. If not provided, a UUID is automatically generated.                                                        |
| `session_id`     | No       | Group multiple runs into an [agent session](/concepts#agent-sessions). See [Track agent sessions](#track-agent-sessions). |
| `conversational` | No       | Set to `True` to indicate the run was initiated by a user. See [Conversational Runs](/concepts#conversational-runs).      |

```python theme={null}
import contextcompany as tcc

r = tcc.run(run_id="your-custom-uuid", session_id="session-123", conversational=True)
```

Every run has a `.run_id` property you can use to retrieve its ID (auto-generated or custom):

```python theme={null}
run_id = r.run_id
```

### Set prompt

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

```python theme={null}
r.prompt(user_prompt, system_prompt=None)
```

| Parameter       | Required | Description                                           |
| --------------- | -------- | ----------------------------------------------------- |
| `user_prompt`   | **Yes**  | The user input to the agent                           |
| `system_prompt` | No       | A system message to include alongside the user prompt |

```python theme={null}
# User prompt only
r.prompt("What is the weather in London?")

# User prompt with system prompt
r.prompt("What is the weather in London?", system_prompt="You are a helpful weather agent.")
```

### End run

End the run and export it. A run must have a **prompt** set before calling `.end()`. The run cannot be modified after calling `.end()`.

```python theme={null}
import contextcompany as tcc

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

# --- Your agent loop ---
# ...
# --- End of agent loop ---

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

***

## Optional run data

### Set response

```python theme={null}
r.response(text)
```

| Parameter | Required | Description                       |
| --------- | -------- | --------------------------------- |
| `text`    | **Yes**  | The final response from the agent |

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

### Mark run as failed

Sets the status code to error and exports the payload. The run cannot be modified after calling `.error()`. Unlike `.end()`, calling `.error()` does not require a prompt to be set.

```python theme={null}
r.error(status_message)
```

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

```python theme={null}
import contextcompany as tcc

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

try:
    result = call_weather_api()
    r.response(result)
    r.end()
except Exception as e:
    r.error(status_message=str(e))
```

***

## Add custom metadata

Custom metadata allows you to add additional properties to your [agent runs](/concepts#agent-runs). This is particularly useful for tying agent runs to your own specific business logic, letting you filter and analyze agent runs by user, organization, feature, or some other dimension.

```python theme={null}
r.metadata(data, **kwargs)
```

| Parameter  | Required | Description                          |
| ---------- | -------- | ------------------------------------ |
| `data`     | No       | A dictionary of key-value pairs      |
| `**kwargs` | No       | Key-value pairs as keyword arguments |

```python theme={null}
# Pass metadata as keyword arguments
r.metadata(userId="4a6b111c-b53a-4d00-a877-67185022ab9e", orgId="org-123")

# Or pass metadata as a dictionary
r.metadata({
    "userId": "4a6b111c-b53a-4d00-a877-67185022ab9e",
    "orgId": "org-123",
})
```

Agent runs are automatically indexed by your custom metadata fields and can be filtered directly in the dashboard.

### Identifying the agent

If your product ships more than one named agent, set the reserved `tcc.agent` metadata key to scope the run to a specific [agent](/concepts#agents). The dashboard's top-level agent selector, per-agent patterns and recaps, and the `agent` filter on the [REST API](/access-data/api) and [MCP tools](/access-data/mcp) all read from this key.

```python theme={null}
r.metadata({
    "tcc.agent": "support-agent",
})
```

<Note>
  Agent names that collide with reserved dashboard routes (for example `runs`, `sessions`, `patterns`, `recaps`, `overview`, `search`, `failures`, `feedback`, `tools`, `topics`, `views`, `settings`, `mcp-and-api`) are dropped.
</Note>

***

### Identifying users and organizations

Attach the end user and their organization to a run as first-class identity using the reserved `tcc.userId`, `tcc.userName`, `tcc.orgId`, and `tcc.orgName` metadata keys. This is **not the same** as adding a `userId` field to custom metadata — these keys promote user and org identity to dedicated dashboard filters and unlock native user/org search, per-user views, and per-org analytics. See [User and organization identity](/concepts#user-and-organization-identity) for the full concept.

Set these whenever you have a stable identifier for the end user or their organization in your product.

```python theme={null}
r.metadata({
    "tcc.userId": "user-123",
    "tcc.userName": "Jane Doe",
    "tcc.orgId": "org-456",
    "tcc.orgName": "Acme Inc.",
})
```

<Note>
  `tcc.userName` and `tcc.orgName` require the corresponding ID (`tcc.userId` / `tcc.orgId`) to also be set. Names without IDs are dropped.
</Note>

***

## Add user feedback

User feedback allows you to collect score (thumbs up & thumbs down) and text feedback (up to 2000 characters) from end users on your [agent runs](/concepts#agent-runs).

This is useful for tracking user satisfaction, identifying problematic responses, and filtering agent runs in the dashboard to focus on positive or negative feedback.

Both `score` and `text` are optional individually, but each request must include at least one of them.

`score` is the thumbs rating. Use only `"thumbs_up"` or `"thumbs_down"`.

`text` is written feedback from your user, up to 2000 characters.

| Parameter | Required | Description                                             |
| --------- | -------- | ------------------------------------------------------- |
| `score`   | No       | Thumbs rating. Must be `"thumbs_up"` or `"thumbs_down"` |
| `text`    | No       | Written user feedback, up to 2000 characters            |

There are two ways to submit feedback:

### Option 1: On the run object

If you have access to the run object, call `.feedback()` directly. No run ID needed.

```python theme={null}
import contextcompany as tcc

r = tcc.run()
r.prompt("What is the weather in London?")
r.response("The weather in London is 15°C and cloudy.")
r.end()

r.feedback(
    score="thumbs_up",  # Optional thumbs rating: "thumbs_up" or "thumbs_down"
    text="Very helpful!",  # Optional written user feedback, up to 2000 characters
)
```

### Option 2: With a run ID

If you need to submit feedback separately (e.g. from a client), pass the run's ID to `tcc.submit_feedback()`.

```python theme={null}
import contextcompany as tcc

# Server side: pass the run ID to your client
r = tcc.run()
run_id = r.run_id

r.prompt("What is the weather in London?")
r.response("The weather in London is 15°C and cloudy.")
r.end()

# Client side: submit score and/or text feedback using the run ID
tcc.submit_feedback(
    run_id=run_id,
    score="thumbs_down",  # Optional thumbs rating: "thumbs_up" or "thumbs_down"
    text="The temperature was wrong.",  # Optional written user feedback, up to 2000 characters
)
```

Agent runs with feedback can be filtered in the dashboard using the feedback filter.

***

## Track agent sessions

[Agent sessions](/concepts#agent-sessions) represent multiple agent runs that are grouped together. The most common use case is tracking entire conversations between a human user and an AI agent in chatbot interfaces.

Agent sessions can be tracked by passing a `session_id` when creating a run:

```python theme={null}
import contextcompany as tcc

session_id = "unique-session-identifier"

# First message in the conversation
r1 = tcc.run(session_id=session_id)
r1.prompt("What is the weather in London?")
r1.response("The weather in London is 15°C and cloudy.")
r1.end()

# Second message in the same conversation
r2 = tcc.run(session_id=session_id)
r2.prompt("What about Paris?")
r2.response("The weather in Paris is 18°C and sunny.")
r2.end()
```

The `session_id` should be a unique string identifier. We recommend using a UUID.

Agent sessions are automatically indexed and can be filtered directly in the dashboard.