> ## 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 Gateway for complete observability, built-in reliability, and access to 300+ LLMs across 20+ providers.

<CardGroup cols={2}>
  <Card title="AI Gateway" icon="arrow-right-arrow-left" href="#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>

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

### Overview

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

### Key Benefits

Orq.ai's AI Gateway 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/ai-studio/organization/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/ai-studio/organization/api-keys).
</Info>

### Installation

Install Mastra:

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

### Configuration

Configure Mastra to use Orq.ai'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 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);
```

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

### 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 orqRouter = {
  url: "https://api.orq.ai/v3/router",
  apiKey: process.env.ORQ_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-4o-mini", ...orqRouter },
  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 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/ai-studio/organization/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"}}
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 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>
```

### 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"}}
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.

<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/ai-studio/observability/quickstart) 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/ai-studio/optimize/evaluators#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>