crewai-observe 0.1.0

Langfuse tracing integration for CrewAI workflows

CrewAI Observe

A Python package that seamlessly adds Langfuse tracing capabilities to CrewAI workflows without disrupting existing functionality. Monitor your AI agents, track token usage, and gain deep observability into your CrewAI executions.

Features

• Seamless Integration: Drop-in replacement for CrewAI crew execution
• Complete Observability: Track LLM calls, token usage, and agent thoughts
• Environment-Based Toggling: Enable/disable tracing via environment variables
• Production Ready: Comprehensive error handling and validation
• Rich Metadata: Associate traces with sessions, users, and custom metadata
• Multiple Interfaces: Function-based, class-based, and decorator approaches
• Async & Sync Support: Works with both synchronous and asynchronous CrewAI operations
• Graceful Degradation: Continues to work even when Langfuse is unavailable

Installation

# Basic installation
pip install crewai-observe

# With development dependencies
pip install crewai-observe[dev]

Configuration

Set up your environment variables to enable Langfuse tracing:

# Required: Enable Langfuse tracing
export LANGFUSE_ENABLED=1

# Required: Langfuse credentials
export LANGFUSE_SECRET_KEY="your-secret-key"
export LANGFUSE_PUBLIC_KEY="your-public-key"
export LANGFUSE_HOST="https://your-langfuse-instance.com"

# Optional: Advanced configuration
export LANGFUSE_SAMPLE_RATE=0.1        # Sample 10% of traces
export LANGFUSE_FLUSH_INTERVAL=2000    # Flush every 2 seconds

If LANGFUSE_ENABLED is not set to "1", the package will execute CrewAI crews normally without any tracing overhead.

Quick Start

Basic Usage

import asyncio
from crewai import Crew, Agent, Task
from crewai_langfuse import execute_crew_with_tracing

# Create your CrewAI setup as usual
agent = Agent(
    role="Data Analyst",
    goal="Analyze data and provide insights",
    backstory="You are an experienced data analyst..."
)

task = Task(
    description="Analyze the provided dataset",
    agent=agent
)

crew = Crew(agents=[agent], tasks=[task])

# Execute with Langfuse tracing
async def main():
    result = await execute_crew_with_tracing(
        crew=crew,
        inputs={"dataset": "sales_data.csv"},
        span_name="data-analysis-crew",
        session_id="session-123",
        user_id="user-456",
        metadata={
            "workspace_id": "ws-789",
            "analysis_type": "sales_report"
        }
    )
    print(result.raw)

if __name__ == "__main__":
    asyncio.run(main())

Class-Based Approach

from crewai_langfuse import TracedCrew

# Wrap your crew with tracing capabilities
traced_crew = TracedCrew(
    crew=crew,
    default_span_name="my-ai-workflow",
    default_session_id="session-789",
    default_metadata={"version": "2.0", "environment": "production"}
)

# Execute with tracing (async)
result = await traced_crew.kickoff_async(
    inputs={"task": "Generate market analysis"},
    user_id="user-123"
)

Decorator Approach

from crewai_langfuse import traced

@traced(span_name="custom-workflow", metadata={"team": "data-science"})
async def run_analysis_workflow(crew, user_input):
    return await crew.kickoff_async({"input": user_input})

# Usage
result = await run_analysis_workflow(crew, "Analyze customer churn")

Advanced Configuration

Custom Configuration

from crewai_langfuse import LangfuseConfig, execute_crew_with_tracing

# Create custom configuration
config = LangfuseConfig(
    secret_key="your-key",
    public_key="your-public-key",
    host="https://your-instance.com",
    enabled=True,
    sample_rate=0.5,
    flush_interval=1000
)

result = await execute_crew_with_tracing(
    crew=crew,
    inputs={"task": "Custom analysis"},
    config=config
)

Requirements

Core Dependencies

• Python >= 3.8
• crewai >= 0.28.0
• langfuse >= 2.0.0
• openinference-instrumentation-crewai >= 0.1.0
• openinference-instrumentation-litellm >= 0.1.0

Running Examples

# Set up your environment variables
export LANGFUSE_ENABLED=1
export LANGFUSE_SECRET_KEY="your-secret-key"
export LANGFUSE_PUBLIC_KEY="your-public-key"
export LANGFUSE_HOST="https://your-langfuse-instance.com"

# Run examples
python examples/basic_usage.py
python examples/advanced_usage.py

License

This project is licensed under the MIT License

Acknowledgments

• CrewAI for the amazing multi-agent framework
• Langfuse for the powerful LLM observability platform
• OpenInference for instrumentation capabilities

---