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

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

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

* fix: address review findings for AGUI protocol implementation

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)

* fix: add AGUI to TUI protocol picker and dev mode dispatch

- 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')

* fix: A2A GoogleADK template passes model=None to Agent constructor

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().

* chore: update protocol references to include AGUI across CLI

- 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

* fix: add InvokeLogger to AGUI CLI path and improve UX polish

- 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)'

* fix: template bugs found during deployment testing

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)

* fix: add ToolNode + ReAct loop to AGUI LangGraph template

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

* fix: address all review findings from AG-UI protocol code review

16 issues from 4-lane parallel code review, all addressed:

Critical fixes:
- Strands template: use session_manager_provider from ag-ui-strands 0.1.7
  instead of hardcoded "default-session"/"default-user"
- Dev client: persist threadId per session for multi-turn conversations
- CRLF handling: use /\r?\n/ in SSE parsers (invoke-agui + invoke.ts)
- Malformed JSON no longer yielded as content (shared parser skips)
- Unbounded aguiEvents array replaced with bounded cursor-based pruning

Structural improvements:
- Unified SSE parser (agui-parser.ts) replaces two divergent parsers
  in invoke-agui.ts (dev) and agentcore.ts (deployed). Net -39 LOC.
- Dual-consumer support with singleConsumer mode for dev path
- AguiEvent type union completed (4 missing members added)
- Dynamic imports converted to static where non-intentional (AGENTS.md)

Python template fixes:
- LangGraph: add LangchainInstrumentor + dep, remove unused END import,
  MemorySaver already removed in prior commit
- GoogleADK: remove dead load_model() + bedrock-agentcore dep, remove
  hardcoded user_id (ADK defaults to per-thread identity)
- Strands: bump ag-ui-strands pin to >= 0.1.7

enableOtel plumbing:
- Dockerfile CMD conditional on enableOtel (Handlebars)
- enableOtel threaded through AgentRenderConfig + BaseRenderer
- Import path: ProtocolModeSchema.safeParse replaces unsafe as-cast
- Import path: MCP enableOtel clamped regardless of YAML value
- GoogleADK uses plain opentelemetry-distro (aws-distro conflicts)

DX + testing:
- formatZodIssue falls back to issue.code instead of literal "undefined"
- New dockerfile-render.test.ts covers both enableOtel branches
- All snapshots updated

* fix: add AGUI to JSON schema protocol enum

The static JSON schema file used for CDK validation was not updated
when AGUI was added to the Zod schema. This caused CDK synth to
reject protocol: "AGUI" with a misleading validation error.

* fix: restore MemorySaver in AGUI LangGraph template

ag_ui_langgraph calls aget_state(config) with thread_id which requires
a checkpointer. Without it, every invocation throws ValueError: No
checkpointer set. The original msgpack crash only triggers with numbers
exceeding 2^63 (ormsgpack limitation), not with normal large numbers.
Bug bash confirmed: 325435 + 435634563456456 works correctly with
MemorySaver present.

* fix: address final review findings in AGUI parser

- Wrap reader.releaseLock() in try/catch to prevent error masking
  if lock is already released (HIGH from code review)
- Replace textStream! non-null assertion with runtime guard
  (MEDIUM from code review)

* fix: use toolCallId for TOOL_CALL_RESULT matching in dev client

Previously matched by activeToolName which was already reset to '' by
TOOL_CALL_END. The find() never matched, falling through to the last
tool call — wrong for parallel tool calls. Now matches by toolCallId
which is the unique identifier AG-UI provides per tool invocation.

* revert: remove manual JSON schema edit (auto-generated during release)

The schemas/ directory is auto-regenerated from Zod schemas during the
release workflow. AGUI is already in ProtocolModeSchema (constants.ts)
and will appear in the JSON schema on next release.

* fix: add configurable PORT env var to AGUI templates + update snapshots

All 3 AGUI templates now read PORT from env with default 8080:
  uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

Addresses PR review comment requesting configurable port for local testing.

* fix: use AG-UI in user-facing strings instead of AGUI

Schema enum stays 'AGUI' (internal), but TUI display text uses
'AG-UI' which is the protocol's official name.

* fix: restore credential wiring in AGUI GoogleADK template

