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

# Integração com o framework CrewAI

> Conecte o CrewAI ao AI Gateway do Toqan Router para ter observabilidade completa, confiabilidade integrada e acesso a mais de 500 LLMs de mais de 30 provedores.

> [card] [AI Gateway](#ai-gateway)
>
> Roteie suas chamadas de LLM pelo AI Gateway alterando apenas a base URL. Sem dependência de fornecedor: use sempre o melhor modelo pelo menor custo para o seu caso de uso.

> [card] [Observabilidade](#observability)
>
> Instrumente seu código com OpenTelemetry para capturar traces, logs e métricas de cada chamada de LLM, etapa de agente e uso de ferramenta.

## AI Gateway

### Visão geral

O CrewAI é um framework para orquestrar equipes de múltiplos agentes, com agentes baseados em papéis, gerenciamento hierárquico de tarefas e fluxos de trabalho de IA colaborativos. Ao conectar o CrewAI ao AI Gateway do Toqan Router, você tem acesso a mais de 500 modelos para suas equipes de agentes com uma única alteração de configuração.

### Principais benefícios

O AI Gateway do Toqan Router aprimora suas aplicações CrewAI com:

> [card] Observabilidade completa
>
> Acompanhe cada tarefa de agente, uso de ferramenta e interação da equipe com traces detalhados

> [card] Confiabilidade integrada
>
> Fallbacks automáticos, novas tentativas e balanceamento de carga para resiliência em produção

> [card] Otimização de custos
>
> Acompanhamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

> [card] Acesso a múltiplos provedores
>
> Acesse mais de 500 LLMs e mais de 30 provedores por meio de uma integração única e unificada

### Pré-requisitos

Antes de integrar o CrewAI ao Toqan Router, certifique-se de ter:

* Uma conta no Toqan Router e uma chave de API
* Python 3.10 a 3.12

> [!NOTE]
>
> Para configurar sua chave de API, consulte Chaves de API e endpoints.

> [!WARNING]
>
> **Python 3.13 e 3.14 ainda não são compatíveis.** A dependência `chromadb` do CrewAI usa Pydantic v1, que falha no momento da importação no Python 3.13+. Use Python 3.10 a 3.12.

### Instalação

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

### Configuração

Configure o CrewAI para usar o AI Gateway do Toqan Router por meio da classe `LLM` com uma `base_url` personalizada:

```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`

### Exemplo básico de agente

```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)
```

### Equipe com múltiplos agentes

Orquestre vários agentes com papéis especializados:

```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)
```

### Seleção de modelo

Com o **Toqan Router**, você pode usar qualquer modelo compatível de mais de 30 provedores:

> [!NOTE]
>
> Sempre adicione o prefixo `openai/` aos IDs de modelo ao usar o **CrewAI** com o **AI Gateway**. Sem ele, o **CrewAI** pode rotear a solicitação por um cliente nativo de provedor correspondente (principalmente seu cliente Google integrado) que ignora a `base_url`, gerando erros enganosos como "API key not valid". O prefixo `openai/` força o caminho de código compatível com OpenAI, que respeita a `base_url` para todos os provedores.

```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",
)
```

## Observabilidade

### Primeiros passos

O CrewAI permite uma coordenação poderosa entre múltiplos agentes para fluxos de trabalho de IA complexos. Rastrear o CrewAI com o Toqan Router oferece insights abrangentes sobre interações entre agentes, execução de tarefas, uso de ferramentas e desempenho da equipe, para que você otimize seus sistemas multiagente.

### Pré-requisitos

Antes de começar, certifique-se de ter:

* Uma conta no Toqan Router e uma chave de API
* O CrewAI instalado no seu projeto
* Python 3.10 a 3.12
* Chave de API da OpenAI (ou credenciais de outro provedor de LLM)

> [!WARNING]
>
> **Python 3.13 e 3.14 ainda não são compatíveis.** A dependência `chromadb` do CrewAI usa Pydantic v1, que falha no momento da importação no Python 3.13+. Use Python 3.10 a 3.12.

### Instalar dependências

```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
```

### Configurar o Toqan Router

Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router:

**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>"
```

**Usando um arquivo .env:**

```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>
```

### Exemplo de integração

> [!NOTE]
>
> Usaremos o OpenInference como TracerProvider com o 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()
```

### Visualizar traces

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


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