View on GitHub

Lightspeed Core Stack

Lightspeed Core Stack

Spike for Widget System in Lightspeed Stack

Overview

The problem: Lightspeed Stack currently supports text streaming and tool-call events, but lacks a standardized way for agents to drive rich, interactive UI elements (forms, confirmation dialogs, data tables, charts) in the frontend. Customers who need widget-like behavior must build bespoke solutions on top of raw tool_call/tool_result SSE events, with no protocol-level support for state synchronization, human-in-the-loop approvals, or structured UI rendering. As more teams evaluate migrating to Lightspeed Stack — most immediately the PCM team — a standardized widget system becomes a prerequisite.

The recommendation: Implement a new /agui endpoint that speaks the AG-UI protocol, using pydantic-ai’s built-in AG-UI integration (AGUIAdapter). Customers provide UI-related tools through their own MCP servers. The AG-UI protocol handles structured communication of tool calls, state, and UI rendering data to the frontend. LCS already depends on pydantic-ai; adding the [ag-ui] optional extra is the only new dependency required.

PoC validation: Not applicable for this spike. The AG-UI protocol is a well-established open standard with integrations from Microsoft, Google, Amazon, and Oracle. The pydantic-ai AGUIAdapter is production-ready and has been validated by Rocket Science in near-production deployments.

Strategic decisions

High-level decisions that determine scope, approach, and cost. Each has a recommendation — please confirm or override.

Decision S1: Protocol approach for the widget system

How should Lightspeed Stack deliver structured widget events to frontends?

Option Description
A. AG-UI protocol endpoint New /agui endpoint speaking the AG-UI protocol via AGUIAdapter. Customers define UI tools on their MCP server; the endpoint streams AG-UI events (tool calls, state sync, interrupts) to the frontend.
B. Reuse existing /streaming_query tool call events No LCS changes. Customers catch tool_call/tool_result SSE events from /streaming_query and map them to widgets client-side.

See: Background: Option A detail, Background: Option B detail.

Recommendation: Option A. The AG-UI protocol provides maximum flexibility via a publicly governed, widely adopted standard. The immediate driver is preparing for a potential PCM team migration, but additional teams will likely need this feature. A standardized protocol avoids per-customer reinvention and provides advanced capabilities (state sync, human-in-the-loop, frontend tools) out of the box. See Recommendation rationale for full trade-off analysis.

Confidence: 85%

Decision S2: Endpoint design

Since AG-UI requires its own request format (RunAgentInput — containing message history, frontend state, frontend tool definitions, and resume entries for interrupts) and emits its own protocol-defined stream events (~30 event types), how should this be exposed?

Option Description
A. Separate /agui endpoint Dedicated endpoint with its own Action enum value and authorization
B. Overload /streaming_query Accept both QueryRequest and AG-UI RunAgentInput on the same path via discriminated union

Recommendation: Option A. The request/response formats are fundamentally different — AG-UI has its own lifecycle events, state management, and tool semantics. Overloading would create a large if/else handler with two incompatible response formats. Separate endpoints match how LCS already separates protocols (A2A gets its own endpoint, rlsapi gets its own, responses gets its own). Shared logic lives in the utility layer (build_agent, prepare_responses_params, apply_compaction_blocking, etc.).

Confidence: 95%

Decision S3: UI tool ownership model

Who defines and maintains the UI-related tools?

Option Description
A. Customer MCP server Customers register UI tools on their own MCP server, maintaining full control over tool definitions and backend logic
B. Built-in LCS tools LCS ships pre-defined UI tool types (e.g., render_form, show_dialog)
C. Both Built-in defaults with customer overrides via MCP

Recommendation: Option A. Customer-owned MCP servers provide a safe, isolated way for teams to implement customized backend logic. Each team’s UI needs differ — PCM needs different widgets than RHEL Lightspeed. Built-in tools can be added in a future iteration if common patterns emerge across consumers.

Confidence: 80%

Technical decisions

Architecture-level and implementation-level decisions.

Decision T1: Integration with AGUIAdapter

How should the /agui endpoint invoke AGUIAdapter?

Option Description
A. dispatch_request() Single class method that takes a Starlette Request, parses RunAgentInput, runs the agent, and returns a StreamingResponse. Minimal code.
B. from_request() + run_stream() Build the adapter from the request, then manually run the stream and encode. More control over intermediate steps.
C. run_stream() with manual parsing Parse RunAgentInput manually, construct the adapter, and run. Maximum flexibility.

See: pydantic-ai AG-UI API reference

