Skip to main content

​
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:

Complete Observability

Track every agent step, tool use, and interaction with detailed traces and analytics

Built-in Reliability

Automatic fallbacks, retries, and load balancing for production resilience

Cost Optimization

Real-time cost tracking and spend management across all AI operations

Multi-Provider Access

Access 300+ LLMs and 20+ providers through a single, unified integration

​
Prerequisites

Before integrating Mastra with Orq.ai, ensure the following are in place:
  • An Orq.ai account and API Key
  • Node.js 18 or higher
  • TypeScript support
  • Mastra installed
To set up an API key, see API keys & Endpoints.

​
Installation

Install Mastra: 
npm install @mastra/core zod

​
Configuration

Configure Mastra to use Orq.ai’s AI Gateway with an OpenAI-compatible model configuration:
TypeScript
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
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
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
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);