@aws/nx-plugin-mcp 0.120.0 → 0.122.0

package/docs/guides/astro-docs.mdx

@@ -0,0 +1,142 @@
+---
+title: Astro Docs
+description: Reference documentation for an Astro + Starlight documentation site
+generator: ts#astro-docs
+---
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+
+This generator scaffolds a documentation site powered by [Astro](https://astro.build/)
+and the [Starlight](https://starlight.astro.build/) docs theme. It wires up
+localisation, reusable content snippets, locale-aware internal links and a
+[`starlight-blog`](https://starlight-blog-docs.vercel.app/) plugin by default.
+
+By default it also scaffolds an automated translation pipeline powered by a
+[Strands Agent](https://strandsagents.com/) on
+[Amazon Bedrock](https://aws.amazon.com/bedrock/).
+
+## Usage
+
+### Generate an Astro docs site
+
+You can generate a new Astro docs site in two ways:
+
+<RunGenerator generator="ts#astro-docs" />
+
+### Options
+
+<GeneratorParameters generator="ts#astro-docs" />
+
+## Generator Output
+
+By default the generator creates the following project structure at `docs/` in the
+workspace root (configurable via the `name`, `directory` and `subDirectory` options):
+
+<FileTree>
+  - astro.config.mjs Astro + Starlight configuration (locales, sidebar, blog plugin)
+  - tsconfig.json Extends astro/tsconfigs/strict with @components / @assets path aliases
+  - project.json Nx project with `build`, `start`, `preview` (and `translate` if enabled) targets
+  - scripts
+    - translate.ts Translation driver — a Strands agent with a scoped file-editor tool (omitted with `--noTranslation`)
+    - translate.config.json Source/target locales, glob patterns, model id, region (omitted with `--noTranslation`)
+  - src
+    - components
+      - link.astro Locale-aware link component (resolves paths against the current locale)
+      - snippet.astro Locale-aware snippet loader component
+    - content
+      - docs
+        - en
+          - index.mdx Landing page
+          - guides
+            - getting-started.mdx Sample guide referencing the link and snippet components
+          - blog
+            - welcome.mdx Sample blog post (omitted with `--noBlog`)
+          - snippets
+            - example.mdx Sample reusable snippet
+    - styles
+      - custom.css Starlight theme overrides
+  - README.md Project README
+</FileTree>
+
+### Localisation
+
+The generator defaults to a single locale (`en`) and redirects the root URL to
+it. To add more languages:
+
+1. Add an entry under `locales` in `astro.config.mjs` (for example `ko: { label: '한국어' }`).
+2. Create a matching directory under `src/content/docs/<locale>/`.
+3. Populate it manually, or use the translation target described below.
+
+## Translation
+
+Unless you passed `--noTranslation`, the generator adds a `translate` target to
+`project.json`, so you can run:
+
+<NxCommands commands={[
+  'translate docs -- --all',
+  'translate docs -- --languages jp,ko',
+  'translate docs -- --dry-run',
+]} />
+
+When run without `--all`, the script only translates files that have changed
+since the last translation commit on the current branch — meaning you can
+safely re-run it on every docs PR without re-translating the whole site.
+
+### Configuring translation
+
+Edit `scripts/translate.config.json` to change:
+
+| Field | Purpose |
+| --- | --- |
+| `sourceLanguage` | Locale to translate **from** (default `en`). |
+| `targetLanguages` | Locales to translate **to**. Empty by default. For example `["fr", "de", "es", "ja", "ko"]`. |
+| `docsDir` | Path to the docs content directory, relative to the project root. |
+| `include` | Glob patterns (relative to `<docsDir>/<sourceLanguage>`) for files to translate. |
+| `exclude` | Glob patterns to skip. |
+| `modelId` | Bedrock model to use for translations. |
+| `awsRegion` | AWS region the Bedrock client is configured with. Can also be set via `AWS_REGION`. |
+| `concurrency` | Max number of concurrent agent invocations. |
+| `translationCommitMessage` | Commit message marker for translation commits (default `docs: update translations`). |
+
+### Locale-aware internal links
+
+The generator ships a `Link` component that automatically resolves internal
+docs paths against the current locale, so a single source of truth produces
+the right URL in every language:
+
+```mdx
+import Link from '@components/link.astro';
+
+<Link path="guides/getting-started">Read the getting-started guide</Link>
+```
+
+### Snippets
+
+Reusable content fragments live in `src/content/docs/<locale>/snippets/`. The
+generated `Snippet` component loads the snippet that matches the current
+locale:
+
+```mdx
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="example" />
+```
+
+### Wiring up CI
+
+No CI workflow is generated out of the box — add one that:
+
+1. Configures AWS credentials with permission to invoke Bedrock `InvokeModel` on
+   the configured model.
+2. Runs the `translate` target on pull requests that touch your source-language
+   docs:
+
+   <NxCommands commands={['translate docs']} />
+
+3. Commits the resulting translations back to the PR branch. The commit message
+   must match the `translationCommitMessage` value in
+   `scripts/translate.config.json` (default `docs: update translations`) so that
+   subsequent incremental runs can detect the baseline commit and only
+   re-translate the files that changed since.

package/docs/guides/connection/py-agent-a2a.mdx

@@ -0,0 +1,105 @@
+---
+title: Python Agent to A2A Agent
+description: Connect a Python Agent to a remote A2A agent
+when:
+  sourceType: py#agent
+  targetType:
+    - ts#agent
+    - py#agent
+---
+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';
+import NxCommands from '@components/nx-commands.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator can connect your <Link path="guides/py-agent">Python Agent</Link> to a remote [A2A](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) agent — either <Link path="guides/ts-agent">TypeScript</Link> or <Link path="guides/py-agent">Python</Link> — so your agent can delegate to another agent as a tool.
+
+The generator sets up all the necessary wiring so your agent can discover and invoke the remote A2A agent, both when deployed to AWS (via Bedrock AgentCore) and when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component (any protocol)
+2. A project with an Agent component generated with `--protocol=A2A` and `--auth=IAM` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
+3. Both components created with `computeType: BedrockAgentCoreRuntime`
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your host agent project as the source and your A2A agent project as the target. If your projects contain multiple components, specify the `sourceComponent` and `targetComponent` options to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator creates a shared `agent_connection` Python project at `packages/common/agent_connection/` (if it doesn't already exist). Per-connection client modules are generated into this shared project:
+
+<FileTree>
+
+- packages/common/agent\_connection
+  - \<scope>\_agent\_connection
+    - \_\_init\_\_.py Re-exports per-connection clients
+    - core
+      - agentcore\_a2a\_client.py Core AgentCore A2A client with SigV4 authentication
+    - app
+      - \<target\_agent\_name>\_client.py Per-connection client for each A2A agent
+
+</FileTree>
+
+Additionally, the generator:
+- Transforms your agent's `agent.py` to register the remote A2A agent as a tool using `@tool`
+- Adds the `agent_connection` project as a workspace dependency of your agent project
+- Updates the agent's `serve-local` target to depend on the target agent's `serve-local` target
+
+## Using the Connected A2A Agent
+
+The generator transforms your agent's `agent.py` to wrap the remote A2A agent as a tool:
+
+```python title="packages/my-project/my_module/agent/agent.py" {4,9-15,21}
+from contextlib import contextmanager
+from strands import Agent, tool
+
+from my_scope_agent_connection import RemoteAgentClient
+
+@contextmanager
+def get_agent(session_id: str):
+    remote_agent = RemoteAgentClient.create(session_id=session_id)
+
+    @tool
+    def ask_remote_agent(prompt: str) -> str:
+        """Delegate a question to the remote RemoteAgent A2A agent and return its reply."""
+        return str(remote_agent(prompt))
+
+    yield Agent(
+        system_prompt="...",
+        tools=[ask_remote_agent],
+    )
+```
+
+The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+
+Under the hood, `RemoteAgentClient.create(session_id=...)` returns a Strands `A2AAgent` configured with an `httpx.AsyncClient` that signs requests with SigV4 when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
+
+## Infrastructure
+
+<Snippet name="connection/a2a-infrastructure" parentHeading="Infrastructure" />
+
+## Local Development
+
+The generator configures the host agent's `serve-local` target to:
+1. Start the connected A2A agent(s) automatically
+2. Set `SERVE_LOCAL=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+
+This will start both the host agent and all connected A2A agents, with the host agent calling the remote agents over plain HTTP on their assigned local ports.

package/docs/guides/connection/py-agent-mcp.mdx

@@ -0,0 +1,147 @@
+---
+title: Python Agent to MCP
+description: Connect a Python Agent to an MCP server
+when:
+  sourceType: py#agent
+  targetType:
+    - ts#mcp-server
+    - py#mcp-server
+---
+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';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can connect your <Link path="guides/py-agent">Python Agent</Link> to an MCP server (either <Link path="guides/ts-mcp-server">TypeScript</Link> or <Link path="guides/py-mcp-server">Python</Link>).
+
+The generator sets up all the necessary wiring so your agent can discover and invoke the MCP server's tools, both when deployed to AWS (via Bedrock AgentCore) and when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component
+2. A project with an MCP server component (either <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>)
+3. Both components created with `computeType: BedrockAgentCoreRuntime`
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your agent project as the source and your MCP server project as the target. If your projects contain multiple components, specify the `sourceComponent` and `targetComponent` options to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator creates a shared `agent_connection` Python project at `packages/common/agent_connection/` (if it doesn't already exist). Per-connection client modules are generated into this shared project:
+
+<FileTree>
+
+- packages/common/agent\_connection
+  - \<scope>\_agent\_connection
+    - \_\_init\_\_.py Re-exports per-connection clients
+    - core
+      - agentcore\_mcp\_client.py Core AgentCore MCP client
+    - app
+      - \<mcp\_server\_name>\_client.py Per-connection client for each MCP server
+
+</FileTree>
+
+Additionally, the generator:
+- Transforms your agent's `agent.py` to import and use the MCP server's tools via a class-based client
+- Adds the `agent_connection` project as a workspace dependency of your agent project
+- Updates the agent's `serve-local` target to depend on the MCP server's serve target
+
+## Using the Connected MCP Server
+
+The generator transforms your agent's `agent.py` to use the MCP server's tools:
+
+```python title="packages/my-project/my_module/agent/agent.py" {4,10-14}
+from contextlib import contextmanager
+from strands import Agent
+
+from my_scope_agent_connection import MyMcpServerClient
+
+@contextmanager
+def get_agent(session_id: str):
+    my_mcp_server = MyMcpServerClient.create(session_id=session_id)
+    with (
+        my_mcp_server,
+    ):
+        yield Agent(
+            system_prompt="...",
+            tools=[*my_mcp_server.list_tools_sync()],
+        )
+```
+
+The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+
+## Infrastructure
+
+<Infrastructure>
+<Fragment slot="cdk">
+After running the connection generator, you need to grant the agent permission to invoke the MCP server:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const mcpServer = new MyMcpServer(this, 'MyMcpServer');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the agent permissions to invoke the MCP server
+mcpServer.grantInvokeAccess(myAgent);
+```
+
+The MCP server's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the agent can discover it at runtime.
+</Fragment>
+<Fragment slot="terraform">
+After running the connection generator, you need to grant the agent permission to invoke the MCP server in your Terraform configuration:
+
+```hcl title="packages/infra/src/main.tf" {12-24}
+module "inventory_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
+}
+
+module "story_agent" {
+  source = "../../common/terraform/src/app/agents/story-agent"
+}
+
+# Grant the agent permissions to invoke the MCP server
+resource "aws_iam_policy" "agent_invoke_mcp" {
+  name = "AgentInvokeMcpPolicy"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = "bedrock-agentcore:InvokeAgent"
+      Resource = module.inventory_mcp_server.agent_core_runtime_arn
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
+  role       = module.story_agent.agent_core_runtime_role_arn
+  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
+}
+```
+
+The MCP server's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the agent can discover it at runtime.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The generator configures the agent's `serve-local` target to:
+1. Start the connected MCP server(s) automatically
+2. Set `SERVE_LOCAL=true` so the generated client uses direct HTTP transport instead of AgentCore
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+
+This will start both the agent and all connected MCP servers, with the agent connecting to the MCP servers directly via HTTP on their assigned local ports.

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