> ## 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 Microsoft Semantic Kernel

> Conecte o Microsoft Semantic Kernel 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)
>
> Encaminhe suas chamadas de LLM pelo AI Gateway alterando apenas a URL base. Sem dependência de fornecedor: execute sempre o melhor modelo pelo menor custo para o seu caso de uso.

> [card] [Observabilidade](#observability)
>
> Envie traces do Semantic Kernel para o **Toqan Router** com OpenTelemetry.

## AI Gateway

### Visão geral

O Microsoft Semantic Kernel é um SDK que integra Large Language Models (LLMs) a linguagens de programação convencionais. Ao conectar o Semantic Kernel ao AI Gateway do Toqan Router, você transforma agentes de IA experimentais em sistemas prontos para produção, com recursos de nível empresarial.

### Principais benefícios

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

> [card] Observabilidade completa
>
> Acompanhe cada etapa do agente, uso de ferramenta e interação com traces e análises detalhados

> [card] Confiabilidade integrada
>
> Fallbacks automáticos, novas tentativas e balanceamento de carga 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 vários 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 Semantic Kernel ao Toqan Router, verifique se você tem:

* Uma conta no Toqan Router e uma chave de API
* Python 3.10 ou superior
* O SDK do Semantic Kernel instalado

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

### Instalação

Instale o Semantic Kernel e o OpenAI SDK:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install semantic-kernel openai
```

### Configuração

Configure o Semantic Kernel para usar o AI Gateway do Toqan Router criando um cliente OpenAI com uma URL base personalizada:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import AsyncOpenAI
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
import os

# Configure OpenAI client with Toqan Router AI Gateway
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router"
)

# Create kernel
kernel = Kernel()

# Add chat completion service
chat_service = OpenAIChatCompletion(
    ai_model_id="openai/gpt-5.6-sol",
    async_client=client
)

kernel.add_service(chat_service)
```

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

### Exemplo básico

Veja um exemplo completo de uso do Semantic Kernel com o Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import AsyncOpenAI
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import (
    OpenAIChatCompletion,
    OpenAIChatPromptExecutionSettings
)
from semantic_kernel.contents import ChatHistory
import asyncio
import os

async def main():
    # Configure client with Toqan Router
    client = AsyncOpenAI(
        api_key=os.getenv("TOQAN_API_KEY"),
        base_url="https://router.toqan.ai/eu/v3/router"
    )

    # Create kernel
    kernel = Kernel()

    # Add chat completion service
    chat_service = OpenAIChatCompletion(
        ai_model_id="openai/gpt-5.6-sol",
        async_client=client
    )
    kernel.add_service(chat_service)

    # Create execution settings
    settings = OpenAIChatPromptExecutionSettings(
        max_tokens=2000,
        temperature=0.7
    )

    # Create chat history
    history = ChatHistory()
    history.add_user_message("What is quantum computing?")

    # Get response
    response = await chat_service.get_chat_message_content(
        chat_history=history,
        settings=settings,
        kernel=kernel
    )

    print(response.content)

if __name__ == "__main__":
    asyncio.run(main())
```

### Usando plugins (funções)

O poder do Semantic Kernel vem da combinação de LLMs com plugins. Veja como usá-los com o Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import AsyncOpenAI
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.functions import kernel_function
from semantic_kernel.contents import ChatHistory
import asyncio
import os

# Define a plugin
class WeatherPlugin:
    @kernel_function(
        name="get_weather",
        description="Get the weather for a location"
    )
    def get_weather(self, location: str) -> str:
        """Get weather for a location."""
        return f"The weather in {location} is sunny and 72°F"

async def main():
    # Configure client
    client = AsyncOpenAI(
        api_key=os.getenv("TOQAN_API_KEY"),
        base_url="https://router.toqan.ai/eu/v3/router"
    )

    # Create kernel
    kernel = Kernel()

    # Add chat completion service
    chat_service = OpenAIChatCompletion(
        ai_model_id="openai/gpt-5.6-sol",
        async_client=client
    )
    kernel.add_service(chat_service)

    # Add plugin
    kernel.add_plugin(
        WeatherPlugin(),
        plugin_name="WeatherPlugin"
    )

    # Create chat history
    history = ChatHistory()
    history.add_user_message("What's the weather in San Francisco?")

    # Enable automatic function calling
    from semantic_kernel.connectors.ai.open_ai import OpenAIChatPromptExecutionSettings
    from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior

    execution_settings = OpenAIChatPromptExecutionSettings(
        function_choice_behavior=FunctionChoiceBehavior.Auto()
    )

    # Get response with function calling
    response = await chat_service.get_chat_message_content(
        chat_history=history,
        settings=execution_settings,
        kernel=kernel
    )

    print(response.content)

if __name__ == "__main__":
    asyncio.run(main())
```

### Seleção de modelo

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

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import AsyncOpenAI
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
import os

# Configure client
client = AsyncOpenAI(
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router"
)

kernel = Kernel()

# Use Claude
claude_service = OpenAIChatCompletion(
    ai_model_id="anthropic/claude-sonnet-5",
    async_client=client,
    service_id="claude"
)
kernel.add_service(claude_service)

# Use Gemini
gemini_service = OpenAIChatCompletion(
    ai_model_id="google-ai/gemini-2.5-flash",
    async_client=client,
    service_id="gemini"
)
kernel.add_service(gemini_service)

# Use any other model
groq_service = OpenAIChatCompletion(
    ai_model_id="groq/qwen/qwen3.8-27b",
    async_client=client,
    service_id="groq"
)
kernel.add_service(groq_service)
```

### Respostas em streaming

O Semantic Kernel oferece suporte a streaming com o Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import AsyncOpenAI
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import (
    OpenAIChatCompletion,
    OpenAIChatPromptExecutionSettings
)
from semantic_kernel.contents import ChatHistory
import asyncio
import os

async def main():
    client = AsyncOpenAI(
        api_key=os.getenv("TOQAN_API_KEY"),
        base_url="https://router.toqan.ai/eu/v3/router"
    )

    kernel = Kernel()
    chat_service = OpenAIChatCompletion(
        ai_model_id="openai/gpt-5.6-sol",
        async_client=client
    )
    kernel.add_service(chat_service)

    settings = OpenAIChatPromptExecutionSettings(
        max_tokens=2000,
        temperature=0.7
    )

    history = ChatHistory()
    history.add_user_message("Write a short story about AI")

    # Stream response
    async for message in chat_service.get_streaming_chat_message_content(
        chat_history=history,
        settings=settings,
        kernel=kernel
    ):
        print(message.content, end="", flush=True)

if __name__ == "__main__":
    asyncio.run(main())
```

## Observabilidade

O **AI Gateway** registra as solicitações de modelo encaminhadas por ele. Para capturar os spans do próprio Semantic Kernel, incluindo chamadas de funções do kernel, configure o OpenTelemetry na aplicação.

### Instale as dependências

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install semantic-kernel openai opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

### Ative o diagnóstico de modelos

Defina esta variável antes de iniciar o Python para que o Semantic Kernel também emita spans de modelo:

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS=true
```

Esta configuração experimental inclui nomes de modelos e uso de tokens sem ativar a captura de prompts ou respostas. Consulte a [documentação de telemetria do Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console) para ver as configurações de diagnóstico disponíveis.

### Envie traces para o Toqan Router

Defina `TOQAN_API_KEY` com uma chave de API do **Toqan Router** e execute este exemplo. Inicialize um único tracer provider para a aplicação e encerre-o quando a aplicação for finalizada.

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

from openai import AsyncOpenAI
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.sdk.trace.export import BatchSpanProcessor
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

tracer_provider = TracerProvider(
    resource=Resource.create({"service.name": "semantic-kernel-app"})
)
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)


async def main():
    async with AsyncOpenAI(
        api_key=os.environ["TOQAN_API_KEY"],
        base_url="https://router.toqan.ai/eu/v3/router",
    ) as client:
        kernel = Kernel()
        kernel.add_service(
            OpenAIChatCompletion(
                ai_model_id="openai/gpt-5.6-sol",
                async_client=client,
            )
        )
        answer = await kernel.invoke_prompt("Explain quantum computing in one sentence.")
        print(answer)


if __name__ == "__main__":
    try:
        asyncio.run(main())
    finally:
        tracer_provider.force_flush()
        tracer_provider.shutdown()
```

Abra [Traces](/docs/pt-BR/ai-studio/observability/traces.md) para inspecionar os spans exportados de `semantic-kernel-app`.


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