Skip to content

crewai.md

Latest commit

 

History

History
285 lines (211 loc) · 7.02 KB

crewai.md

File metadata and controls

285 lines (211 loc) · 7.02 KB

CrewAI Integration Guide

Automatic observability for CrewAI multi-agent systems

Overview

The CrewAI adapter provides automatic tracing for:

  • ✅ Task execution
  • ✅ Agent decisions
  • ✅ Tool usage
  • ✅ Multi-agent coordination
  • ✅ Crew orchestration

Integration time: <5 minutes (just import and go!)

Quick Start

Installation

pip install agent-observability-kit crewai

Basic Usage (Auto-Detection)

from agent_observability import init_tracer
from crewai import Agent, Task, Crew

# 1. Initialize tracer (auto-detects CrewAI)
tracer = init_tracer(agent_id="my-crew")

# 2. Use CrewAI normally - it's automatically traced!
researcher = Agent(
    role="Research Specialist",
    goal="Find information",
    backstory="Expert researcher",
)

task = Task(
    description="Research AI observability",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()  # ← Automatically traced!

# 3. View traces
# python server/app.py
# open http://localhost:5000

That's it! Every task, agent decision, and crew execution is automatically captured.

What Gets Captured

Task Execution

Every Task.execute() creates a span capturing:

{
  "span_type": "workflow_step",
  "framework": "crewai",
  "inputs": {
    "task": "Research AI observability benefits",
    "agent": "Research Specialist"
  },
  "outputs": {
    "result": "Benefits: 1) Debug faster, 2) Track costs..."
  },
  "metadata": {
    "agent_role": "Research Specialist",
    "tools": ["search_web", "read_article"]
  },
  "duration_ms": 2300
}

Crew Orchestration

Every Crew.kickoff() creates a root trace capturing:

{
  "trace_id": "tr_abc123",
  "framework": "crewai",
  "metadata": {
    "agents": ["Research Specialist", "Technical Writer"],
    "tasks": ["Research AI observability", "Write blog post"]
  },
  "spans": [...]
}

Advanced Usage

Manual Adapter Installation

If you want to control when adapters are installed:

from agent_observability import init_tracer
from agent_observability.adapters.crewai import CrewAIAdapter

# Initialize without auto-detection
tracer = init_tracer(agent_id="my-crew", auto_detect_frameworks=False)

# Manually install CrewAI adapter
adapter = CrewAIAdapter(tracer=tracer)
adapter.install()

# Now use CrewAI...

Custom Metadata

Add custom context to your traces:

from agent_observability import trace

with trace("customer_service_flow") as trace_id:
    # Add metadata
    tracer.start_span(
        name="Handle customer request",
        metadata={
            "customer_id": "CUST-123",
            "priority": "high",
            "source": "email"
        }
    )
    
    # Run crew
    result = crew.kickoff()

Filtering Traces

Only trace specific crews:

from agent_observability import init_tracer

# Initialize tracer for production crews only
tracer = init_tracer(agent_id="production-crew")

# Development crew - not traced
dev_crew = Crew(agents=[...], tasks=[...])
# (To trace dev crew, create separate tracer)

Visualization

Execution Graph

CrewAI traces appear in the visual debugger with framework badges:

┌─────────────────────────────────────────────────────┐
│ Crew: Content Generation Pipeline                  │
├─────────────────────────────────────────────────────┤
│                                                     │
│   [Start]                                           │
│      ↓                                              │
│   ┌─────────────┐                                  │
│   │ 🟩 CrewAI   │ Research Task                   │
│   │ Researcher  │ 2.3s | $0.008                   │
│   └─────────────┘                                  │
│      ↓                                              │
│   ┌─────────────┐                                  │
│   │ 🟩 CrewAI   │ Writing Task                    │
│   │ Writer      │ 1.8s | $0.012                   │
│   └─────────────┘                                  │
│      ↓                                              │
│   [Complete]                                        │
│                                                     │
│ Legend: 🟩 CrewAI                                  │
└─────────────────────────────────────────────────────┘

CrewAI-Specific Details

Click any span to see CrewAI-specific metadata:

  • Agent Role: "Research Specialist"
  • Goal: "Find accurate information"
  • Backstory: "Expert researcher..."
  • Tools: [search_web, read_article]
  • Delegation: Enabled/Disabled

Performance

Overhead: <1% latency impact

The adapter uses lightweight monkey-patching and async data collection:

# Benchmark (1000 task executions)
# Without tracing: 23.4s
# With tracing:    23.6s
# Overhead:        0.8%

Troubleshooting

"CrewAI is not installed" Error

Problem: Adapter tries to load but CrewAI not installed

Solution:

pip install crewai

Traces Not Appearing

Problem: Traces not showing in UI

Solution:

  1. Check tracer is initialized:

    tracer = init_tracer(agent_id="my-crew")
print(tracer.get_installed_frameworks())  # Should include 'crewai'

  2. Check trace storage:

    ls ~/.openclaw/traces/
# Should see trace files

  3. Restart the server:

    python server/app.py

Missing Task Details

Problem: Task spans don't show agent info

Solution: Ensure tasks are assigned to agents:

task = Task(
    description="...",
    agent=researcher,  # ← Required for agent metadata
)

Migration from LangSmith

If you're using LangSmith with CrewAI custom callbacks:

Before (LangSmith):

from langsmith import LangChainCallbackHandler

# Doesn't work with CrewAI! ❌
handler = LangChainCallbackHandler()
crew.kickoff()  # Not traced

After (Agent Observability Kit):

from agent_observability import init_tracer

tracer = init_tracer(agent_id="my-crew")
crew.kickoff()  # ✅ Automatically traced!

Benefits:

  • ✅ No callback boilerplate
  • ✅ Automatic detection
  • ✅ Framework-specific metadata
  • ✅ Works with multi-framework systems

Examples

See examples/crewai_example.py for a complete working example.

Support

Issues? Open a GitHub issue: github.com/reflectt/agent-observability-kit

Questions? Join our Discord: discord.gg/openclaw