graph TB
    subgraph "Frontend (React / Angular / Vanilla)"
        FT["Frontend Tools
<i>Functions agents can call</i>"]
        CTX["Agent Context
<i>Data agents can read</i>"]
        RTC["Tool Call Renderers
<i>Custom UI for tool calls</i>"]
        HIL["Human-in-the-Loop
<i>Approval before execution</i>"]
        RAM["Activity Renderers
<i>Custom activity messages</i>"]
        RCM["Custom Message Renderers
<i>Inject UI before/after messages</i>"]
        SUG["Suggestions Config
<i>AI or static suggestions</i>"]
        SUBS["Event Subscribers
<i>React to lifecycle events</i>"]
    end

    subgraph "Backend (Runtime)"
        BM["Before Middleware
<i>Auth, logging, transforms</i>"]
        AM["After Middleware
<i>Post-processing</i>"]
        RUNNER["Agent Runner
<i>How agents execute</i>"]
        TS["Transcription Service
<i>Audio → text</i>"]
    end

    subgraph "Agent Level"
        MW["AG-UI Middleware
<i>Intercept agent pipeline</i>"]
    end

// Type signature
type FrontendTool<T> = {
  name: string;
  description?: string;
  parameters?: z.ZodType<T>;
  handler?: (args: T, context: FrontendToolHandlerContext) => Promise<unknown>;
  followUp?: boolean; // Re-run agent after tool completes
  agentId?: string; // Scope to specific agent
};

sequenceDiagram
    participant Agent
    participant Core as CopilotKitCore
    participant Tool as Your Tool Handler

    Agent->>Core: TOOL_CALL_START { name: "myTool" }
    Agent->>Core: TOOL_CALL_ARGS { ... }
    Core->>Tool: handler(args)
    Tool-->>Core: result
    Core->>Agent: TOOL_CALL_RESULT
    opt followUp = true
        Core->>Agent: Re-run agent with result
    end

type AgentContextInput = {
  description: string; // Human-readable label
  value: JsonSerializable; // Any JSON value
};

type ReactToolCallRenderer<T> = {
  name: string; // Tool name to render
  args: z.ZodSchema<T>; // Schema for type-safe args
  agentId?: string; // Scope to specific agent
  render: React.ComponentType<
    | { status: "in-progress"; args: Partial<T>; result: undefined }
    | { status: "executing"; args: T; result: undefined }
    | { status: "complete"; args: T; result: string }
  >;
};

graph LR
    IP["in-progress
<i>Args streaming in
Partial&lt;T&gt; available</i>"]
    EX["executing
<i>Handler running
Full args available</i>"]
    CO["complete
<i>Result available</i>"]
    IP --> EX --> CO

type ReactHumanInTheLoop<T> = Omit<FrontendTool<T>, "handler"> & {
  render: React.ComponentType<{
    args: T;
    status: "in-progress" | "executing" | "complete";
    respond: (result: unknown) => Promise<void>; // Call this to approve/deny
  }>;
};

sequenceDiagram
    participant Agent
    participant Core as CopilotKitCore
    participant UI as Your Approval UI
    participant User

    Agent->>Core: TOOL_CALL { name: "deleteUser" }
    Core->>UI: Render with status: "executing"
    UI->>User: "Delete user X?"
    User->>UI: Clicks "Approve"
    UI->>Core: respond("approved")
    Core->>Agent: TOOL_CALL_RESULT
    Agent->>Agent: Continues

type ReactActivityMessageRenderer<T> = {
  activityType: string; // Use "*" for wildcard
  agentId?: string;
  content: z.ZodSchema<T>;
  render: React.ComponentType<{
    activityType: string;
    content: T;
    message: ActivityMessage;
    agent: AbstractAgent | undefined;
  }>;
};

type ReactCustomMessageRenderer = {
  agentId?: string;
  render: React.ComponentType<{
    message: Message;
    position: "before" | "after";
    runId: string;
    messageIndex: number;
    agentId: string;
    stateSnapshot: any;
  }> | null;
};

// AI-generated suggestions
type DynamicSuggestionsConfig = {
  instructions: string; // What to suggest
  minSuggestions?: number; // Default: 1
  maxSuggestions?: number; // Default: 3
  available?: SuggestionAvailability; // When to show
  providerAgentId?: string; // Which agent generates them
  consumerAgentId?: string; // Which agent receives them ("*" = all)
};

// Static suggestions
type StaticSuggestionsConfig = {
  suggestions: Array<{ title: string; message: string }>;
  available?: SuggestionAvailability;
  consumerAgentId?: string;
};

type SuggestionAvailability =
  | "before-first-message" // Default for static
  | "after-first-message" // Default for dynamic
  | "always"
  | "disabled";

graph TB
    subgraph "Suggestion Types"
        DYN["Dynamic
<i>AI generates suggestions
from instructions</i>"]
        STA["Static
<i>You provide fixed
suggestion list</i>"]
    end

    subgraph "Availability"
        BFM["before-first-message"]
        AFM["after-first-message"]
        ALW["always"]
        DIS["disabled"]
    end

    DYN -.->|default| AFM
    STA -.->|default| BFM

type CopilotKitCoreSubscriber = {
  onRuntimeConnectionStatusChanged?: (event) => void;
  onToolExecutionStart?: (event) => void;
  onToolExecutionEnd?: (event) => void;
  onAgentsChanged?: (event) => void;
  onContextChanged?: (event) => void;
  onSuggestionsChanged?: (event) => void;
  onSuggestionsStartedLoading?: (event) => void;
  onSuggestionsFinishedLoading?: (event) => void;
  onPropertiesChanged?: (event) => void;
  onHeadersChanged?: (event) => void;
  onError?: (event) => void;
};

type BeforeRequestMiddleware = (params: {
  runtime: CopilotRuntime;
  request: Request;
  path: string;
}) => MaybePromise<Request | void>;
// Return modified Request, or void to pass through
// Return a Response to short-circuit (e.g., 401)

graph LR
    REQ["Incoming Request"]
    BM["beforeRequestMiddleware"]
    HANDLER["Route Handler"]
    REJECT["401 / Error Response"]

    REQ --> BM
    BM -->|pass through| HANDLER
    BM -->|reject| REJECT

type AfterRequestMiddleware = (params: {
  runtime: CopilotRuntime;
  response: Response;
  path: string;
}) => MaybePromise<void>;

abstract class AgentRunner {
  abstract run(request: AgentRunnerRunRequest): Observable<BaseEvent>;
  abstract connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
  abstract isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean>;
  abstract stop(request: AgentRunnerStopRequest): Promise<boolean | undefined>;
}

graph TB
    RT["CopilotRuntime"]
    RUNNER["runner (AgentRunner)"]

    RT --> RUNNER

    subgraph Implementations
        IM["InMemoryAgentRunner
<i>Default — in-process</i>"]
        SQ["SQLiteAgentRunner
<i>Persistent on disk</i>"]
        CU["YourCustomRunner
<i>Redis, Postgres, etc.</i>"]
    end

    RUNNER -.-> IM
    RUNNER -.-> SQ
    RUNNER -.-> CU

abstract class TranscriptionService {
  abstract transcribeFile(options: {
    audioFile: File;
    mimeType?: string;
    size?: number;
  }): Promise<string>;
}

abstract class Middleware {
  abstract run(
    input: RunAgentInput,
    next: AbstractAgent,
  ): Observable<BaseEvent>;
}

// Built-in implementations:
// - FunctionMiddleware — wrap a function as middleware
// - FilterToolCallsMiddleware — filter which tools are sent

graph LR
    INPUT["RunAgentInput"]
    MW1["Middleware 1
<i>e.g., logging</i>"]
    MW2["Middleware 2
<i>e.g., tool filtering</i>"]
    AGENT["Agent.run()"]

    INPUT --> MW1 --> MW2 --> AGENT

graph TB
    subgraph "Provider / Config"
        P["CopilotKitProvider
or provideCopilotKit()"]
        P --> FT_P["frontendTools"]
        P --> RTC_P["renderToolCalls"]
        P --> RAM_P["renderActivityMessages"]
        P --> RCM_P["renderCustomMessages"]
        P --> HIL_P["humanInTheLoop"]
        P --> HDR["headers"]
        P --> CRD["credentials"]
        P --> PRP["properties"]
        P --> DC["showDevConsole"]
    end

    subgraph "Hooks / Service Methods"
        UFT["useFrontendTool()"]
        UAC["useAgentContext()"]
        URT["useRenderToolCall()"]
        UHL["useHumanInTheLoop()"]
        UCS["useConfigureSuggestions()"]
        URA["useRenderActivityMessage()"]
        URC["useRenderCustomMessages()"]
    end

    subgraph "CopilotRuntime"
        RT["new CopilotRuntime()"]
        RT --> AGENTS["agents (required)"]
        RT --> RUNNER["runner"]
        RT --> BM["beforeRequestMiddleware"]
        RT --> AM["afterRequestMiddleware"]
        RT --> TS["transcriptionService"]
    end

    subgraph "Core API"
        SUB["copilotKit.subscribe()"]
        AT["copilotKit.addTool()"]
        AC["copilotKit.addContext()"]
    end