crewai-observe 0.1.0
Langfuse tracing integration for CrewAI workflows
License: MIT
Requires Python: <=3.13,>=3.10
Keywords: crewai, langfuse, tracing, observability, llm, ai, monitoring

# 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

```bash
# Basic installation
pip install crewai-observe

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

## Configuration

Set up your environment variables to enable Langfuse tracing:

```bash
# 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

```python
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

```python
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

```python
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

```python
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

```bash
# 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](https://github.com/joaomdmoura/crewAI) for the amazing multi-agent framework
- [Langfuse](https://github.com/langfuse/langfuse) for the powerful LLM observability platform
- [OpenInference](https://github.com/Arize-ai/openinference) for instrumentation capabilities

---