Chapter 4: Create io.Assist

ACME Banking now has the two platform pieces the assistant needs:

• MCP Web running inside io.Connect Browser and exposing platform tools.
• A Mastra backend exposing the io.Intelligence Agent Protocol through AI Mastra Bridge.

In this chapter, you will create the actual io.Assist web app. The starter project includes two empty assistant shells, one Angular and one React. You can follow either implementation, or complete both if you want to compare the framework integrations.

Both versions use the same runtime idea:

• initialize io.Connect Browser from inside the assistant app
• point AI Web to the local backend
• connect AI Web to the MCP Web server running in the platform
• render the io.Assist UI
• identify the current user as an ACME Banking advisor

warning

The guide backend is intentionally open so the local sample is easy to run. A production deployment must protect the agent backend with proper authentication, authorization, transport security, and user-specific request headers.

Related API References

This chapter uses the ready-made io.Assist packages and the AI Web configuration they wrap:

• io.Assist NG Component API
• io.Assist NG Configuration
• io.Assist React Component API
• io.Assist React Configuration
• AI Web Configuration

Register The Assistant Apps

Before building either assistant, register both app shells in the platform configuration so io.Connect Browser can launch them.

Open:

io-assist-anywhere-start/apps/io-cb-home/src/config.json

Add io-assist-angular and io-assist-react to the apps array:

apps/io-cb-home/src/config.json

{
  "apps": [
    {
      "name": "client-list",
      "type": "window",
      "details": {
        "url": "http://localhost:4201"
      },
      "customProperties": {
        "includeInWorkspaces": true
      }
    },
    {
      "name": "client-portfolio",
      "type": "window",
      "details": {
        "url": "http://localhost:4202"
      },
      "customProperties": {
        "includeInWorkspaces": true
      }
    },
    {
      "name": "io-assist-angular",
      "type": "window",
      "details": {
        "url": "http://localhost:4003"
      },
      "customProperties": {
        "includeInWorkspaces": true
      }
    },
    {
      "name": "io-assist-react",
      "type": "window",
      "details": {
        "url": "http://localhost:4004"
      },
      "customProperties": {
        "includeInWorkspaces": true
      }
    }
  ]
}

The client-management workspace still opens the two banking apps by default. The assistant apps are registered so you can launch either assistant from the platform when you want to test it.

Confirm The Shared Browser Dependencies

From the frontend package root:

cd io-assist-anywhere-start

The frontend package already has @interopio/browser in its root package.json. This is intentional because the guide contains multiple apps that are io.Connect Browser clients. Keeping the browser package at the frontend package root makes the same browser API factory available to the platform and to the assistant apps.

Install the OpenTelemetry metrics package once for the frontend package:

npm install --save-dev @opentelemetry/sdk-metrics

The current browser dependency chain includes @interopio/insights-metrics, which imports @opentelemetry/sdk-metrics during bundling. Installing it at the frontend package root makes it available to all workspace apps without adding it separately to both assistant app packages.

Angular Implementation

Use this section if you want to build io.Assist with Angular.

Install The Angular Packages

Install the Angular assistant package in the Angular workspace:

npm install --workspace io-assist-angular @interopio/io-assist-ng @angular/cdk

These packages provide the io.Assist Angular component and UI dependencies used by the assistant. The IOBrowser factory used later in the chapter comes from the shared @interopio/browser dependency at the frontend package root.

Import The io.Assist Styles

Replace the contents of:

apps/io-assist-angular/src/styles.css

with:

apps/io-assist-angular/src/styles.css

@import "@interopio/io-assist-ng/styles.css";

html,
body {
    width: 100%;
    height: 100%;
    margin: 0;
}

The package stylesheet contains the base io.Assist UI styles and font assets. The html and body rules allow the assistant to fill the full app window.

Simplify The Angular Shell

Replace the contents of:

apps/io-assist-angular/src/app/app.css

with:

apps/io-assist-angular/src/app/app.css

:host {
    display: block;
    width: 100vw;
    height: 100vh;
}

Replace the generated Angular template with the assistant component:

apps/io-assist-angular/src/app/app.html

<io-assist [config]="dynamicConfig()" />

Update the root component:

apps/io-assist-angular/src/app/app.ts

import { Component, signal } from "@angular/core";
import { IoAssist, type IoAssistDynamicConfig } from "@interopio/io-assist-ng";

@Component({
    selector: "app-root",
    imports: [IoAssist],
    templateUrl: "./app.html",
    styleUrl: "./app.css",
})
export class App {
    protected readonly dynamicConfig = signal<IoAssistDynamicConfig>({
        user: {
            id: "acme-advisor",
            name: "ACME Advisor",
        },
    });
}

dynamicConfig contains runtime values. In this guide, the only runtime value is the current user. In a real ACME Banking deployment, this data would usually come from the authenticated session.

Configure The Angular Assistant

Open:

apps/io-assist-angular/src/app/app.config.ts

Replace it with:

apps/io-assist-angular/src/app/app.config.ts

import { ApplicationConfig, provideBrowserGlobalErrorListeners } from "@angular/core";
import IOBrowser from "@interopio/browser";
import { provideIoAssist } from "@interopio/io-assist-ng";

const AGENT_SERVER_URL = "http://localhost:4111";

export const appConfig: ApplicationConfig = {
    providers: [
        provideBrowserGlobalErrorListeners(),
        provideIoAssist({
            connectConfig: {
                browser: {
                    factory: IOBrowser,
                    config: {
                        modals: {
                            dialogs: {
                                enabled: true,
                            },
                        },
                    },
                },
            },
            defaultAgentName: "io-agent",
            aiWebConfig: {
                agentServer: {
                    baseUrl: AGENT_SERVER_URL,
                },
                mcp: {
                    clientsConfig: {
                        enforceStrictCapabilities: false,
                        capabilities: {},
                    },
                    ioIntel: {
                        web: {
                            enabled: true,
                        },
                    },
                },
            },
        }),
    ],
};

