Skip to main content

​
Three-Layer Architecture

CopilotKit is built on a clean, event-driven three-layer architecture: 
Frontend (React/Angular/Vanilla)  →  Runtime (Express/Hono)  →  Agent (LangGraph/CrewAI/BuiltIn/Custom)
All layers communicate via the AG-UI protocol — an event-based standard streamed over Server-Sent Events (SSE).
The three-layer separation allows you to:
  • Use any frontend framework (React, Angular, or Vanilla JS)
  • Deploy your runtime on any Node.js server (Express, Hono, etc.)
  • Integrate any agent framework (LangGraph, CrewAI, or build your own)

​
Architecture Diagram

​
Layer Responsibilities

​
Frontend Layer

The frontend layer manages the user interface and local application state:
  • CopilotKitCore - Central orchestrator managing agent registry, tool registry, context store, and event subscriptions
  • Framework wrappers - React hooks, Angular services, or Vanilla JS API
  • ProxiedAgent - Frontend representation of remote agents that translates calls into HTTP requests
  • Frontend tools - Tool handlers that execute locally in the browser
  • Context providers - Supply application state to agents via useAgentContext
Reference: packages/v2/core/src/core/core.ts:179

​
Runtime Layer

The runtime layer is a server-side component that orchestrates agent execution:
  • CopilotRuntime - Central runtime class that receives HTTP requests and delegates to agents
  • AgentRunner - Abstraction for managing thread/conversation state (in-memory or persistent)
  • Middleware - Before/after request hooks for authentication, logging, and transformations
  • Adapters - Express and Hono server adapters for easy integration
Reference: packages/v2/runtime/src/runtime.ts:57
The runtime can be deployed separately from your frontend, enabling microservice architectures and better scalability.

​
Agent Layer

The agent layer contains the AI logic and can be implemented with any framework:
  • BuiltInAgent - Default agent powered by Vercel AI SDK
  • LangGraph agents - Use LangGraph for complex multi-step workflows
  • CrewAI agents - Integrate CrewAI for multi-agent orchestration
  • Custom agents - Implement the AbstractAgent interface for full control

​
Request Lifecycle

Understanding the complete request lifecycle helps you debug and optimize your application:

​
1. Initialization Phase

// Frontend creates CopilotKitCore
const core = new CopilotKitCore({
  runtimeUrl: "http://localhost:4000",
  agents__unsafe_dev_only: {}
});

// Fetches agent info from runtime (/info endpoint)
// Creates a ProxiedAgent instance per remote agent
Reference: packages/v2/core/src/core/agent-registry.ts

​
2. User Sends Message

// Message is added to the agent
agent.addMessage({ role: "user", content: "Hello!" });

// runAgent() is called
await agent.runAgent(input);

​
3. HTTP Request to Runtime

A POST request is sent to the runtime with a RunAgentInput payload: 
{
  threadId: "thread_123",
  runId: "run_456",
  messages: [...],
  tools: [...],      // Registered tools
  context: {...},    // Application context
  state: {...},      // Agent state
  forwardedProps: {} // Custom properties
}
Reference: packages/v2/core/src/agent.ts:148

​
4. Runtime Processing

The runtime performs these steps in order:
  1. Middleware - beforeRequestMiddleware runs for auth/logging
  2. Agent resolution - Runtime looks up the requested agent
  3. Agent cloning - Creates an isolated instance for this request
  4. AgentRunner execution - Runner manages thread state and executes the agent
Reference: packages/v2/runtime/src/runtime.ts:66

​
5. SSE Stream Back to Frontend

The agent emits AG-UI events streamed to the frontend:
  • Run lifecycle events: RUN_STARTED, RUN_FINISHED, RUN_ERROR
  • Message events: TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END (streaming)
  • Tool events: TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT
  • Step events: STEP_STARTED, STEP_FINISHED
Reference: See the AG-UI Protocol page for complete event types.

​
6. Frontend Tool Execution

When the agent calls a frontend tool:
  1. Agent emits TOOL_CALL_START with tool name and arguments
  2. Core looks up the handler in its tool registry
  3. Handler executes locally in the browser
  4. Result is sent back to runtime via HTTP
  5. Agent continues processing with the tool result
Reference: packages/v2/core/src/core/run-handler.ts
Frontend tools are powerful for accessing local state, user interactions, or browser APIs that wouldn’t be available server-side.

​
7. UI Update

As events arrive:
  1. Core updates its message store
  2. Subscribers are notified
  3. React/Angular re-renders UI components

​
V1 vs V2 Architecture

Understanding the relationship between V1 and V2 is important for maintaining compatibility and planning migrations.

​
V2 Packages (Real Implementation)

V2 (@copilotkitnext/*) is the actual implementation where new features are built:
  • @copilotkitnext/shared - Common utilities, types, and constants
  • @copilotkitnext/core - CopilotKitCore orchestrator (framework-agnostic)
  • @copilotkitnext/react - React hooks and provider
  • @copilotkitnext/angular - Angular services and signals
  • @copilotkitnext/runtime - Server-side CopilotRuntime and AgentRunner
  • @copilotkitnext/agent - BuiltInAgent implementation
  • @copilotkitnext/voice - Voice input and transcription
  • @copilotkitnext/web-inspector - Debug console for development
  • @copilotkitnext/sqlite-runner - Persistent AgentRunner with SQLite

​
V1 Packages (Public API)

V1 (@copilotkit/*) wraps V2 internally for backward compatibility:
  • @copilotkit/react-core - Public <CopilotKit> provider and hooks (wraps V2)
  • @copilotkit/react-ui - Chat UI components
  • @copilotkit/react-textarea - AI-assisted text editing component
  • @copilotkit/runtime - Server-side runtime with GraphQL server
  • @copilotkit/runtime-client-gql - GraphQL client for frontend
  • @copilotkit/sdk-js - Helpers for LangGraph/LangChain integration
Development Strategy: Build new features in V2 first. Add V1 wrappers only if backward compatibility is needed.

​
Next Steps

AG-UI Protocol

Learn about the event-based communication protocol

Agents

Understand ProxiedAgent, AbstractAgent, and agent implementations

Runtime

Deep dive into CopilotRuntime and AgentRunner

Frontend Integration

Explore hooks and frontend tools