Chapter 3: Configure The Agent Backend

In Chapter 2, ACME Banking's io.Connect Browser platform gained an MCP Web server and one MCP tool for reading the client list.

The next piece is the agent backend. The assistant frontend you build in the next chapter will use AI Web, and AI Web expects the backend to speak the io.Intelligence Agent Protocol. That protocol is based on AG-UI and defines routes for agent discovery, thread management, streaming runs, and frontend tool results.

In this chapter, you will add AI Mastra Bridge to the root-level Mastra backend so it exposes that protocol.

Use these references when wiring the backend protocol:

Open The Backend Package

The backend is not inside the frontend Lerna package. From the guide repository root, open the standalone backend:

cd agentic-backend

Its source lives under:

agentic-backend/src/mastra/

The backend already contains a minimal io-agent and a Mastra application setup.

Install AI Mastra Bridge

Install the bridge package in the backend package:

npm install @interopio/ai-mastra-bridge

This package creates Hono route definitions that can be registered directly in the Mastra server configuration.

After installation, agentic-backend/package.json should include:

agentic-backend/package.json
{
  "dependencies": {
    "@interopio/ai-mastra-bridge": "^1.1.0"
  }
}

Your file will contain the rest of the existing Mastra and model dependencies too.

Register The Bridge Routes

Open:

agentic-backend/src/mastra/index.ts

Import IoMastraBridgeFactory, create the bridge, and add its routes to the Mastra server config:

agentic-backend/src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra';
import { PinoLogger } from '@mastra/loggers';
import { LibSQLStore } from '@mastra/libsql';
import { IoMastraBridgeFactory } from '@interopio/ai-mastra-bridge';
import { ioAgent } from './agents/io-agent';

const bridge = IoMastraBridgeFactory();

export const mastra = new Mastra({
    agents: { ioAgent },
    storage: new LibSQLStore({
        id: 'mastra-storage',
        url: ':memory:'
    }),
    logger: new PinoLogger({
        name: 'Mastra',
        level: 'info'
    }),
    server: {
        apiRoutes: [...bridge.createHonoRoutes()]
    }
});

IoMastraBridgeFactory() uses the default /io-bridge prefix. With this setup, the backend exposes routes such as:

Route	Purpose
`GET /io-bridge/agents`	List available agents
`GET /io-bridge/agents/:agentId`	Read one agent
`POST /io-bridge/threads`	Create a conversation thread
`GET /io-bridge/threads`	List conversation threads
`GET /io-bridge/threads/:threadId/messages`	Read thread messages
`POST /io-bridge/run`	Start a streaming assistant run

The bridge handles the protocol translation between AI Web's AG-UI-based request and response model and the Mastra runtime.

Build The Backend

Run a backend build:

npm run build

The build should complete successfully and generate Mastra output under .mastra/output.

Start The Backend

Start the backend:

npm start

Mastra prints the local Studio and API URLs:

Studio: http://localhost:4111
API:    http://localhost:4111/api

If port 4111 is already in use, Mastra may choose another port. Use the port printed in your terminal for the checks below.

Verify The Bridge Routes

In another terminal, call the agent discovery route:

curl http://localhost:4111/io-bridge/agents

You should see the io-agent:

[
  {
    "id": "io-agent",
    "name": "IO Agent"
  }
]

Create a test thread:

curl -X POST http://localhost:4111/io-bridge/threads \
  -H "Content-Type: application/json" \
  -d '{"resourceId":"guide-user","title":"Guide validation"}'

The response should include a generated thread id, the resourceId, and timestamps:

{
  "id": "generated-thread-id",
  "resourceId": "guide-user",
  "title": "Guide validation",
  "createdAt": "2026-05-31T16:22:19.506Z",
  "updatedAt": "2026-05-31T16:22:19.506Z"
}

You can also confirm that the run route is active by sending an intentionally invalid body:

curl -X POST http://localhost:4111/io-bridge/run \
  -H "Content-Type: application/json" \
  -d '{}'

The bridge should reject it with a validation error:

{
  "error": "Invalid RunAgentInput: threadId: Required; runId: Required; messages: Required; tools: Required; context: Required",
  "code": "INVALID_INPUT"
}

That error is useful here. It means the request reached AI Mastra Bridge and the bridge is enforcing the protocol boundary.

What You Have Now

ACME Banking now has:

an io.Connect Browser platform with MCP Web
a get_clients MCP tool backed by the platform's getClients method
a Mastra backend exposing the /io-bridge protocol routes
one available backend agent, io-agent

The frontend and backend are now ready to speak the same protocol. In the next chapter, you will create the assistant web app and connect it to this backend.

Related API References​

Open The Backend Package​

Install AI Mastra Bridge​

Register The Bridge Routes​

Build The Backend​

Start The Backend​

Verify The Bridge Routes​

What You Have Now​

Related API References