feat: add AG-UI agent patterns and frontend support

Author: razkenari

docs/AGUI_INTEGRATION.md

@@ -0,0 +1,139 @@
+# AG-UI Protocol Integration
+
+Guide for using the AG-UI (Agent-User Interaction) protocol patterns in FAST.
+
+---
+
+## Overview
+
+[AG-UI](https://docs.ag-ui.com/concepts/overview) is an open protocol that defines a standard SSE event format for agent-to-frontend communication. Instead of each framework emitting its own event schema (Strands events, LangChain message chunks, etc.), AG-UI provides a unified event vocabulary: `TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_RESULT`, `RUN_FINISHED`, and so on.
+
+FAST includes two AG-UI agent patterns:
+
+| Pattern | Framework | Location |
+|---------|-----------|----------|
+| `agui-strands-agent` | Strands + `ag-ui-strands` | `agent_patterns/agui-strands-agent/` |
+| `agui-langgraph-agent` | LangGraph + `copilotkit` | `agent_patterns/agui-langgraph-agent/` |
+
+Both patterns use `BedrockAgentCoreApp` as the entrypoint (same as the HTTP patterns), which means AgentCore Runtime headers (WorkloadAccessToken, Authorization, Session-Id) are available for Gateway auth, Memory, and secure user identity extraction.
+
+---
+
+## How It Works
+
+### Architecture
+
+```
+Frontend (Amplify)
+  │
+  │  POST /invocations  (AG-UI RunAgentInput payload)
+  ▼
+AgentCore Runtime
+  │
+  │  Proxies request to container port 8080
+  │  Injects: WorkloadAccessToken, Authorization, Session-Id headers
+  ▼
+Agent Container
+  │
+  │  BedrockAgentCoreApp reads headers → sets ContextVars
+  │  @entrypoint handler creates agent, runs it
+  ▼
+AG-UI Wrapper (StrandsAgent / LangGraphAGUIAgent)
+  │
+  │  Translates framework events → AG-UI SSE events
+  ▼
+Frontend Parser (parsers/agui.ts)
+  │
+  │  Maps AG-UI events → StreamEvent types
+  ▼
+ChatInterface.tsx renders messages
+```
+
+### Request Flow
+
+1. The frontend sends an AG-UI `RunAgentInput` payload (with `threadId`, `messages`, `runId`)
+2. AgentCore Runtime proxies the request, injecting auth headers
+3. `BedrockAgentCoreApp` reads headers and populates `BedrockAgentCoreContext` (ContextVars)
+4. The `@entrypoint` handler extracts user identity from the JWT, creates the agent with Memory and Gateway tools
+5. The AG-UI wrapper translates framework streaming events into AG-UI SSE events
+6. The frontend `parseAguiChunk` parser maps AG-UI events to the shared `StreamEvent` types
+
+### AG-UI vs HTTP Protocol on AgentCore Runtime
+
+AgentCore Runtime supports both `HTTP` and `AGUI` server protocols. The difference is minimal: with `AGUI`, platform-level errors are returned as AG-UI-compliant `RUN_ERROR` events in the SSE stream (HTTP 200) instead of HTTP error codes. Everything else — auth, session headers, payload passthrough — is identical.
+
+The AG-UI patterns in FAST deploy with `HTTP` protocol, which works correctly because the agent container handles AG-UI event formatting internally.
+
+---
+
+## Agent Patterns
+
+### AG-UI Strands (`agui-strands-agent`)
+
+**Location**: `agent_patterns/agui-strands-agent/`
+
+Uses `ag-ui-strands` (`StrandsAgent`) to wrap a Strands `Agent`. The agent is created per-request inside the `@entrypoint` handler, ensuring each request gets a fresh `Agent` with the correct `session_manager` and fresh MCP client connections.
+
+**Includes**: AgentCore Memory, Gateway MCP tools, Code Interpreter, AG-UI SSE streaming.
+
+### AG-UI LangGraph (`agui-langgraph-agent`)
+
+**Location**: `agent_patterns/agui-langgraph-agent/`
+
+Uses `copilotkit` (`LangGraphAGUIAgent`) to wrap a LangGraph compiled graph. Uses `ActorAwareLangGraphAgent`, a subclass that rebuilds the graph per-request to ensure fresh Gateway MCP tool connections with valid tokens.
+
+**Includes**: AgentCore Memory (checkpointer), Gateway MCP tools, Code Interpreter, CopilotKit middleware, AG-UI SSE streaming.
+
+---
+
+## Frontend
+
+### Parser Auto-Selection
+
+The AG-UI parser is automatically selected based on the pattern name prefix. Any pattern starting with `agui-` uses the AG-UI parser (`parsers/agui.ts`). Unlike the HTTP patterns — which each require a framework-specific parser (Strands, LangGraph, Claude) to handle their different streaming formats — all AG-UI patterns share a single parser. This is one of the key benefits of the AG-UI protocol: the backend framework is abstracted away behind a standard event vocabulary, so the frontend doesn't need to know whether the agent uses Strands or LangGraph.
+
+See `frontend/src/lib/agentcore-client/client.ts` for the parser selection logic and `infra-cdk/config.yaml` comments for the full prefix-to-parser mapping.
+
+### AG-UI Payload Format
+
+The frontend automatically sends the correct payload format based on the pattern prefix. AG-UI patterns receive a `RunAgentInput` payload (with `threadId`, `messages`, `runId`), while HTTP patterns receive the standard `{ prompt, runtimeSessionId }` format. This is handled by `AgentCoreClient.invoke()`.
+
+---
+
+## Deployment
+
+Set the pattern in `infra-cdk/config.yaml`:
+
+```yaml
+backend:
+  pattern: agui-strands-agent    # or agui-langgraph-agent
+  deployment_type: docker
+```
+
+No CDK changes are required. The AG-UI patterns deploy as standard HTTP containers on AgentCore Runtime.
+
+---
+
+## CopilotKit Integration
+
+[CopilotKit](https://www.copilotkit.ai/) is a React UI library that natively understands the AG-UI protocol. While FAST's built-in frontend includes a lightweight AG-UI parser for basic chat streaming, CopilotKit provides a much richer set of capabilities for building agent-powered applications:
+
+- **Chat UI components**: Pre-built `<CopilotChat />` and `<CopilotPopup />` components with streaming, markdown rendering, and tool call visualization out of the box
+- **Generative UI**: Agents can render custom React components in the chat via `TOOL_CALL_RESULT` events — tables, charts, forms, or any UI the agent decides to show
+- **Frontend tool calls**: Define tools that execute on the client side (e.g., updating a canvas, modifying app state), which the agent can invoke through the AG-UI protocol
+- **Shared state**: Bidirectional state sync between the agent and the frontend via `STATE_SNAPSHOT` events — the agent can read and write to frontend state (e.g., a todo list, a document editor)
+- **Human-in-the-loop**: Built-in support for agent interrupts where the agent pauses execution and asks the user for confirmation or input before proceeding
+- **Textarea AI suggestions**: `<CopilotTextarea />` provides inline AI-powered autocompletions in any text input
+
+CopilotKit is a separate frontend that can replace the built-in FAST frontend when deeper AG-UI integration is needed. The AG-UI agent patterns in FAST (`agui-strands-agent`, `agui-langgraph-agent`) work as the backend for CopilotKit without any changes — CopilotKit connects to the same `/invocations` endpoint and speaks the same AG-UI protocol.
+
+For a full working example, see [PR #63](https://github.com/awslabs/fullstack-solution-template-for-agentcore/pull/63) which demonstrates CopilotKit integrated with the AG-UI LangGraph pattern, including generative UI, frontend tools, and shared state.
+
+---
+
+## Additional Resources
+
+- [AG-UI Protocol Documentation](https://docs.ag-ui.com/concepts/overview)
+- [ag-ui-strands on PyPI](https://pypi.org/project/ag-ui-strands/)
+- [CopilotKit Documentation](https://docs.copilotkit.ai/)
+- [Strands AG-UI Integration Guide](https://strandsagents.com/docs/community/integrations/ag-ui/)

frontend/src/lib/agentcore-client/client.ts

@@ -5,24 +5,29 @@ import type { AgentCoreConfig, AgentPattern, ChunkParser, StreamCallback } from
 import { parseStrandsChunk } from "./parsers/strands"
 import { parseLanggraphChunk } from "./parsers/langgraph"
 import { parseClaudeAgentSdkChunk } from "./parsers/claude-agent-sdk"
+import { parseAguiChunk } from "./parsers/agui"
 import { readSSEStream } from "./utils/sse"
 
-const PARSERS: Record<AgentPattern, ChunkParser> = {
-  "strands-single-agent": parseStrandsChunk,
-  "langgraph-single-agent": parseLanggraphChunk,
-  "claude-agent-sdk-single-agent": parseClaudeAgentSdkChunk,
-  "claude-agent-sdk-multi-agent": parseClaudeAgentSdkChunk,
+/** Resolve parser from pattern prefix. Defaults to strands parser. */
+function getParser(pattern: AgentPattern): ChunkParser {
+  if (pattern.startsWith("agui-")) return parseAguiChunk
+  if (pattern.startsWith("langgraph-")) return parseLanggraphChunk
+  if (pattern.startsWith("claude-")) return parseClaudeAgentSdkChunk
+  if (pattern.startsWith("strands-")) return parseStrandsChunk
+  return parseStrandsChunk
 }
 
 export class AgentCoreClient {
   private runtimeArn: string
   private region: string
+  private pattern: AgentPattern
   private parser: ChunkParser
 
   constructor(config: AgentCoreConfig) {
     this.runtimeArn = config.runtimeArn
     this.region = config.region ?? "us-east-1"
-    this.parser = PARSERS[config.pattern]
+    this.pattern = config.pattern
+    this.parser = getParser(config.pattern)
   }
 
   generateSessionId(): string {
@@ -44,6 +49,22 @@ export class AgentCoreClient {
 
     const traceId = `1-${Math.floor(Date.now() / 1000).toString(16)}-${crypto.randomUUID()}`
 
+    // Build payload based on pattern — AG-UI protocol expects a different format
+    const body = this.pattern.startsWith("agui-")
+      ? {
+          threadId: sessionId,
+          runId: crypto.randomUUID(),
+          messages: [{ id: crypto.randomUUID(), role: "user", content: query }],
+          state: {},
+          tools: [],
+          context: [],
+          forwardedProps: {},
+        }
+      : {
+          prompt: query,
+          runtimeSessionId: sessionId,
+        }
+
     // User identity is extracted server-side from the validated JWT token
     // (Authorization header), not sent in the payload body. This prevents
     // impersonation via prompt injection.
@@ -55,10 +76,7 @@ export class AgentCoreClient {
         "Content-Type": "application/json",
         "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": sessionId,
       },
-      body: JSON.stringify({
-        prompt: query,
-        runtimeSessionId: sessionId,
-      }),
+      body: JSON.stringify(body),
     })
 
     if (!response.ok) {

frontend/src/lib/agentcore-client/parsers/agui.ts

@@ -0,0 +1,81 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ChunkParser } from "../types"
+
+/**
+ * Parses SSE chunks from AG-UI (ag-ui-strands) agents.
+ *
+ * AG-UI events arrive as `data: <JSON>` where each JSON object has a `type` field:
+ *   RUN_STARTED, STATE_SNAPSHOT, TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT,
+ *   TEXT_MESSAGE_END, TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END,
+ *   TOOL_CALL_RESULT, RUN_FINISHED
+ */
+export const parseAguiChunk: ChunkParser = (line, callback) => {
+  if (!line.startsWith("data: ")) return
+
+  const data = line.substring(6).trim()
+  if (!data) return
+
+  try {
+    const json = JSON.parse(data)
+    const eventType: string = json.type
+
+    switch (eventType) {
+      case "TEXT_MESSAGE_CONTENT":
+        callback({ type: "text", content: json.delta ?? "" })
+        break
+
+      case "TOOL_CALL_START":
+        callback({
+          type: "tool_use_start",
+          toolUseId: json.toolCallId,
+          name: json.toolCallName,
+        })
+        break
+
+      case "TOOL_CALL_ARGS":
+        callback({
+          type: "tool_use_delta",
+          toolUseId: json.toolCallId,
+          input: json.delta ?? "",
+        })
+        break
+
+      case "TOOL_CALL_RESULT":
+        callback({
+          type: "tool_result",
+          toolUseId: json.toolCallId,
+          result: json.content ?? "",
+        })
+        break
+
+      case "RUN_FINISHED":
+        callback({ type: "result", stopReason: "end_turn" })
+        callback({ type: "lifecycle", event: "run_finished" })
+        break
+
+      case "RUN_STARTED":
+        callback({ type: "lifecycle", event: "run_started" })
+        break
+
+      case "TEXT_MESSAGE_START":
+        callback({ type: "lifecycle", event: "message_start" })
+        break
+
+      case "TEXT_MESSAGE_END":
+        callback({ type: "lifecycle", event: "message_end" })
+        break
+
+      case "STATE_SNAPSHOT":
+      case "TOOL_CALL_END":
+        // Informational — no action needed
+        break
+
+      default:
+        console.debug("Unhandled AG-UI event type:", eventType)
+    }
+  } catch {
+    console.debug("Failed to parse AG-UI event:", data)
+  }
+}

frontend/src/lib/agentcore-client/types.ts

@@ -1,12 +1,12 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-/** Supported agent framework patterns */
+/** Supported agent pattern prefixes — determines the frontend parser */
 export type AgentPattern =
-  | "strands-single-agent"
-  | "langgraph-single-agent"
-  | "claude-agent-sdk-single-agent"
-  | "claude-agent-sdk-multi-agent"
+  | `agui-${string}`
+  | `strands-${string}`
+  | `langgraph-${string}`
+  | `claude-${string}`
 
 /** Configuration for AgentCoreClient */
 export interface AgentCoreConfig {

infra-cdk/lib/backend-stack.ts

@@ -364,6 +364,13 @@ export class BackendStack extends cdk.NestedStack {
       description: `${pattern} agent runtime for ${config.stack_name_base}`,
     })
 
+    // AGUI protocol override — CloudFormation doesn't support AGUI enum yet
+    // (only MCP | HTTP | A2A). Runtime deploys as HTTP, which also works properly.
+    // if (pattern.startsWith("agui-")) {
+    //   const cfnRuntime = this.agentRuntime.node.defaultChild as cdk.CfnResource
+    //   cfnRuntime.addPropertyOverride("ProtocolConfiguration", "AGUI")
+    // }
+
     // Make sure that ZIP is uploaded before Runtime is created
     if (zipPackagerResource) {
       this.agentRuntime.node.addDependency(zipPackagerResource)

patterns/agui-langgraph-agent/Dockerfile

@@ -0,0 +1,45 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+WORKDIR /app
+
+# Configure UV for container environment
+ENV UV_SYSTEM_PYTHON=1 \
+    UV_COMPILE_BYTECODE=1 \
+    DOCKER_CONTAINER=1 \
+    OTEL_PYTHON_LOG_CORRELATION=true \
+    PYTHONUNBUFFERED=1
+
+# Copy pyproject.toml and shared packages for installation
+COPY pyproject.toml .
+COPY gateway/ gateway/
+COPY tools/ tools/
+
+# Copy and install agent-specific requirements first
+COPY patterns/agui-langgraph-agent/requirements.txt requirements.txt
+RUN uv pip install --no-cache -r requirements.txt && \
+    uv pip install --no-cache aws-opentelemetry-distro==0.10.1
+
+# Install FAST package with only core dependencies (no dev/agent optional deps)
+RUN uv pip install --no-cache -e . --no-deps && \
+    uv pip install --no-cache requests>=2.31.0
+
+# Create non-root user
+RUN useradd -m -u 1000 bedrock_agentcore
+USER bedrock_agentcore
+
+EXPOSE 8080
+
+# Copy agent code and tools
+COPY patterns/agui-langgraph-agent/agent.py .
+COPY patterns/agui-langgraph-agent/tools/ tools/
+COPY patterns/utils/ utils/
+
+# Healthcheck
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/ping', timeout=2)" || exit 1
+
+# Start agent with OpenTelemetry instrumentation
+CMD ["opentelemetry-instrument", "python", "-m", "agent"]