Docs › CrewAI

Integration Guide

CrewAI Observability with Nexus

Monitor your CrewAI multi-agent crews with Nexus. Track each agent's performance, task execution, and inter-agent handoffs — all in one dashboard.

Why use Nexus with CrewAI?

Step 1 — Install the SDK

pip install keylightdigital-nexus crewai

Step 2 — Create an API key

Go to /dashboard/keys and create a new API key. Add it as an environment variable: NEXUS_API_KEY.

Step 3 — Instrument your crew

Pattern: one trace per crew run, one span per agent task

from nexus_client import NexusClient
from crewai import Agent, Task, Crew, Process
import os

nexus = NexusClient(
    api_key=os.environ["NEXUS_API_KEY"],
    agent_id="research-crew",
)

# Define your CrewAI agents
researcher = Agent(
    role="Senior Research Analyst",
    goal="Find accurate and relevant information",
    backstory="Expert researcher with access to web tools",
    verbose=True,
)

writer = Agent(
    role="Content Writer",
    goal="Write compelling, well-structured content",
    backstory="Professional writer specializing in technical content",
    verbose=True,
)

def run_crew(topic: str) -> str:
    # Start a single trace for the entire crew run
    trace = nexus.start_trace(
        name=f"Crew run: {topic[:50]}",
        metadata={"topic": topic, "crew_size": 2},
    )

    try:
        # Track research phase
        research_span = trace.add_span(
            name="researcher-task",
            input={"topic": topic},
        )

        research_task = Task(
            description=f"Research the topic: {topic}",
            expected_output="A detailed research summary with key findings",
            agent=researcher,
        )

        write_task = Task(
            description="Write a blog post based on the research",
            expected_output="A 500-word blog post",
            agent=writer,
            context=[research_task],
        )

        crew = Crew(
            agents=[researcher, writer],
            tasks=[research_task, write_task],
            process=Process.sequential,
            verbose=True,
        )

        result = crew.kickoff()

        # Update the research span with the result
        trace.add_span(
            name="writer-task",
            input={"research": "research summary"},
            output={"post": str(result)[:500]},
        )

        trace.end(status="success")
        return str(result)

    except Exception as e:
        trace.add_span(
            name="crew-error",
            error=str(e),
        )
        trace.end(status="error")
        raise

if __name__ == "__main__":
    result = run_crew("The future of AI agent observability")
    print(result)

Pro tip: Track individual agent metrics

Use a separate Nexus agent_id per CrewAI role (e.g., researcher-agent, writer-agent). This lets you compare performance per role in the Agents dashboard and set per-agent error alerts on Pro plan.

Advanced: track per-agent performance

from nexus_client import NexusClient
import os

# One NexusClient per agent role for per-role metrics
researcher_nexus = NexusClient(api_key=os.environ["NEXUS_API_KEY"], agent_id="crew-researcher")
writer_nexus = NexusClient(api_key=os.environ["NEXUS_API_KEY"], agent_id="crew-writer")

def run_researcher(topic: str) -> str:
    trace = researcher_nexus.start_trace(name=f"Research: {topic[:40]}")
    try:
        # ... research logic ...
        result = "Research findings here"
        trace.end(status="success")
        return result
    except Exception as e:
        trace.end(status="error")
        raise

def run_writer(research: str) -> str:
    trace = writer_nexus.start_trace(name="Write blog post")
    try:
        # ... writing logic ...
        result = "Blog post content here"
        trace.end(status="success")
        return result
    except Exception as e:
        trace.end(status="error")
        raise

With this pattern, the Agents dashboard shows a health card per role. Error alerts (Pro) fire per-agent — so if your writer agent fails, you know immediately.

Step 4 — View crew traces

Run your crew and navigate to /dashboard/traces to see each crew run as a trace. The span waterfall shows each agent's task in sequence.

View demo →

More resources

Start monitoring your CrewAI agents

Free plan: 1,000 traces/month. No credit card needed.

Start free → View demo