|
| 1 | +# Architecture & Packages |
| 2 | + |
| 3 | +## Three-Layer Architecture |
| 4 | + |
| 5 | +``` |
| 6 | +Frontend (React/Angular/Vanilla) → Runtime (Express/Hono server) → Agent (LangGraph/CrewAI/BuiltIn/Custom) |
| 7 | +``` |
| 8 | + |
| 9 | +All layers communicate via the **AG-UI protocol** — an event-based standard streamed over SSE. |
| 10 | + |
| 11 | +## V1 vs V2 |
| 12 | + |
| 13 | +V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public API that wraps V2 internally. New features always go in V2. If V1 compatibility is needed, create a thin re-export or wrapper in the corresponding V1 package. |
| 14 | + |
| 15 | +## V2 Packages |
| 16 | + |
| 17 | +- **shared**: Common utilities, types, and constants used across all other packages. |
| 18 | +- **core**: The `CopilotKitCore` orchestrator — the central brain on the frontend. Manages the agent registry, tool registry, context store, and event subscriptions. All framework packages (React, Angular, Vanilla) wrap this. |
| 19 | +- **react**: React hooks (`useAgent`, `useFrontendTool`, `useAgentContext`, etc.) and `CopilotKitProvider`. Hooks are thin wrappers that register/unregister with `CopilotKitCore` on mount/unmount. |
| 20 | +- **angular**: Angular DI tokens, services, and signal-based state. Same concepts as React but using Angular patterns (`inject()`, signals, `AgentStore`). |
| 21 | +- **runtime**: The server-side `CopilotRuntime` class that receives HTTP requests and delegates to agents. Provides Express and Hono adapters. Contains the `AgentRunner` abstraction for managing thread/conversation state. |
| 22 | +- **agent**: The `BuiltInAgent` — a default agent implementation powered by the Vercel AI SDK. Used when developers don't bring their own agent framework. |
| 23 | +- **voice**: Voice input and transcription support. |
| 24 | +- **web-inspector**: A debug console (Lit web component) for inspecting agent communication in development. |
| 25 | +- **sqlite-runner**: An `AgentRunner` implementation that persists thread state to SQLite instead of memory. |
| 26 | + |
| 27 | +## V1 Packages |
| 28 | + |
| 29 | +- **react-core**: The public `<CopilotKit>` provider and hooks. Internally delegates to V2 core. |
| 30 | +- **react-ui**: Chat UI components — `CopilotChat`, `CopilotPopup`, `CopilotSidebar`, `CopilotPanel`. |
| 31 | +- **react-textarea**: The `CopilotTextarea` component for AI-assisted text editing. |
| 32 | +- **shared**: Shared types and telemetry utilities. |
| 33 | +- **runtime**: Server-side runtime with GraphQL server and LLM adapters. |
| 34 | +- **runtime-client-gql**: urql-based GraphQL client for frontend-to-runtime communication. |
| 35 | +- **sdk-js**: Helpers for LangGraph/LangChain agent integration. |
| 36 | + |
| 37 | +## Request Lifecycle |
| 38 | + |
| 39 | +1. **Init**: Frontend creates `CopilotKitCore` → fetches agent info from runtime → creates a `ProxiedAgent` instance per remote agent. |
| 40 | +2. **User sends message**: Message is added to the agent, then `runAgent()` is called. |
| 41 | +3. **HTTP request**: A POST is sent to the runtime with a `RunAgentInput` payload containing messages, registered tools, context, threadId, and state. |
| 42 | +4. **Runtime processing**: Request middleware runs → agent is resolved and cloned → `AgentRunner` executes the agent. |
| 43 | +5. **SSE stream back**: Agent emits AG-UI events streamed to the frontend: run lifecycle events, text message chunks (streaming), and optional tool call events. |
| 44 | +6. **Frontend tool execution**: When the agent calls a frontend tool, Core looks up the handler in its registry, executes it locally in the browser, and sends the result back to the agent which continues processing. |
| 45 | +7. **UI update**: Core updates its message store and notifies subscribers → React/Angular re-renders. |
| 46 | + |
| 47 | +## Core Concepts |
| 48 | + |
| 49 | +### AG-UI Protocol |
| 50 | + |
| 51 | +All agent↔UI communication is event-based. Events follow a structured lifecycle: `RUN_STARTED` → `STEP_STARTED` → message/tool events → `STEP_FINISHED` → `RUN_FINISHED`. Events are streamed over SSE and validated with Zod schemas. The `EventType` enum in `@ag-ui/core` defines all event types. |
| 52 | + |
| 53 | +### ProxiedAgent |
| 54 | + |
| 55 | +The frontend representation of a remote agent. Implements the `AbstractAgent` interface but translates calls into HTTP requests to the runtime, streaming SSE events back. Created automatically when the runtime reports available agents. |
| 56 | + |
| 57 | +### AgentRunner |
| 58 | + |
| 59 | +An abstract class on the runtime side responsible for managing thread state (conversation history, agent state). The default `InMemoryAgentRunner` is ephemeral; `SQLiteAgentRunner` provides persistence. Custom runners can be built for any storage backend. |
| 60 | + |
| 61 | +### Tool Registration |
| 62 | + |
| 63 | +Tools can be **frontend tools** (handler runs in the browser, registered via `useFrontendTool`) or **backend tools** (handler runs on the server, defined in the agent config). Tools can be scoped to a specific agent via `agentId`, or available to all agents by omitting it. |
| 64 | + |
| 65 | +### Context |
| 66 | + |
| 67 | +Application data sent alongside messages to give agents awareness of the current UI state. Registered via `useAgentContext(description, data)` where data is any JSON-serializable value. Automatically included in every agent run. |
| 68 | + |
| 69 | +### Multi-Agent |
| 70 | + |
| 71 | +Multiple agents can be registered in a single `CopilotRuntime`. Each agent gets its own endpoint, message thread, state, and optionally scoped tools. The frontend selects which agent to interact with via `useAgent({ agentId })`. |
| 72 | + |
| 73 | +### Middleware |
| 74 | + |
| 75 | +`CopilotRuntime` supports `beforeRequestMiddleware` and `afterRequestMiddleware` for cross-cutting concerns like authentication, logging, and request/response transformation. |
0 commit comments