Docs/Integrations/Crewai/Sdk

SDK + EventListener

For self-hosted CrewAI, or when you want Python SDK control over agent naming, tags and flush timing, use the ants-platform SDK with its EventListener. The listener subscribes to CrewAI's event bus and turns events into observations.

ℹ

Running CrewAI Enterprise? The Native OTel path needs no code.

Setup

Install the SDK

bash
pip install "ants-platform[crewai]"

Requires Python 3.10 to 3.13 and CrewAI 0.80 or later.

Set environment variables

bash
ANTS_PLATFORM_PUBLIC_KEY=pk-ap-... ANTS_PLATFORM_SECRET_KEY=sk-ap-... ANTS_PLATFORM_HOST=https://<your-ants-host>

Create keys under Project Settings > API Keys in ANTS Platform.

Register the EventListener at module level in crew.py

python
from crewai import Agent, Crew, Process, Task from crewai.project import CrewBase, agent, crew, task from ants_platform import AntsPlatform from ants_platform.crewai import EventListener ants_platform = AntsPlatform(timeout=30) listener = EventListener( public_key=ants_platform._public_key, agent_name="research_crew", agent_display_name="Research & Blog Crew", ) @CrewBase class ResearchCrew(): agents_config = "config/agents.yaml" tasks_config = "config/tasks.yaml" @agent def researcher(self) -> Agent: return Agent(config=self.agents_config["researcher"]) @task def research_task(self) -> Task: return Task(config=self.tasks_config["research_task"]) @crew def crew(self) -> Crew: return Crew(agents=self.agents, tasks=self.tasks, process=Process.sequential)
⚠

Initialise in crew.py, not main.py. CrewAI's deployment runner imports the @CrewBase class directly and never runs main.py.

Flush before exit

In main.py, or wherever you call kickoff():

python
from my_project.crew import ResearchCrew, ants_platform def run(): try: ResearchCrew().crew().kickoff(inputs={"topic": "AI agents"}) finally: ants_platform.flush() if __name__ == "__main__": run()

Configuration

EventListener parameters

ParameterTypeDefaultDescription
public_keystrnonePass ants_platform._public_key. Required when deploying to CrewAI's cloud platform (see below).
agent_namestrthe crew name, else crewStable agent name for the crew in the AI Agent Center. Also the root observation name. Stored in lower case.
agent_display_namestrnoneName shown in the UI. Can change later.
tagsdictnoneKey-value pairs added to every trace as key:value tags, for example {"env": "production"}. They override the automatic tags with the same key.

AntsPlatform client options

ParameterDefaultDescription
public_key / secret_key / hostenv varsAPI credentials and host.
timeout5HTTP timeout in seconds. Use 30 for slower networks.

See the Python SDK for all options.

Deploying to CrewAI's cloud platform

CrewAI's deployment runner skips main.py and imports your @CrewBase class directly. Two rules:

  1. Initialise in crew.py at module level, before the class.
  2. Pass public_key to EventListener. CrewAI's own telemetry creates a second client in the process. Without an explicit public_key, the SDK sees several clients and returns a disabled one.
python
ants_platform = AntsPlatform(timeout=30) listener = EventListener(public_key=ants_platform._public_key, agent_name="my_crew")

Set ANTS_PLATFORM_PUBLIC_KEY, ANTS_PLATFORM_SECRET_KEY and ANTS_PLATFORM_HOST in your CrewAI deployment's environment variables. Push your changes to your Git remote first. crewai deploy push builds from the remote, not your local files.

How events map to observations

CrewAI eventObservation
CrewKickoffStartedEvent / Completed / FailedRoot span for the crew run
AgentExecutionStartedEvent / Completed / ErrorSpan for the agent step, with role and task prompt
LLMCallStartedEvent / Completed / FailedGeneration with model, messages and token usage
ToolUsageStartedEvent / Finished / ErrorTool observation with arguments and output
LLMGuardrailStartedEvent / Completed / FailedGuardrail observation, if your CrewAI version emits it
AgentReasoningStartedEvent / Completed / FailedSpan for agent reasoning, if your CrewAI version emits it

Failed and error events set level ERROR on the observation. Automatic trace tags: framework:crewai, agent:<name>, process_type, crewai_version, num_agents and num_tasks. The listener blocks CrewAI's own telemetry spans so they do not appear as separate traces.

Next

© 2026 ANTS Platform, Inc.Docs v1.0 · Last updated June 2026