@aws/nx-plugin-mcp 1.0.0-rc.8 → 1.0.0-rc.80

package/docs/guides/ts-agent.mdx

@@ -4,7 +4,9 @@ description: Generate a TypeScript Agent for building AI agents with tools and d
 generator: ts#agent
 ---
 
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, CardGrid, Steps } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
 import RunGenerator from '@components/run-generator.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Link from '@components/link.astro';
@@ -58,6 +60,7 @@ The generator will add the following files to your existing TypeScript project.
         - init.ts tRPC initialization
         - router.ts tRPC router with agent procedures
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - client.ts Vended client for invoking your agent
         - agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
@@ -77,6 +80,7 @@ The entry point uses the [Strands A2A Express Server](https://strandsagents.com/
       - agent/ (or custom name if specified)
         - index.ts A2A Express server entry point
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - package.json Updated with Strands and Express dependencies
     - project.json Updated with agent serve targets
@@ -94,6 +98,7 @@ The entry point uses [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui
       - agent/ (or custom name if specified)
         - index.ts AG-UI server entry point (Express + SSE)
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - package.json Updated with Strands and AG-UI dependencies
     - project.json Updated with agent serve targets
@@ -113,8 +118,8 @@ For deploying your Agent, the following files are generated:
   - packages/common/constructs/src
     - app
       - agents
-        - \<project-name>
-          - \<project-name>.ts CDK construct for deploying your agent
+        - \<agent-name>
+          - \<agent-name>.ts CDK construct for deploying your agent
 </FileTree>
 </Fragment>
 <Fragment slot="terraform">
@@ -122,8 +127,8 @@ For deploying your Agent, the following files are generated:
   - packages/common/terraform/src
     - app
       - agents
-        - \<project-name>
-          - \<project-name>.tf Module for deploying your agent
+        - \<agent-name>
+          - \<agent-name>.tf Module for deploying your agent
     - core
       - agent-core
         - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
@@ -183,7 +188,7 @@ const letterCounter = tool({
 });
 
 // Add tools to your agent
-export const getAgent = async (sessionId: string) => {
+export const getAgent = async () => {
   return new Agent({
     systemPrompt: 'You are a helpful assistant with access to various tools.',
     tools: [letterCounter],
@@ -198,7 +203,7 @@ The Strands framework automatically handles:
 
 ### Model Configuration
 
-By default, Strands agents use Claude 4 Sonnet, but you can easily switch between model providers:
+By default, Strands agents use Claude Sonnet 4.6 on Amazon Bedrock, but you can easily switch between model providers:
 
 ```typescript
 import { Agent } from '@strands-agents/sdk';
@@ -242,7 +247,7 @@ For a more in-depth guide to writing Strands agents, refer to the [Strands docum
 <OptionFilter when={{ protocol: 'a2a' }} description="A2A Express server details">
 ## A2A Server (A2A protocol)
 
-The generated `index.ts` mounts the [Strands A2A Express Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) onto an Express app so the generated agent exposes the A2A protocol endpoints alongside a `/ping` health check. When deployed to AgentCore, the entry point resolves the runtime's public ARN from AppConfig and advertises it in the agent card.
+The generated `index.ts` mounts the [Strands A2A Express Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) onto an Express app so the generated agent exposes the A2A protocol endpoints alongside a `/ping` health check. The URL advertised in the agent card comes from the `AGENTCORE_RUNTIME_URL` environment variable, falling back to `http://localhost:<port>/` for local development.
 
 Most users will not need to modify this file — edit `agent.ts` to change tools or the system prompt. A2A agents listen on port `9000` (vs `8080` for HTTP), which the generated Dockerfile and infrastructure are already configured for.
 </OptionFilter>
@@ -250,7 +255,7 @@ Most users will not need to modify this file — edit `agent.ts` to change tools
 <OptionFilter when={{ protocol: 'ag-ui' }} description="AG-UI server details">
 ## AG-UI Server (AG-UI protocol)
 
-The generated `index.ts` wraps your Strands `Agent` in an [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui/aws-strands) `StrandsAgent` and creates an Express app via `createStrandsApp()`. The resulting app exposes a single POST endpoint that streams [AG-UI](https://docs.ag-ui.com/) events over Server-Sent Events (SSE), as well as `/ping` for the AgentCore runtime health check.
+The generated `index.ts` wraps your Strands `Agent` in an [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui/aws-strands) `StrandsAgent` and builds an Express app. The resulting app exposes a single POST endpoint that streams [AG-UI](https://docs.ag-ui.com/) events over Server-Sent Events (SSE), as well as `/ping` for the AgentCore runtime health check.
 
 AG-UI agents are designed to be consumed directly by a frontend. Use the <Link path="/guides/connection/react-agui">`connection` generator</Link> to wire your React website up to the agent with a [CopilotKit](https://docs.copilotkit.ai/aws-strands) provider and [AG-UI HttpAgent](https://docs.ag-ui.com/) client.
 
@@ -261,19 +266,61 @@ Most users will not need to modify `index.ts` — edit `agent.ts` to change tool
 
 ### Local Development
 
-The generator configures a target named `<your-agent-name>-serve`, which starts your Agent locally for development and testing.
+To run your Agent (and everything connected to it) locally, use the project's `dev` target:
 
-<NxCommands commands={['agent-serve your-project']} />
+<NxCommands commands={['dev your-project']} />
 
-This command uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
+If you have added multiple components to your project (agents, MCP servers, etc.), this starts them all. To run just this agent, target its `<your-agent-name>-dev` target:
+
+<NxCommands commands={['agent-dev your-project']} />
+
+This uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
 
 ### Chat with Your Agent
 
-The generator configures a `<your-agent-name>-chat` Nx target that depends on `<your-agent-name>-serve-local`. Running it starts the agent locally and drops you into an interactive terminal chat:
+The generator configures a `<your-agent-name>-chat` Nx target that drops you into an interactive terminal chat with your agent.
+
+The chat target runs standalone. By default it connects to your locally running agent, so start the agent's `<your-agent-name>-dev` target first (in a separate terminal):
+
+<NxCommands commands={['agent-dev your-project']} />
+
+Then, in another terminal, start the chat:
 
 <NxCommands commands={['run your-project:agent-chat']} />
 
-For **HTTP** (tRPC over WebSocket) agents, the generator also emits a tiny `scripts/<your-agent-name>/chat.ts` that wraps the generated `<Agent>Client.local({ url })` so you can customize it as you evolve the agent's input shape.
+The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. You can customize it as you evolve the agent's input shape. It connects to the local agent by default, or to your deployed agent when `RUNTIME_CONFIG_APP_ID` is set (see [Chat with your deployed agent](#chat-with-your-deployed-agent) below).
+
+<OptionFilter when={{ infra: 'agentcore' }} description="Deployed agent chat details">
+#### Chat with your deployed agent
+
+To chat with your agent deployed to Bedrock AgentCore, set the `RUNTIME_CONFIG_APP_ID` environment variable to the AppConfig application id of the deployment (output as `RuntimeConfigApplicationId` by the deployed stack). The chat script resolves your agent's runtime ARN from runtime configuration and connects to the deployed endpoint:
+
+<Tabs syncKey="auth">
+<TabItem label="IAM" _filter={{ auth: 'iam' }}>
+For IAM-authenticated agents, requests are signed with [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) using your default AWS credentials. Ensure the environment has AWS credentials with permission to invoke the runtime:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>' }} />
+</TabItem>
+
+<TabItem label="Cognito" _filter={{ auth: 'cognito' }}>
+For Cognito-authenticated agents, provide a Cognito access token via the `AGENT_ACCESS_TOKEN` environment variable, which is sent as a bearer token:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>', AGENT_ACCESS_TOKEN: '<access-token>' }} />
+
+You can obtain an access token using the AWS CLI's `cognito-idp admin-initiate-auth` command, for example:
+
+```bash
+aws cognito-idp admin-initiate-auth \
+  --user-pool-id <user-pool-id> \
+  --client-id <user-pool-client-id> \
+  --auth-flow ADMIN_NO_SRP_AUTH \
+  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
+  --query 'AuthenticationResult.AccessToken' \
+  --output text
+```
+</TabItem>
+</Tabs>
+</OptionFilter>
 
 <OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your Agent to Bedrock AgentCore Runtime
@@ -292,6 +339,10 @@ The generator configures a `<your-agent-name>-docker` target which copies the `D
 
 A `docker` target is also generated which prepares the docker context for all agents if you have multiple defined.
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### Observability
 
 Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.
@@ -299,6 +350,38 @@ Your agent is automatically configured with observability using the [AWS Distro
 You can find traces in the CloudWatch AWS Console, by selecting "GenAI Observability" in the menu. Note that for traces to be populated you will need to enable [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
 
 For more details, refer to the [AgentCore documentation on observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html).
+
+### Session Management
+
+The `session` option controls how your agent persists conversation state (message history, tool state, etc.) across invocations, using the Strands SDK's [SessionManager](https://strandsagents.com/docs/user-guide/concepts/agents/session-management/):
+
+- **`s3`** (default): The CDK/Terraform infrastructure provisions a dedicated S3 bucket for session data, encrypted with a dedicated KMS key and with all public access blocked; server access logs are delivered to a CloudWatch Logs log group via the same key. The agent's IAM role is granted read/write/list/delete access to the bucket and decrypt/generate-data-key access to the key, and the bucket name is registered alongside the agent's ARN in AppConfig runtime configuration.
+- **`in-memory`**: No bucket is provisioned. Conversation state is kept in memory only for the lifetime of the running process and does not survive restarts or scale-in.
+
+This is implemented in the generated `session.ts`, which exports a `getSessionManager()` function resolving a `SessionManager` for the current session.
+
+The session ID itself comes from the AgentCore Runtime session (propagated via the `x-amzn-bedrock-agentcore-runtime-session-id` header for A2A/AG-UI, or the WebSocket connection context for HTTP/tRPC) and is bound to an [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage)-based context so `getCurrentSessionId()` can resolve it anywhere in the request — including in any downstream MCP or A2A clients wired up via the <Link path="/guides/connection">`connection` generator</Link>, so the whole call chain shares a consistent session.
+
+:::note[Local Development]
+When running locally (`LOCAL_DEV=true`, set automatically by the `-dev` target), session data is always stored on disk under `tmp/agents/strands/<agent-name>` at the workspace root, regardless of the configured `session` option, for convenience.
+:::
+
+#### Restricting sessions to their owner
+
+The session ID arrives from the caller, so on its own it identifies a conversation but not who the conversation belongs to. AgentCore Runtime authorizes an invocation against the agent runtime resource ARN rather than against an individual session, which leaves the agent free to decide what a session means to your application.
+
+:::caution[The session also selects the microVM]
+A session ID selects the [microVM](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html) that serves the request, so its filesystem, `/tmp` and in-process caches are shared by every request resolving to that session. Two callers who send the same session ID share those resources even when their stored conversations are separate.
+:::
+
+To restrict each user to their own conversations:
+
+<Steps>
+  1. Add an API to create a session, using <Link path="guides/trpc">tRPC</Link>, <Link path="guides/fastapi">FastAPI</Link> or <Link path="guides/ts-smithy-api">Smithy</Link>. Generate an opaque session ID (at least 33 characters) and store it alongside the calling user's ID — for example in a table created with the <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> generator. Each API guide shows how to retrieve the calling user's ID.
+  2. In your agent, look up the stored user ID for the session ID it was given, and reject the request when it does not match the caller. With `auth=cognito` the caller's JWT reaches your agent code, so its `sub` claim identifies them.
+</Steps>
+
+Generate the session ID rather than deriving it from user-supplied values such as a conversation name — anything a caller can predict, a caller can send.
 </OptionFilter>
 
 ## Invoking your Agent
@@ -312,13 +395,15 @@ You can invoke a locally running agent using the `.local` factory method from th
 
 You can, for example create a file named `scripts/test.ts` in your workspace which imports the client:
 
+The client class is named after your agent, so an agent named `my-agent` exports `MyAgentClient`.
+
 ```typescript
 // scripts/test.ts
-import { AgentClient } from '../packages/<project>/src/agent/client.js';
+import { MyAgentClient } from '../packages/<project>/src/agent/client.js';
 
-const client = AgentClient.local({ url: 'http://localhost:8081/ws' });
+const client = MyAgentClient.local({ url: 'http://localhost:8081/ws' });
 
-client.invoke.subscribe({ message: 'what is 1 plus 1?' }, { onData: console.log });
+client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, { onData: console.log });
 ```
 
 :::tip[Quick Testing]
@@ -346,13 +431,13 @@ The client factory uses HTTP headers in the WebSocket handshake to authenticate
 You can invoke your deployed agent by passing its ARN to the `withIamAuth` factory method:
 
 ```typescript
-import { AgentClient } from './agent/client.js';
+import { MyAgentClient } from './agent/client.js';
 
-const client = AgentClient.withIamAuth({
+const client = MyAgentClient.withIamAuth({
   agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
 });
 
-client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
+client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
   onData: (message) => console.log(message),
   onError: (error) => console.error(error),
   onComplete: () => console.log('Done'),
@@ -370,12 +455,12 @@ This will use the default AWS credential provider chain to authenticate requests
 Use the `withJwtAuth` factory method to authenticate with the JWT / Cognito access token.
 
 ```typescript
-const client = AgentClient.withJwtAuth({
+const client = MyAgentClient.withJwtAuth({
   agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
   accessTokenProvider: async () => `<access-token>`,
 });
 
-client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
+client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
   onData: console.log,
 });
 ```
@@ -387,7 +472,7 @@ import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provid
 
 const cognito = new CognitoIdentityProvider();
 
-const jwtClient = AgentClient.withJwtAuth({
+const jwtClient = MyAgentClient.withJwtAuth({
   agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
   accessTokenProvider: async () => {
     const response = await cognito.adminInitiateAuth({
@@ -434,3 +519,102 @@ To invoke your AG-UI agent from a React website, use the <Link path="/guides/con
 
 Refer to the <Link path="/guides/connection/react-agui">`connection` generator guide</Link> for details about how the connection is set up.
 </OptionFilter>
+
+## Securing your Agent
+
+<Snippet name="agent/securing-your-agent" parentHeading="Securing your Agent" />
+
+```typescript
+// agent.ts
+import { Agent } from '@strands-agents/sdk';
+import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
+
+const model = new BedrockModel({
+  modelId: process.env.MODEL_ID,
+  guardrailConfig: {
+    guardrailIdentifier: process.env.GUARDRAIL_ID!,
+    guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
+  },
+});
+
+const agent = new Agent({ model, /* ... */ });
+```
+
+See the Strands [Guardrails](https://strandsagents.com/docs/user-guide/safety-security/guardrails/) guide for more detail.
+
+## Connections
+
+Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
+
+<CardGrid>
+  <ConnectionCard
+    title="React to TypeScript Agent"
+    description="Call a TypeScript Agent from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-ts-agent`}
+    source="react"
+    target="strands"
+    targetBadge="typescript"
+  />
+  <ConnectionCard
+    title="React to AG-UI Agent"
+    description="Call an Agent exposing the AG-UI protocol from a React website via CopilotKit"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agui`}
+    source="react"
+    target="copilotkit"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to MCP"
+    description="Connect a TypeScript Agent to an MCP server"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-mcp`}
+    source="strands"
+    sourceBadge="typescript"
+    target="mcp"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to A2A Agent"
+    description="Connect a TypeScript Agent to a remote A2A agent"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-a2a`}
+    source="strands"
+    sourceBadge="typescript"
+    target="a2a"
+  />
+  <ConnectionCard
+    title="Python Agent to A2A Agent"
+    description="Connect a Python Agent to a remote A2A agent"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-a2a`}
+    source="strands"
+    sourceBadge="python"
+    target="a2a"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to Relational Database"
+    description="Connect a TypeScript Agent to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-rdb`}
+    source="strands"
+    sourceBadge="typescript"
+    target="aurora"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to TypeScript DynamoDB"
+    description="Connect a TypeScript Agent to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-dynamodb`}
+    source="strands"
+    sourceBadge="typescript"
+    target="dynamodb"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to AgentCore Gateway"
+    description="Connect a TypeScript Agent to an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-gateway`}
+    source="strands"
+    sourceBadge="typescript"
+    target="agentcore"
+  />
+  <ConnectionCard
+    title="AgentCore Gateway to Agent"
+    description="Front an agent with an AgentCore Gateway as a runtime target"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-agent`}
+    source="agentcore"
+    target="strands"
+  />
+</CardGrid>