> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Mastra framework integration > Connect Mastra to Toqan Router's AI Gateway for complete observability, built-in reliability, and access to 500+ LLMs across 30+ providers. > [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 Mastra is a TypeScript framework for building AI-powered applications with pipelines, agents, and workflows. By connecting Mastra to Toqan Router's AI Gateway, you transform experimental AI applications into production-ready systems with enterprise-grade capabilities. ### Key Benefits Toqan Router's AI Gateway enhances your Mastra applications 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 Mastra with Toqan Router, ensure you have: * A Toqan Router account and API Key * Node.js 22.13 or higher * TypeScript support * Mastra installed in your project > [!NOTE] > > To setup your API key, see API keys & Endpoints. ### Installation Install Mastra: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install @mastra/core zod ``` ### Configuration Configure Mastra to use Toqan Router's AI Gateway with an OpenAI-compatible model configuration: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { Agent } from "@mastra/core/agent"; // Create agent with Toqan Router-powered model const agent = new Agent({ id: "assistant", name: "Assistant", instructions: "You are a helpful assistant.", model: { id: "openai/gpt-5.6-sol", url: "https://router.toqan.ai/eu/v3/router", apiKey: process.env.TOQAN_API_KEY, }, }); ``` > **url**: `https://router.toqan.ai/eu/v3/router` ### Basic Agent Example Here's a complete example of creating and running a Mastra agent through Toqan Router: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { Agent } from "@mastra/core/agent"; // Create agent export const assistantAgent = new Agent({ id: "assistant", name: "Assistant", instructions: "You are a helpful assistant that explains complex concepts simply.", model: { id: "openai/gpt-5.6-sol", url: "https://router.toqan.ai/eu/v3/router", apiKey: process.env.TOQAN_API_KEY, }, }); // Run the agent async function main() { const result = await assistantAgent.generate("Explain quantum computing in simple terms"); console.log(result.text); } main().catch(console.error); ``` ### Model Selection With Toqan Router, you can use any supported model from 30+ providers: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { Agent } from "@mastra/core/agent"; const toqanRouter = { url: "https://router.toqan.ai/eu/v3/router", apiKey: process.env.TOQAN_API_KEY, }; // Use Claude export const claudeAgent = new Agent({ id: "claude-assistant", name: "Claude Assistant", model: { id: "anthropic/claude-sonnet-5", ...toqanRouter }, instructions: "You are a helpful assistant.", }); // Use Gemini export const geminiAgent = new Agent({ id: "gemini-assistant", name: "Gemini Assistant", model: { id: "google/gemini-2.5-flash", ...toqanRouter }, instructions: "You are a helpful assistant.", }); // Use any other model export const groqAgent = new Agent({ id: "groq-assistant", name: "Groq Assistant", model: { id: "groq/qwen/qwen3.8-27b", ...toqanRouter }, instructions: "You are a helpful assistant.", }); // Run with different models async function main() { const result = await claudeAgent.generate("Explain machine learning"); console.log(result.text); } main().catch(console.error); ``` ### Agent with tools Define tools with `createTool` and attach them to an agent through the `tools` field: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { Agent } from "@mastra/core/agent"; import { createTool } from "@mastra/core/tools"; import { z } from "zod"; const toqanRouter = { url: "https://router.toqan.ai/eu/v3/router", apiKey: process.env.TOQAN_API_KEY, }; const weatherTool = createTool({ id: "weather-tool", description: "Fetches a short weather summary for a location.", inputSchema: z.object({ location: z.string().describe('City name, e.g. "Paris"'), }), outputSchema: z.object({ weather: z.string() }), execute: async (inputData) => { const { location } = inputData; const res = await fetch( `https://wttr.in/${encodeURIComponent(location)}?format=3`, ); return { weather: (await res.text()).trim() }; }, }); export const weatherAgent = new Agent({ id: "weather-agent", name: "Weather Agent", instructions: "Call weatherTool when the user asks about the current weather in a city.", model: { id: "openai/gpt-5.4-mini", ...toqanRouter }, tools: { weatherTool }, }); async function main() { const result = await weatherAgent.generate("What is the weather in Paris?"); console.log(result.text); } main().catch(console.error); ``` ## Observability ### Getting Started Integrate Mastra with Toqan Router's observability to gain complete insights into pipeline execution, agent performance, workflow orchestration, and system reliability using OpenTelemetry. ### Prerequisites Before you begin, ensure you have: * A Toqan Router account and API Key * Node.js 22.13 or higher and TypeScript support * Mastra installed in your project * API keys for your LLM providers and external services ### Install Dependencies ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install @mastra/core @mastra/observability @mastra/otel-bridge \ @opentelemetry/api @opentelemetry/sdk-node \ @opentelemetry/exporter-trace-otlp-http \ @opentelemetry/auto-instrumentations-node \ @opentelemetry/resources @opentelemetry/semantic-conventions \ zod ``` ### Configure Toqan Router Set up your environment variables to connect to Toqan Router's OpenTelemetry collector: **Unix/Linux/macOS:** ```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 " export OTEL_RESOURCE_ATTRIBUTES="service.name=mastra-app,service.version=1.0.0" export OPENAI_API_KEY="" ``` **Windows (PowerShell):** ```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 " $env:OTEL_RESOURCE_ATTRIBUTES = "service.name=mastra-app,service.version=1.0.0" $env:OPENAI_API_KEY = "" ``` **Using .env file:** ```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 OTEL_RESOURCE_ATTRIBUTES=service.name=mastra-app,service.version=1.0.0 OPENAI_API_KEY= ``` ### Custom Instrumentation Mastra supports native OpenTelemetry integration for comprehensive observability. Create an `instrumentation.mjs` file in your Mastra project: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { NodeSDK } from '@opentelemetry/sdk-node'; import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; const sdk = new NodeSDK({ traceExporter: new OTLPTraceExporter({ url: 'https://router.toqan.ai/eu/v2/otel/v1/traces', headers: { Authorization: "Bearer " } }), instrumentations: [getNodeAutoInstrumentations()], }); sdk.start(); ``` Load it when starting the app: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} NODE_OPTIONS="--import ./instrumentation.mjs" npm run dev ``` Enable Telemetry in your Mastra initialization: ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { Mastra } from "@mastra/core"; import { Observability } from "@mastra/observability"; import { OtelBridge } from "@mastra/otel-bridge"; export const mastra = new Mastra({ agents: { /* register agents here */ }, observability: new Observability({ configs: { default: { serviceName: "mastra-app", bridge: new OtelBridge(), }, }, }), }); ``` Register every agent in the `agents` field of the **Mastra** constructor. Unregistered agents do not emit traces, because **OtelBridge** only sees agents passed in at construction time. > [!TIP] > > All Mastra pipelines and agent calls will be instrumented and exported to Toqan Router through the OTLP exporter. ### View Traces View your traces in the [AI Studio](/docs/ai-studio/observability/quickstart.md) in the **Traces** tab. > [!NOTE] > > Visit your [AI Studio](https://router.toqan.ai/eu) to view real-time analytics and traces. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.