feat: add AG-UI (AGUI) as fourth first-class protocol mode by aidandaly24 · Pull Request #858 · aws/agentcore-cli

aidandaly24 · 2026-04-15T15:46:34Z

Description

Adds AG-UI (AGUI) as a fourth protocol mode in the AgentCore CLI alongside HTTP, MCP, and A2A. AGUI is an open, event-based protocol for agent-to-user interaction that enables rich streaming of structured events (text, tool calls, reasoning, state) from agents to frontends.

What's included:

Schema & Types

'AGUI' added to ProtocolModeSchema and PROTOCOL_FRAMEWORK_MATRIX (Strands, LangGraph, GoogleADK)
Full TypeScript type system for ~27 AG-UI event types (agui-types.ts)
parseAguiEvent() parser and buildAguiRunInput() helper
Reserved project names updated, hardcoded protocol unions fixed

Python Agent Templates (3 frameworks)

src/assets/python/agui/strands/ — uses ag-ui-strands / StrandsAgent / create_strands_app
src/assets/python/agui/langchain_langgraph/ — uses ag-ui-langgraph / LangGraphAgent
src/assets/python/agui/googleadk/ — uses ag-ui-adk / ADKAgent / AGUIToolset
Memory capability for Strands (matching A2A pattern)

Invoke Layer

invokeAguiRuntime() with dual-stream architecture: typed stream (AG-UI events) for rich TUI + textStream (plain text) for CLI
invokeAguiStreaming() for local dev with proper RunAgentInput body construction
Protocol dispatch in invokeForProtocol(), handleInvoke(), and dev command
InvokeLogger integration for AGUI CLI path

TUI

AGUI in protocol picker with description "Stream rich agent events to frontends (AG-UI)"
Rich event rendering in InvokeScreen with MessagePart[] model (tool calls, reasoning, errors)
Dev screen streaming and placeholder text for AGUI
Protocol label display in invoke and dev headers

Cross-codebase updates

All JSDoc comments, help text, error messages, and AddScreen description updated to include AGUI
agent-env.test.ts protocol acceptance test includes AGUI
codezip-dev-server.ts comment updated for AGUI
import/types.ts and yaml-parser.ts hardcoded unions updated

Related Issue

Closes #796

Documentation PR

Type of Change

Testing

How have you tested the change?

I ran npm run test:unit and npm run test:integ
I ran npm run typecheck
I ran npm run lint
If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Deployment Testing

All 3 AGUI framework configurations were deployed to AWS and invoked end-to-end:

Framework	Create	Deploy	Invoke	Response
Strands + Bedrock	PASS	PASS	PASS	Text streaming confirmed
LangGraph + Bedrock	PASS	PASS	PASS	Text streaming confirmed
GoogleADK + Gemini	PASS	PASS	PASS	Text streaming confirmed

Review Rounds

4 rounds of review (20 total reviewer agents) covering:

TUI wizard flows, schema validation edge cases, dev server lifecycle
Deploy/status/logs pipeline, exhaustive grep for missed protocol refs
Handlebars template rendering output, error paths, HTTP feature parity
Cross-package CLI/CDK sync, first-time user experience walkthrough

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

Note: This PR depends on the companion CDK PR at aws/agentcore-l3-cdk-constructs for the ProtocolModeSchema and PROTOCOL_FRAMEWORK_MATRIX changes in the CDK package.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

github-actions · 2026-04-15T15:47:22Z

Package Tarball

aws-agentcore-0.8.1.tgz

How to install

npm install https://github.com/aws/agentcore-cli/releases/download/pr-858-tarball/aws-agentcore-0.8.1.tgz

Add AGUI protocol support across the full CLI stack: - Schema: Add 'AGUI' to ProtocolModeSchema, PROTOCOL_FRAMEWORK_MATRIX (Strands, LangChain_LangGraph, GoogleADK), and RESERVED_PROJECT_NAMES - Types: New agui-types.ts with 27 event type enum, typed interfaces, parseAguiEvent parser, and buildAguiRunInput helper - Templates: Python AGUI agent templates for Strands (ag-ui-strands), LangGraph (ag-ui-langgraph), and GoogleADK (ag-ui-adk) frameworks - Invoke: invokeAguiRuntime with dual-stream architecture (typed events for TUI, text-only for CLI), local dev invokeAguiStreaming with RunAgentInput body, protocol dispatch in invokeForProtocol - TUI: Rich AGUI event rendering with MessagePart type (text, tool_call, reasoning, error) in InvokeScreen, AGUI placeholder text in DevScreen - Validation: Updated error messages and help text to include AGUI - Tests: 24 unit tests for parseAguiEvent/buildAguiRunInput, snapshot updates for new template files

