> ## 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 framework Mastra > Conecte o Mastra 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 a base URL. Sem dependência de fornecedor: use sempre o melhor modelo pelo 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 Mastra é um framework TypeScript para criar aplicações com IA usando pipelines, agentes e fluxos de trabalho. Ao conectar o Mastra ao AI Gateway do Toqan Router, você transforma aplicações 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 Mastra com: > [card] Observabilidade completa > > Acompanhe cada etapa de 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 > > Acompanhamento 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 integração única e unificada ### Pré-requisitos Antes de integrar o Mastra ao Toqan Router, certifique-se de ter: * Uma conta no Toqan Router e uma chave de API * Node.js 22.13 ou superior * Suporte a TypeScript * O Mastra instalado no seu projeto > [!NOTE] > > Para configurar sua chave de API, consulte Chaves de API e endpoints. ### Instalação Instale o Mastra: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install @mastra/core zod ``` ### Configuração Configure o Mastra para usar o AI Gateway do Toqan Router com uma configuração de modelo compatível com OpenAI: ```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` ### Exemplo básico de agente Veja um exemplo completo de criação e execução de um agente Mastra por meio do 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); ``` ### Seleção de modelo Com o Toqan Router, você pode usar qualquer modelo compatível de mais de 30 provedores: ```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); ``` ### Agente com ferramentas Defina ferramentas com `createTool` e anexe-as a um agente por meio do campo `tools`: ```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); ``` ## Observabilidade ### Primeiros passos Integre o Mastra à observabilidade do Toqan Router para obter insights completos sobre execução de pipelines, desempenho de agentes, orquestração de fluxos de trabalho e confiabilidade do sistema usando OpenTelemetry. ### Pré-requisitos Antes de começar, certifique-se de ter: * Uma conta no Toqan Router e uma chave de API * Node.js 22.13 ou superior e suporte a TypeScript * O Mastra instalado no seu projeto * Chaves de API dos seus provedores de LLM e serviços externos ### Instalar dependências ```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 ``` ### Configurar o Toqan Router Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router: **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 = "" ``` **Usando um arquivo .env:** ```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= ``` ### Instrumentação personalizada O Mastra oferece integração nativa com OpenTelemetry para observabilidade abrangente. Crie um arquivo `instrumentation.mjs` no seu projeto Mastra: ```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(); ``` Carregue-o ao iniciar a aplicação: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} NODE_OPTIONS="--import ./instrumentation.mjs" npm run dev ``` Habilite a telemetria na inicialização do Mastra: ```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(), }, }, }), }); ``` Registre todos os agentes no campo `agents` do construtor do **Mastra**. Agentes não registrados não emitem traces, porque o **OtelBridge** só enxerga os agentes passados no momento da construção. > [!TIP] > > Todos os pipelines e chamadas de agentes do Mastra serão instrumentados e exportados para o Toqan Router pelo exporter OTLP. ### Visualizar traces Visualize seus traces no [AI Studio](/docs/pt-BR/ai-studio/observability/quickstart.md), na aba **Traces**. > [!NOTE] > > Acesse seu [AI Studio](https://router.toqan.ai/eu) para ver análises e traces em tempo real. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.