> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CrewAI framework integration

> Connect CrewAI to Toqan Router's AI Gateway for complete observability, built-in reliability, and access to 500+ LLMs across 30+ providers.

> [card] [AI Gateway](#ai-gateway)
>
> Route your LLM calls through the AI Gateway with a single base URL change. Zero vendor lock-in: always run on the best model at the lowest cost for your use case.

> [card] [Observability](#observability)
>
> Instrument your code with OpenTelemetry to capture traces, logs, and metrics for every LLM call, agent step, and tool use.

## AI Gateway

### Overview

CrewAI is a framework for orchestrating multi-agent teams with role-based agents, hierarchical task management, and collaborative AI workflows. By connecting CrewAI to Toqan Router's AI Gateway, you get access to 500+ models for your agent crews with a single configuration change.

### Key Benefits

Toqan Router's AI Gateway enhances your CrewAI applications with:

> [card] Complete Observability
>
> Track every agent task, tool use, and crew interaction with detailed traces

> [card] Built-in Reliability
>
> Automatic fallbacks, retries, and load balancing for production resilience

> [card] Cost Optimization
>
> Real-time cost tracking and spend management across all your AI operations

> [card] Multi-Provider Access
>
> Access 500+ LLMs and 30+ providers through a single, unified integration

### Prerequisites

Before integrating CrewAI with Toqan Router, ensure you have:

* A Toqan Router account and API Key
* Python 3.10 to 3.12

> [!NOTE]
>
> To setup your API key, see API keys & Endpoints.

> [!WARNING]
>
> **Python 3.13 and 3.14 are not yet supported.** CrewAI's `chromadb` dependency uses Pydantic v1, which breaks at import time on Python 3.13+. Use Python 3.10 to 3.12.

### Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install crewai
```

### Configuration

Configure CrewAI to use Toqan Router's AI Gateway via the `LLM` class with a custom `base_url`:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from crewai import LLM
import os

llm = LLM(
    model="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)
```

> **base\_url**: `https://router.toqan.ai/eu/v3/router`

### Basic Agent Example

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from crewai import Agent, Task, Crew, LLM
import os

llm = LLM(
    model="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

researcher = Agent(
    role="Research Analyst",
    goal="Provide accurate and concise information on topics",
    backstory="Expert analyst with broad knowledge across many domains.",
    llm=llm,
)

task = Task(
    description="In two sentences, explain what machine learning is.",
    agent=researcher,
    expected_output="A concise two-sentence explanation of machine learning.",
)

crew = Crew(agents=[researcher], tasks=[task], tracing=False)
result = crew.kickoff()
print(result)
```

### Multi-Agent Crew

Orchestrate multiple agents with specialized roles:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from crewai import Agent, Task, Crew, LLM
import os

llm = LLM(
    model="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

researcher = Agent(
    role="Research Analyst",
    goal="Research topics and gather key facts",
    backstory="Expert at finding and summarizing information.",
    llm=llm,
)

writer = Agent(
    role="Content Writer",
    goal="Write clear, engaging content",
    backstory="Skilled at turning research into readable content.",
    llm=llm,
)

research_task = Task(
    description="Research the key benefits of renewable energy in 3 bullet points.",
    agent=researcher,
    expected_output="3 bullet points about renewable energy benefits.",
)

write_task = Task(
    description="Write a one-paragraph summary based on the research.",
    agent=writer,
    expected_output="A single paragraph summarizing renewable energy benefits.",
    context=[research_task],
)

crew = Crew(agents=[researcher, writer], tasks=[research_task, write_task], tracing=False)
result = crew.kickoff()
print(result)
```

### Model Selection

With **Toqan Router**, you can use any supported model from 30+ providers:

> [!NOTE]
>
> Always prefix model IDs with `openai/` when using **CrewAI** with the **AI Gateway**. Without it, **CrewAI** may route the request through a matching native provider client (notably its built-in Google client) that ignores `base_url`, producing misleading errors like "API key not valid". The `openai/` prefix forces the OpenAI-compatible code path, which respects `base_url` for every provider.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from crewai import LLM
import os

# Use Claude
claude_llm = LLM(
    model="openai/anthropic/claude-sonnet-5",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

# Use Gemini
gemini_llm = LLM(
    model="openai/google/gemini-2.5-flash",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

# Use Groq
groq_llm = LLM(
    model="openai/groq/qwen/qwen3.8-27b",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)
```

## Observability

### Getting Started

CrewAI enables powerful multi-agent coordination for complex AI workflows. Tracing CrewAI with Toqan Router provides comprehensive insights into agent interactions, task execution, tool usage, and crew performance to optimize your multi-agent systems.

### Prerequisites

Before you begin, ensure you have:

* A Toqan Router account and API Key
* CrewAI installed in your project
* Python 3.10 to 3.12
* OpenAI API key (or other LLM provider credentials)

> [!WARNING]
>
> **Python 3.13 and 3.14 are not yet supported.** CrewAI's `chromadb` dependency uses Pydantic v1, which breaks at import time on Python 3.13+. Use Python 3.10 to 3.12.

### Install Dependencies

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# OpenTelemetry, crewai, openinference
pip install crewai openinference-instrumentation-crewai openinference-instrumentation-openai
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

# LLM providers
pip install openai anthropic

# Optional: Advanced tools and integrations
pip install crewai-tools
```

### Configure Toqan Router

Set up your environment variables to connect to Toqan Router's OpenTelemetry collector:

**Unix/Linux/macOS:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=crewai-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
```

**Windows (PowerShell):**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <TOQAN_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=crewai-app,service.version=1.0.0"
$env:OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
```

**Using .env file:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_EXPORTER_OTLP_ENDPOINT=https://router.toqan.ai/eu/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <TOQAN_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=crewai-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
```

### Integrations Example

> [!NOTE]
>
> We'll be using OpenInference as TracerProvider with CrewAI

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openinference.instrumentation.crewai import CrewAIInstrumentor
from openinference.instrumentation.openai import OpenAIInstrumentor
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from crewai import Agent, Task, Crew

# Initialize OpenTelemetry
tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
    headers={"Authorization": "Bearer <TOQAN_API_KEY>"}
)))
trace.set_tracer_provider(tracer_provider)

# Instrument CrewAI
CrewAIInstrumentor().instrument(tracer_provider=tracer_provider)
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

# Your CrewAI code is automatically traced
researcher = Agent(
    role='Market Research Analyst',
    goal='Gather comprehensive market data and trends',
    backstory='Expert in analyzing market dynamics and consumer behavior'
)

task = Task(
    description='Research the latest trends in AI and machine learning',
    agent=researcher,
    expected_output='Comprehensive report on AI and ML trends with key insights and recommendations'
)

crew = Crew(agents=[researcher], tasks=[task], tracing=False)
result = crew.kickoff()
```

### View Traces

[Traces](/docs/ai-studio/observability/traces.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.