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

# Mastra framework integration

> Connect Mastra to Orq.ai's AI Router for complete observability, built-in reliability, and access to 300+ LLMs across 20+ providers.

<CardGroup cols={2}>
  <Card title="AI Router" icon="arrow-right-arrow-left" href="#ai-router">
    Route your LLM calls through the AI Router 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>

  <Card title="Observability" icon="chart-line" href="#observability">
    Instrument your code with OpenTelemetry to capture traces, logs, and metrics for every LLM call, agent step, and tool use.
  </Card>
</CardGroup>

## AI Router

### Overview

Mastra is a TypeScript framework for building AI-powered applications with pipelines, agents, and workflows. By connecting Mastra to Orq.ai's AI Router, you transform experimental AI applications into production-ready systems with enterprise-grade capabilities.

### Key Benefits

Orq.ai's AI Router enhances your Mastra applications with:

<CardGroup cols={2}>
  <Card title="Complete Observability" icon="chart-line">
    Track every agent step, tool use, and interaction with detailed traces and analytics
  </Card>

  <Card title="Built-in Reliability" icon="shield-check">
    Automatic fallbacks, retries, and load balancing for production resilience
  </Card>

  <Card title="Cost Optimization" icon="chart-pie">
    Real-time cost tracking and spend management across all your AI operations
  </Card>

  <Card title="Multi-Provider Access" icon="cubes">
    Access 300+ LLMs and 20+ providers through a single, unified integration
  </Card>
</CardGroup>

### Prerequisites

Before integrating Mastra with Orq.ai, ensure you have:

* An Orq.ai account and [API Key](/docs/administer/api-keys)
* Node.js 18 or higher
* TypeScript support
* Mastra installed in your project

<Info>
  To setup your API key, see [API keys & Endpoints](/docs/administer/api-keys).
</Info>

### Installation

Install Mastra:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @mastra/core
```

### Configuration

Configure Mastra to use Orq.ai's AI Router 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 Orq.ai-powered model
const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a helpful assistant.",
  model: {
    id: "openai/gpt-4o",
    url: "https://api.orq.ai/v3/router",
    apiKey: process.env.ORQ_API_KEY,
  },
});
```

> **url**: `https://api.orq.ai/v3/router`

### Basic Agent Example

Here's a complete example of creating and running a Mastra agent through Orq.ai:

```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-4o",
    url: "https://api.orq.ai/v3/router",
    apiKey: process.env.ORQ_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);
```

<Note>
  **Tool Calling Limitation**: Mastra's tool call format in the Responses API currently has schema incompatibilities with the AI Router. Basic agent usage works, but tool-based workflows require using the Observability integration or direct provider access.
</Note>

### Model Selection

With Orq.ai, you can use any supported model from 20+ providers:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Agent } from "@mastra/core/agent";

const orqRouter = {
  url: "https://api.orq.ai/v3/router",
  apiKey: process.env.ORQ_API_KEY,
};

// Use Claude
export const claudeAgent = new Agent({
  id: "claude-assistant",
  name: "Claude Assistant",
  model: { id: "anthropic/claude-sonnet-4-5-20250929", ...orqRouter },
  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", ...orqRouter },
  instructions: "You are a helpful assistant.",
});

// Use any other model
export const groqAgent = new Agent({
  id: "groq-assistant",
  name: "Groq Assistant",
  model: { id: "groq/llama-3.3-70b-versatile", ...orqRouter },
  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);
```

## Observability

### Getting Started

Integrate Mastra with Orq.ai'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:

* An Orq.ai account and [API Key](/docs/administer/api-keys)
* Node.js 16+ 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"}}
# Core Mastra framework
npm install mastra

# OpenTelemetry packages for Node.js
npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

# Additional OpenTelemetry instrumentation
npm install @opentelemetry/semantic-conventions @opentelemetry/resources

# LLM providers and tools (choose what you need)
npm install openai @anthropic-ai/sdk axios
```

### Configure Orq.ai

Set up your environment variables to connect to Orq.ai's OpenTelemetry collector:

**Unix/Linux/macOS:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.orq.ai/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <ORQ_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=mastra-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
```

**Windows (PowerShell):**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://api.orq.ai/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <ORQ_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=mastra-app,service.version=1.0.0"
$env:OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
```

**Using .env file:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.orq.ai/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <ORQ_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=mastra-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
```

### Default Export

In your Mastra server configuration, enable export tracing. The previously set environment variables will be used.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
export const mastra = new Mastra({
  // ... other config
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    export: {
      type: "otlp",
      // endpoint and headers will be picked up from env vars
    },
  },
});
```

### 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://api.orq.ai/v2/otel/v1/traces',
    headers: {
      Authorization: "Bearer <ORQ_API_KEY>"
    }
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();
```

Enable Telemetry in your Mastra initialization:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
export const mastra = new Mastra({
  telemetry: {
    enabled: true,
  },
});
```

<Check>
  All Mastra pipelines and agent calls will be instrumented and exported to Orq.ai through the OTLP exporter.
</Check>

### View Traces

View your traces in the [AI Studio](/docs/observability/overview) in the **Traces** tab.

<Info>
  Visit your [AI Studio](https://my.orq.ai) to view real-time analytics and traces.
</Info>

## Evaluations & Experiments

Once your agents are running, use **Evaluatorq** to score outputs across a dataset and **Experiments** to compare configurations side-by-side.

<CardGroup cols={2}>
  <Card title="Run Evaluations with Evaluatorq" icon="flask" href="/docs/evaluators/build#evaluatorq">
    Run parallel evaluations across your agents and compare results.
  </Card>

  <Card title="Run Experiments via the API" icon="flask-vial" href="/docs/experiments/api">
    Compare agent configurations and view results in the AI Studio.
  </Card>
</CardGroup>