@agent-provider/react

React bindings and a reference chat surface for Agent Provider.

npm install @agent-provider/react react react-dom

Import @agent-provider/react/styles.css when using the reference UI. The headless runtime remains available separately from @agent-provider/runtime.

What it does

Agent Provider lets a trusted web application run a typed, tool-using AI agent without owning the user's model credentials. Credentials live in the browser extension and are only released to an origin after an explicit, exact-origin grant; page code never sees them. This package provides the React half of that contract: a context provider and hooks that expose the runtime's observable state, plus a reference chat surface (AgentProviderChat and AgentProviderLauncher) that handles connection status, permission prompts, tool-approval requests, and streaming messages out of the box.

Quick start

Create a runtime with @agent-provider/runtime, hand it to AgentProviderProvider, and render the launcher:

import { instantChatbot } from "@agent-provider/runtime";
import {
  AgentProviderProvider,
  AgentProviderLauncher,
} from "@agent-provider/react";
import "@agent-provider/react/styles.css";

const runtime = instantChatbot({
  appName: "My App",
  modelAlias: "default",
  instructions: "You are the copilot for this page.",
});

export function App() {
  return (
    <AgentProviderProvider runtime={runtime} destroyOnUnmount>
      <AgentProviderLauncher title="My App copilot" />
    </AgentProviderProvider>
  );
}

Model execution requires the Agent Provider browser extension and an exact-origin grant from the user; without them the surface renders a status message instead of a working chat.

Exports

Components:

• AgentProviderProvider — supplies an AgentProviderRuntime to the tree. Pass destroyOnUnmount to destroy the runtime when the provider unmounts.
• AgentProviderChat — inline reference chat surface: transcript, composer, connection/permission status, approvals, and tool activity.
• AgentProviderLauncher — toggleable button that opens an AgentProviderChat panel. The panel stays mounted while closed and fades/slides via CSS (driven by data-open on the launcher wrapper), so the transcript survives open/close; this also means the chat's auto-connect probe fires when the launcher mounts, not on first open. Placement is a first-class host choice: pass placement (bottom-right default, also bottom-left, top-right, top-left) and optional insets ({ top, right, bottom, left } as px numbers or CSS lengths). These set data-placement and the --agent-provider-inset-* custom properties, so a host stylesheet can drive the same knobs without a prop. To show/hide the whole launcher with the same fade (e.g. while probing for the extension), set visible={false} or data-visible="false" on the .agent-provider-launcher element.

New in 0.1.5 — toolResultRenderer prop on AgentProviderChat and AgentProviderLauncher. When provided, the expanded tool-call Result section shows a [rendered|pretty|raw] button group that fades in. "rendered" calls the host function with the full ToolActivity and displays its React output. Without a renderer, the toggle shows [pretty|raw].

import type { ToolResultRenderer } from "@agent-provider/react";

const renderResult: ToolResultRenderer = (activity) => {
  if (activity.toolName === "get_weather") {
    return <WeatherCard data={activity.output} />;
  }
  return <pre>{JSON.stringify(activity.output, null, 2)}</pre>;
};

<AgentProviderChat toolResultRenderer={renderResult} />;

New in 0.1.4 — additional props on AgentProviderChat and AgentProviderLauncher:

| Prop | Type | Default | Purpose | | ------------------ | ------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- | | headerLabel | string \| ((info: { toolCount: number; modelLabel: string }) => string) | auto | Override the header subtitle. Default: Page tools (n) · Model: gpt-5-mini high | | thinkingColor | string | accent | CSS color for thinking dots (also via --agent-provider-thinking) | | markdown | boolean | true | Render assistant messages with markdown formatting | | draggable | boolean | false | Let the launcher panel be dragged out of its docked corner | | showToolActivity | boolean | true | Show collapsible tool-call indicators |

Also new in 0.1.4: assistant message role label is "Agent" (was "AgentProvider"). Tool-call indicators show live status dots, tool name, and phase; click to expand args/results (collapsed by default). Error messages show a warning icon in the far empty space of each message row. The launcher's draggable prop adds a drag handle to pop the panel out to a fixed position.

Hooks (must be used inside AgentProviderProvider):

• useAgentProviderRuntime() — the runtime instance.
• useAgentProviderState() — the current AgentProviderRuntimeState (connection, run state, messages, approvals, tool activity), subscribed via useSyncExternalStore.

Props and component-override types: AgentProviderProviderProps, AgentProviderChatProps, AgentProviderLauncherProps, and AgentProviderChatComponents (override the Button, Textarea, Message, Approval, and Activity slots of the reference UI).

Notes

• ESM-only. Requires React and React DOM 18.3 or newer (peer dependencies).
• The reference UI runs in the page's DOM; it needs a browser environment and a page willing to host it. The runtime itself never reads the DOM directly — page context is supplied explicitly, e.g. via @agent-provider/context.
• styles.css is only needed for the reference UI; headless usage through the hooks needs no stylesheet. The CSS is the package's only declared side effect.
• Provider credentials are configured in the extension, never in page code. Every page tool keeps ordinary server-side authorization and validation; see the repository's threat model.

Links

• Repository: https://github.com/clankercode/agent-provider
• @agent-provider/runtime — headless runtime, tools, approvals, run state.
• @agent-provider/context — bounded, revisioned page-context extraction.
• examples/operations-dashboard in the repository — a runnable trusted-app integration using this package.

License

CC0-1.0 OR Unlicense.