The template was missing load_model() call and bedrock-agentcore dep,
so GOOGLE_API_KEY was never set from the AgentCore credential. Both
dev mode and deployed agents failed with "No API key provided."

* fix: convert AGUI dynamic import to static in invokeForProtocol

AGENTS.md requires all imports at top of file. The dynamic import had
no meaningful performance benefit — AGUI parser is ~4KB in a 2.1MB CLI.

Author: aidandaly24

src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -0,0 +1,77 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Dockerfile enableOtel rendering > renders opentelemetry-instrument CMD when enableOtel is true > Dockerfile-enableOtel-true 1`] = `
+"FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+
+WORKDIR /app
+
+ENV UV_SYSTEM_PYTHON=1 \\
+    UV_COMPILE_BYTECODE=1 \\
+    UV_NO_PROGRESS=1 \\
+    PYTHONUNBUFFERED=1 \\
+    DOCKER_CONTAINER=1 \\
+    UV_DEFAULT_INDEX=\${UV_DEFAULT_INDEX} \\
+    UV_INDEX=\${UV_INDEX} \\
+    PATH="/app/.venv/bin:$PATH"
+
+RUN useradd -m -u 1000 bedrock_agentcore
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY --chown=bedrock_agentcore:bedrock_agentcore . .
+RUN uv sync --frozen --no-dev
+
+USER bedrock_agentcore
+
+# AgentCore Runtime service contract ports
+# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html
+# 8080: HTTP Mode
+# 8000: MCP Mode
+# 9000: A2A Mode
+EXPOSE 8080 8000 9000
+
+CMD ["opentelemetry-instrument", "python", "-m", "main"]
+"
+`;
+
+exports[`Dockerfile enableOtel rendering > renders plain python CMD when enableOtel is false > Dockerfile-enableOtel-false 1`] = `
+"FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+
+WORKDIR /app
+
+ENV UV_SYSTEM_PYTHON=1 \\
+    UV_COMPILE_BYTECODE=1 \\
+    UV_NO_PROGRESS=1 \\
+    PYTHONUNBUFFERED=1 \\
+    DOCKER_CONTAINER=1 \\
+    UV_DEFAULT_INDEX=\${UV_DEFAULT_INDEX} \\
+    UV_INDEX=\${UV_INDEX} \\
+    PATH="/app/.venv/bin:$PATH"
+
+RUN useradd -m -u 1000 bedrock_agentcore
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY --chown=bedrock_agentcore:bedrock_agentcore . .
+RUN uv sync --frozen --no-dev
+
+USER bedrock_agentcore
+
+# AgentCore Runtime service contract ports
+# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html
+# 8080: HTTP Mode
+# 8000: MCP Mode
+# 9000: A2A Mode
+EXPOSE 8080 8000 9000
+
+CMD ["python", "-m", "main"]
+"
+`;

src/assets/__tests__/__snapshots__/dockerfile-render.test.ts.snap

@@ -0,0 +1,24 @@
+import * as fs from 'fs';
+import Handlebars from 'handlebars';
+import * as path from 'path';
+import { describe, expect, it } from 'vitest';
+
+const DOCKERFILE_PATH = path.resolve(__dirname, '..', 'container', 'python', 'Dockerfile');
+
+describe('Dockerfile enableOtel rendering', () => {
+  const template = Handlebars.compile(fs.readFileSync(DOCKERFILE_PATH, 'utf-8'));
+
+  it('renders opentelemetry-instrument CMD when enableOtel is true', () => {
+    const rendered = template({ entrypoint: 'main', enableOtel: true });
+    expect(rendered).toMatchSnapshot('Dockerfile-enableOtel-true');
+    expect(rendered).toContain('opentelemetry-instrument');
+    expect(rendered).not.toContain('CMD ["python", "-m"');
+  });
+
+  it('renders plain python CMD when enableOtel is false', () => {
+    const rendered = template({ entrypoint: 'main', enableOtel: false });
+    expect(rendered).toMatchSnapshot('Dockerfile-enableOtel-false');
+    expect(rendered).toContain('CMD ["python", "-m"');
+    expect(rendered).not.toContain('opentelemetry-instrument');
+  });
+});

src/assets/__tests__/dockerfile-render.test.ts

@@ -31,4 +31,8 @@ USER bedrock_agentcore
 # 9000: A2A Mode
 EXPOSE 8080 8000 9000
 
+{{#if enableOtel}}
 CMD ["opentelemetry-instrument", "python", "-m", "{{entrypoint}}"]
+{{else}}
+CMD ["python", "-m", "{{entrypoint}}"]
+{{/if}}

src/assets/container/python/Dockerfile

@@ -7,6 +7,8 @@
 from bedrock_agentcore.runtime import serve_a2a
 from model.load import load_model
 
+load_model()  # Sets GOOGLE_API_KEY env var (returns None)
+
 
 def add_numbers(a: int, b: int) -> int:
     """Return the sum of two numbers."""
@@ -73,7 +75,7 @@ def list_files(directory: str = "") -> str:
 """
 
 agent = Agent(
-    model=load_model(),
+    model="gemini-2.5-flash",
     name="{{ name }}",
     description="A helpful assistant that can use tools.",
     instruction=AGENT_INSTRUCTION,

src/assets/python/a2a/googleadk/base/main.py

@@ -0,0 +1,30 @@
+# {{ name }}
+
+An AG-UI agent deployed on Amazon Bedrock AgentCore using Google ADK.
+
+## Overview
+
+This agent implements the AG-UI protocol using Google's Agent Development Kit, enabling rich agent-user interaction via the AG-UI event stream.
+
+## Local Development
+
+```bash
+uv sync
+uv run python main.py
+```
+
+The agent starts on port 8080 and serves requests at `/invocations`.
+
+## Health Check
+
+```
+GET /ping
+```
+
+Returns `{"status": "healthy"}`.
+
+## Deploy
+
+```bash
+agentcore deploy
+```

src/assets/python/agui/googleadk/base/README.md

@@ -0,0 +1,41 @@
+# Environment variables
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

src/assets/python/agui/googleadk/base/gitignore.template

@@ -0,0 +1,31 @@
+import os
+import uvicorn
+from google.adk.agents import LlmAgent
+from ag_ui_adk import ADKAgent, AGUIToolset, create_adk_app
+from model.load import load_model
+
+load_model()
+
+agent = LlmAgent(
+    name="{{ name }}",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant.",
+    tools=[AGUIToolset()],
+)
+
+adk_agent = ADKAgent(
+    adk_agent=agent,
+    app_name="{{ name }}",
+    use_in_memory_services=True,
+)
+
+app = create_adk_app(adk_agent, path="/invocations")
+
+
+@app.get("/ping")
+async def ping():
+    return {"status": "healthy"}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

src/assets/python/agui/googleadk/base/main.py

@@ -0,0 +1 @@
+# Package marker

src/assets/python/agui/googleadk/base/model/__init__.py

@@ -0,0 +1,41 @@
+import os
+from bedrock_agentcore.identity.auth import requires_api_key
+
+IDENTITY_PROVIDER_NAME = "{{identityProviders.[0].name}}"
+IDENTITY_ENV_VAR = "{{identityProviders.[0].envVarName}}"
+
+
+@requires_api_key(provider_name=IDENTITY_PROVIDER_NAME)
+def _agentcore_identity_api_key_provider(api_key: str) -> str:
+    """Fetch API key from AgentCore Identity."""
+    return api_key
+
+
+def _get_api_key() -> str:
+    """
+    Uses AgentCore Identity for API key management in deployed environments.
+    For local development, run via 'agentcore dev' which loads agentcore/.env.
+    """
+    if os.getenv("LOCAL_DEV") == "1":
+        api_key = os.getenv(IDENTITY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
+            )
+        return api_key
+    return _agentcore_identity_api_key_provider()
+
+
+def load_model() -> None:
+    """
+    Set up Gemini API key authentication.
+    Uses AgentCore Identity for API key management in deployed environments,
+    and falls back to .env file for local development.
+    Sets the GOOGLE_API_KEY environment variable for the Google ADK.
+    """
+    api_key = _get_api_key()
+    # Use Google AI Studios API Key Authentication.
+    # https://google.github.io/adk-docs/agents/models/#google-ai-studio
+    os.environ["GOOGLE_API_KEY"] = api_key
+    # Set to TRUE is using Google Vertex AI, Set to FALSE for Google AI Studio
+    os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "FALSE"