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

# Integração multiagente com o AutoGen

> Conecte o Microsoft AutoGen ao AI Gateway para fluxos de trabalho multiagente. Crie sistemas de IA colaborativos com roteamento, cache e observabilidade aprimorados.

> [card] [AI Gateway](#ai-gateway)
>
> Roteie suas chamadas de LLM pelo AI Gateway alterando apenas a URL base. Sem dependência de fornecedor: rode sempre no melhor modelo, com o 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 Microsoft AutoGen é um framework para criar sistemas de IA conversacional multiagente, com resolução colaborativa de problemas por meio de interações automatizadas entre agentes. Ao conectar o AutoGen ao AI Gateway do Toqan Router, você tem acesso a mais de 500 modelos para seus fluxos de trabalho multiagente com uma única alteração de configuração.

### Principais benefícios

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

> [card] Observabilidade completa
>
> Acompanhe cada conversa de agente, uso de ferramenta e interação multiagente

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

> [card] Otimização de custos
>
> Rastreamento 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 única integração unificada

### Pré-requisitos

Antes de integrar o AutoGen ao Toqan Router, verifique se você tem:

* Uma conta do Toqan Router e uma chave de API
* Python 3.10 ou superior

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

### Instalação

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install "autogen-agentchat" "autogen-ext[openai]"
```

### Configuração

Configure o AutoGen para usar o AI Gateway do Toqan Router via `OpenAIChatCompletionClient` com uma `base_url` personalizada:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(
    model="openai/gpt-5.6-sol",
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
    model_info={
        "vision": False,
        "function_calling": True,
        "json_output": True,
        "family": "unknown",
        "structured_output": True,
    },
)
```

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

> [!NOTE]
>
> Defina `model_info` para modelos que o AutoGen não reconhece, incluindo IDs de modelo do **AI Gateway** com prefixo de provedor. Ele descreve os recursos do modelo.
>
> O AutoGen pode emitir o aviso `Resolved model mismatch` quando o nome do modelo retornado em uma resposta difere do modelo solicitado ou do mapeamento de modelos do AutoGen. O aviso, por si só, não significa que a requisição falhou, e `model_info` não o suprime. Compare o modelo retornado com o modelo pretendido e continue usando um ID de modelo suportado pelo **AI Gateway**.

### Exemplo básico de agente

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def main():
    model_client = OpenAIChatCompletionClient(
        model="openai/gpt-5.6-sol",
        base_url="https://router.toqan.ai/eu/v3/router",
        api_key=os.getenv("TOQAN_API_KEY"),
        model_info={
            "vision": False,
            "function_calling": True,
            "json_output": True,
            "family": "unknown",
            "structured_output": True,
        },
    )

    agent = AssistantAgent(
        name="assistant",
        model_client=model_client,
        system_message="You are a helpful assistant.",
    )

    result = await agent.run(task="What is quantum computing?")
    print(result.messages[-1].content)
    await model_client.close()

asyncio.run(main())
```

### Equipe multiagente

Orquestre vários agentes especializados com `RoundRobinGroupChat`:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import MaxMessageTermination
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def main():
    model_client = OpenAIChatCompletionClient(
        model="openai/gpt-5.6-sol",
        base_url="https://router.toqan.ai/eu/v3/router",
        api_key=os.getenv("TOQAN_API_KEY"),
        model_info={
            "vision": False,
            "function_calling": True,
            "json_output": True,
            "family": "unknown",
            "structured_output": True,
        },
    )

    researcher = AssistantAgent(
        name="researcher",
        model_client=model_client,
        system_message="You research topics and provide key facts.",
    )

    writer = AssistantAgent(
        name="writer",
        model_client=model_client,
        system_message="You write clear summaries based on research.",
    )

    team = RoundRobinGroupChat(
        participants=[researcher, writer],
        termination_condition=MaxMessageTermination(max_messages=2),
    )

    result = await team.run(task="Research and summarize what LLMs are.")
    print(result.messages[-1].content)
    await model_client.close()

asyncio.run(main())
```

### Seleção de modelo

Com o Toqan Router, você pode usar qualquer modelo suportado de mais de 30 provedores:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_info = {
    "vision": False,
    "function_calling": True,
    "json_output": True,
    "family": "unknown",
    "structured_output": True,
}

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

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

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

## Observabilidade

### Primeiros passos

O Microsoft AutoGen possibilita conversas multiagente sofisticadas e sistemas de IA colaborativos. Fazer o tracing do AutoGen com o Toqan Router oferece insights profundos sobre interações entre agentes, fluxos de conversa, uso de ferramentas e padrões de coordenação multiagente, para otimizar suas aplicações de IA conversacional.

### Pré-requisitos

Antes de começar, verifique se você tem:

* Uma conta do Toqan Router e uma chave de API
* Python 3.8+
* Microsoft AutoGen instalado no seu projeto
* Chave de API da OpenAI (ou credenciais de outro provedor de LLM)

### Instalar dependências

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Core AutoGen and OpenTelemetry packages
pip install pyautogen opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-openai

# LLM providers
pip install openai
```

### 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=autogen-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=autogen-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=autogen-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
```

### Integração

O AutoGen tem suporte integrado ao OpenTelemetry. Configure o tracer provider e passe-o para o runtime do AutoGen.

> Configure o tracing do OpenTelemetry na sua aplicação:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import autogen
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.instrumentation.openai import OpenAIInstrumentor
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Configure tracer provider
tracer_provider = TracerProvider(
    resource=Resource({"service.name": "autogen-app"})
)

# Set up OTLP exporter
otlp_exporter = OTLPSpanExporter()

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
trace.set_tracer_provider(tracer_provider)

# Instrument OpenAI calls for automatic tracing
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

config_list = [{"model": "gpt-5.6-sol", "api_key": os.getenv("OPENAI_API_KEY")}]

# Create agents
assistant = autogen.AssistantAgent(
    name="assistant",
    llm_config={"config_list": config_list, "temperature": 0}
)

user_proxy = autogen.UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    max_consecutive_auto_reply=3,
    code_execution_config={"work_dir": "coding", "use_docker": False}
)

print("Starting AutoGen conversation (this will be traced)...")

# Start conversation (automatically traced)
user_proxy.initiate_chat(
    assistant,
    message="Write a Python function to calculate fibonacci numbers up to n=10"
)
```

> [!TIP]
>
> Todas as conversas e interações dos agentes AutoGen serão instrumentadas e exportadas para o Toqan Router pelo exportador OTLP. Para mais detalhes, consulte [Traces](/docs/pt-BR/ai-studio/observability/traces.md).

### Exemplos avançados

**Chat em grupo multiagente**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import autogen
import os
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.instrumentation.openai import OpenAIInstrumentor
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Configure tracer provider
tracer_provider = TracerProvider(
  resource=Resource({"service.name": "autogen-app"})
)

# Set up OTLP exporter
otlp_exporter = OTLPSpanExporter()

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
trace.set_tracer_provider(tracer_provider)

# Instrument OpenAI calls for automatic tracing
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

# Setup done as shown in Integration section above

config_list = [{"model": "gpt-5.6-sol", "api_key": os.getenv("OPENAI_API_KEY")}]

# Create specialized agents
coder = autogen.AssistantAgent(
    name="coder",
    system_message="You are an expert Python developer.",
    llm_config={"config_list": config_list}
)

reviewer = autogen.AssistantAgent(
    name="code_reviewer",
    system_message="You review code for quality and best practices.",
    llm_config={"config_list": config_list}
)

user_proxy = autogen.UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    max_consecutive_auto_reply=5,
    code_execution_config={"work_dir": "workspace"}
)

# Create group chat
groupchat = autogen.GroupChat(
    agents=[user_proxy, coder, reviewer],
    messages=[],
    max_round=10
)

manager = autogen.GroupChatManager(
    groupchat=groupchat,
    llm_config={"config_list": config_list}
)

# Start group conversation (automatically traced)
user_proxy.initiate_chat(
    manager,
    message="Create a REST API for user management with FastAPI"
)
```

**Agente com ferramentas personalizadas**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import autogen
import os
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.instrumentation.openai import OpenAIInstrumentor
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Configure tracer provider
tracer_provider = TracerProvider(
  resource=Resource({"service.name": "autogen-app"})
)

# Set up OTLP exporter
otlp_exporter = OTLPSpanExporter()

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
trace.set_tracer_provider(tracer_provider)

# Instrument OpenAI calls for automatic tracing
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

config_list = [{"model": "gpt-5.6-sol", "api_key": os.getenv("OPENAI_API_KEY")}]

# Define custom tools/functions
def get_weather(location: str) -> str:
    """Get current weather for a location."""
    return f"Weather in {location}: Sunny, 75°F"

def calculate_distance(city1: str, city2: str) -> str:
    """Calculate distance between two cities."""
    return f"Distance between {city1} and {city2}: 500 km"

# Create agent with function calling
travel_planner = autogen.AssistantAgent(
    name="travel_planner",
    system_message="You help plan travel itineraries.",
    llm_config={
        "config_list": config_list,
        "functions": [
            {
                "name": "get_weather",
                "description": "Get current weather for a location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string"}
                    },
                    "required": ["location"]
                }
            },
            {
                "name": "calculate_distance",
                "description": "Calculate distance between cities",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city1": {"type": "string"},
                        "city2": {"type": "string"}
                    },
                    "required": ["city1", "city2"]
                }
            }
        ]
    }
)

user_proxy = autogen.UserProxyAgent(
    name="user",
    human_input_mode="NEVER",
    max_consecutive_auto_reply=5,
    function_map={
        "get_weather": get_weather,
        "calculate_distance": calculate_distance
    },
    code_execution_config=False
)

# Use agent with tools (automatically traced)
user_proxy.initiate_chat(
    travel_planner,
    message="Plan a 3-day trip from New York to London"
)
```

> [!NOTE]
>
> O AutoGen também pode ser usado pelo nosso [AI Gateway](#ai-gateway). Para saber mais, consulte [AutoGen Gateway](#ai-gateway).


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