Recommendation: Option B. dispatch_request() (Option A) is too opaque — LCS needs to inject its own middleware (auth, MCP header resolution, shield moderation, quota checks, conversation context, BYOK token refresh, compaction) between request parsing and agent execution. Option B provides a clean split: from_request() handles AG-UI protocol parsing, then LCS inserts its middleware, then run_stream() executes the agent.

Confidence: 75% — depends on whether AGUIAdapter allows injecting middleware between parsing and execution; may need to use Option C if not.

Decision T2: Conversation mapping

How should AG-UI threadId map to LCS conversations?

Option Description
A. Direct mapping threadId maps directly to conversation_id via normalize_conversation_id()
B. Context store mapping Use a context store (like A2A’s A2AContextStore) to map threadId to conversation_id

Recommendation: Option A. AG-UI’s threadId serves the same purpose as conversation_id in LCS. A direct mapping avoids an extra indirection layer. The A2A endpoint uses a context store because A2A contextId is a separate concept; AG-UI threadId is a direct conversation identifier.

Confidence: 70%

Decision T3: State management scope

What LCS state (if any) should be exposed through AG-UI’s state sync mechanism?

Option Description
A. Passthrough only LCS passes frontend state through without interpreting it; customers manage state entirely between their MCP tools and frontend
B. LCS-managed state LCS populates AG-UI state with conversation metadata, tool progress, quota info, etc.
C. Hybrid Passthrough by default, with optional LCS-managed fields

Recommendation: Option A. State semantics are widget-specific and customer-defined. LCS should not impose state structure. Customers define what state means for their widgets through their MCP server tools that return StateSnapshotEvent or StateDeltaEvent objects. Conversation metadata (ID, model, quota) is already conveyed through other AG-UI events.

Confidence: 80%

Decision T4: Telemetry approach

How should the /agui endpoint emit observability data?

Option Description
A. OTEL tracing only Add OTEL spans inline in the endpoint handler (same pattern as A2A and every other endpoint)
B. OTEL + Splunk telemetry Also create a dedicated Splunk event format module

Recommendation: Option A. OTEL tracing is standard across all endpoints and is implemented inline in the handler — not a separate module. Splunk telemetry is only implemented in 2 of ~15 endpoints (/responses and /rlsapi) and is not required for parity. A Splunk module can be added later if the product/analytics team requests it.

Confidence: 90%

Stakeholder decisions — for PCM team

Decisions that the requesting team is uniquely positioned to weigh in on.

Decision SH1: Frontend framework for AG-UI consumption

Which frontend framework will the PCM team (and other early consumers) use to consume AG-UI events?

Option Description
A. CopilotKit Official AG-UI reference frontend; zero-effort AG-UI consumption with built-in widget rendering
B. Custom implementation Parse AG-UI SSE events directly; full control, more work
C. Vercel AI SDK Alternative AG-UI-compatible frontend SDK

Recommendation: No recommendation from LCS side — this is a consumer decision. LCS emits standard AG-UI events; any AG-UI-compatible frontend works.

Confidence: N/A

Out of scope

What this spike deliberately does not address. Each item explains why it’s deferred.

Proposed JIRAs

Order reflects dependency / kickoff sequence.

Epic: Implement AG-UI widget system endpoint

Goals:

Scope:

Success criteria:

LCORE-4577 E2E feature files for AG-UI widget system (no step implementation)

Description: Author behave .feature files under tests/e2e/features/ that describe the behaviors required of the AG-UI widget system.

Scope:

Acceptance criteria:

LCORE-4578 Implement behave step definitions for AG-UI feature files

Description: Implement Python step definitions under tests/e2e/features/steps/ for the .feature files authored in the kickoff ticket. Take the Gherkin as-is.

Scope:

Acceptance criteria:

Blocked by:

LCORE-4576 Implement /agui endpoint (client mode)

Description: Create the core AG-UI endpoint handler in src/app/endpoints/agui.py with client mode conversation handling. In client mode the frontend owns the conversation history and sends the entire message history on every request, aligning with the AG-UI protocol’s design. No server-side conversation persistence or compaction is applied in this mode.

The endpoint receives AG-UI RunAgentInput requests, applies LCS middleware (auth, MCP, shields via agent capability, quota, BYOK), runs the pydantic-ai agent via AGUIAdapter, and streams AG-UI events back as SSE. This includes adding the Action.AGUI authorization action to the Action enum.

Note: This ticket is blocked on the pydantic-ai migration being completed. Having a working /agui endpoint with OGX alone provides no practical value — the AG-UI integration is built on pydantic-ai’s AGUIAdapter, and the effort required to adapt OGX-specific utility functions (e.g., prepare_responses_params()) for a path that will be replaced by the pydantic-ai provider is not justified. Implementation should begin after the pydantic-ai migration lands.

Scope:

