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

# CrewAI

> Trace CrewAI multi-agent runs in Braintrust to debug crews, agents, and tool calls

[CrewAI](https://www.crewai.com/) is a framework for orchestrating teams of AI agents. Braintrust traces a CrewAI run as a single nested trace, covering crew kickoff, task execution, agent reasoning, LLM calls, and tool usage. The integration works with any model provider CrewAI supports.

> [!WARNING]
>
> CrewAI requires Python \< 3.14. A transitive dependency (`pydantic-core`) does not yet ship Python 3.14 wheels, so installation will fail on Python 3.14 and later.

**Python**

## Setup

Install the Braintrust SDK and CrewAI, then set your API keys. The examples below use OpenAI.

**1. Install packages**

```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv add braintrust crewai
```

```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust crewai
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>
OPENAI_API_KEY=<your-openai-api-key>
```

## Auto-instrumentation

To trace CrewAI alongside Braintrust's other supported libraries, call `braintrust.auto_instrument()` before creating your crew.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

import braintrust
from crewai import Agent, Crew, Task
from crewai.llm import LLM

braintrust.auto_instrument()
braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="crewai-example",  # Replace with your project name
)

llm = LLM(model="gpt-4o-mini")

coder = Agent(
    role="Software developer",
    goal="Write clear, concise code on demand",
    backstory="An expert coder with a keen eye for software trends.",
    llm=llm,
)

task = Task(
    description="Write a minimal HTML page with a heading that says Hello Braintrust.",
    expected_output="A concise HTML document",
    agent=coder,
)

crew = Crew(agents=[coder], tasks=[task])
result = crew.kickoff()
print(result)
```

To trace CrewAI without auto-instrumenting other libraries, use `setup_crewai()` instead of `braintrust.auto_instrument()`.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from braintrust.integrations.crewai import setup_crewai
from crewai import Agent, Crew, Task
from crewai.llm import LLM

setup_crewai(project_name="crewai-example")

llm = LLM(model="gpt-4o-mini")
coder = Agent(
    role="Software developer",
    goal="Write clear, concise code on demand",
    backstory="An expert coder with a keen eye for software trends.",
    llm=llm,
)
task = Task(
    description="Write a minimal HTML page with a heading that says Hello Braintrust.",
    expected_output="A concise HTML document",
    agent=coder,
)

print(Crew(agents=[coder], tasks=[task]).kickoff())
```

> [!TIP]
>
> Already running CrewAI with OpenTelemetry? Keep that setup and route spans to Braintrust using the [Braintrust OpenTelemetry guide](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/send-traces-and-logs.md#python-sdk-configuration).

## What Braintrust traces

Braintrust traces CrewAI runs as nested spans that mirror the actual execution flow. Captured spans:

* Crew kickoff spans (`crewai.kickoff`), with crew inputs, name, process, and fingerprint.
* Task spans (`crewai.task`), with description, expected output, assigned agent, and execution context.
* Agent execution spans (`crewai.agent`), with task prompt, role/goal/backstory, and available tools.
* LLM call spans (`crewai.llm`), with messages, model, tools, and provider config (temperature, max tokens, top p, response format, and so on); response on completion.
* Tool call spans (`crewai.tool.<name>`), with tool arguments, output, run attempts, and cache hits.
* Token usage metrics for LLM calls (input, output, total, plus cached and reasoning tokens when the provider reports them), captured on `crewai.llm` spans by default, or on the LiteLLM completion child span when LiteLLM is also auto-instrumented (to avoid double-counting).
* Time-to-first-token metric for streaming LLM calls.
* Errors on failed kickoffs, tasks, agents, LLM calls, and tool calls.
* Causal nesting via CrewAI event IDs, nested under any enclosing Braintrust span.

## Resources

* [CrewAI documentation](https://docs.crewai.com/)
* [Braintrust Python SDK reference](https://docs.braintrust.dev/sdks/python/versions/latest.md)
* [Braintrust OpenTelemetry guide](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/send-traces-and-logs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.