CrewAI (tracing) | Respan Docs

CrewAI is a framework for orchestrating role-playing autonomous AI agents. Respan’s first-party respan-instrumentation-crewai listener subscribes to CrewAI’s official lifecycle events and emits the canonical workflow, task, agent, tool, and chat span hierarchy directly. Chat spans include the model, provider, prompt, completion, and provider-reported token usage.

Complete first-party tracing requires: respan-instrumentation-crewai 0.2.0 or later and crewai 1.10.1 or later. Earlier 0.1.x instrumentation releases can export workflow structure without a chat child span or token usage.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Use Respan Gateway

See CrewAI gateway setup to route this integration through the Respan gateway.

Example projects

Python examples

Setup

Install packages

$ pip install respan-ai "respan-instrumentation-crewai>=0.2.0" "crewai>=1.10.1"

Set environment variables

$ export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

OPENAI_API_KEY is used for LLM requests. RESPAN_API_KEY is used to export traces to Respan.

Initialize and run

Initialize Respan before importing CrewAI so the listener is active before CrewAI emits lifecycle events.

1 from respan import Respan
2 from respan_instrumentation_crewai import CrewAIInstrumentor
3 
4 respan = Respan(instrumentations=[CrewAIInstrumentor()])
5 
6 from crewai import Agent, Crew, Task
7 
8 researcher = Agent(
9     role="Researcher",
10     goal="Research and summarize the latest AI trends",
11     backstory="You are a senior AI researcher with years of experience.",
12 )
13 
14 writer = Agent(
15     role="Writer",
16     goal="Write a concise report based on the research",
17     backstory="You are a technical writer who excels at clear communication.",
18 )
19 
20 research_task = Task(
21     description="Research the latest trends in AI agent frameworks.",
22     expected_output="A summary of key trends and developments.",
23     agent=researcher,
24 )
25 
26 write_task = Task(
27     description="Write a brief report based on the research findings.",
28     expected_output="A well-structured report in markdown format.",
29     agent=writer,
30 )
31 
32 crew = Crew(
33     agents=[researcher, writer],
34     tasks=[research_task, write_task],
35 )
36 
37 result = crew.kickoff()
38 print(result)

View your trace

Open the Traces page to see your CrewAI workflow with agent spans, task execution, tool usage, and LLM calls with provider-reported token usage.

The coordinated backend release includes CrewAI LLM spans classified as chat in llm_call_count. Historical materialized aggregate rows are not backfilled, so traces aggregated before that release can retain their previous summary count; the LLM child span and its model, prompt, completion, and token fields remain the source of truth.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate, such as `CrewAIInstrumentor()`.
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag (e.g. `"production"`).

CrewAIInstrumentor() takes no configuration. Activation and deactivation are idempotent, and the listener uses CrewAI’s official event bus to emit canonical spans directly.

LLM usage and cost

On the supported baseline, CrewAI tracing records the model, prompt, completion, and provider-reported prompt, completion, and total token counts. The instrumentation does not emit a direct cost. Respan can derive cost when the model is in its pricing catalog; custom or unknown models can show zero cost until custom pricing is configured.

Attributes

In Respan()

Set defaults at initialization. These apply to all spans.

1 from respan import Respan
2 from respan_instrumentation_crewai import CrewAIInstrumentor
3 
4 respan = Respan(
5     instrumentations=[CrewAIInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "crew-api", "version": "1.0.0"},
8 )

With propagate_attributes

Override per-request using a context scope.

1 from respan import Respan, propagate_attributes
2 from respan_instrumentation_crewai import CrewAIInstrumentor
3 
4 respan = Respan(instrumentations=[CrewAIInstrumentor()])
5 
6 from crewai import Agent, Crew, Task
7 
8 def handle_request(user_id: str, topic: str):
9     with propagate_attributes(
10         customer_identifier=user_id,
11         thread_identifier="conv_abc_123",
12         metadata={"plan": "pro"},
13     ):
14         researcher = Agent(
15             role="Researcher",
16             goal=f"Research {topic}",
17             backstory="Expert researcher.",
18         )
19         task = Task(
20             description=f"Research {topic}",
21             expected_output="Summary",
22             agent=researcher,
23         )
24         crew = Crew(agents=[researcher], tasks=[task])
25         print(crew.kickoff())

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.

Decorators (optional)

Decorators are not required. On the supported baseline, each CrewAI kickoff automatically emits a workflow with task, agent, tool, and chat descendants. Use @workflow and @task to add structure when you want to group related crews into a named workflow with nested tasks.

1 from respan import Respan, workflow, task
2 from respan_instrumentation_crewai import CrewAIInstrumentor
3 
4 respan = Respan(instrumentations=[CrewAIInstrumentor()])
5 
6 from crewai import Agent, Crew, Task
7 
8 @task(name="run_research_crew")
9 def run_research_crew(topic: str) -> str:
10     researcher = Agent(
11         role="Researcher",
12         goal=f"Research {topic}",
13         backstory="Expert.",
14     )
15     research_task = Task(
16         description=f"Research {topic}",
17         expected_output="Findings.",
18         agent=researcher,
19     )
20     crew = Crew(agents=[researcher], tasks=[research_task])
21     return str(crew.kickoff())
22 
23 @workflow(name="content_pipeline")
24 def pipeline(topic: str):
25     findings = run_research_crew(topic)
26     print(findings)
27 
28 pipeline("AI agent frameworks")

Examples

Tool calls

Tool calls are automatically captured as spans with inputs, outputs, and timing.

1 from respan import Respan
2 from respan_instrumentation_crewai import CrewAIInstrumentor
3 
4 respan = Respan(instrumentations=[CrewAIInstrumentor()])
5 
6 from crewai import Agent, Crew, Task
7 from crewai.tools import tool
8 
9 @tool
10 def get_weather(city: str) -> str:
11     """Get the current weather for a city."""
12     return f"Sunny, 22C in {city}"
13 
14 researcher = Agent(
15     role="City Researcher",
16     goal="Gather weather data for a city",
17     backstory="You collect city data using available tools.",
18     tools=[get_weather],
19 )
20 
21 task = Task(
22     description="Research the weather in Paris.",
23     expected_output="Weather data for Paris.",
24     agent=researcher,
25 )
26 
27 crew = Crew(agents=[researcher], tasks=[task])
28 print(crew.kickoff())