Skip to main content

Capabilities

AI Web is the product-facing runtime in the io.Intelligence stack. It collects the assistant building blocks that custom web applications typically need and exposes them through one frontend SDK. This page focuses on what that means in practice.

Custom Experience Toolkit

AI Web combines assistant runs, MCP connectivity, threads, and interactive apps in one browser-facing layer.

That combination matters because most custom copilots become difficult when those responsibilities are scattered across multiple client integrations. AI Web gives you one place to coordinate them.

Capability Areas at a Glance​

Agent runs

Start streaming or generated runs against backends that implement the io.Intelligence Agent Protocol and keep frontend event handling consistent.

Conversation state

Create persistent threads, reload message history, and keep conversations scoped to a user, session, or workflow.

MCP access

Discover tools and resources from the io.Intelligence MCP server plus additional remote MCP servers.

Interactive UI

Render MCP Apps inline or in workspaces when a tool result needs a richer visual surface than plain chat text.

Run Agents from Product Code​

AI Web gives the frontend direct control over assistant execution. You can list agents, start runs, subscribe to streaming events, or ask for a simpler generated response when streaming is not necessary.

CapabilityWhy it matters
Streaming runsPower live assistant interfaces, progressive rendering, and richer step-by-step feedback
Generated responsesUse the same backend contract for simpler "ask and render" flows
Abort supportStop active runs when the user changes course
Stable event modelKeep the UI logic consistent across backends that implement the same protocol
agent-run.ts
const agents = await aiWeb.agents.list();
const agent = agents[0];

const stream = await agent.stream({
  messages: "Summarize the active workflow and highlight open actions.",
  resourceId: "user-123",
});

stream.subscribe({
  next: (event) => {
    if (event.type === "TEXT_MESSAGE_CONTENT") {
      console.log("delta", event.delta);
    }
  },
});

Keep Conversations Persistent​

AI Web treats threads as a first-class concern rather than something every application needs to invent separately.

This is especially useful when users return to earlier work, when assistants are tied to a specific business process, or when multiple product surfaces need to reopen the same conversation.

Thread capabilityOutcome
Create threadsStart a conversation with a stable identifier
List and reopen threadsResume earlier work instead of starting over
Scope by resourceKeep history aligned to a user or business entity
Message retrievalRebuild or inspect conversation history in custom UI

Aggregate MCP Servers Behind One Frontend API​

AI Web acts as an MCP host. It can connect to the io.Intelligence MCP server through the io.Connect environment, connect to it remotely over Streamable HTTP, or add other remote MCP servers alongside it.

Why this matters

Many assistant products need both internal application capabilities and external or third-party tools. AI Web lets the frontend combine those sources without forcing the product UI to understand multiple MCP transports.

mcp-config.ts
const aiWeb = await IoAiWebFactory(io, {
  agentServer: {
    baseUrl: "http://localhost:4111",
  },
  mcp: {
    clientsConfig: {
      capabilities: {},
    },
    ioIntel: {
      web: {
        hasPriority: false,
      },
      remote: {
        streamableHttp: {
          url: "http://localhost:8989/mcp",
          name: "primary-remote-server",
        },
      },
    },
    remoteServers: [
      {
        streamableHttp: {
          url: "http://localhost:8081/mcp",
          name: "secondary-mcp-server",
        },
      },
    ],
  },
});

What becomes available​

  • discover tool definitions and invoke tools from application code
  • list and read MCP resources
  • keep the product UI focused on user experience while AI Web handles transport concerns

Ground Runs in Business Context​

When you pair AI Web with Working Context, the assistant can receive live business context from io.Connect instead of relying only on whatever the user typed in the current message.

Context-aware behaviorBenefit
Live workflow awarenessResponses can reflect the user's current selection, workspace, or shared context
Less repetitionUsers do not need to restate the same context in every request
Better orchestrationTool calls and follow-up actions can align with what the user is already doing
context-config.ts
import { IoIntelWorkingContextFactory } from "@interopio/working-context";

