Architecture overview

Context

AgentsKit provides framework-neutral chat state and bindings for React, Vue, Svelte, Solid, Angular, React Native, and Ink. Building a product-grade interactive agent experience still requires teams to assemble deterministic routing, structured turns, action policy, component registries, sessions, streaming, persistence, replay, theming, and framework-specific shells.

AgentsKit Chat is the opinionated application framework above those primitives.

Architectural style

The project begins as a TypeScript modular monorepo. Shared behavior is organized around deep, testable contracts; native renderers remain thin adapters over the corresponding AgentsKit binding.

Product boundary

AgentsKit owns adapters, model invocation, tools, memory, RAG, agent runtime, chat controller, and base framework bindings. AgentsKit Chat owns application definitions, the turn pipeline, deterministic interaction, action policy, session protocol, semantic component manifests, native application shells, scaffolding, and parity tooling.

ADR-0002 makes this boundary enforceable: AgentsKit Chat composes published AgentsKit APIs. Missing or defective framework-neutral primitives are changed at the source in AgentsKit-io/agentskit before this repository consumes them.

The concrete source-to-responsibility mapping lives in the AgentsKit upstream adoption matrix. It is revalidated by each implementation issue rather than treated as permanently current.

Containers

Application
├── shared chat definition
├── AgentsKit Chat server/runtime
│   └── AgentsKit runtime, adapters, tools, memory, and RAG
└── native client renderer
    └── corresponding AgentsKit UI binding

Planned modules

Core

Defines chats that compile to or derive AgentsKit ChatConfig, plus deterministic application routes, component manifests, conversation machines, and policy composition. It does not implement another controller, tool loop, confirmation engine, or model runtime.

Conversation machines compile to the published @agentskit/statechart primitive. The Chat layer retains only application route matching, adapter composition, actions, traces, and session decision replay (ADR-0023).

Protocol

Owns application-specific client-server events, runtime schemas, serialization, resumption, compatibility fixtures, and semantic fallbacks. Existing AgentsKit lifecycle and UI semantics are transported without being renamed or reimplemented.

Server

Mounts chat definitions onto Web-standard handlers and provides context, authentication seams, sessions, persistence ports, streaming, cancellation, and audit hooks.

The first server slice is @agentskit/chat-server: a Web Request/Response handler that authenticates before parsing, drives the upstream controller, and streams versioned full snapshots as NDJSON. Framework HTTP adapters remain thin host bridges.

The trusted Ask vertical composes deterministic escalation with authenticated site configuration, injected local/federated AgentsKit retrieval, cited Ask events, CAS persistence, cancellation, and privacy-safe baseline metrics. The same public contracts run hosted or self-hosted (ADR-0026).

Native renderers

React, Vue, Svelte, Solid, Angular, React Native, and Ink renderers consume the protocol and the matching AgentsKit package. Custom visual implementations are platform-specific; component identity, props schema, actions, and fallback behavior are shared.

The first renderer set shares a runtime-validated semantic application theme and maps it through upstream CSS variables, React Native styles, and Ink theming. Composition slots remain native to each renderer, while fully headless state remains the corresponding AgentsKit useChat API (ADR-0013).

The Vue renderer uses native named scoped slots and the controller-free ChatRoot released upstream in @agentskit/vue@0.4.4. Its application behavior remains identical to the shared renderer contract; no Vue reactive state is introduced downstream.

The Svelte renderer uses the upstream createChatStore and Svelte 5 snippets. Store replacement is isolated to a keyed binding; an active store is cancelled through its upstream stop action before replacement, while application/session state stays mounted.

The Solid renderer uses upstream useChat and native signals, control flow, and render props. Keyed owners isolate session and config identity; owner cleanup cancels active streams through @agentskit/solid@0.4.4.

The Angular renderer uses the upstream AgentskitChat signal service and standalone components. A component-scoped provider isolates every shell; Angular content templates customize application surfaces, and upstream destroy() owns active-stream cancellation.

The closed standard catalog adds 12 application components through one generic native presentation per renderer, while ChoiceList retains its action-aware specialization. Schemas, declared intent events, accessibility metadata, capability declarations, semantic fallbacks, and generated parity remain framework-neutral (ADR-0015).

CLI

Detects the host framework and runtime, scaffolds a complete vertical slice, adds semantic components, validates configuration, and diagnoses renderer parity.

The first slice is @agentskit/chat-cli: a safe, standard-library init for React, Expo/React Native, and Ink (ADR-0014).

Devtools and eval

Composes application traces, fixture capture, renderer conformance, accessibility evidence, and cross-platform parity reporting around AgentsKit replay and eval primitives.

The concrete application trace/replay boundary is documented in ADR-0017 and the devtools guide.

Upstream adoption

Before implementation, each issue records the AgentsKit source and exports inspected, what is reused directly, what application-layer behavior is added, and any upstream gap. A generally useful primitive is implemented in AgentsKit first; AgentsKit Chat never vendors or temporarily forks it.

Initial mandatory mappings include:

• defineChat → AgentsKit ChatConfig and createChatController;
• lifecycle → AgentsKit ChatController operations;
• actions → AgentsKit ToolDefinition plus application policy;
• confirmation → AgentsKit tool confirmation and HITL primitives;
• portable UI → AgentsKit UIMessage/UIElement plus registered custom components;
• message history → AgentsKit ChatMemory;
• replay/eval → AgentsKit replay and eval primitives;
• renderers → corresponding AgentsKit framework packages.

Reference turn pipeline

input
  -> deterministic route or conversation transition
  -> AgentsKit agent when interpretation/generation is required
  -> runtime-validated turn envelope
  -> component/action registry validation
  -> authorization, confirmation, and action policy
  -> versioned events
  -> native renderer and persistence

External dogfood hosts

The public alpha is consumed by Docs, Registry, and Playbook through immutable release assets. Host repositories keep corpus configuration and native styling; they do not own chat reducers, lifecycle, memory, cancellation, or a second component protocol. The Registry/Playbook ownership correction and parity evidence are recorded in the dogfood migration record.

Public documentation property

The Fumadocs application under apps/docs is a first-class dogfood host. It renders the canonical docs/ corpus without copying it and composes the public protocol, chat, server, and React packages for deterministic-first documentation Ask. Hosted and self-hosted modes share one Ask contract; retrieval and provider execution remain injected AgentsKit adapters. See ADR-0027.

Initial architecture proof

The first shared example must run from one unchanged chat definition in React, React Native, and Ink. These targets exercise DOM, native mobile, and terminal constraints. Vue, Svelte, and Solid now host the same shared references under apps/example-{vue,svelte,solid} with Playwright coverage for Vue. Angular remains covered by package-level conformance and agent-chat suites.

Risks

• Framework parity may become superficial. Mitigation: shared conformance fixtures and behavioral gates.
• The framework may duplicate AgentsKit. Mitigation: dependency-direction checks and explicit ownership rules.
• Generative UI can become unsafe. Mitigation: closed registries, runtime schemas, inert unknown output, semantic fallback, and action policy outside the model.
• Package proliferation may create shallow modules. Mitigation: packages are introduced only by vertical implementation slices with a public outcome.