This is the complete static configuration for the Angular assistant.

React Implementation

Use this section if you want to build io.Assist with React.

Install The React Packages

Install the React assistant package in the React workspace:

npm install --workspace io-assist-react @interopio/io-assist-react

This package provides the React assistant component. The IOBrowser factory used later in the chapter comes from the shared @interopio/browser dependency at the frontend package root.

Import The io.Assist Styles

Replace the contents of:

apps/io-assist-react/src/index.css

with:

apps/io-assist-react/src/index.css

@import '@interopio/io-assist-react/styles';

html,
body,
#root {
  width: 100%;
  height: 100%;
  margin: 0;
}

The package stylesheet contains the base io.Assist UI styles and font assets. The root sizing rules let the assistant fill the full app window.

Simplify The React Shell

Replace the contents of:

apps/io-assist-react/src/App.css

with:

apps/io-assist-react/src/App.css

.assist-shell {
  width: 100vw;
  height: 100vh;
}

Replace the generated app component with the assistant:

apps/io-assist-react/src/App.tsx

import { useMemo } from 'react'
import IOBrowser from '@interopio/browser'
import {
  IoAssist,
  type IoAssistDynamicConfig,
  type IoAssistStaticConfig,
} from '@interopio/io-assist-react'
import './App.css'

const AGENT_SERVER_URL = 'http://localhost:4111'

const staticConfig: IoAssistStaticConfig = {
  connectConfig: {
    browser: {
      factory: IOBrowser,
      config: {
        modals: {
          dialogs: {
            enabled: true,
          },
        },
      },
    },
  },
  defaultAgentName: 'io-agent',
  aiWebConfig: {
    agentServer: {
      baseUrl: AGENT_SERVER_URL,
    },
    mcp: {
      clientsConfig: {
        enforceStrictCapabilities: false,
        capabilities: {},
      },
      ioIntel: {
        web: {
          enabled: true,
        },
      },
    },
  },
}

function App() {
  const dynamicConfig = useMemo<IoAssistDynamicConfig>(
    () => ({
      user: {
        id: 'acme-advisor',
        name: 'ACME Advisor',
      },
    }),
    [],
  )

  return (
    <main className="assist-shell">
      <IoAssist staticConfig={staticConfig} dynamicConfig={dynamicConfig} />
    </main>
  )
}

export default App

The React integration separates staticConfig from dynamicConfig. The static config defines the platform, backend, and MCP wiring. The dynamic config supplies user-specific runtime values.

Why The Configuration Matters

Both framework implementations use the same configuration concepts.

Property	Why it is needed
connectConfig.browser.factory	Tells io.Assist to initialize io.Connect Browser by using the IOBrowser factory. This lets the assistant run as an io.Connect app inside the platform instead of as a disconnected web page.
connectConfig.browser.config.modals.dialogs.enabled	Enables io.Connect dialogs for the assistant app. io.Assist can use elicitation and sampling flows that ask the user for input or approval, and the platform dialogs keep those prompts visually consistent with the rest of io.Connect Browser.
defaultAgentName	Selects the backend agent that io.Assist should use by default. In this guide, Chapter 3 exposed an agent named io-agent.
aiWebConfig.agentServer.baseUrl	Points AI Web to the local Mastra backend. The backend listens on http://localhost:4111 and exposes the /io-bridge routes added in Chapter 3.
aiWebConfig.mcp.clientsConfig.enforceStrictCapabilities	Keeps the guide's MCP client configuration permissive while connecting to the platform-hosted MCP Web server. This lets the assistant use the available tools without adding advanced capability negotiation to the beginner guide.
aiWebConfig.mcp.clientsConfig.capabilities	Provides the required client capabilities object. The empty object is enough for this chapter because the assistant only needs tool access from MCP Web.
aiWebConfig.mcp.ioIntel.web.enabled	Enables the io.Intelligence MCP Web client integration. This is what connects AI Web in the assistant app to the MCP Web server running in the io.Connect Browser platform.
dynamicConfig.user	Identifies the current assistant user. AI Web uses this identity for user-scoped operations such as thread ownership.

The key point is that io.Assist is not only rendering a chat component. It is joining the io.Connect Browser platform, connecting to the agent backend, and discovering tools from the MCP Web server that was added earlier.

Build The Assistant Apps

Build the Angular assistant:

npm run build --workspace io-assist-angular

Build the React assistant:

npm run build --workspace io-assist-react

You may see framework bundling warnings about CommonJS dependencies or large chunks. Those warnings are acceptable for this guide as long as the builds complete successfully.

Run The Full Local System

Start the backend in one terminal:

cd agentic-backend
npm start

Start the frontend package in another terminal:

cd io-assist-anywhere-start
npm start

Open the platform:

http://localhost:4200

Launch either io-assist-angular or io-assist-react from the platform. The assistant should load, connect to the backend, and connect to MCP Web.

Verify The Assistant

Send this message to the assistant:

Hi! What can you do for me?

You should receive a response that understands it is running inside io.Connect rather than in a generic web environment.

That response confirms the important integration path for this chapter:

• the io.Assist UI is running
• io.Connect Browser initialized inside the assistant app
• AI Web can reach the Mastra backend
• the backend can answer through the io.Intelligence Agent Protocol

At this point, ACME Banking has a running io.Assist web app that can talk to the backend. In the next chapters, you will make that assistant more useful by connecting it to the client workflow.