> ## 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 AWS Strands Agents

> Conecte o AWS Strands Agents ao AI Gateway do Toqan Router com observabilidade via OpenTelemetry. Acesse mais de 500 LLMs com confiabilidade e tracing integrados.

> [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 AWS Strands é um framework para criar agentes de IA com raciocínio estruturado e uso de ferramentas. Ao conectar o AWS Strands ao AI Gateway do Toqan Router, você transforma agentes experimentais em sistemas prontos para produção, com recursos de nível empresarial.

### Principais benefícios

O AI Gateway do Toqan Router aprimora seus AWS Strands Agents com:

> [card] Observabilidade completa
>
> Acompanhe cada etapa do agente, uso de ferramenta e interação 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

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

* Uma conta do Toqan Router e uma chave de API
* Python 3.10 ou superior
* SDK do AWS Strands instalado

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

### Instalação

Instale o SDK do Strands Agents (requer Python 3.10+):

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Install Strands Agents SDK
pip install strands-agents

# Optional: Install additional tools
pip install strands-agents-tools
```

### Configuração

Configure o Strands Agents para usar o AI Gateway do Toqan Router passando argumentos de cliente personalizados com a URL base:

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

# Configure model with Toqan Router AI Gateway
model = OpenAIModel(
    model_id="openai/gpt-5.6-sol",
    client_args={
        "api_key": os.getenv('TOQAN_API_KEY'),
        "base_url": "https://router.toqan.ai/eu/v3/router"
    }
)

# Create agent with Toqan Router-powered model
agent = Agent(
    model=model,
    system_prompt="You are a helpful AI assistant."
)
```

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

### Exemplo básico de agente

Veja um exemplo completo de criação e execução de um agente Strands pelo Toqan Router:

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

# Configure model with Toqan Router AI Gateway
model = OpenAIModel(
    model_id="openai/gpt-5.6-sol",
    client_args={
        "api_key": os.getenv('TOQAN_API_KEY'),
        "base_url": "https://router.toqan.ai/eu/v3/router"
    }
)

# Create a simple agent
agent = Agent(
    model=model,
    system_prompt="You are a research assistant that helps users find and summarize information."
)

# Run the agent
result = agent("Explain quantum computing in simple terms")
print(result)
```

### Agente com ferramentas

Os agentes Strands podem usar ferramentas enquanto são roteados pelo Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from strands import Agent, tool
from strands.models.openai import OpenAIModel
import os

# Configure model
model = OpenAIModel(
    model_id="openai/gpt-5.6-sol",
    client_args={
        "api_key": os.getenv('TOQAN_API_KEY'),
        "base_url": "https://router.toqan.ai/eu/v3/router"
    }
)

# Define a custom tool using the @tool decorator
@tool
def search_database(query: str) -> str:
    """Search the knowledge database for relevant information."""
    # Your database search logic here
    return f"Search results for: {query}"

# Create agent with tools
agent = Agent(
    model=model,
    tools=[search_database],
    system_prompt="You are a knowledge assistant. Use the search_database tool to find information when needed."
)

# Run agent with tool access
result = agent("Find information about machine learning best practices")
print(result)
```

### Configuração de fallback

Configure fallbacks automáticos para ter confiabilidade:

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

# Configure model - Toqan Router handles fallbacks automatically
model = OpenAIModel(
    model_id="openai/gpt-5.6-sol",
    client_args={
        "api_key": os.getenv('TOQAN_API_KEY'),
        "base_url": "https://router.toqan.ai/eu/v3/router"
    }
)

agent = Agent(
    model=model,
    system_prompt="You are a helpful assistant."
)
```

## Observabilidade

O AWS Strands se integra à [plataforma de observabilidade](/docs/pt-BR/ai-studio/observability/quickstart.md) do Toqan Router por meio do OpenTelemetry. Capture traces completos das interações dos seus agentes, chamadas de ferramentas e invocações de modelos para obter insights profundos sobre o comportamento, o desempenho e os custos dos agentes.

### Pré-requisitos

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

* Uma conta do Toqan Router e uma chave de API
* SDK do AWS Strands instalado
* Python 3.10+

> [!NOTE]
>
> Os exemplos abaixo usam modelos da OpenAI com tracing do OpenTelemetry enviado ao Toqan Router. Defina as variáveis de ambiente `OPENAI_API_KEY` (para acesso ao modelo) e `TOQAN_API_KEY` (para exportação de telemetria).

### Instalação

```bash bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install strands-agents opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

### Configuração

Configure o OpenTelemetry para enviar traces ao Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from opentelemetry import trace
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.sdk.resources import Resource

# Configure OTLP exporter
exporter = OTLPSpanExporter(
    endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.getenv('TOQAN_API_KEY')}"}
)

# Create tracer provider with service name
resource = Resource(attributes={
    "service.name": "strands-agent-app"
})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(exporter))

# Set as global tracer provider
trace.set_tracer_provider(provider)
```

### Exemplo básico

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from opentelemetry import trace
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.sdk.resources import Resource
from strands import Agent
from strands.models.openai import OpenAIModel

# Setup OpenTelemetry
exporter = OTLPSpanExporter(
    endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.getenv('TOQAN_API_KEY')}"}
)
resource = Resource(attributes={"service.name": "strands-agent"})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

# Configure model
model = OpenAIModel(
    model_id="gpt-5.6-sol",
    client_args={
        "api_key": os.getenv('OPENAI_API_KEY'),
    }
)

# Create agent
agent = Agent(
    model=model,
    system_prompt="You are a helpful research assistant."
)

# Run agent (traces automatically sent to Toqan Router)
result = agent("Explain quantum computing in simple terms")
print(result)
```

### Agente com ferramentas

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from opentelemetry import trace
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.sdk.resources import Resource
from strands import Agent, tool
from strands.models.openai import OpenAIModel

# Setup OpenTelemetry
exporter = OTLPSpanExporter(
    endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.getenv('TOQAN_API_KEY')}"}
)
resource = Resource(attributes={"service.name": "strands-agent-tools"})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

# Configure model
model = OpenAIModel(
    model_id="gpt-5.6-sol",
    client_args={
        "api_key": os.getenv('OPENAI_API_KEY'),
    }
)

# Define tools
@tool
def search_database(query: str) -> str:
    """Search the knowledge database for relevant information."""
    return f"Search results for: {query}"

@tool
def get_weather(location: str) -> str:
    """Get current weather for a location."""
    return f"Weather in {location}: Sunny, 72°F"

# Create agent with tools
agent = Agent(
    model=model,
    tools=[search_database, get_weather],
    system_prompt="You are a helpful assistant with access to search and weather tools."
)

# Run agent (all tool calls traced)
result = agent("What's the weather like in San Francisco?")
print(result)
```


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