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

# Debug CrewAI Agents and Flows Locally with AgentDbg

> Import the AgentDbg CrewAI adapter to automatically record every LLM call and tool call from your crews and flows into a local AgentDbg timeline.

AgentDbg's CrewAI integration registers execution hooks that tap into CrewAI's native before/after call lifecycle. Import the adapter once and every LLM invocation and tool execution from your crew or flow is automatically captured in the active AgentDbg run—including agent role, task description, and timing metadata.

## What gets captured

The adapter hooks into four CrewAI execution points:

* **LLM calls** (`before_llm_call` / `after_llm_call`) — records model name, prompt messages, response, and duration as an `LLM_CALL` event.
* **Tool calls** (`before_tool_call` / `after_tool_call`) — records tool name, input arguments, result, and duration as a `TOOL_CALL` event.

Framework-specific context from each call is stored in `meta.crewai.*`:

| Field                     | Description                               |
| ------------------------- | ----------------------------------------- |
| `meta.crewai.executor_id` | Identity of the executor running the call |
| `meta.crewai.iterations`  | Iteration count at the time of the call   |
| `meta.crewai.duration_ms` | Elapsed time in milliseconds for the call |
| `meta.agent_role`         | The role of the agent making the call     |
| `meta.task_desc`          | Description of the task being executed    |

## Installation

Install AgentDbg with the CrewAI extra:

```bash theme={null}
pip install "agentdbg[crewai]"
```

This installs `crewai[tools]` alongside AgentDbg. If you import the integration without `crewai` present, you get a clear `ImportError` with install instructions.

## Setting up the adapter

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    pip install "agentdbg[crewai]"
    ```
  </Step>

  <Step title="Import the integration module">
    Importing `agentdbg.integrations.crewai` registers the execution hooks automatically. Import it once, anywhere before your crew or flow runs:

    ```python theme={null}
    import agentdbg
    from agentdbg.integrations import crewai as adbg_crewai  # registers hooks
    ```
  </Step>

  <Step title="Wrap your entrypoint with @trace">
    The adapter only records events while an active AgentDbg run is open. Wrap the function that calls `crew.kickoff()` or `flow.kickoff()`:

    ```python theme={null}
    @agentdbg.trace
    def run_crew():
        result = my_crew.kickoff()
        return result
    ```
  </Step>

  <Step title="Run your crew or flow">
    Call your traced function normally:

    ```python theme={null}
    run_crew()
    ```

    Then open the timeline:

    ```bash theme={null}
    agentdbg view
    ```
  </Step>
</Steps>

## Full example

```python theme={null}
import agentdbg
from agentdbg.integrations import crewai as adbg_crewai  # registers hooks


@agentdbg.trace(name="my crewai run")
def run_crew():
    # Your crew.kickoff() or flow.kickoff() call goes here.
    result = my_crew.kickoff()
    return result


if __name__ == "__main__":
    run_crew()
    print("Run complete. View with: agentdbg view")
```

## Hook ordering caveat

CrewAI runs execution hooks in registration order. If another `before_llm_call` or `before_tool_call` hook registered before AgentDbg's returns `False` and blocks execution, the AgentDbg hook may not run for that specific call—and that call will not appear in the trace.

<Warning>
  If you register your own before-hooks on CrewAI, make sure they do not return `False` unless you intentionally want to block execution. Returning `False` from a before-hook prevents all subsequent hooks for that call from running.
</Warning>

## What's coming

The following adapter is planned and not yet available:

* **Agno** — adapter for Agno-based agents.

<Note>
  The adapter requires an active AgentDbg run. Wrap your entrypoint with `@trace` or `traced_run(...)`.
</Note>