@aws/nx-plugin-mcp 0.119.0 → 0.121.0

package/docs/guides/connection/react-agui.mdx

@@ -0,0 +1,240 @@
+---
+title: React to AG-UI Agent
+description: Connect a React website to an Agent via the AG-UI protocol using CopilotKit
+when:
+  sourceType: react
+  targetType:
+    - ts#agent
+    - py#agent
+  protocol: AG-UI
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Snippet from '@components/snippet.astro';
+
+Nx Plugin for AWS provides a generator to connect a React website to an Agent that exposes the [AG-UI protocol](https://docs.ag-ui.com/). It wires up [CopilotKit](https://docs.copilotkit.ai/aws-strands) with an [`@ag-ui/client`](https://docs.ag-ui.com/) `HttpAgent` on your website, with 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 TypeScript or Python Agent with `protocol=AG-UI` (generated using the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator)
+3. For deployed agents, 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 AG-UI 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 a **single shared** `AguiProvider` component, one hook per connected agent, and a themed wrapper for the CopilotKit chat components:
+
+<FileTree>
+
+- src
+  - components
+    - AguiProvider.tsx Single `CopilotKitProvider` for every AG-UI agent. Created on the first `connection` run and updated on subsequent runs to register each new agent.
+    - copilot
+      - index.tsx Re-exports `CopilotChat`, `CopilotSidebar` and `CopilotPopup` with slot defaults that match your website's `uxProvider` (Cloudscape, Shadcn, or no theme at all).
+      - *ThemeComponents*.tsx Per-slot theme components (e.g. `CloudscapeAssistantMessage.tsx`, `ShadcnChatInput.tsx`). Only vended when `uxProvider` is `Cloudscape` or `Shadcn`.
+  - hooks
+    - useAgui\<AgentName>.tsx Registers one AG-UI agent. One file per `connection` run.
+    - useSigV4.tsx SigV4 signing (IAM only)
+
+</FileTree>
+
+Running `connection` a second time for a different agent **adds a new `useAgui<AgentName>.tsx` hook** and updates `AguiProvider.tsx` to register both hooks — any custom edits you've made to the provider are preserved. `main.tsx` keeps its single `<AguiProvider>` wrapper — you never end up with nested providers.
+
+The following dependencies are added to the root `package.json`:
+
+- `@copilotkit/react-core` — ships `CopilotKitProvider` and chat components (`CopilotChat`, `CopilotSidebar`, `CopilotPopup`)
+- `@ag-ui/client` — `HttpAgent` used by the generated hooks
+- `aws4fetch`, `oidc-client-ts`, `react-oidc-context`, `@aws-sdk/credential-providers` — IAM auth only
+- `react-oidc-context` — Cognito auth
+
+## How It Works
+
+### AG-UI Connection
+
+Each `useAgui<AgentName>` hook reads its agent's runtime value from <Link path="guides/runtime-config">Runtime Configuration</Link> and instantiates an `@ag-ui/client` `HttpAgent`:
+
+- **Deployed**: the runtime value is a Bedrock AgentCore Runtime ARN, which is converted to the AgentCore HTTPS endpoint: `https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT`
+- **Local development**: `serve-local` overrides the value to the agent's local URL (e.g. `http://localhost:8081`)
+
+The shared `AguiProvider` calls every generated hook and spreads each one into `selfManagedAgents` on a single `CopilotKitProvider`, which exposes them all to CopilotKit components.
+
+### CopilotKit Integration
+
+[CopilotKit](https://docs.copilotkit.ai/aws-strands) is the 1st-party reference React client for the AG-UI protocol and ships ready-made chat components:
+
+- `<CopilotChat />` — full chat interface
+- `<CopilotSidebar />` — fixed side panel chat
+- `<CopilotPopup />` — floating chat popup
+
+Place any of these anywhere inside the `<AguiProvider>` wrapper (already wired into `main.tsx` for you).
+
+### 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.
+
+## Infrastructure
+
+<Snippet name="connection/react-agent-infrastructure" parentHeading="Infrastructure" />
+
+## Using the Generated Code
+
+### Adding a Chat Interface
+
+Instantiate CopilotKit components with `agentId` to select which agent to use. The id is the agent's name — the same one you chose when you ran the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator — and you can also find it in the generated hook file (e.g. the key returned from `packages/web/src/hooks/useAgui<AgentName>.tsx`).
+
+Import the chat components from the generated `./components/copilot` module so the theme that matches your website's `uxProvider` is applied automatically:
+
+```tsx
+import { CopilotChat } from './components/copilot';
+
+function ChatPage() {
+  return (
+    <CopilotChat
+      agentId="agent"
+      labels={{
+        welcomeMessageText: 'How can I help you today?',
+        chatInputPlaceholder: 'Ask me anything...',
+      }}
+    />
+  );
+}
+```
+
+### Connecting Multiple AG-UI Agents
+
+Run the `connection` generator once per agent. Every agent registered via the shared `AguiProvider` is visible from anywhere in the app — instantiate a CopilotKit component with a different `agentId` to route each chat to the agent you want:
+
+```tsx
+import { CopilotChat } from './components/copilot';
+
+<CopilotChat agentId="story" />    {/* talks to StoryAgent */}
+<CopilotChat agentId="research" /> {/* talks to ResearchAgent */}
+```
+
+## Customising the Look and Feel
+
+`<CopilotChat />` (and `<CopilotSidebar />`, `<CopilotPopup />`) use a recursive **slot system** — you can override any sub-component with either a Tailwind class string, a prop object, or a custom React component. See the [CopilotKit slots guide](https://docs.copilotkit.ai/aws-strands/custom-look-and-feel/slots) for the full slot tree.
+
+### Built-in Themes
+
+The generator reads `metadata.uxProvider` from your React website project and vends a themed wrapper module at `src/components/copilot/index.tsx` so the chat components match the rest of your UI without any extra configuration:
+
+| `uxProvider` | Styling applied to `CopilotChat` / `CopilotSidebar` / `CopilotPopup` |
+| ------------ | -------------------------------------------------------------------- |
+| `Cloudscape` | Messages render inside Cloudscape `ChatBubble`s with gen-AI `Avatar`s (matching the [Cloudscape generative AI chat pattern](https://cloudscape.design/patterns/genai/generative-AI-chat/)); the typing indicator becomes a `LoadingBar` and the input is a `PromptInput`. Built from `@cloudscape-design/components` and `@cloudscape-design/chat-components`. |
+| `Shadcn` | Assistant messages render in a `bg-muted` bubble with a `Sparkles` avatar; user messages render right-aligned in a `bg-primary` bubble with a `User` avatar. The input is a rounded `Textarea` + pill-shaped send/stop `Button` (Enter submits, Shift+Enter newlines). Uses shadcn primitives from the shared `common-shadcn` package. |
+| `None` (or anything else) | No theme — the module just re-exports the default CopilotKit components. |
+
+Import the themed components from the **local theme module** (not `@copilotkit/react-core/v2` directly) so the theme is applied automatically:
+
+```tsx
+import { CopilotChat } from './components/copilot';
+
+<CopilotChat agentId="agent" />
+```
+
+The theme is applied as slot defaults, so any slot you explicitly pass still wins — you keep full control whenever you need a one-off override.
+
+### Customising the Theme
+
+The generated theme lives entirely inside your project:
+
+- `src/components/copilot/index.tsx` — exports the themed `CopilotChat` / `CopilotSidebar` / `CopilotPopup` and the `cloudscapeCopilotTheme` / `shadcnCopilotTheme` objects. Edit this file to change the default slot wiring for every chat in your app.
+- `src/components/copilot/<ThemeComponent>.tsx` — per-slot theme components (e.g. `CloudscapeAssistantMessage`, `ShadcnChatInput`). Edit these to tweak the look of a single slot without re-wiring the theme.
+
+For example, to drop in your own user-message renderer while keeping the rest of the theme, edit the relevant file in `src/components/copilot/` and re-export it from `index.tsx`.
+
+### Tailwind styling via slots
+
+Per-chat overrides still work alongside the theme — anything you pass as a slot prop overrides the themed default:
+
+```tsx
+<CopilotChat
+  agentId="agent"
+  // style the input and its children
+  input={{
+    textArea: 'text-blue-600',
+    sendButton: 'bg-blue-600 hover:bg-blue-700',
+  }}
+  // style nested message slots
+  messageView={{
+    assistantMessage: 'bg-blue-50 rounded-xl p-2',
+    userMessage: 'bg-blue-100 rounded-xl',
+  }}
+/>
+```
+
+### Replacing a slot with a custom component
+
+Any slot can take a React component instead of a className, so you can replace the default entirely:
+
+```tsx
+import { CopilotChat } from './components/copilot';
+
+const MySendButton: React.FC<{ onClick: () => void }> = ({ onClick }) => (
+  <button onClick={onClick} className="my-send-btn">
+    Send
+  </button>
+);
+
+<CopilotChat
+  agentId="agent"
+  input={{ sendButton: MySendButton }}
+/>;
+```
+
+Deeper overrides follow the same shape — e.g. replace just the copy button on assistant messages:
+
+```tsx
+<CopilotChat
+  agentId="agent"
+  messageView={{
+    assistantMessage: {
+      copyButton: ({ onClick }) => <button onClick={onClick}>Copy</button>,
+    },
+  }}
+/>
+```
+
+## Local Development
+
+The connection generator automatically configures `serve-local` integration:
+
+1. Running `nx serve-local <website>` will also start the agent's local server
+2. The runtime config is overridden to point to the local AG-UI URL (e.g. `http://localhost:8081`)
+3. Both the website and the agent hot-reload together
+
+<NxCommands commands={['serve-local <WebsiteProject>']} />
+
+:::tip[Hot Reloading]
+The website and connected agent hot-reload together, enabling you to quickly iterate on both sides without deploying to AWS.
+:::
+
+## More Information
+
+- <Link path="guides/ts-agent">TypeScript Agent Guide</Link>
+- <Link path="guides/py-agent">Python Agent Guide</Link>
+- [AG-UI Protocol Documentation](https://docs.ag-ui.com/)
+- [CopilotKit + AWS Strands Documentation](https://docs.copilotkit.ai/aws-strands)
+- [CopilotKit Custom Look & Feel](https://docs.copilotkit.ai/aws-strands/custom-look-and-feel/slots)
+- [Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/)