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

## AI Gateway

### Overview

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

### Key Benefits

Orq.ai's AI Gateway enhances 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 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 the following are in place:

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

<Info>
  To set up an API key, see [API keys & Endpoints](/docs/ai-gateway/configuration/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, any supported model from 20+ providers can be used:

```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-6", ...orqRouter },
  instructions: "You are a helpful assistant.",
});

// Use Gemini
export const geminiAgent = new Agent({
  id: "gemini-assistant",
  name: "Gemini Assistant",
  model: { id: "google-ai/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);
```