Skip to main content

Overview

AI Mastra Bridge is the backend package for teams using Mastra as the agent runtime and frontend clients that speak the io.Intelligence Agent Protocol. It turns a Mastra application into a clean bridge service that can stream agent runs, expose agents, and manage conversation threads through a stable HTTP API.

It is the first released item in the AI Server module offering.

If AI Web and io.Assist NG are the frontend side of the integration, AI Mastra Bridge is one of the simplest ways to supply the backend contract they expect.

Mastra Backend Adapter

AI Mastra Bridge turns a Mastra runtime into a frontend-ready assistant backend with a cleaner contract.

It exists so backend teams do not have to make frontend clients understand Mastra's native streaming behavior, route shapes, or tool-loop quirks. The bridge absorbs that complexity and exposes the io.Intelligence Agent Protocol instead.

Why Teams Choose AI Mastra Bridge​

Standardize the backend contract

Expose runs, agents, threads, and messages through a route surface that frontend assistant clients can understand consistently.

Translate streaming behavior

Convert Mastra stream chunks into AG-UI events so frontend logic stays predictable.

Support frontend tool proxying

Let frontend-owned tools participate in Mastra's normal tool loop and memory flow without a rerun workaround.

Keep thread access practical

Give clients a clear thread API instead of exposing Mastra-specific backend details directly.

What AI Mastra Bridge Does​

Bridges Mastra to the io.Intelligence Agent Protocol​

Mastra has its own streaming model, while io.Intelligence frontends expect the io.Intelligence Agent Protocol, which is AG-UI-based but also defines route behavior, thread APIs, and frontend tool execution rules. AI Mastra Bridge translates between those models so frontend applications receive one predictable contract.

Exposes a Route Surface for Frontends​

The bridge provides Hono route definitions that you register into the Mastra server. Those routes cover:

  • streaming runs
  • agent discovery
  • thread creation and retrieval
  • thread updates and deletion
  • thread message retrieval

Supports Frontend Tool Execution​

When the frontend needs to execute a tool, the bridge proxies that tool into Mastra as a temporary backend tool and accepts the result on a dedicated callback route. That lets Mastra continue the same run and persist the outcome through its normal memory flow.

Keeps Thread Management in One Place​

The frontend can work with a clean thread API without needing to speak directly to Mastra's own internals or REST surface.

Who It Helps​

AudienceWhy it matters
Backend teamsIntegrate Mastra once and expose a cleaner contract to every assistant client
Frontend teamsConsume a stable route and event model without becoming experts in Mastra stream behavior
Platform teamsStandardize how Mastra-based assistants are exposed across products
Product ownersReduce the integration gap between an agent runtime and a usable assistant experience

When to Use AI Mastra Bridge​

AI Mastra Bridge is a good fit when you want to:

  • use Mastra as the backend runtime for an io.Intelligence assistant
  • support AI Web or io.Assist NG on the frontend
  • expose a stable route contract for runs, agents, and threads
  • avoid translating Mastra stream behavior yourself

If your backend is not Mastra-based, this package is probably not the right entry point. In that case, match the same io.Intelligence Agent Protocol with a different backend integration.

Minimal Mental Model​

mastra.ts
import "reflect-metadata";
import { Mastra } from "@mastra/core/mastra";
import { IoMastraBridgeFactory } from "@interopio/ai-mastra-bridge";

const bridge = IoMastraBridgeFactory({ prefix: "/io-bridge" });

export const mastra = new Mastra({
  agents: { myAgent },
  server: {
    apiRoutes: [...bridge.createHonoRoutes()],
  },
});

This small amount of setup is the point of the package. Instead of hand-building a translation layer, you register the bridge and give frontend assistant clients a route model they can start using.

How It Fits in the Stack​

AI Mastra Bridge usually sits between the frontend assistant client and the Mastra runtime:

  • Step 1 A frontend such as AI Web or io.Assist NG sends run and thread requests to the bridge.

  • Step 2 The bridge calls Mastra agents and reads Mastra memory where available.

  • Step 3 Mastra stream chunks are translated into the protocol event sequence expected by the frontend.

  • Step 4 The frontend keeps a stable assistant experience without knowing backend-specific translation details.

Typical Host Application Pattern​

In practice, host applications usually:

  1. import reflect-metadata once at startup
  2. create a bridge with IoMastraBridgeFactory()
  3. register bridge.createHonoRoutes() into Mastra apiRoutes
  4. add middleware for logging, auth, or deployment-specific policies around those routes

That is also the pattern used by the reference app in apps/io-assist-mastra.

What You Need Before You Start​

Typical prerequisites:

  • a Mastra application
  • reflect-metadata imported in the host entry point
  • at least one Mastra agent
  • Mastra memory configured if you want thread CRUD behavior
  • peer dependencies such as @mastra/core and hono

Without memory configured on at least one agent, thread operations cannot behave as a persistent thread API.

AI Mastra Bridge is commonly paired with:

  • AI Web for custom frontend assistants
  • io.Assist NG for Angular applications that want the ready-made assistant UI
  • MCP when frontend assistants also need tools, resources, and prompts from io.Connect applications
  • Working Context when assistants should stay aware of user workflow context
  • Agent Protocol Reference for the shared contract this package implements

Next Steps​

Continue with: