Add AIP to a React app

The library is the agent-interface-protocol package in packages/aip. The React bindings need nothing beyond React.

The package isn’t published to npm yet. Until it is, add the repo as a workspace or copy packages/aip into your project.

Import	Contents
`agent-interface-protocol`	Types, validators, `agentInstructions`, `readJsonResponse` (browser and server safe)
`agent-interface-protocol/react`	`AgentInterfaceProvider`, `useAgentState`, `useAgentAction`, `useAgentStore`
`agent-interface-protocol/vanilla`	`startAgentInterface`, `registry`
`agent-interface-protocol/server`	`createBridge`, `createDiscovery`, `createMemoryStorage`
`agent-interface-protocol/vite`	`agentInterfacePlugin` for `vite dev` / `vite preview`

1. Wrap your app

import { AgentInterfaceProvider } from "agent-interface-protocol/react";

export function App() {
  return (
    <AgentInterfaceProvider pages={["/control-panel"]} instructions="Reject requests only when the user asks.">
      <ControlPanel />
    </AgentInterfaceProvider>
  );
}

The provider creates the session, shows the token and agent instructions, syncs snapshots and polls for invocations. pages limits it to your agent-enabled pathnames (omit it to connect everywhere); widgetStyle styles its built-in connection panel.

2. Publish state

import { useAgentState } from "agent-interface-protocol/react";

function ControlPanel() {
  const requests = useRequests();
  useAgentState("requests", requests);
  // ...
}

Every key you publish appears under state in the manifest and updates live. Unmounting removes it. If your state lives in a zustand store, publish the whole store at once:

import { useAgentStore } from "agent-interface-protocol/react";
useAgentStore(useCartStore, "cart");

3. Register actions

import { useAgentAction } from "agent-interface-protocol/react";

const approve = useAgentAction(
  {
    id: "approve_request",
    description: "Approve one pending request",
    input_schema: {
      type: "string",
      description: "The request ID itself; do not wrap it in an object",
      minLength: 1,
    },
    input_example: "req-3",
    consequential: true,
  },
  (id: string) => approveRequest(id),
);

return <button onClick={() => approve(request.id)}>Approve</button>;

The returned function is the same handler the agent calls. Wire your button to it and humans and agents share one code path. Throwing from a handler returns 422 with your error message to the agent.

Input schemas

0.1 supports two shapes:

// A single string
{ type: "string", description: "...", minLength?: number }

// A flat object of strings
{
  type: "object",
  description: "...",
  properties: { username: { type: "string", description: "..." } },
  required: ["username"],
  additionalProperties: false,
}

Numbers are passed as strings (for example "quantity": "2"). Metadata is validated when registered, and input_example must itself be valid.

4. Serve the bridge

Create a bridge for the page, serve discovery, and mount both into Vite:

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { agentInterfacePlugin } from "agent-interface-protocol/vite";
import { createBridge, createDiscovery, createMemoryStorage } from "agent-interface-protocol/server";

const bridge = createBridge(createMemoryStorage(), 8000, [], "/control-panel");
const discovery = createDiscovery({
  title: "My app",
  pages: [{ url: "/control-panel", title: "Approvals", description: "Approve or reject requests", login_required: false }],
});

export default defineConfig({
  plugins: [
    react(),
    agentInterfacePlugin({
      handle: async (request) => discovery(request) ?? bridge(request),
      match: (path) => path === "/control-panel.toon" || path === "/control-panel.json",
    }),
  ],
});

createBridge(storage, waitMs, publicActions, page, pages): publicActions is the catalog agents see without a session, and pages lists every AIP page on the site. The demo’s server/application.ts shows a fuller setup with login and two pages. For production hosting, see Deploy.

Getting started

Learn

Develop

Specification

Security

Community

1. Wrap your app

2. Publish state

3. Register actions

Input schemas

4. Serve the bridge

​1. Wrap your app

​2. Publish state

​3. Register actions

​Input schemas

​4. Serve the bridge

1. Wrap your app

2. Publish state

3. Register actions

Input schemas

4. Serve the bridge