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

# AWS Strands Agents integration

> Connect AWS Strands Agents to Toqan Router's AI Gateway with OpenTelemetry observability. Access 500+ LLMs with built-in reliability and tracing.

> [card] [AI Gateway](#ai-gateway)
>
> Route your LLM calls through the AI Gateway with a single base URL change. Zero vendor lock-in: always run on the best model at the lowest cost for your use case.

> [card] [Observability](#observability)
>
> Instrument your code with OpenTelemetry to capture traces, logs, and metrics for every LLM call, agent step, and tool use.

## AI Gateway

### Overview

AWS Strands is a framework for building AI agents with structured reasoning and tool use. By connecting AWS Strands to Toqan Router's AI Gateway, you transform experimental agents into production-ready systems with enterprise-grade capabilities.

### Key Benefits

Toqan Router's AI Gateway enhances your AWS Strands Agents with:

> [card] Complete Observability
>
> Track every agent step, tool use, and interaction with detailed traces and analytics

> [card] Built-in Reliability
>
> Automatic fallbacks, retries, and load balancing for production resilience

> [card] Cost Optimization
>
> Real-time cost tracking and spend management across all your AI operations

> [card] Multi-Provider Access
>
> Access 500+ LLMs and 30+ providers through a single, unified integration

### Prerequisites

Before integrating AWS Strands with Toqan Router, ensure you have:

* A Toqan Router account and API Key
* Python 3.10 or higher
* AWS Strands SDK installed

> [!NOTE]
>
> To setup your API key, see API keys & Endpoints.

### Installation

Install the Strands Agents SDK (requires 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
```

### Configuration

Configure Strands Agents to use Toqan Router's AI Gateway by passing custom client arguments with the base URL:

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

### Basic Agent Example

Here's a complete example of creating and running a Strands agent through 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)
```

### Agent with Tools

Strands agents can use tools while routing through 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)
```

### Fallback Configuration

Configure automatic fallbacks for reliability:

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

## Observability

AWS Strands integrates with Toqan Router's [Observability Platform](/docs/ai-studio/observability/quickstart.md) through OpenTelemetry. Capture complete traces of your agent interactions, tool calls, and model invocations to gain deep insights into agent behavior, performance, and costs.

### Prerequisites

Before you begin, ensure you have:

* A Toqan Router account and an API Key
* AWS Strands SDK installed
* Python 3.10+

> [!NOTE]
>
> The examples below use OpenAI models with OpenTelemetry tracing sent to Toqan Router. Set both `OPENAI_API_KEY` (for model access) and `TOQAN_API_KEY` (for telemetry export) environment variables.

### Installation

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

### Configuration

Configure OpenTelemetry to send traces to 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)
```

### Basic Example

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

### Agent with Tools

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