> ## 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](/docs/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, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[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](/docs/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](/docs/sdks/python/versions/latest)
  * [Braintrust OpenTelemetry guide](/docs/integrations/sdk-integrations/opentelemetry)
</View>