HIGH fixes: - Add sessionId to AguiInvokeOptions, pass as runtimeSessionId (H-1) - Throw early for bearerToken on AGUI (not yet supported) (H-2) - Add bedrock-agentcore dep to all 3 template pyproject.toml files (H-4/5/6) - Fix LangGraph /ping to return "healthy" not "ok" (H-7) - Match TOOL_CALL_RESULT to tool_call parts by toolCallId, not position (H-12) - Add complete enum coverage to agui-types test (H-15) MEDIUM fixes: - Fix langchain version pin from 1.2.0 (nonexistent) to 0.3.0 (M-11) - Remove invalid allow_credentials=True with wildcard CORS (M-12) - Replace in-place parts mutation with immutable updates for React safety (M-5) - Surface readLoop errors in consumer generators instead of swallowing (M-1) - Disable retry once streaming starts to prevent duplicate output (M-3) - Handle TEXT_MESSAGE_CHUNK events alongside TEXT_MESSAGE_CONTENT (M-2) - Update gemini model from 2.0-flash to 2.5-flash in GoogleADK (M-8) - Add missing event type exports to barrel index.ts (M-18) LOW fixes: - Move AGUI imports to top-level in action.ts (L-1) - Gate OTEL_SDK_DISABLED on LOCAL_DEV env var in Strands template (L-9) - Add explanatory comment for LANGGRAPH_FAST_API env var (L-10)

- Add AGUI option to PROTOCOL_OPTIONS in generate/types.ts so users can select AGUI from the interactive create/add wizards - Add AGUI case to useDevServer.ts sendMessage dispatch so local dev TUI sends correct RunAgentInput body via invokeAguiStreaming - Add AGUI case to dev/command.tsx non-interactive dispatch so agentcore dev "prompt" uses invokeForProtocol('AGUI')

load_model() returns None (it only sets GOOGLE_API_KEY env var as a side effect). Passing model=load_model() to Agent() results in model=None, causing the agent to either crash or use a default model. Fix: call load_model() standalone for the side effect, then pass the model ID string directly to Agent().

- AddScreen description: 'HTTP, MCP, A2A' → includes AGUI - create --protocol help text: includes AGUI - JSDoc comments in agent/types.ts, templates/types.ts, agent-env.ts - codezip-dev-server comment: 'MCP/A2A' → 'MCP/A2A/AGUI' - agent-env.test.ts: add AGUI to protocol acceptance test

- Add InvokeLogger to AGUI CLI invoke block (action.ts) for prompt/response logging and log file creation — parity with HTTP invoke path - Track RUN_ERROR events in textStream and return success: false when agent errors are detected - Pass sessionId and logger to invokeAguiRuntime options - Improve AGUI protocol picker description from circular 'AG-UI agent-to-user interaction protocol' to actionable 'Stream rich agent events to frontends (AG-UI)'

Bugs found by deploying all 3 AGUI frameworks to AWS and invoking: - Bump ag-ui-strands to >= 0.1.4 (0.1.3 crashes on strands >= 1.19.0 due to accessing removed private attr agent.state._state) - Remove parallel_tool_calls=False from LangGraph template (Bedrock rejects this OpenAI-specific parameter with ValidationException) - Remove aws-opentelemetry-distro from GoogleADK template (conflicts with google-adk >= 1.16.0 OpenTelemetry dependencies — agents using this template should set instrumentation.enableOtel: false)

When creating an AGUI project, users can now opt to include a CopilotKit frontend. A new "Frontend" TUI wizard step (AGUI only) offers 4 layout options: Sidebar, Popup, Chat, or No frontend. Template files (10) scaffold a Next.js + CopilotKit app in frontend/ that connects to the AGUI agent via CopilotRuntime proxy. CLI changes: - renderFrontendTemplate() function (EvaluatorRenderer pattern) - FrontendLayout type + frontendLayout on AgentRenderConfig - --frontend flag on agentcore create command - Frontend step in TUI wizard (before Advanced, AGUI only) - schema-mapper maps frontend config to frontendLayout

