feat: add protocol mode support (HTTP, MCP, A2A) (aws#550)

* feat: add protocol mode support (HTTP, MCP, A2A, AGUI)

Add the protocol dimension to all agent creation flows: non-interactive
CLI, TUI wizard, and BYO agent. Each protocol mode routes to the correct
template directory under a new protocol-first layout
(python/{protocol}/{framework}/base/).

Key changes:
- Schema: ProtocolModeSchema, PROTOCOL_FRAMEWORK_MATRIX, helpers
- Templates: restructure under http/, add mcp/, a2a/, agui/ dirs
- Rendering: BaseRenderer uses protocol in template path, new McpRenderer
- CLI: --protocol flag on add agent and create commands with validation
- TUI: protocol step in wizard, conditional framework/model filtering
- Schema mapper: protocolMode passthrough, MCP skips model/memory/creds
- Tests: unit tests for schema, validation, rendering, and mapping

* test: add integration tests for protocol mode creation flows

Add create-protocols.test.ts covering MCP, A2A, AGUI, and HTTP create
and add-agent flows. Fix MCP create defaulting undefined model provider
by falling back to Bedrock (no credential needed). Add protocol option
to createTestProject helper.

* fix: always set explicit protocolMode (including HTTP)

Previously HTTP agents omitted protocolMode for backwards compatibility.
Now all agents have an explicit protocolMode field set to HTTP, MCP,
A2A, or AGUI. This makes the config self-documenting and consistent.

* fix: update A2A and AGUI templates to use bedrock-agentcore-sdk APIs

Align templates with bedrock-agentcore-sdk-python PRs aws#349 and aws#350:

A2A templates now use serve_a2a() from bedrock_agentcore.runtime:
- Strands: StrandsA2AExecutor from strands.multiagent.a2a.executor
- GoogleADK: A2aAgentExecutor with Runner + AgentCard from a2a-sdk
- LangGraph: custom AgentExecutor subclass with AgentCard from a2a-sdk
- Dependencies: bedrock-agentcore[a2a], removed uvicorn/langgraph-a2a

AGUI templates now use serve_ag_ui() and AGUIApp from runtime:
- Strands: StrandsAgent from ag_ui_strands + serve_ag_ui()
- GoogleADK: AGUIApp decorator with Runner, yields AG-UI events
- LangGraph: AGUIApp decorator with graph.ainvoke, yields AG-UI events
- Dependencies: bedrock-agentcore[ag-ui], removed uvicorn/fake adapters

* fix: rename protocolMode to protocol, remove AGUI, fix TUI crash

- Rename `protocolMode` field to `protocol` in AgentEnvSpec schema and
  all downstream types (GenerateConfig, AddAgentConfig, AgentRenderConfig)
- Remove AGUI protocol support (CDK L1 does not support it yet):
  delete all agui templates, remove from enums/matrix/tests/options
- Fix TUI crash in Add Agent -> New Agent flow: ADD_AGENT_STEP_LABELS
  was missing the 'protocol' step, causing StepIndicator to crash on
  undefined.length
- Pass protocol selection through AddAgentConfig so it isn't silently
  dropped when creating agents via the TUI add-agent flow
- Fix type error in create/validate.ts: capture validated ProtocolMode
  from safeParse instead of using untyped string

* Fix lint and format errors from CI

- Remove unnecessary type assertion on cliOptions.protocol
- Remove unused SDK_OPTIONS import from GenerateWizardUI
- Remove unused getSDKOptionsForProtocol import from useGenerateWizard
- Prefix unused destructured variable with underscore in test
- Run prettier on 4 files that failed format check

* Fix integration test: rename protocolMode to protocol, remove AGUI test

The integration test still referenced the old `protocolMode` field name
instead of `protocol`, and included an AGUI test case that was removed
from the schema.

* Fix review findings: missing __init__.py, build validation order

- Add model/__init__.py to all A2A template directories (strands,
  googleadk, langchain_langgraph) matching HTTP template structure
- Move build type validation before MCP early return in create/validate
  so invalid --build values are caught for MCP agents too
- Add clarifying comment for phantom framework/modelProvider defaults
  in MCP path of create/command.tsx

* Address review feedback: McpRenderer, phantom defaults, required protocol

- Add shouldRenderMemory() hook to BaseRenderer, override in McpRenderer
  to return false instead of reimplementing entire render() method
- Make framework/modelProvider optional in CreateWithAgentOptions, resolve
  defaults explicitly in createProjectWithAgent for MCP path
- Make protocol field required in AgentEnvSpecSchema (no backwards compat
  needed per reviewer)
- Update tests for required protocol field

* Add required protocol field to all AgentEnvSpec test fixtures

Making protocol required on AgentEnvSpecSchema means every test fixture
that constructs an AgentCoreRuntime object needs protocol: 'HTTP'.

* Remove accidentally committed ProtocolTesting directory

Local test directory was inadvertently staged during merge commit.
Added to .gitignore to prevent recurrence.

Author: tejaskash

.gitignore

@@ -60,3 +60,4 @@ workdir-tmp/
 bun.lock
 
 .agentreview
+ProtocolTesting/

integ-tests/create-protocols.test.ts

@@ -0,0 +1,274 @@
+/* eslint-disable security/detect-non-literal-fs-filename */
+import { exists, prereqs, readProjectConfig, runCLI } from '../src/test-utils/index.js';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+describe.skipIf(!prereqs.npm || !prereqs.git)('integration: create with protocol modes', () => {
+  let testDir: string;
+
+  beforeAll(async () => {
+    testDir = join(tmpdir(), `agentcore-integ-protocols-${randomUUID()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterAll(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it('creates MCP standalone project (no framework, no model provider)', async () => {
+    const name = `Mcp${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      ['create', '--name', name, '--language', 'Python', '--protocol', 'MCP', '--json'],
+      testDir
+    );
+
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.success).toBe(true);
+
+    const agentName = json.agentName || name;
+    const agentDir = join(json.projectPath, 'app', agentName);
+
+    expect(await exists(agentDir), 'Agent directory should exist').toBe(true);
+    expect(await exists(join(agentDir, 'main.py')), 'main.py should exist').toBe(true);
+    expect(await exists(join(agentDir, 'pyproject.toml')), 'pyproject.toml should exist').toBe(true);
+
+    // Verify pyproject.toml references mcp (FastMCP)
+    const pyproject = await readFile(join(agentDir, 'pyproject.toml'), 'utf-8');
+    expect(pyproject.toLowerCase().includes('mcp'), 'pyproject.toml should reference mcp').toBe(true);
+
+    // Verify config has protocol set to MCP
+    const config = await readProjectConfig(json.projectPath);
+    const agents = config.agents as Record<string, unknown>[];
+    expect(agents).toBeDefined();
+    expect(agents.length).toBe(1);
+    expect(agents[0]!.name).toBe(agentName);
+    expect(agents[0]!.protocol).toBe('MCP');
+
+    // MCP agents should have no credentials
+    const credentials = (config.credentials as Record<string, unknown>[]) ?? [];
+    expect(credentials.length).toBe(0);
+  });
+
+  it('creates A2A project with Strands framework', async () => {
+    const name = `A2a${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      [
+        'create',
+        '--name',
+        name,
+        '--language',
+        'Python',
+        '--protocol',
+        'A2A',
+        '--framework',
+        'Strands',
+        '--model-provider',
+        'Bedrock',
+        '--memory',
+        'none',
+        '--json',
+      ],
+      testDir
+    );
+
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.success).toBe(true);
+
+    const agentName = json.agentName || name;
+    const agentDir = join(json.projectPath, 'app', agentName);
+
+    expect(await exists(agentDir), 'Agent directory should exist').toBe(true);
+    expect(await exists(join(agentDir, 'main.py')), 'main.py should exist').toBe(true);
+
+    // Verify config has protocol set to A2A
+    const config = await readProjectConfig(json.projectPath);
+    const agents = config.agents as Record<string, unknown>[];
+    expect(agents.length).toBe(1);
+    expect(agents[0]!.protocol).toBe('A2A');
+  });
+
+  it('creates HTTP project with explicit protocol HTTP', async () => {
+    const name = `Http${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      [
+        'create',
+        '--name',
+        name,
+        '--language',
+        'Python',
+        '--framework',
+        'Strands',
+        '--model-provider',
+        'Bedrock',
+        '--memory',
+        'none',
+        '--json',
+      ],
+      testDir
+    );
+
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.success).toBe(true);
+
+    // Verify config has explicit protocol: HTTP
+    const config = await readProjectConfig(json.projectPath);
+    const agents = config.agents as Record<string, unknown>[];
+    expect(agents.length).toBe(1);
+    expect(agents[0]!.protocol).toBe('HTTP');
+  });
+
+  it('rejects invalid protocol', async () => {
+    const name = `Bad${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      ['create', '--name', name, '--language', 'Python', '--protocol', 'INVALID', '--json'],
+      testDir
+    );
+
+    expect(result.exitCode).not.toBe(0);
+  });
+
+  it('rejects MCP with --framework flag', async () => {
+    const name = `McpFw${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      ['create', '--name', name, '--language', 'Python', '--protocol', 'MCP', '--framework', 'Strands', '--json'],
+      testDir
+    );
+
+    expect(result.exitCode).not.toBe(0);
+  });
+
+  it('rejects A2A with unsupported framework (CrewAI)', async () => {
+    const name = `A2aCrew${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      [
+        'create',
+        '--name',
+        name,
+        '--language',
+        'Python',
+        '--protocol',
+        'A2A',
+        '--framework',
+        'CrewAI',
+        '--model-provider',
+        'Bedrock',
+        '--memory',
+        'none',
+        '--json',
+      ],
+      testDir
+    );
+
+    expect(result.exitCode).not.toBe(0);
+  });
+});
+
+describe.skipIf(!prereqs.npm || !prereqs.git)('integration: add agent with protocol modes', () => {
+  let testDir: string;
+  let projectPath: string;
+
+  beforeAll(async () => {
+    testDir = join(tmpdir(), `agentcore-integ-add-protocol-${randomUUID()}`);
+    await mkdir(testDir, { recursive: true });
+
+    // Create a base project first (HTTP, no agent)
+    const result = await runCLI(['create', '--name', 'ProtoTest', '--no-agent', '--json'], testDir);
+    expect(result.exitCode, `setup stderr: ${result.stderr}`).toBe(0);
+    const json = JSON.parse(result.stdout);
+    projectPath = json.projectPath;
+  });
+
+  afterAll(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it('adds MCP agent to existing project', async () => {
+    const name = `McpAgent${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      ['add', 'agent', '--name', name, '--protocol', 'MCP', '--language', 'Python', '--json'],
+      projectPath
+    );
+
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.success).toBe(true);
+
+    const config = await readProjectConfig(projectPath);
+    const agents = config.agents as Record<string, unknown>[];
+    const mcpAgent = agents.find(a => a.name === name);
+    expect(mcpAgent).toBeDefined();
+    expect(mcpAgent!.protocol).toBe('MCP');
+  });
+
+  it('adds A2A agent to existing project', async () => {
+    const name = `A2aAgent${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      [
+        'add',
+        'agent',
+        '--name',
+        name,
+        '--protocol',
+        'A2A',
+        '--framework',
+        'Strands',
+        '--model-provider',
+        'Bedrock',
+        '--memory',
+        'none',
+        '--language',
+        'Python',
+        '--json',
+      ],
+      projectPath
+    );
+
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.success).toBe(true);
+
+    const config = await readProjectConfig(projectPath);
+    const agents = config.agents as Record<string, unknown>[];
+    const a2aAgent = agents.find(a => a.name === name);
+    expect(a2aAgent).toBeDefined();
+    expect(a2aAgent!.protocol).toBe('A2A');
+  });
+
+  it('adds BYO agent with MCP protocol', async () => {
+    const name = `ByoMcp${Date.now().toString().slice(-6)}`;
+    const result = await runCLI(
+      [
+        'add',
+        'agent',
+        '--name',
+        name,
+        '--type',
+        'byo',
+        '--protocol',
+        'MCP',
+        '--language',
+        'Python',
+        '--code-location',
+        `app/${name}/`,
+        '--json',
+      ],
+      projectPath
+    );
+
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.success).toBe(true);
+
+    const config = await readProjectConfig(projectPath);
+    const agents = config.agents as Record<string, unknown>[];
+    const byoAgent = agents.find(a => a.name === name);
+    expect(byoAgent).toBeDefined();
+    expect(byoAgent!.protocol).toBe('MCP');
+  });
+});