awslabs · nx-plugin-for-aws · Mar 31, 2026 · Mar 31, 2026 · Apr 2, 2026 · Apr 2, 2026
diff --git a/docs/src/content/docs/en/get_started/tutorials/dungeon-game/1.mdx b/docs/src/content/docs/en/get_started/tutorials/dungeon-game/1.mdx
@@ -399,21 +399,20 @@ This has configured a Python project and [UV Workspace](https://docs.astral.sh/u
 
 ### Story agent: Strands Agent
 
-To add a Strands agent to the project with the `py#strands-agent` generator:
+To add a Strands agent to the project with the `py#strands-agent` generator. We use the `AG-UI` protocol to enable direct frontend integration via [CopilotKit](https://copilotkit.ai/):
 
-<RunGenerator generator="py#strands-agent" requiredParameters={{project:"story"}} noInteractive />
+<RunGenerator generator="py#strands-agent" requiredParameters={{project:"story", protocol:"AG-UI"}} noInteractive />
 
 You will see some new files appear in your file tree.
 <Drawer title="py#strands-agent updated files" trigger="Click here to examine these files in more detail.">
-The `py#strands-agent` generates these files:
+The `py#strands-agent` generates these files (with `protocol=AG-UI`):
 
 <FileTree>
 - packages/
   - story/
     - dungeon_adventure_story/ python module
       - agent/
-        - init.py sets up the FastAPI app and middleware
-        - main.py entrypoint for your agent in Bedrock AgentCore Runtime
+        - main.py AG-UI server entry point using ag-ui-strands
         - agent.py defines an example agent and tools
         - Dockerfile defines the docker image for deployment to AgentCore Runtime
   - common/constructs/
@@ -995,6 +994,36 @@ The generator:
 For more details, refer to the <Link path="guides/connection/py-strands-agent-mcp">Python Strands Agent to MCP connection guide</Link>.
 </Drawer>
 
+### Game UI: Connect to Story Agent
+
+Let us connect our React Game UI to the Story Agent so the frontend can communicate with the agent via the AG-UI protocol using [CopilotKit](https://copilotkit.ai/).
+
+<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-ui", targetProject:"story", targetComponent:"agent"}} noInteractive />
+
+<Drawer title="Game UI -> Story Agent connection updated files" trigger="Click here to examine these files in more detail.">
+The `connection` generator generates/updates these files:
+
+<FileTree>
+- packages/
+  - game-ui/
+    - src/
+      - components/
+        - **AgentCopilotProvider.tsx** Sets up CopilotKit with AG-UI HttpAgent and auth
+      - hooks/
+        - **useSigV4.tsx** Hook for signing requests with SigV4 (when using IAM auth)
+      - **main.tsx** Updated to wrap the app in the CopilotKit provider
+
+</FileTree>
+
+The generator:
+- Creates a `AgentCopilotProvider` component that connects to the AG-UI agent via `@ag-ui/client`'s `HttpAgent`
+- Handles authentication (IAM/Cognito) for AgentCore requests
+- Wraps the app in the CopilotKit provider in `main.tsx`
+- Updates the `serve-local` target to automatically start the agent when running locally
+
+For more details, refer to the <Link path="guides/connection/react-py-strands-agent">React to Python Strands Agent AG-UI connection guide</Link>.
+</Drawer>
+
 ### Game UI: Infrastructure
 
 Let us create the final sub-project for the CDK infrastructure.

diff --git a/docs/src/content/docs/en/guides/connection/react-py-strands-agent.mdx b/docs/src/content/docs/en/guides/connection/react-py-strands-agent.mdx
@@ -0,0 +1,136 @@
+---
+title: React to Python Strands Agent (AG-UI)
+description: Connect a React website to a Python Strands Agent via the AG-UI protocol
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+
+Nx Plugin for AWS provides a generator to quickly integrate your <Link path="guides/py-strands-agent">Python Strands Agent</Link> with a React website via the [AG-UI protocol](https://docs.ag-ui.com/). It sets up [CopilotKit](https://copilotkit.ai/) components for a rich, out-of-the-box chat experience with your agent, including AWS IAM and Cognito authentication support.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A React website (generated using the <Link path="guides/react-website">`ts#react-website` generator</Link>)
+2. A Python Strands Agent with `protocol=AG-UI` (generated using the <Link path="guides/py-strands-agent">`py#strands-agent` generator</Link>)
+3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#react-website-auth` generator</Link>
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+You will be prompted to select your React website as the source project and the project containing your Python Strands Agent as the target project. If your target project contains multiple components (such as multiple agents or other component types), you will be prompted to specify a `targetComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator creates the following structure in your React application:
+
+<FileTree>
+
+- src
+  - components
+    - \<AgentName>CopilotProvider.tsx Sets up the CopilotKit provider with AG-UI HttpAgent
+  - hooks
+    - useSigV4.tsx Hook for signing requests with SigV4 (IAM only)
+
+</FileTree>
+
+Additionally, it installs the required dependencies:
+
+  - `@copilotkit/react-core`
+  - `@copilotkit/react-ui`
+  - `@ag-ui/client`
+  - `aws4fetch` (if using IAM auth)
+
+## How It Works
+
+### AG-UI Connection
+
+The generated client connects to your Python Strands Agent via the [AG-UI protocol](https://docs.ag-ui.com/), an open standard for Agent-User Interaction. The agent uses the [`ag-ui-strands`](https://pypi.org/project/ag-ui-strands/) library to expose the Strands agent via Server-Sent Events (SSE) over HTTP.
+
+- **Deployed**: The agent runtime ARN is loaded from <Link path="guides/runtime-config">Runtime Configuration</Link>. The ARN is converted to the AgentCore HTTP endpoint: `https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT`
+- **Local development**: When running with `serve-local`, the runtime config override sets the value to a local HTTP URL (e.g., `http://localhost:8081`)
+
+### CopilotKit Integration
+
+The connection uses [CopilotKit](https://copilotkit.ai/) to provide a production-ready chat UI. CopilotKit is the 1st-party reference React client for the AG-UI protocol and provides:
+
+- `<CopilotChat />` - Full chat interface
+- `<CopilotSidebar />` - Fixed side panel chat
+- `<CopilotPopup />` - Floating chat popup
+
+Import these from `@copilotkit/react-core/v2` and place them anywhere within the `<AgentNameCopilotProvider>` wrapper.
+
+### Authentication
+
+The generated code handles authentication depending on your agent's configuration:
+
+- **IAM** (default): Uses AWS SigV4 signed HTTP requests. Credentials are obtained from the Cognito Identity Pool configured with your website's auth
+- **Cognito**: Embeds the JWT access token in the `Authorization` header as a Bearer token
+
+## Using the Generated Code
+
+### Adding a Chat Interface
+
+The CopilotKit provider wraps your application and provides access to the agent. You can add a chat component anywhere within the provider:
+
+```tsx
+import { CopilotChat } from '@copilotkit/react-core/v2';
+
+function ChatPage() {
+  return (
+    <CopilotChat
+      labels={{
+        welcomeMessageText: 'How can I help you today?',
+        chatInputPlaceholder: 'Ask me anything...',
+      }}
+    />
+  );
+}
+```
+
+### Using a Sidebar or Popup
+
+For a sidebar or popup chat experience:
+
+```tsx
+import { CopilotSidebar } from '@copilotkit/react-core/v2';
+
+function App() {
+  return (
+    <div>
+      <YourMainContent />
+      <CopilotSidebar />
+    </div>
+  );
+}
+```
+
+## Local Development
+
+The connection generator automatically configures `serve-local` integration for your react website:
+
+1. Running `nx run <website>:serve-local` will also start the agent's local server
+2. The runtime config is overridden to point to the local AG-UI HTTP URL (e.g., `http://localhost:8081`)
+3. Authentication is skipped in `serve-local` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+
+:::tip[Hot Reloading]
+The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.
+:::
+
+## More Information
+
+For more information, please refer to:
+
+- <Link path="guides/py-strands-agent">Python Strands Agent Guide</Link>
+- [AG-UI Protocol Documentation](https://docs.ag-ui.com/)
+- [CopilotKit Documentation](https://docs.copilotkit.ai/)
+- [Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui.html)
diff --git a/docs/src/content/docs/en/guides/py-strands-agent.mdx b/docs/src/content/docs/en/guides/py-strands-agent.mdx
@@ -12,7 +12,7 @@ import Infrastructure from '@components/infrastructure.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 import Drawer from '@components/drawer.astro';
 
-Generate a Python [Strands Agent](https://strandsagents.com/) for building AI agents with tools, and optionally deploy it to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/).
+Generate a Python [Strands Agent](https://strandsagents.com/) for building AI agents with tools, and optionally deploy it to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/). By default, the generator uses [FastAPI](https://fastapi.tiangolo.com/) to expose an HTTP server. Alternatively, you can choose the [Agent-to-Agent (A2A)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) protocol for interoperability with other A2A-compatible agents, or the [AG-UI](https://docs.ag-ui.com/) protocol for direct frontend integration via [CopilotKit](https://copilotkit.ai/).
 
 ## What is Strands?
 
@@ -43,7 +43,9 @@ First use the <Link path="/guides/python-project">`py#project`</Link> generator
 
 ## Generator Output
 
-The generator will add the following files to your existing Python project:
+The generator will add the following files to your existing Python project. The files generated depend on the chosen `protocol`:
+
+### HTTP Protocol (default)
 
 <FileTree>
   - your-project/
@@ -52,12 +54,48 @@ The generator will add the following files to your existing Python project:
         - \_\_init\_\_.py Python package initialization
         - init.py FastAPI application setup with CORS and error handling middleware
         - agent.py Main agent definition with sample tools
-        - main.py Entry point for Bedrock AgentCore Runtime
+        - main.py FastAPI entry point for Bedrock AgentCore Runtime
         - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
     - pyproject.toml Updated with Strands dependencies
     - project.json Updated with agent serve targets
 </FileTree>
 
+### A2A Protocol
+
+When `protocol` is set to `A2A`, the entry point uses the [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) instead of FastAPI:
+
+<FileTree>
+  - your-project/
+    - your_module/
+      - agent/ (or custom name if specified)
+        - \_\_init\_\_.py Python package initialization
+        - agent.py Main agent definition with sample tools
+        - main.py A2A server entry point
+        - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
+    - pyproject.toml Updated with Strands dependencies
+    - project.json Updated with agent serve targets
+</FileTree>
+
+### AG-UI Protocol
+
+When `protocol` is set to `AG-UI`, the entry point uses the [AG-UI Strands](https://docs.ag-ui.com/) integration, which exposes your agent via the AG-UI protocol for direct frontend integration with [CopilotKit](https://copilotkit.ai/):
+
+<FileTree>
+  - your-project/
+    - your_module/
+      - agent/ (or custom name if specified)
+        - \_\_init\_\_.py Python package initialization
+        - agent.py Main agent definition with sample tools
+        - main.py AG-UI server entry point using ag-ui-strands
+        - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
+    - pyproject.toml Updated with Strands and AG-UI dependencies
+    - project.json Updated with agent serve targets
+</FileTree>
+
+:::tip
+AG-UI agents can be connected to a React frontend using the `connection` generator, which will set up [CopilotKit](https://copilotkit.ai/) components for a rich chat experience.
+:::
+
 ### Infrastructure
 
 :::note
@@ -174,7 +212,16 @@ For other MCP servers, please refer to the [Strands Documentation](https://stran
 
 For a more in-depth guide to writing Strands agents, refer to the [Strands documentation](https://strandsagents.com/docs/user-guide/quickstart/overview/).
 
-## FastAPI Server
+## Protocol
+
+Your agent's server protocol determines how it communicates. You can choose between:
+
+- **HTTP** (default): Uses [FastAPI](https://fastapi.tiangolo.com/) for a full-featured HTTP server with streaming, OpenAPI docs, and CORS support. Best for custom client integrations.
+- **A2A**: Uses the [Agent-to-Agent (A2A)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) protocol for standardized inter-agent communication. Best when your agent needs to be discoverable and invokable by other A2A-compatible agents.
+
+The protocol is set in the CDK/Terraform infrastructure, and the application code is generated accordingly.
+
+## FastAPI Server (HTTP protocol)
 
 The generator uses [FastAPI](https://fastapi.tiangolo.com/) to create the HTTP server for your Strands Agent. FastAPI provides a modern, fast web framework for building APIs with Python, with automatic API documentation and type validation.
 
@@ -257,6 +304,38 @@ You can find more details about the SDK's capabilities in the [documentation her
 Since the generator vends CDK or Terraform infrastructure which manages deploying your agent, you do not need to utilise the `bedrock-agentcore-starter-toolkit` which the docs mention for deploying your agent.
 :::
 
+## A2A Server
+
+When using the A2A protocol, the generated `main.py` uses the [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent), exposed as a FastAPI app for hot-reload support during development:
+
+```python
+from strands.multiagent.a2a import A2AServer
+from .agent import get_agent
+
+_agent_ctx = get_agent(session_id="default")
+_agent = _agent_ctx.__enter__()
+
+a2a_server = A2AServer(
+    agent=_agent,
+    name="MyAgent",
+    description="My A2A agent",
+    port=9000,
+)
+
+# Exposed as a FastAPI app for hot reloading with `fastapi dev`
+app = a2a_server.to_fastapi_app()
+```
+
+The A2A server automatically:
+- Serves the agent card at `/.well-known/agent-card.json`
+- Handles JSON-RPC requests at the root path
+- Supports streaming responses by default
+- Runs on port `9000` by default (per the Strands A2A SDK convention)
+
+:::note
+A2A agents use port `9000` by default, which differs from the `8080` port used by HTTP agents. The Dockerfile and CDK/Terraform infrastructure are configured accordingly.
+:::
+
 ## Running Your Strands Agent
 
 ### Local Development
@@ -498,3 +577,41 @@ aws cognito-idp admin-initiate-auth \
   --query 'AuthenticationResult.AccessToken' \
   --output text
 ```
+
+### Invoking an A2A Agent
+
+A2A agents use the standardized [Agent-to-Agent protocol](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) for communication. You can invoke them using the Strands A2A client tool.
+
+#### Using the Strands A2A Client Tool
+
+Install `strands-agents-tools` with the A2A extra:
+
+```bash
+pip install 'strands-agents-tools[a2a_client]'
+```
+
+Then use the `A2AClientToolProvider` to discover and interact with your A2A agent:
+
+```python
+from strands import Agent
+from strands_tools.a2a_client import A2AClientToolProvider
+
+# Point to your locally running A2A agent
+provider = A2AClientToolProvider(known_agent_urls=["http://127.0.0.1:9000"])
+
+# Create an agent with A2A client tools
+agent = Agent(tools=provider.tools)
+
+# The agent can now discover and interact with the A2A server
+response = agent("pick an agent and make a sample call")
+print(response)
+```
+
+The A2A client tool provides:
+- **Agent Discovery**: Automatically discover available A2A agents and their capabilities via `/.well-known/agent-card.json`
+- **Protocol Communication**: Send messages using the standardized A2A protocol
+- **Natural Language Interface**: Interact with remote agents using natural language
+
+:::note
+The A2A client tool is currently available for Python only. For TypeScript, you can interact with A2A agents using the [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) package directly.
+:::