Skip to main content

Mastra

Integrate OpenRouter with Mastra to access a variety of AI models through a unified interface. This guide provides complete examples from basic setup to advanced configurations.

Step 1: Initialize a new Mastra project

The simplest way to start is using the automatic project creation:
You’ll be guided through prompts to set up your project. For this example, select:
  • Name your project: my-mastra-openrouter-app
  • Components: Agents (recommended)
  • For default provider, select OpenAI (recommended) - we’ll configure OpenRouter manually later
  • Optionally include example code
For detailed instructions on setting up a Mastra project manually or adding Mastra to an existing project, refer to the official Mastra documentation.

Step 2: Configure your environment variables

After creating your project with create-mastra, you’ll find a .env.development file in your project root. Since we selected OpenAI during setup but will be using OpenRouter instead:
  1. Open the .env.development file
  2. Remove or comment out the OPENAI_API_KEY line
  3. Add your OpenRouter API key:
You can also remove the @ai-sdk/openai package since we’ll be using OpenRouter instead:

Step 3: Configure your agent to use OpenRouter

After setting up your Mastra project, you’ll need to modify the agent files to use OpenRouter instead of the default OpenAI provider. If you used create-mastra, you’ll likely have a file at src/mastra/agents/agent.ts or similar. Replace its contents with:
Keep the agent file free of model calls. Mastra imports it every time the server starts, so a call to generate at the top level would send a billable request on each startup, and a failed request would stop the server from starting. To try the agent, call it from a separate script such as src/try-agent.ts:
src/try-agent.ts
Output
Also make sure to update your Mastra entry point at src/mastra/index.ts to use your renamed agent:
This step is specific to Mastra, which is a TypeScript framework, so it has no Python, Go, or cURL equivalent. The samples in those languages on this page call the OpenRouter API directly and need no registration.

Step 4: Running the Application

Once you’ve configured your agent to use OpenRouter, you can run the Mastra development server:
This will start the Mastra development server and make your agent available at:
  • REST API endpoint: http://localhost:4111/api/agents/assistant/generate
  • Interactive playground: http://localhost:4111
The Mastra playground provides a user-friendly interface where you can interact with your agent and test its capabilities without writing any additional code. You can also test the API endpoint using curl if needed:

Basic Integration with Mastra

The simplest way to integrate OpenRouter with Mastra is by using the OpenRouter AI provider with Mastra’s Agent system:
Output

Advanced Configuration

For more control over your OpenRouter requests, you can pass additional configuration options:
Output

Provider-Specific Options

You can also pass provider-specific options in your requests:

Using Multiple Models with OpenRouter

OpenRouter gives you access to various models from different providers. Here’s how to use multiple models:
Output

Resources

For more information and detailed documentation, check out these resources: