@b4run/ag-ui

Use this when#Copy link to section: Use this when

Use this package when a web client speaks AG-UI and your route emits B4.run stream chunks. Most applications should start with AG-UI and Web Clients. This reference is for wiring a custom transport or client adapter.

Install and import#Copy link to section: Install and import

npm install @b4run/ag-ui

import { fromRunAgentInput, toAguiEvents } from "@b4run/ag-ui"
import { encodeAgUiEvent } from "@b4run/ag-ui/sse"

A client that runs a B4.run route over HTTP, such as a CopilotKit runtime, imports the agent from the ./client subpath:

import { B4HttpAgent } from "@b4run/ag-ui/client"

A client in any framework folds the event stream into turns with the reducers from the ./view subpath:

import { reduceTurns } from "@b4run/ag-ui/view"

In a React client, and only there, import the activity kit from the ./react subpath:

import { ApprovalCard, TurnActivity } from "@b4run/ag-ui/react"

A React CopilotKit chat connects the kit through the ./react/copilotkit subpath, which is the only entry that imports @copilotkit/react-core:

import { B4Activity, useB4ChatSlots } from "@b4run/ag-ui/react/copilotkit"

In an Angular client, import the activity kit from the ./angular subpath, and connect it to a thread's events with ./angular/events or to CopilotKit's <copilot-chat> with ./angular/copilotkit, the only Angular entry that imports @copilotkit/angular:

import { TurnActivityComponent } from "@b4run/ag-ui/angular"
import { MessageActivityComponent, provideB4Turns } from "@b4run/ag-ui/angular/events"
import { provideB4Activity } from "@b4run/ag-ui/angular/copilotkit"

Both kits share one stylesheet, @b4run/ag-ui/styles.css.

A CopilotKit runtime route restores a conversation from B4's storage with createB4AgentRunner from the ./copilotkit-runtime subpath. The entry never imports @copilotkit/runtime: the route passes CopilotKit's InMemoryAgentRunner class in, so the runner extends whichever copy the route resolves, wherever the package manager placed it. It depends on rxjs, which installs with the package:

import { InMemoryAgentRunner } from "@copilotkit/runtime/v2"
import { createB4AgentRunner } from "@b4run/ag-ui/copilotkit-runtime"
 
const runner = createB4AgentRunner(InMemoryAgentRunner, { url, fetch })

Compatibility and audience#Copy link to section: Compatibility and audience

@ag-ui/client >=1.0.1 <2.0.0 is an optional peer. Runtime validators (RunAgentInputSchema, AgentCapabilitiesSchema, *EventSchema) live at @ag-ui/core/schemas in 1.0; import types from @ag-ui/core.

The adapter only translates protocol data, so it neither authenticates a caller nor makes client-supplied thread, run, state, tool, or context data authoritative.

@b4run/ag-ui/view is the framework-free client entry: pure reducers over AG-UI events with no React dependency. @b4run/ag-ui/react is the React activity kit built on it: TurnActivity, ApprovalCard and the step rows take the view core's props and render one turn in plain language. @b4run/ag-ui/react/copilotkit connects the kit to a stock CopilotKit chat. React and @copilotkit/react-core are optional peer dependencies, so a server that imports only the root or /sse entry installs neither; only ./react/copilotkit imports CopilotKit's React package. @ag-ui/client is the same kind of optional peer, needed only by ./client. The ./react entry is recorded as node-only because B4.run's edge guard requires an import graph free of unguarded Node globals, and React's JSX runtime reads process.env.NODE_ENV. It is meant for browser bundles, where your bundler substitutes that value. The ./react/copilotkit entry is recorded as browser-only: CopilotKit's bundle imports its own CSS, so plain Node cannot load it either. Browser bundles only: import it from a bundled React app, not from Node or an edge runtime.

@b4run/ag-ui/angular is the Angular activity kit, built on the same view core and rendering the same DOM contract as ./react; ./angular/events and ./angular/copilotkit connect it to a chat. @angular/core, @angular/common, @angular/platform-browser (^22.0.0) and @copilotkit/angular (>=0.5.3) are optional peer dependencies, and only ./angular/copilotkit imports CopilotKit's Angular package. The three Angular entries ship in Angular's partial compilation format, which your Angular build's linker finishes, so they are recorded as browser-only: import them from an Angular application built with the Angular CLI (@angular/build), not from Node or an edge runtime, where a plain import fails for want of Angular's JIT compiler.

Public exports#Copy link to section: Public exports

@b4run/ag-ui#Copy link to section: @b4run/ag-ui

@b4run/ag-ui/sse#Copy link to section: @b4run/ag-ui/sse

@b4run/ag-ui/client#Copy link to section: @b4run/ag-ui/client

@b4run/ag-ui/view#Copy link to section: @b4run/ag-ui/view

The framework-free half of the client: pure reducers and selectors over AG-UI events, with no React and no CopilotKit. ./react builds on it; so can any other framework. The runtime uses the same entry to serve GET /threads/:thread_id/turns, so a restored thread folds into the same TurnsView a live stream builds. It also holds the activity kit's framework-free rules (wording, durations, the open/closed rule, the clocks, the glyphs), so every kit words, times and draws a turn the same way.

@b4run/ag-ui/react#Copy link to section: @b4run/ag-ui/react

The React activity kit. Components are pure functions of the TurnView/StepView props @b4run/ag-ui/view builds; interaction state (open/closed, elapsed time, the 300 ms no-flash rule) lives in the hooks next to them.

TurnActivity is the drop-in: give it a TurnView from reduceTurns and it renders the turn. The kit components are plain React and don't need CopilotKit; the CopilotKit connector is @b4run/ag-ui/react/copilotkit.

@b4run/ag-ui/react/copilotkit#Copy link to section: @b4run/ag-ui/react/copilotkit

The CopilotKit (React) connector: it drives a stock <CopilotChat> with the activity kit.

@b4run/ag-ui/angular#Copy link to section: @b4run/ag-ui/angular

The Angular activity kit: standalone, OnPush components with signal inputs that render the same DOM contract (classes, data-* and aria-* attributes, text) as the React kit, from the TurnView/StepView values @b4run/ag-ui/view builds. Element hosts are display: contents; the step rows attach to the list item itself (<li b4-step>).

@b4run/ag-ui/angular/events#Copy link to section: @b4run/ag-ui/angular/events

The Angular kit's connector for any chat, with no chat framework: give it the thread's AG-UI events.

@b4run/ag-ui/angular/copilotkit#Copy link to section: @b4run/ag-ui/angular/copilotkit

The CopilotKit (Angular) connector, on @copilotkit/angular: it drives a stock <copilot-chat> with the activity kit.

@b4run/ag-ui/copilotkit-runtime#Copy link to section: @b4run/ag-ui/copilotkit-runtime

The server half of the CopilotKit connector, for the CopilotKit runtime route in your app. It uses only fetch and rxjs, so it runs in a Node or an edge runtime route.

@b4run/ag-ui/styles.css#Copy link to section: @b4run/ag-ui/styles.css

This subpath is the activity kits' default stylesheet, one sheet for the React and Angular kits. It has no TypeScript exports, runtime classification, or purity claim. A bundler resolves it, and it is never evaluated as JavaScript. Import it once, wherever your application imports its global CSS:

import "@b4run/ag-ui/styles.css"

In an Angular application, list it in angular.json's styles ("@b4run/ag-ui/styles.css") or @import it from a global stylesheet.

The sheet is optional, and the components render without it. Every rule sits in @layer b4-activity, so any unlayered app CSS wins, and every rule that styles an element is scoped to the b4- prefix, so it can't restyle the rest of your application.

The sheet also declares --b4-activity-* design tokens on :root. To restyle the kit, override these properties in your own CSS:

• --b4-activity-surface, --b4-activity-surface-alt, --b4-activity-border, --b4-activity-text, --b4-activity-muted
• --b4-activity-running, --b4-activity-running-bg, --b4-activity-complete, --b4-activity-failed, --b4-activity-failed-bg, --b4-activity-primary, --b4-activity-on-primary
• --b4-activity-radius, --b4-activity-radius-card, --b4-activity-radius-pill, and --b4-activity-font-mono

Put the overrides in plain, unlayered CSS. A Tailwind @theme block won't work, because token values declared there lose to this sheet. Dark mode follows the host, not the OS: the dark palette applies under a .dark or [data-theme="dark"] ancestor, or when data-b4-theme="dark" is set on the root element. data-b4-theme="light" pins light, and data-b4-theme="auto" follows prefers-color-scheme instead. The token blocks are wrapped in :where(), so your own :root override wins in every theme.

Key contracts#Copy link to section: Key contracts

Activity identifiers and payloads#Copy link to section: Activity identifiers and payloads

export declare const B4_PLAN_ACTIVITY_TYPE: "b4.plan"

