Skip to content

Commit b0806f8

Browse files
razkenarirazkenari
committed
feat: add AG-UI agent patterns and frontend support
1 parent 1a194ce commit b0806f8

20 files changed

Lines changed: 832 additions & 101 deletions

File tree

‎docs/AGUI_INTEGRATION.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# AG-UI Protocol Integration
2+
3+
Guide for using the AG-UI (Agent-User Interaction) protocol patterns in FAST.
4+
5+
---
6+
7+
## Overview
8+
9+
[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.
10+
11+
FAST includes two AG-UI agent patterns:
12+
13+
| Pattern | Framework | Location |
14+
|---------|-----------|----------|
15+
| `agui-strands-agent` | Strands + `ag-ui-strands` | `agent_patterns/agui-strands-agent/` |
16+
| `agui-langgraph-agent` | LangGraph + `copilotkit` | `agent_patterns/agui-langgraph-agent/` |
17+
18+
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.
19+
20+
---
21+
22+
## How It Works
23+
24+
### Architecture
25+
26+
```
27+
Frontend (Amplify)
28+
│
29+
│ POST /invocations (AG-UI RunAgentInput payload)
30+
▼
31+
AgentCore Runtime
32+
│
33+
│ Proxies request to container port 8080
34+
│ Injects: WorkloadAccessToken, Authorization, Session-Id headers
35+
▼
36+
Agent Container
37+
│
38+
│ BedrockAgentCoreApp reads headers → sets ContextVars
39+
│ @entrypoint handler creates agent, runs it
40+
▼
41+
AG-UI Wrapper (StrandsAgent / LangGraphAGUIAgent)
42+
│
43+
│ Translates framework events → AG-UI SSE events
44+
▼
45+
Frontend Parser (parsers/agui.ts)
46+
│
47+
│ Maps AG-UI events → StreamEvent types
48+
▼
49+
ChatInterface.tsx renders messages
50+
```
51+
52+
### Request Flow
53+
54+
1. The frontend sends an AG-UI `RunAgentInput` payload (with `threadId`, `messages`, `runId`)
55+
2. AgentCore Runtime proxies the request, injecting auth headers
56+
3. `BedrockAgentCoreApp` reads headers and populates `BedrockAgentCoreContext` (ContextVars)
57+
4. The `@entrypoint` handler extracts user identity from the JWT, creates the agent with Memory and Gateway tools
58+
5. The AG-UI wrapper translates framework streaming events into AG-UI SSE events
59+
6. The frontend `parseAguiChunk` parser maps AG-UI events to the shared `StreamEvent` types
60+
61+
### AG-UI vs HTTP Protocol on AgentCore Runtime
62+
63+
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.
64+
65+
The AG-UI patterns in FAST deploy with `HTTP` protocol, which works correctly because the agent container handles AG-UI event formatting internally.
66+
67+
---
68+
69+
## Agent Patterns
70+
71+
### AG-UI Strands (`agui-strands-agent`)
72+
73+
**Location**: `agent_patterns/agui-strands-agent/`
74+
75+
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.
76+
77+
**Includes**: AgentCore Memory, Gateway MCP tools, Code Interpreter, AG-UI SSE streaming.
78+
79+
### AG-UI LangGraph (`agui-langgraph-agent`)
80+
81+
**Location**: `agent_patterns/agui-langgraph-agent/`
82+
83+
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.
84+
85+
**Includes**: AgentCore Memory (checkpointer), Gateway MCP tools, Code Interpreter, CopilotKit middleware, AG-UI SSE streaming.
86+
87+
---
88+
89+
## Frontend
90+
91+
### Parser Auto-Selection
92+
93+
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.
94+
95+
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.
96+
97+
### AG-UI Payload Format
98+
99+
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()`.
100+
101+
---
102+
103+
## Deployment
104+
105+
Set the pattern in `infra-cdk/config.yaml`:
106+
107+
```yaml
108+
backend:
109+
pattern: agui-strands-agent # or agui-langgraph-agent
110+
deployment_type: docker
111+
```
112+
113+
No CDK changes are required. The AG-UI patterns deploy as standard HTTP containers on AgentCore Runtime.
114+
115+
---
116+
117+
## CopilotKit Integration
118+
119+
[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:
120+
121+
- **Chat UI components**: Pre-built `<CopilotChat />` and `<CopilotPopup />` components with streaming, markdown rendering, and tool call visualization out of the box
122+
- **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
123+
- **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
124+
- **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)
125+
- **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
126+
- **Textarea AI suggestions**: `<CopilotTextarea />` provides inline AI-powered autocompletions in any text input
127+
128+
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.
129+
130+
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.
131+
132+
---
133+
134+
## Additional Resources
135+
136+
- [AG-UI Protocol Documentation](https://docs.ag-ui.com/concepts/overview)
137+
- [ag-ui-strands on PyPI](https://pypi.org/project/ag-ui-strands/)
138+
- [CopilotKit Documentation](https://docs.copilotkit.ai/)
139+
- [Strands AG-UI Integration Guide](https://strandsagents.com/docs/community/integrations/ag-ui/)

‎frontend/package-lock.json‎

Lines changed: 58 additions & 57 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)