@aws/nx-plugin-mcp 0.120.0 → 0.121.0

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

@@ -0,0 +1,198 @@
+---
+title: React to Python Agent
+description: Connect a React website to a Python Agent
+when:
+  sourceType: react
+  targetType: py#agent
+  protocol: HTTP
+---
+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 quickly integrate your <Link path="guides/py-agent">Python Agent</Link> with a React website. It sets up all necessary configuration for connecting to your agent via a type-safe OpenAPI-generated client, including AWS IAM and Cognito authentication support.
+
+:::tip[AG-UI agents]
+If your Python Agent was generated with `protocol=AG-UI`, the connection generator instead wires up [CopilotKit](https://docs.copilotkit.ai/aws-strands) and an [`@ag-ui/client`](https://docs.ag-ui.com/) `HttpAgent` on the React website. See the <Link path="guides/connection/react-agui">React to AG-UI Agent</Link> guide for details.
+:::
+
+## 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 Agent with `protocol=HTTP` (generated using the <Link path="guides/py-agent">`py#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 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 in your Python Agent project:
+
+<FileTree>
+
+- scripts
+  - \<agent_name>_openapi.py Script to generate an OpenAPI specification from the agent's FastAPI app
+- project.json A new `<agent-name>-openapi` target is added
+
+</FileTree>
+
+The generator creates the following structure in your React application:
+
+<FileTree>
+
+- src
+  - components
+    - \<AgentName>Provider.tsx Provider for the OpenAPI client
+    - QueryClientProvider.tsx TanStack React Query client provider
+  - hooks
+    - useSigV4.tsx Hook for signing requests with SigV4 (IAM only)
+    - use\<AgentName>.tsx Hook returning the TanStack Query options proxy for your agent's API
+    - use\<AgentName>Client.tsx Hook returning the vanilla API client
+  - generated
+    - \<agent-name>
+      - types.gen.ts Generated types from the agent's Pydantic models
+      - client.gen.ts Type-safe client for calling your agent's API
+      - options-proxy.gen.ts TanStack Query hooks options for interacting with your agent
+- project.json Targets added for client generation and watching for changes
+- .gitignore The generated client files are ignored by default
+
+</FileTree>
+
+## How It Works
+
+### OpenAPI Client Generation
+
+At build time, the Python Agent's FastAPI app is introspected to generate an OpenAPI specification. This spec is then used to generate a type-safe TypeScript client with TanStack Query hooks, following the same pattern as the <Link path="guides/connection/react-fastapi">React to FastAPI connection</Link>.
+
+Each agent gets its own scoped OpenAPI script (e.g., `scripts/agent_openapi.py`) so that projects with multiple agents can generate individual specs.
+
+### Runtime Configuration
+
+Running this connection generator also patches the agent's generated CDK/Terraform construct to publish its AgentCore runtime ARN to the website's `runtime-config.json` (under the `connection` namespace), so only agents you explicitly connect are exposed to the frontend. See <Link path="guides/runtime-config">Runtime Configuration</Link> for details.
+
+### Authentication
+
+The generated code handles authentication depending on your agent's configuration:
+
+- **IAM** (default): Uses AWS SigV4 to sign HTTP requests. Credentials are obtained from the Cognito Identity Pool configured with your website's auth
+- **Cognito**: Embeds the JWT access token in an Authorization header
+- **None**: No authentication
+
+## Infrastructure
+
+<Snippet name="connection/react-agent-infrastructure" parentHeading="Infrastructure" />
+
+## Using the Generated Code
+
+### Using the API Hook
+
+The `use<AgentName>` hook provides TanStack Query options for calling your agent's API endpoints:
+
+```tsx
+import { useState } from 'react';
+import { useMutation } from '@tanstack/react-query';
+import { useMyAgent } from '../hooks/useMyAgent';
+import type { StreamChunk } from '../generated/my-agent/types.gen';
+
+function ChatComponent() {
+  const api = useMyAgent();
+  const [chunks, setChunks] = useState<StreamChunk[]>([]);
+
+  const invoke = useMutation(api.invoke.mutationOptions({
+    onSuccess: async (stream) => {
+      setChunks([]);
+      for await (const chunk of stream) {
+        setChunks((prev) => [...prev, chunk]);
+      }
+    },
+  }));
+
+  const handleSend = (message: string) => {
+    invoke.mutate({
+      prompt: message,
+      sessionId: 'my-session',
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleSend('Hello!')}>Send</button>
+      {invoke.isPending && <p>Agent is thinking...</p>}
+      {chunks.map((chunk, i) => (
+        <span key={i}>{chunk.content}</span>
+      ))}
+    </div>
+  );
+}
+```
+
+### Using the Vanilla Client
+
+The `use<AgentName>Client` hook provides direct access to the API client:
+
+```tsx
+import { useState } from 'react';
+import { useMyAgentClient } from '../hooks/useMyAgentClient';
+import type { StreamChunk } from '../generated/my-agent/types.gen';
+
+function ChatComponent() {
+  const client = useMyAgentClient();
+  const [chunks, setChunks] = useState<StreamChunk[]>([]);
+
+  const handleSend = async (message: string) => {
+    setChunks([]);
+    for await (const chunk of client.invoke({
+      prompt: message,
+      sessionId: 'my-session',
+    })) {
+      setChunks((prev) => [...prev, chunk]);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleSend('Hello!')}>Send</button>
+      {chunks.map((chunk, i) => (
+        <span key={i}>{chunk.content}</span>
+      ))}
+    </div>
+  );
+}
+```
+
+## Local Development
+
+The connection generator automatically configures `serve-local` integration:
+
+1. Running `nx serve-local <website>` will also start the agent's local FastAPI server
+2. The runtime config is overridden to point to the local HTTP URL (e.g., `http://localhost:8081/`)
+3. The TypeScript client is automatically regenerated when the agent's API changes
+
+<NxCommands commands={['serve-local <WebsiteProject>']} />
+
+:::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-agent">Python Agent Guide</Link>
+- <Link path="guides/connection/react-fastapi">React to FastAPI Connection Guide</Link>
+- [TanStack Query Documentation](https://tanstack.com/query/v5)