export interface B4PlanActivityContent {
  readonly todos: ReadonlyArray<{
    readonly content: string
    readonly status: "pending" | "in_progress" | "completed"
  }>
}

Behavior contract ag-ui.activities.plan-snapshot

A valid plan update becomes a complete replacement snapshot with activity type b4.plan and the stable message ID b4:plan:<runId> without breaking an open assistant text message.

Behavior contract ag-ui.subagents.lifecycle

A subagent is announced with SUBAGENT_STARTED before any event is attributed to it, every event it produces carries its subagentRunId, and every announced invocation closes before RUN_FINISHED: with SUBAGENT_FINISHED on its result, suspended at an interrupt, or SUBAGENT_ERROR on failure, cancel, or a stream that ended first.

ToAguiOptions#Copy link to section: ToAguiOptions

Supply an IdFactory when emitted IDs must be deterministic. Production integrations use the default factory.

export interface ToAguiOptions {
  readonly idFactory?: IdFactory
  readonly cancelled?: () => boolean
  readonly pendingToolCallIds?: () => readonly string[] | Promise<readonly string[]>
}

Fields: @b4run/ag-ui#.:ToAguiOptions

Inbound and outbound calls#Copy link to section: Inbound and outbound calls

export interface B4RunInput {
  readonly messages: B4Message[]
  readonly resume?: B4ResumeRequest[]
  readonly raw: RunAgentInput
}

Fields: @b4run/ag-ui#.:B4RunInput

export interface B4Message {
  readonly role: "user" | "assistant" | "system" | "developer" | "tool"
  /** Plain text, or the ordered content parts the client sent (AG-UI 1.0). */
  readonly content: string | readonly B4ContentPart[]
  readonly id?: string
  readonly toolCallId?: string
}

B4ContentPart is exported by @b4run/sdk and is structurally AG-UI's ContentPart.

export interface RunContext {
  readonly threadId: string
  readonly runId: string
}

export interface B4UsageData {
  readonly provider?: string | undefined
  readonly model?: string | undefined
  readonly usage_metadata: Readonly<Record<string, unknown>>
}

Fields: @b4run/ag-ui#.:B4UsageData

export declare function fromRunAgentInput(input: RunAgentInput): B4RunInput

export declare function toAguiEvents(
  chunks: AsyncIterable<B4AgentStreamChunk>,
  ctx: RunContext,
  options?: ToAguiOptions,
): AsyncGenerator<AguiOutboundEvent>

export declare function encodeAgUiEvent(event: BaseEvent, accept?: string): Uint8Array<ArrayBuffer>

export declare function agUiContentType(accept?: string): string

export declare class B4HttpAgent extends HttpAgent {
  getCapabilities(): Promise<AgentCapabilities>
}

getCapabilities() sends GET to the agent's url with its headers and fetch, and parses the answer with AG-UI's AgentCapabilitiesSchema. It throws on a non-2xx answer.

Behavior contract ag-ui.outbound.errors-as-events

toAguiEvents turns an upstream throw into a final RUN_ERROR event and closes an open text frame instead of throwing to the consumer.

Behavior contract ag-ui.inbound.lossless-input

fromRunAgentInput maps supported messages and resume entries into B4.run shapes, omits resume for an empty array, and preserves the untouched AG-UI input under raw for tools, state, and context.

Stream edge cases#Copy link to section: Stream edge cases

Unknown chunk kinds are ignored after closing an open text frame. A stream that ends without done still finishes successfully. Interrupts are accumulated in the RUN_FINISHED outcome. After an interrupt, later non-interrupt chunks are suppressed until the outcome. A malformed interrupt terminates with RUN_ERROR. A step chunk becomes a CUSTOM event named b4.step; a malformed one is ignored.

fromRunAgentInput() normalizes messages and resume entries. It preserves the original input as raw, leaving tools, state, and context for application-owned validation and policy.

Examples and related guides#Copy link to section: Examples and related guides

import { type B4AgentStreamChunk, toAguiEvents } from "@b4run/ag-ui"
import { encodeAgUiEvent } from "@b4run/ag-ui/sse"
 
async function* aguiFrames(chunks: AsyncIterable<B4AgentStreamChunk>) {
  for await (const event of toAguiEvents(chunks, { threadId: "thread-1", runId: "run-1" })) {
    yield encodeAgUiEvent(event)
  }
}

Continue with AG-UI and Web Clients, Embed the Runtime, and Security Architecture.