Skip to main content

Examples

These examples are based on the released package API and the reference backend app in apps/io-assist-mastra.

Minimal Registration​

Use this pattern when you want the smallest working bridge integration inside a Mastra app.

import 'reflect-metadata';
import { Mastra } from '@mastra/core/mastra';
import { IoMastraBridgeFactory } from '@interopio/ai-mastra-bridge';
import { myAgent } from './agents/my-agent';

const bridge = IoMastraBridgeFactory();

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

Custom Prefix​

Use a custom prefix when the bridge should live under an existing API namespace.

const bridge = IoMastraBridgeFactory({
  prefix: '/api/v1/agent',
});

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

With this configuration, the streaming route becomes POST /api/v1/agent/run.

Production-Oriented Host Pattern​

The reference app uses a richer host setup around the bridge:

import 'reflect-metadata';
import { Mastra } from '@mastra/core/mastra';
import { IoMastraBridgeFactory } from '@interopio/ai-mastra-bridge';
import { LibSQLStore } from '@mastra/libsql';
import { PinoLogger } from '@mastra/loggers';
import { Observability, DefaultExporter } from '@mastra/observability';

const bridge = IoMastraBridgeFactory();

export const mastra = new Mastra({
  agents: { ioAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'io-assist-mastra',
        exporters: [new DefaultExporter()],
      },
    },
  }),
  server: {
    apiRoutes: [...bridge.createHonoRoutes()],
    middleware: [
      async (c, next) => {
        console.log(`${c.req.method} ${c.req.url}`);
        await next();
      },
      {
        handler: authMiddlewareHandler,
        path: '/api/*',
      },
    ],
  },
});

This pattern is a good fit when the bridge is part of a broader backend with storage, logging, observability, and request policies.

Frontend Pairing​

Once the bridge is running, frontend clients typically point their agent-server base URL at the Mastra host:

agentServer: {
  baseUrl: 'http://localhost:4111',
}

This is the common pairing for:

Structured Output and Frontend Tools​

The bridge types also support:

  • frontend-declared tools through tools
  • structured output constraints through structuredOutput

Those values are part of the run flow when the frontend needs to:

  • let the LLM request a client-side tool
  • constrain the final LLM response to a JSON schema

Use those features from the frontend run request side, while the bridge takes care of translating the resulting stream and proxying frontend tool execution back into Mastra's live tool loop.