> ## 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 Azure AI Agents

> Conecte o Azure AI Agents 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 o endpoint. 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

Use o Azure AI Inference SDK para rotear todas as chamadas de modelo pelo AI Gateway do Toqan Router. Aponte o `ChatCompletionsClient` para o endpoint do Toqan Router para acessar mais de 500 modelos de mais de 30 provedores — OpenAI, Anthropic, Google e outros — sem alterar a lógica do seu agente.

### Principais benefícios

> [card] Observabilidade completa
>
> Acompanhe cada etapa do agente, uso de ferramenta e chamada de LLM com traces e analytics detalhados

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

* Uma conta do Toqan Router e uma chave de API
* Python 3.9 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 azure-ai-inference azure-core
```

### Configuração

Configure o `ChatCompletionsClient` para apontar para o AI Gateway do Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from azure.ai.inference import ChatCompletionsClient
from azure.core.credentials import AzureKeyCredential

client = ChatCompletionsClient(
    endpoint="https://router.toqan.ai/eu/v3/router",
    credential=AzureKeyCredential(os.environ["TOQAN_API_KEY"]),
)
```

> **endpoint**: `https://router.toqan.ai/eu/v3/router`

### Exemplo básico

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from azure.ai.inference import ChatCompletionsClient
from azure.ai.inference.models import SystemMessage, UserMessage
from azure.core.credentials import AzureKeyCredential

client = ChatCompletionsClient(
    endpoint="https://router.toqan.ai/eu/v3/router",
    credential=AzureKeyCredential(os.environ["TOQAN_API_KEY"]),
)

response = client.complete(
    model="openai/gpt-5.6-sol",
    messages=[
        SystemMessage(content="You are a helpful research assistant. Answer questions concisely and accurately."),
        UserMessage(content="What are the three most important factors when evaluating an LLM for production use?"),
    ],
)

print(response.choices[0].message.content)
```

### Agente com ferramentas de função

O `ChatCompletionsClient` oferece suporte a chamadas de ferramentas em múltiplos turnos. O loop do agente é executado até que nenhuma outra chamada de ferramenta seja retornada:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import json
from azure.ai.inference import ChatCompletionsClient
from azure.ai.inference.models import (
    SystemMessage,
    UserMessage,
    AssistantMessage,
    ToolMessage,
    ChatCompletionsToolDefinition,
    FunctionDefinition,
)
from azure.core.credentials import AzureKeyCredential

client = ChatCompletionsClient(
    endpoint="https://router.toqan.ai/eu/v3/router",
    credential=AzureKeyCredential(os.environ["TOQAN_API_KEY"]),
)

tools = [
    ChatCompletionsToolDefinition(
        function=FunctionDefinition(
            name="get_weather",
            description="Get the current weather for a given location.",
            parameters={
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and country, e.g. Amsterdam, NL",
                    }
                },
                "required": ["location"],
            },
        )
    )
]


def get_weather(location: str) -> str:
    data = {
        "amsterdam, nl": "Cloudy, 14°C",
        "london, uk": "Rainy, 11°C",
        "san francisco, us": "Sunny, 18°C",
    }
    return data.get(location.lower(), f"No weather data for {location}")


messages = [
    SystemMessage(content="You are a weather assistant. Always use get_weather to look up weather."),
    UserMessage(content="What's the weather in Amsterdam and London?"),
]

# Agent loop — run until no tool calls remain
while True:
    response = client.complete(
        model="openai/gpt-5.6-sol",
        messages=messages,
        tools=tools,
    )

    choice = response.choices[0]

    if choice.finish_reason == "tool_calls":
        messages.append(AssistantMessage(tool_calls=choice.message.tool_calls))
        for tool_call in choice.message.tool_calls:
            args = json.loads(tool_call.function.arguments)
            result = get_weather(args["location"])
            messages.append(ToolMessage(tool_call_id=tool_call.id, content=result))
    else:
        print(choice.message.content)
        break
```

### Seleção de modelo

Troque de modelo alterando o parâmetro `model`. Todos os mais de 500 modelos estão disponíveis pelo mesmo cliente:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from azure.ai.inference import ChatCompletionsClient
from azure.ai.inference.models import SystemMessage, UserMessage
from azure.core.credentials import AzureKeyCredential

client = ChatCompletionsClient(
    endpoint="https://router.toqan.ai/eu/v3/router",
    credential=AzureKeyCredential(os.environ["TOQAN_API_KEY"]),
)

messages = [
    SystemMessage(content="You are a helpful assistant."),
    UserMessage(content="Explain transformer architectures briefly."),
]

# Use Claude
response = client.complete(model="anthropic/claude-sonnet-5", messages=messages)

# Use Gemini
response = client.complete(model="google/gemini-2.5-flash", messages=messages)

# Use GPT-5.6 Sol
response = client.complete(model="openai/gpt-5.6-sol", messages=messages)

print(response.choices[0].message.content)
```

## Observabilidade

### Visão geral

Instrumente sua aplicação Azure AI Agents com OpenTelemetry para enviar traces ao Toqan Router. O pacote `azure-core-tracing-opentelemetry` se conecta ao mecanismo de tracing distribuído do Azure SDK, capturando automaticamente spans de cada chamada de agente, operação de thread e invocação de LLM.

### Pré-requisitos

* Uma conta do Toqan Router e uma chave de API
* Projeto do Azure AI Foundry com um agente implantado
* Python 3.9+
* `AZURE_AI_PROJECT_ENDPOINT` — o endpoint do seu projeto do Azure AI Foundry
* `AZURE_AI_MODEL_DEPLOYMENT_NAME` — o nome do deployment do modelo no seu projeto do Foundry

### Instalar dependências

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install azure-ai-agents azure-identity \
            'azure-core-tracing-opentelemetry>=1.0.0b12' \
            opentelemetry-sdk opentelemetry-exporter-otlp
```

### Configuração

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from azure.core.settings import settings
from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry import trace

settings.tracing_implementation = OpenTelemetrySpan

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
            headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
        )
    )
)
trace.set_tracer_provider(tracer_provider)
tracer = trace.get_tracer(__name__)
```

### Exemplo básico

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from azure.core.settings import settings
from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry import trace
from azure.ai.agents import AgentsClient
from azure.identity import DefaultAzureCredential

settings.tracing_implementation = OpenTelemetrySpan

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
            headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
        )
    )
)
trace.set_tracer_provider(tracer_provider)
tracer = trace.get_tracer(__name__)

with AgentsClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential()
) as agents_client:
    with tracer.start_as_current_span("azure-agent-workflow"):
        agent = agents_client.create_agent(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            name="Research Assistant",
            instructions="You are a helpful research assistant."
        )
        thread = agents_client.threads.create()
        agents_client.messages.create(
            thread_id=thread.id,
            role="user",
            content="Summarize the key advantages of transformer architectures."
        )
        run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
        print(f"Run status: {run.status}")
        agents_client.delete_agent(agent.id)

tracer_provider.force_flush()
```

### Ver traces

Veja seus traces no [AI Studio](/docs/pt-BR/ai-studio/observability/quickstart.md), na aba **Traces**.

> [!NOTE]
>
> Acesse o seu [AI Studio](https://router.toqan.ai/eu) para ver analytics e traces em tempo real.


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