…flict Handlebars interprets `={{` in JSX (e.g., `labels={{ title: "..." }}`) as template syntax, causing parse errors during template rendering. Fix: extract labels and suggestions as const variables before JSX, using single-brace `{labels}` which Handlebars ignores.

Reverts commits 9e08418 and 1533497. The frontend scaffolding is being replaced with a different approach. AGUI protocol support (templates, invoke, TUI) remains intact — only the CopilotKit frontend template and associated wizard step/CLI flag are removed.

avi-alpert · 2026-04-15T23:45:01Z

+
+# Enable LangGraph FastAPI mode (must be set before langgraph imports)
+os.environ["LANGGRAPH_FAST_API"] = "true"
+


im thinking we will also want to add instrumentation like we do for the other langchain templates

https://github.com/aws/agentcore-cli/blob/main/src/assets/python/http/langchain_langgraph/base/main.py#L14

avi-alpert · 2026-04-16T00:21:03Z

+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8080)


Suggested change

uvicorn.run(app, host="0.0.0.0", port=8080)

uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

for local testing it would be nice if we could optionally specify a different port through an env var. (If you end up making this change please apply it to all the agui templates)

The AGUI LangGraph template had a single-node graph (chat → END) with no tool execution loop. When the model called add_numbers, the graph exited without executing the tool or generating a text response, producing "(no content in AGUI response)" in agentcore dev. Template fix: - Add ToolNode(tools=backend_tools) as a "tools" node - Replace set_finish_point("chat") with tools_condition conditional edge - Add edge from "tools" back to "chat" for the ReAct loop - Separate backend_tools list from frontend tools (state["tools"]) This matches the standard LangGraph ReAct pattern (agent → tools → agent → ... → END) and how the HTTP/A2A templates use create_react_agent. Dev invoke fix: - invoke-agui.ts now tracks TOOL_CALL_START/ARGS/END/RESULT events - When no text is produced but tool calls were seen, surfaces them as [Tool: name(args)] instead of generic "(no content)" message

aidandaly24 requested a review from a team April 15, 2026 15:46

github-actions bot added the size/xl PR size: XL label Apr 15, 2026

aidandaly24 had a problem deploying to e2e-testing April 15, 2026 15:46 — with GitHub Actions Failure

aidandaly24 added 10 commits April 15, 2026 11:51

aidandaly24 force-pushed the feat/agui-protocol branch from 3d2587b to aa64583 Compare April 15, 2026 15:51

github-actions bot added size/xl PR size: XL and removed size/xl PR size: XL labels Apr 15, 2026

aidandaly24 temporarily deployed to e2e-testing April 15, 2026 15:51 — with GitHub Actions Inactive

avi-alpert reviewed Apr 15, 2026

View reviewed changes

avi-alpert reviewed Apr 16, 2026

View reviewed changes

github-actions bot added size/xl PR size: XL and removed size/xl PR size: XL labels Apr 16, 2026

aidandaly24 temporarily deployed to e2e-testing April 16, 2026 14:59 — with GitHub Actions Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add AG-UI (AGUI) as fourth first-class protocol mode#858

feat: add AG-UI (AGUI) as fourth first-class protocol mode#858
aidandaly24 wants to merge 11 commits intoaws:mainfrom
aidandaly24:feat/agui-protocol

aidandaly24 commented Apr 15, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

avi-alpert Apr 15, 2026

Uh oh!

avi-alpert Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		# Enable LangGraph FastAPI mode (must be set before langgraph imports)
		os.environ["LANGGRAPH_FAST_API"] = "true"



		if __name__ == "__main__":
		uvicorn.run(app, host="0.0.0.0", port=8080)

	uvicorn.run(app, host="0.0.0.0", port=8080)
	uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

Conversation

aidandaly24 commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What's included:

Related Issue

Documentation PR

Type of Change

Testing

Deployment Testing

Review Rounds

Checklist

Uh oh!

github-actions bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package Tarball

How to install

Uh oh!

avi-alpert Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

avi-alpert Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aidandaly24 commented Apr 15, 2026 •

edited

Loading

github-actions bot commented Apr 15, 2026 •

edited

Loading