Out of scope (covered by separate tickets):

Acceptance criteria:

Blocked by:

LCORE-5145 Implement /agui server mode conversation handling

Description: Add server mode to the /agui endpoint. In server mode LCS manages conversation persistence — the frontend sends only the new message items for the current turn, and LCS loads the existing conversation history from the conversation store, appends the new items, and passes the assembled history to the agent.

This mode wires the AG-UI endpoint into the LCS conversation endpoints and enables all features that modify history (compaction, conversation listing, deletion, metadata).

Scope:

Acceptance criteria:

Blocked by:

LCORE-5146 Add OTEL tracing to /agui endpoint

Description: Add OpenTelemetry tracing spans to the /agui endpoint following the A2A span pattern.

Scope:

Acceptance criteria:

Blocked by:

LCORE-4588 Document AG-UI widget system for operators and API consumers

Description: Create user-facing documentation for the AG-UI widget system feature.

Scope:

Acceptance criteria:

LCORE-5147 Build AG-UI demo: CopilotKit + Lightspeed Stack + MCP

Description: Build a working end-to-end demo that showcases the /agui endpoint with a CopilotKit frontend, Lightspeed Stack backend, and an MCP server providing UI-related tools (using A2UI generative UI or plain tool definitions). The demo serves two purposes: (1) give teams evaluating migration to the AG-UI endpoint a concrete example they can assess against their own use cases, and (2) provide a practical reference implementation they can learn from and adapt.

Scope:

Acceptance criteria:

Blocked by:

PoC results

No PoC was built for this spike. The core mechanisms are already validated:

  1. pydantic-ai is already a dependency: LCS depends on pydantic-ai; adding the [ag-ui] optional extra is the only new dependency required
  2. AGUIAdapter is production-ready: The adapter handles AG-UI protocol parsing, agent execution, and SSE encoding. It supports all AG-UI event types including state management, frontend tools, and interrupts
  3. LCS utility layer is reusable: build_agent(), prepare_responses_params(), apply_compaction_blocking(), auth dependencies, MCP header resolution, shield moderation, and quota checks are all framework-agnostic and callable from a new endpoint
  4. A2A endpoint validates the pattern: src/app/endpoints/a2a.py (~1250 lines) demonstrates that adding a protocol adapter endpoint is a proven pattern in this codebase

The main implementation work is:

Background sections

Option A — AG-UI protocol endpoint (/agui)

AG-UI (Agent-User Interaction Protocol) is an open standard for bidirectional, event-driven communication between AI agents and frontend applications, developed by CopilotKit and released in 2025. It defines ~30 event types organized into categories:

Lifecycle events: RunStarted, RunFinished, RunError, StepStarted, StepFinished — enable frontends to show progress indicators and handle errors.

Text message events: TextMessageStart, TextMessageContent, TextMessageEnd — incremental text streaming (equivalent to LCS token events).

Tool call events: ToolCallStart, ToolCallArgs, ToolCallEnd, ToolCallResult — structured tool invocation with streaming argument support.

State management events: StateSnapshot, StateDelta — real-time state synchronization between agent and frontend using JSON Patch (RFC 6902).

Reasoning events: ReasoningStart, ReasoningMessageContent, ReasoningEnd — chain-of-thought visualization.

Sub-agent events: SubagentStarted, SubagentFinished, SubagentError — nested agent delegation with scoped state.

Custom events: Open-ended extension mechanism for application-specific needs.

AG-UI advanced features relevant to the widget system:

Ecosystem adoption: By 2026, AG-UI has first-party integrations with Microsoft Agent Framework, Google ADK, AWS Bedrock AgentCore, Oracle Agent Spec, Pydantic AI, LlamaIndex, and AG2. CopilotKit raised $27M Series A (May 2026) tied to AG-UI adoption. The protocol is MIT-licensed.

Pydantic-ai integration: The AGUIAdapter class handles the full AG-UI lifecycle. For FastAPI/Starlette, dispatch_request() is a single class method that parses RunAgentInput, runs the agent, and returns a streaming response. For more control, from_request() + run_stream() allows inserting middleware. See pydantic-ai AG-UI docs.

Architecture diagram:

                                                     ┌──────────────────────────────┐
