Skip to content

AG-UI (Agent-User Interface) Canonical Research Record

READ BEFORE ANY AG-UI WORK IN ANY PROJECT. DO NOT RE-RESEARCH.

This document captures the canonical evaluation, structure, and adoption path for the AG-UI protocol within the Bluefly estate.

1. What is AG-UI?

AG-UI (Agent-User Interface) is an open standard protocol designed to standardize the interaction layer between autonomous AI agents and user interfaces.

It defines how events, state, streaming, and message exchanges flow between the intelligence layer (the agent) and the presentation layer (the UI), replacing ad-hoc HTTP/WebSocket/SSE implementations with a structured contract.

2. Technical Architecture & SDKs

Protocol Spec & Transport Layer

AG-UI relies on Server-Sent Events (SSE) for transport and uses JSON and Protobuf for wire-format serialization. It specifies distinct event types for streaming state, text deltas, structured UI actions (A2UI), and lifecycle boundaries.

Available SDKs and Parity

The protocol enforces strict cross-SDK parity, governed by the following hierarchy:

  1. TypeScript (@ag-ui/client): The canonical source of truth. It owns the wire format and the client run-loop behavior.
  2. .NET: Implements full client run-loop and wire-format (JSON/protobuf/SSE) capabilities. Must strictly maintain feature and wire-format parity with TypeScript.
  3. Python: Used for types and encoding only (core/ and encoder/). It does not implement a client run-loop or protobuf definitions.

3. Relationship to Bluefly ContextControl

Bluefly’s ContextControl.ai SaaS app (built on Drupal) currently provides a chat UI and Canvas integrations. Historically, Agent ↔ UI streaming in Bluefly relied on custom transports (e.g., useSSE.ts).

AG-UI directly solves this by providing a unified middleware and client package (@ag-ui/client) to replace custom SSE logic. Furthermore, AG-UI natively supports A2UI (Agent-to-UI) middleware (@ag-ui/a2ui-middleware), which detects and paints structured A2UI operations on the client renderer, natively aligning with ContextControl's Canvas capabilities.

4. Evaluation and Adoption Recommendation

  • Evaluation: Does AG-UI solve a Bluefly need? YES. It eliminates the technical debt of custom SSE implementations (useSSE.ts) and provides a durable, multi-language contract for UI rendering, aligning perfectly with the separation of intelligence (agents) and presentation (applications).
  • Recommendation: ADOPT.

Integration Path

  1. Deprecate Custom Transports: Remove custom useSSE.ts implementations across frontends.
  2. Implement @ag-ui/client: Standardize the interaction protocol on the canonical TS SDK for web frontends.
  3. Adopt A2UI Middleware: Wire @ag-ui/a2ui-middleware to bridge agent responses to ContextControl/Drupal Canvas rendering.

5. Agent Skills Available

To implement or maintain AG-UI integrations, agents MUST leverage the specialized skills curated in the estate:

  • .agents/skills/agui-cross-sdk-parity: Guides the parity process and cross-language implementation between TS and .NET.
  • .agents/skills/ag-ui-a2ui-integration: Guides adding A2UI rendering to any AG-UI supported framework or custom AG-UI application.
  • .agents/skills/agui-dotnet-*: Extensive test, serialization, and transport mechanics for the .NET SDK.

(See the .agents/skills/ directory for the full suite of executable AG-UI knowledge.)