CrewAI

Available for: Python and TypeScript.

Python
TypeScript

Installation

pip install zespan crewai

Usage

Wrap your Crew instance with wrap_crew before calling kickoff. Both sync and async kickoff are supported.

from crewai import Agent, Task, Crew
from zespan.integrations.crewai_handler import wrap_crew
import zespan

zespan.init(api_key="zsp_your_api_key_here")

researcher = Agent(
    role="Researcher",
    goal="Research the topic thoroughly",
    backstory="Expert researcher with broad knowledge",
    llm="gpt-4o",
)

task = Task(
    description="Research the impact of LLMs on software development",
    expected_output="A detailed summary",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
crew = wrap_crew(crew)

result = crew.kickoff(inputs={"topic": "LLMs in software development"})
print(result.raw)

Async usage

import asyncio

crew = wrap_crew(crew)
result = asyncio.run(crew.kickoff_async(inputs={"topic": "AI agents"}))

With guardrails

Pass guardrails=True to run pre/post content checks on crew inputs and outputs.

from zespan.integrations.crewai_handler import wrap_crew
from zespan import GuardrailBlockedError

crew = wrap_crew(crew, guardrails=True)

try:
    result = crew.kickoff(inputs={"topic": "..."})
except GuardrailBlockedError as e:
    print(f"Blocked at {e.phase}:", e.results)

For fine-grained control:

crew = wrap_crew(crew, guardrails={
    "pre": True,
    "post": True,
    "fail_closed": False,
})

Agent steps

The crew’s span records zespan.agent.step (how many tasks the crew ran), zespan.agent.stop_reason (done, or error when the run failed) and zespan.agent.route_candidates (how many agents the crew has). With the zespan-crewai event listener, each agent span carries its run number in the crew (zespan.agent.step), the agent’s max_iter as zespan.agent.max_steps, and a stop reason of done or error. See Agent steps.

CrewAI is a Python framework. For Node.js services that receive HTTP calls from a Python CrewAI agent, use context extraction to continue the trace across the boundary.

import { extractAgentContext, zespan } from "@zespan/sdk";
import { type NextRequest } from "next/server";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

export async function POST(req: NextRequest) {
  // Restore trace context injected by the upstream CrewAI agent
  extractAgentContext(Object.fromEntries(req.headers));

  // All LLM calls made here now link back to the CrewAI trace
  const result = await processRequest(req);
  return Response.json(result);
}

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

Installation

Usage

Async usage

With guardrails

Agent steps

​Installation

​Usage

​Async usage

​With guardrails

​Agent steps

Installation

Usage

Async usage

With guardrails

Agent steps