const aiWeb = await IoAiWebFactory(io, {
  agentServer: {
    baseUrl: "http://localhost:4111",
  },
  context: {
    factory: IoIntelWorkingContextFactory,
    config: {
      schema: {
        clientId: {
          type: "string",
          source: {
            context: {
              location: { workspace: { target: "my" } },
              path: "client.id",
            },
          },
        },
      },
    },
  },
});

Launch MCP Apps When Text Is Not Enough​

Some assistant interactions are better as applications than as paragraphs. When an MCP tool returns an interactive UI resource, AI Web handles the entire MCP App lifecycle automatically — no extra orchestration code needed in your frontend.

Rendering modeBest for
InlineEmbedded panels, assistants inside dashboards, compact contextual UI
WorkspaceLarger multi-window flows and richer task execution inside io.Connect

What AI Web Manages for You​

When MCP Apps are enabled, AI Web intercepts the AG-UI stream transparently. As soon as a tool call with a UI resource appears in a run, AI Web:

  • Creates and manages the app instance lifecycle (create, replace, close)
  • Resolves the display mode automatically — inline when no workspace is active, workspace window when one is
  • Loads the MCP HTML resource and delivers it through a sandboxed proxy iframe
  • Establishes bidirectional communication between the host and the embedded app
  • Forwards tool call arguments and results to the app as the stream progresses
  • Persists app state across thread switches and restores it when the user returns
  • Broadcasts response-generation status to all active apps so they can lock their controls while the AI is working

None of this requires custom stream handling in your application code.

For how the proxy layer works — including the ready-made proxy you can serve as-is and guidance on building your own — see The Sandbox Proxy.

What You Can Do with the MCP Apps API​

Once configured, aiWeb.mcpApps exposes the full app management surface:

mcp-apps-integration.ts
import { IoAiWebFactory } from "@interopio/ai-web";

const aiWeb = await IoAiWebFactory(io, {
  agentServer: { baseUrl: "http://localhost:4111" },
  mcp: {
    clientsConfig: {
      capabilities: {
        extensions: {
          "io.modelcontextprotocol/ui": {
            mimeTypes: ["text/html;profile=mcp-app"],
          },
        },
      },
    },
    mcpApps: {
      sandboxProxyUrl: "/sandbox-proxy.html",
      displayMode: "workspace", // or 'inline', or omit for auto-detection
    },
  },
});

// React when a new app is created for the current thread
aiWeb.mcpApps.onAppCreated((app) => {
  if (app.displayMode === "inline" && app.element) {
    // Mount the app DOM element into your chat UI
    document.getElementById("app-container").appendChild(app.element);
  }
  // Listen for messages the app posts back to the conversation
  app.onMessage((text) => {
    injectUserMessage(text);
  });
});

// Handle the case where the AI calls the same tool twice
aiWeb.mcpApps.onRecreateRequested(async (event) => {
  const choice = await showReplaceDialog(event.toolName);
  // Options: 'recreateOldest' | 'recreateAll' | 'newInstance'
  await event.select(choice);
});

// Notify apps when the AI starts or stops generating
aiWeb.mcpApps.notifyPendingResponse(true);  // AI generating
aiWeb.mcpApps.notifyPendingResponse(false); // AI done

// Restore apps when switching back to an existing thread
await aiWeb.mcpApps.recreate({
  threadId: "thread-123",
  apps: activeToolCallsForThread,
});

// Close all apps when switching to a new empty thread
await aiWeb.mcpApps.closeAll();
Best for
  • workflows where the assistant should open a form, review screen, or action panel
  • embedded applications that need to exchange messages with the host application
  • teams that want the assistant to trigger real product UI, not just return prose

→ For a full explanation of MCP Apps, display modes, and the custom notification layer, see MCP Apps.

Participate in MCP Capability Flows​

AI Web can also advertise and handle MCP client capabilities such as sampling or elicitation. That lets the host application participate when an MCP server needs confirmation, model-based decision support, or user input.

This is one of the reasons AI Web works well for advanced assistant products: it is not just a chat transport, it is the application-side runtime for the broader assistant loop.

Next Steps​