┌─────────────────────┐   POST /agui                 │       Lightspeed Stack       │
│                     │   (RunAgentInput)            │                              │
│   Frontend App      │ ─────────────────────────▶   │  ┌────────────────────────┐  │
│   (CopilotKit /     │                              │  │    /agui endpoint      │  │
│    custom client)   │  ◀─────────────────────────  │  │                        │  │
│                     │   SSE (AG-UI events)         │  │ ┌──────────────────┐   │  │
│  ┌───────────────┐  │     RunStarted               │  │ │  AGUIAdapter     │   │  │
│  │ Widget        │  │     TextMessageContent       │  │ │       │          │   │  │
│  │ Renderer      │  │     ToolCallStart/Args/End   │  │ │       ▼          │   │  │
│  │  (forms,      │  │     StateSnapshot/Delta      │  │ │  pydantic-ai     │   │  │
│  │   dialogs,    │  │     RunFinished              │  │ │  Agent           │   │  │
│  │   charts)     │  │                              │  │ │       │          │   │  │
│  └───────────────┘  │                              │  │ │       ▼          │   │  │
│                     │                              │  │ │  OGX (LLM)       │   │  │
└─────────────────────┘                              │  │ └──────────────────┘   │  │
                                                     │  └───────────┬────────────┘  │
                                                     │              │               │
                                                     │              ▼               │
                                                     │  ┌────────────────────────┐  │
                                                     │  │ Customer MCP Server    │  │
                                                     │  │ (UI tool definitions)  │  │
                                                     │  └────────────────────────┘  │
                                                     └──────────────────────────────┘

Pros:

Cons:

Complexity / Impact: Medium. Affected components: new endpoint file, routers.py, Action enum, telemetry module, tests. Reuses all existing infrastructure. No modifications to existing endpoints.

Option B — Reuse /streaming_query tool call events

No changes to Lightspeed Stack. Customers define UI-related tools on their MCP server (e.g., render_form, show_confirmation_dialog), and the existing /streaming_query endpoint emits tool_call and tool_result SSE events when the agent invokes those tools. Customers intercept these events in their frontend and render the corresponding widgets.

Existing SSE events emitted by /streaming_query (stream_payloads.py):

Event Payload Purpose
start conversation_id, request_id Stream lifecycle start
token id, token Incremental text delta
tool_call ToolCallSummary (name, tool_call_id, arguments) Agent invoked a tool
tool_result ToolResultSummary (tool_call_id, content) Tool returned a result
turn_complete id, token Full assistant text for completed turn
end referenced_documents, input_tokens, output_tokens Stream lifecycle end
error status_code, response, cause Error during stream
interrupted request_id Stream was interrupted

Architecture diagram:

┌──────────────────────┐   POST /v1/streaming_query      ┌────────────────────────┐
│                      │   (QueryRequest)                │                        │
│   Frontend App       │ ────────────────────────────▶   │  Lightspeed Stack      │
│                      │                                 │                        │
│  ┌────────────────┐  │  ◀────────────────────────────  │  ┌──────────────────┐  │
│  │ Custom Event   │  │   SSE (existing events)         │  │ /streaming_query │  │
│  │ Parser         │  │     event: start                │  │                  │  │
│  │   │            │  │     event: token                │  │ pydantic-ai Agent│  │
│  │   ▼            │  │     event: tool_call ◀── catch  │  │       │          │  │
│  │ Widget         │  │     event: tool_result          │  │       ▼          │  │
│  │ Renderer       │  │     event: end                  │  │  OGX (LLM)       │  │
│  └────────────────┘  │                                 │  └──────┬───────────┘  │
│                      │                                 │         │              │
└──────────────────────┘                                 │         ▼              │
                                                         │  ┌──────────────────┐  │
                                                         │  │ Customer MCP     │  │
                                                         │  │ Server (UI tools)│  │
                                                         │  └──────────────────┘  │
                                                         └────────────────────────┘

Pros:

Cons:

Complexity / Impact: Low (on LCS side) / Medium-High (on each customer). No LCS changes. Each consumer bears full complexity.

Recommendation rationale

Option A is recommended for the following reasons:

  1. Per-customer cost: With Option B, every team needing widgets must build their own SSE parser, state manager, and widget-event conventions from scratch. With AG-UI, they adopt a documented protocol with existing frontend SDKs.

  2. Advanced capabilities included: State synchronization, human-in-the-loop, predictive state updates, frontend tool calls, and sub-agent composition are part of the AG-UI spec and already implemented in AGUIAdapter. Building these on raw tool_call events would be significant effort per consumer.

  3. Ecosystem alignment: AG-UI has integrations with Microsoft, Google, Amazon, Oracle, and frontend frameworks (CopilotKit, Vercel AI SDK). Adopting it positions LCS in line with industry direction.

  4. Bounded implementation cost: LCS already depends on pydantic-ai; adding the [ag-ui] extra is trivial. The endpoint reuses all existing LCS infrastructure. Net-new code is the endpoint handler, an Action enum value, telemetry builders, and tests — estimated ~2-3 weeks for one developer.

Trade-offs:

Glossary

Appendix A — External references