> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[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.</Warning>

<View title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-python">
    Setup
  </h2>

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

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```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
        ```
      </CodeGroup>
    </Step>

    <Step title="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>
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-python">
    Auto-instrumentation
  </h2>

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

  <CodeGroup>
    ```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)
    ```
  </CodeGroup>

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

  <CodeGroup>
    ```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())
    ```
  </CodeGroup>

  <Tip>
    Already running CrewAI with OpenTelemetry? Keep that setup and route spans to Braintrust using the [Braintrust OpenTelemetry guide](/integrations/sdk-integrations/opentelemetry#python-sdk-configuration).
  </Tip>

  <h2 id="what-traced-python">
    What Braintrust traces
  </h2>

  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.

  <h2 id="resources-python">
    Resources
  </h2>

  * [CrewAI documentation](https://docs.crewai.com/)
  * [Braintrust Python SDK reference](/sdks/python/versions/latest)
  * [Braintrust OpenTelemetry guide](/integrations/sdk-integrations/opentelemetry)
</View>