Use Orq.ai as the model control layer for Mastra. Route LLM calls through one OpenAI‑compatible endpoint, capture traces, monitor cost, and manage fallback behavior without rebuilding your Mastra agent graphs, tools, or workflows.
What is Mastra?
Mastra is an AI agent framework for building production‑ready assistants and workflows, with abstractions for tools, memory, workflows, and integration with existing backends. It helps teams focus on agent behavior and business logic instead of wiring every model call, retry, and monitoring path by hand.
Why use Orq with Mastra
Trace agent behavior end to end
Trace Mastra runs end to end, including prompts, tool invocations, workflow steps, LLM calls, and errors in one place. You get clearer visibility into how each agent decided, called tools, and produced answers, without stitching together logs across multiple services.
Model flexibility without rewiring agents
Test new models, add alternative providers, or assign different model tiers to different Mastra agents and workflows from Orq.ai, while keeping your Mastra definitions and orchestration code stable. Your Mastra agents still “think” they’re talking to a single LLM client; Orq handles which underlying model is called.
Evaluate real production runs
Use real Mastra traces like requests, intermediate steps, tool chains, and LLM interactions to build datasets, compare prompt or model changes, and move from subjective tuning to measurable quality checks. Failed or slow agent runs can be turned into eval inputs before you roll out changes.
Control spend and access centrally
Track token usage and spend per agent, tool, team, and workflow so you can see which routes drive cost. Add budgets, rate limits, and approved‑model lists at the Orq platform layer instead of enforcing governance separately inside each Mastra‑based application.
How the integration works
Step 1
Point Mastra’s LLM client at Orq.ai’s router
Configure the LLM client Mastra uses so that its HTTP calls go to Orq.ai’s base URL and API key instead of calling each provider directly. This gives Orq the context it needs to apply routing rules, capture usage, and enforce fallback behavior behind your agents and workflows.
Step 2
Enable tracing from Mastra workloads to Orq
Keep your existing logging and monitoring in place while routing LLM calls through Orq’s AI Gateway / Router. Your Mastra agents continue to emit logs for tool steps and workflow decisions, and Orq records LLM interactions, latency, and cost metrics, so you can see both agent‑level and model‑level traces.
Step 3
Define routes, fallbacks, and policies in Orq
Create routes for key Mastra workflows (for example customer‑support agents, internal copilots, or multi‑tool orchestrators) and assign them model tiers, fallback chains, and region/data policies. Mastra sends LLM requests to the configured Orq routes, and Orq applies routing before invoking OpenAI, Gemini, Claude, or other models.
Step 4
Monitor, evaluate, and tune
Once connected, use Orq’s dashboards to watch latency, errors, and cost for Mastra agents, and run evals or experiments on their traces. You can adjust routes, models, or prompt configurations centrally where supported, while Mastra continues to coordinate tools, memory, and workflows.
Use Cases
Multi‑agent products with real observability
Trace which Mastra agent, tool, workflow step, and model contributed to a failed workflow or unexpected outcome, combining your own application logs with Orq’s router‑level LLM traces.
Cost‑aware internal tools
Route routine steps like simple QA, summarization, or routing decisions to lower‑cost models while keeping complex reasoning, multi‑tool orchestration, or safety‑critical flows on your strongest routes configured in Orq.
Eval‑driven agent improvements
Reuse failed conversations, mis‑routed tool calls, and slow agent runs as eval inputs before shipping prompt, workflow, or model changes, turning production telemetry into a continuous improvement loop.
Safer experimentation across providers
Test a new model or provider on a small share of Mastra traffic, then promote or roll back based on traces and evals, instead of editing each agent definition or LLM client config by hand.
FAQ
Do I have to change my Mastra code to use Orq.ai?
In many cases, you can repoint the LLM client Mastra uses (base URL, API key, and model identifier) to Orq’s router and keep your existing agent definitions, tools, and workflows as‑is, adding only minimal configuration instead of rewriting agents.
Does Orq.ai replace Mastra’s own runtime or framework?
No. Mastra remains your framework for building and running agents and workflows. Orq.ai sits alongside it as the control plane for models, multi‑provider routing, cost tracking, and evaluation. You still design and run agents with Mastra at the core, but you use Orq to see what they cost, which models they should call, and how LLM behavior compares across providers under the same agent workflow.
Can I keep using my existing LLM providers with Mastra if I move to Orq.ai?
Yes. You can bring your existing provider keys into Orq.ai and route Mastra traffic through them, alongside any new models you add later. That way you centralize access, routing, and tracking without losing the LLM setup you already rely on. Bring production controls to Mastra agents
