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

# CrewAI

> Set up AI agent observability for Python apps using the CrewAI framework integration.

<Note>CrewAI instrumentation is available for Python only.</Note>

## 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"
```

## Instrument CrewAI

#### Step 1: Install dependencies

<CodeGroup>
  ```Title pip theme={null}
  pip install "contextcompany[crewai]"
  ```

  ```Title poetry theme={null}
  poetry add "contextcompany[crewai]"
  ```
</CodeGroup>

#### Step 2: Add instrumentation

You'll need to initialize instrumentation **before** CrewAI is imported. This is typically at the top of your application's entry point (for example, in `main.py` or `app.py`).

```python main.py theme={null}
import os
from dotenv import load_dotenv
load_dotenv()

# Import and initialize TCC instrumentation BEFORE importing CrewAI
from contextcompany.crewai import instrument_crewai

instrument_crewai()

# Your existing CrewAI code
from crewai import Agent, Crew, Task

researcher = Agent(
    role="Researcher",
    goal="Research the topic thoroughly",
    backstory="You are an expert researcher.",
)

task = Task(
    description="Research the latest trends in AI",
    expected_output="A summary of AI trends",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[task],
)

result = crew.kickoff()
```

That's it! Your app will now be instrumented and any CrewAI runs, LLM calls, and tool executions will be viewable in the dashboard.

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

CrewAI uses the `set_metadata` function to attach metadata to the next crew run:

```python main.py theme={null}
from contextcompany.crewai import set_metadata

set_metadata({
    # e.g. tag this agent run with a user id
    "userId": "4a6b111c-b53a-4d00-a877-67185022ab9e",
    "agentName": "research-crew",
    "environment": "production",
})

result = crew.kickoff()
```

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

<Note>
  The `tcc.*` namespace is reserved. Only the [reserved TCC metadata keys](/concepts#tcc-metadata-keys) (`tcc.runId`, `tcc.sessionId`, `tcc.conversational`, `tcc.agent`, `tcc.userId`, `tcc.userName`, `tcc.orgId`, `tcc.orgName`) are recognized; any other `tcc.*` keys are ignored. None of them appear in your custom metadata.
</Note>

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

### Step 1: Generate and pass a run ID

```python main.py theme={null}
import uuid
from contextcompany.crewai import set_metadata

# Generate a unique run ID (must be a UUID) before your crew execution
run_id = str(uuid.uuid4())

set_metadata({
    "tcc.runId": run_id,  # Pass the run ID in metadata
})

result = crew.kickoff()

# Return the run_id to your client
return {"response": result, "run_id": run_id}
```

### Step 2: Submit feedback from your client

Store the `run_id` on your client, then when the user provides feedback, submit it using the `submit_feedback` function.

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.

```python feedback.py theme={null}
from contextcompany import submit_feedback

# Submit score and/or text feedback:
submit_feedback(
    run_id=run_id,  # The run ID from your crew execution
    score="thumbs_up",  # Optional thumbs rating: "thumbs_up" or "thumbs_down"
    text="This was a helpful response!",  # Optional written user feedback, up to 2000 characters
)
```

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

## Tracking 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 setting `tcc.sessionId` in the `set_metadata` call:

```python main.py theme={null}
from contextcompany.crewai import set_metadata

session_id = "unique-session-identifier"

set_metadata({
    "tcc.sessionId": session_id,  # Track agent sessions
})

result = crew.kickoff()
```

The value of `session_id` should be a unique identifier for the agent session. This can be any string, but it's generally recommended to use a UUID.

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

## Marking runs as conversational

A [conversational run](/concepts#conversational-runs) is an agent run that was initiated by a user. Marking a run as conversational tells The Context Company that this run involves direct user interaction.

This is important because conversational runs are the only runs monitored for user insights, such as user confusion, frustration, or any other custom insights you want to track. Runs that are not marked as conversational (e.g. background jobs, cron tasks, or internal automations) are excluded from user insight analysis.

Mark a run as conversational by setting `tcc.conversational` to `"true"` in metadata:

```python main.py theme={null}
from contextcompany.crewai import set_metadata

set_metadata({
    "tcc.conversational": "true",
})

result = crew.kickoff()
```

## 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 main.py theme={null}
from contextcompany.crewai import set_metadata

set_metadata({
    "tcc.agent": "support-agent",
})

result = crew.kickoff()
```

<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 main.py theme={null}
from contextcompany.crewai import set_metadata

set_metadata({
    "tcc.userId": "user-123",
    "tcc.userName": "Jane Doe",
    "tcc.orgId": "org-456",
    "tcc.orgName": "Acme Inc.",
})

result = crew.kickoff()
```

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

## Combining multiple options

You can combine all TCC options in a single `set_metadata` call:

```python main.py theme={null}
import uuid
from contextcompany.crewai import set_metadata

run_id = str(uuid.uuid4())
session_id = "session-abc-123"

set_metadata({
    # TCC-specific options
    "tcc.runId": run_id,
    "tcc.sessionId": session_id,
    "tcc.conversational": "true",
    "tcc.agent": "support-agent",
    "tcc.userId": "user-123",
    "tcc.userName": "Jane Doe",
    "tcc.orgId": "org-456",
    "tcc.orgName": "Acme Inc.",
    # Custom metadata (tracked automatically)
    "agentName": "research-crew",
    "environment": "production",
})

result = crew.kickoff()
```

| Key                  | Type     | Description                                                        |
| -------------------- | -------- | ------------------------------------------------------------------ |
| `tcc.sessionId`      | `string` | Session ID for grouping runs                                       |
| `tcc.conversational` | `string` | Set to `"true"` if this run involves user interaction              |
| `tcc.runId`          | `string` | Custom run ID for feedback tracking                                |
| `tcc.agent`          | `string` | Agent name for first-class agent filtering                         |
| `tcc.userId`         | `string` | End user's ID. Required if setting `tcc.userName`.                 |
| `tcc.userName`       | `string` | End user's display name. Ignored unless `tcc.userId` is also set.  |
| `tcc.orgId`          | `string` | End user's organization ID. Required if setting `tcc.orgName`.     |
| `tcc.orgName`        | `string` | Organization display name. Ignored unless `tcc.orgId` is also set. |
| Other keys           | `string` | Custom metadata for filtering (tracked automatically)              |

## Async support

CrewAI instrumentation automatically captures both sync and async crew executions:

```python main.py theme={null}
# Sync execution
result = crew.kickoff()

# Async execution
result = await crew.akickoff()

# Batch execution (each input is tracked as a separate run)
results = crew.kickoff_for_each(inputs=[...])
```

## Examples

See our [examples repository](https://github.com/The-Context-Company/examples) for more detailed usage examples.