@aws/nx-plugin-mcp 1.0.0-rc.2 → 1.0.0-rc.21

package/docs/guides/license.mdx

@@ -6,10 +6,12 @@ generator: license
 import { FileTree } from '@astrojs/starlight/components';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
+import Drawer from '@components/drawer.astro';
+import LicenseAllowlist from '@components/license-allowlist.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
-Automatically manage `LICENSE` files and source code headers in your workspace.
-
-This generator registers a [sync generator](https://nx.dev/concepts/sync-generators) to execute as part of your `lint` targets which will ensure that your source files conform to the desired license content and format, as well as ensuring that your project's `LICENSE` files are correct, and licensing information is included in relevant project files (`package.json`, `pyproject.toml`).
+Manage licensing across your workspace: synchronise `LICENSE` files and source code headers for your own code (`license.source`), and check that every dependency conforms to a license allowlist (`license.dependencies`).
 
 ## Usage
 
@@ -26,15 +28,17 @@ This generator registers a [sync generator](https://nx.dev/concepts/sync-generat
 The generator will create or update the following files:
 
 <FileTree>
-  - nx.json The lint target is configured to run the license sync generator
-  - aws-nx-plugin.config.mts Configuration for the license sync generator
+  - nx.json The lint target is configured to run the license sync generator and depends on the license-check target
+  - aws-nx-plugin.config.mts Configuration for license source sync (`license.source`) and dependency checking (`license.dependencies`)
 </FileTree>
 
-Some default configuration for license header content and format is added to `aws-nx-plugin.config.mts` to write appropriate headers for a handful of file types. You may wish to customise this further; please see the [configuration section](#configuration) below.
+## License Headers & Files
+
+The generator registers a [sync generator](https://nx.dev/concepts/sync-generators) to execute as part of your `lint` targets which ensures that your source files contain the correct license headers, your projects contain `LICENSE` files, and licensing metadata is set in `package.json` and `pyproject.toml`.
 
-## Workflow
+### Workflow
 
-Whenever you build your projects (and a `lint` target runs), the license sync generator will make sure that the licensing in your project matches your configuration (see [license sync behaviour below](#license-sync-behaviour)). If it detects that anything is out of sync, you will receive a message such as:
+Whenever you build your projects (and a `lint` target runs), the license sync generator will make sure that the licensing in your project matches your configuration. If it detects that anything is out of sync, you will receive a message such as:
 
 ```bash
   NX   The workspace is out of sync
@@ -67,40 +71,36 @@ Select `Yes` to sync the changes.
 Make sure you check the changes the license sync generator makes in to version control to ensure that any continuous integration build tasks don't fail due to licenses being out of sync.
 :::
 
-## License Sync Behaviour
+### Sync Behaviour
 
 The license sync generator performs three main tasks:
 
-### 1. Synchronise Source File License Headers
+#### 1. Synchronise Source File License Headers
 
 When the sync generator is run, it will ensure that all source code files in your workspace (based on your configuration) contain the appropriate license header. The header is written as the first block comment or consecutive series of line comments in the file (besides the shebang/hashbang if present in a file).
 
-You can update the configuration at any time to change which files should be included or excluded, as well as the content or format of license headers for different file types. For more details, please see the [configuration section](#configuration) below.
-
-### 2. Synchronise LICENSE Files
+#### 2. Synchronise LICENSE Files
 
 When the sync generator is run, it will ensure that the root `LICENSE` file corresponds to your configured license, as well as ensuring that all subprojects in your workspace also contain the correct `LICENSE` file.
 
-You can exclude projects in the configuration if required. For more details, please see the [configuration section](#configuration) below.
-
-### 3. Synchronise licensing information in project files
+#### 3. Synchronise licensing information in project files
 
 When the sync generator is run, it will ensure the `license` fields in `package.json` and `pyproject.toml` files are set to your configured license.
 
-You can exclude projects in the configuration if required. For more details, please see the [configuration section](#configuration) below.
-
-## Configuration
+### Header & File Configuration
 
 Configuration is defined in the `aws-nx-plugin.config.mts` file in the root of your workspace.
 
-### SPDX and Copyright Holder
+#### SPDX and Copyright Holder
 
 Your chosen license can be updated at any time via the `spdx` configuration property:
 
-```typescript title="aws-nx-plugin.config.mts" {3}
+```typescript title="aws-nx-plugin.config.mts" {4}
 export default {
   license: {
-    spdx: 'MIT',
+    source: {
+      spdx: 'MIT',
+    },
   },
 } satisfies AwsNxPluginConfig;
 ```
@@ -109,36 +109,38 @@ When the sync generator runs, all `LICENSE` files, `package.json` and `pyproject
 
 You can additionally configure the copyright holder and copyright year, which are included in some `LICENSE` files:
 
-```typescript title="aws-nx-plugin.config.mts" {4,5}
+```typescript title="aws-nx-plugin.config.mts" {5,6}
 export default {
   license: {
-    spdx: 'MIT',
-    copyrightHolder: 'Amazon.com, Inc. or its affiliates',
-    copyrightYear: 2025,
+    source: {
+      spdx: 'MIT',
+      copyrightHolder: 'Amazon.com, Inc. or its affiliates',
+      copyrightYear: 2025,
+    },
   },
 } satisfies AwsNxPluginConfig;
 ```
 
-### License Headers
-
-#### Content
+#### License Header Content
 
 The license header content can be configured in two ways:
 
 1. Using inline content:
 
-```typescript title="aws-nx-plugin.config.mts" {5-9}
+```typescript title="aws-nx-plugin.config.mts" {6-10}
 export default {
   license: {
-    header: {
-      content: {
-        lines: [
-          'Copyright: My Company, Incorporated.',
-          'Licensed under the MIT License',
-          'All rights reserved',
-        ];
+    source: {
+      header: {
+        content: {
+          lines: [
+            'Copyright: My Company, Incorporated.',
+            'Licensed under the MIT License',
+            'All rights reserved',
+          ];
+        }
+        // ... format configuration
       }
-      // ... format configuration
     }
   }
 } satisfies AwsNxPluginConfig;
@@ -146,51 +148,55 @@ export default {
 
 2. Loading from a file:
 
-```typescript title="aws-nx-plugin.config.mts" {5}
+```typescript title="aws-nx-plugin.config.mts" {6}
 export default {
   license: {
-    header: {
-      content: {
-        filePath: 'license-header.txt'; // relative to workspace root
+    source: {
+      header: {
+        content: {
+          filePath: 'license-header.txt'; // relative to workspace root
+        }
+        // ... format configuration
       }
-      // ... format configuration
     }
   }
 } satisfies AwsNxPluginConfig;
 ```
 
-#### Format
+#### Header Format
 
 You can specify how license headers should be formatted for different file types using glob patterns. The format configuration supports line comments, block comments, or a combination of both:
 
-```typescript title="aws-nx-plugin.config.mts" {7-29}
+```typescript title="aws-nx-plugin.config.mts" {8-30}
 export default {
   license: {
-    header: {
-      content: {
-        lines: ['Copyright notice here'],
-      },
-      format: {
-        // Line comments
-        '**/*.ts': {
-          lineStart: '// ',
-        },
-        // Block comments
-        '**/*.css': {
-          blockStart: '/*',
-          blockEnd: '*/',
+    source: {
+      header: {
+        content: {
+          lines: ['Copyright notice here'],
         },
-        // Block comments with line prefixes
-        '**/*.java': {
-          blockStart: '/*',
-          lineStart: ' * ',
-          blockEnd: ' */',
-        },
-        // Line comments with header/footer
-        '**/*.py': {
-          blockStart: '# ------------',
-          lineStart: '# ',
-          blockEnd: '# ------------',
+        format: {
+          // Line comments
+          '**/*.ts': {
+            lineStart: '// ',
+          },
+          // Block comments
+          '**/*.css': {
+            blockStart: '/*',
+            blockEnd: '*/',
+          },
+          // Block comments with line prefixes
+          '**/*.java': {
+            blockStart: '/*',
+            lineStart: ' * ',
+            blockEnd: ' */',
+          },
+          // Line comments with header/footer
+          '**/*.py': {
+            blockStart: '# ------------',
+            lineStart: '# ',
+            blockEnd: '# ------------',
+          },
         },
       },
     },
@@ -209,27 +215,29 @@ The format configuration supports:
 
 For file types that aren't natively supported, you can specify custom comment syntax to tell the sync generator how to identify existing license headers in these file types.
 
-```typescript title="aws-nx-plugin.config.mts" {12-22}
+```typescript title="aws-nx-plugin.config.mts" {13-23}
 export default {
   license: {
-    header: {
-      content: {
-        lines: ['My license header'],
-      },
-      format: {
-        '**/*.xyz': {
-          lineStart: '## ',
+    source: {
+      header: {
+        content: {
+          lines: ['My license header'],
         },
-      },
-      commentSyntax: {
-        xyz: {
-          line: '##', // Define line comment syntax
+        format: {
+          '**/*.xyz': {
+            lineStart: '## ',
+          },
         },
-        abc: {
-          block: {
-            // Define block comment syntax
-            start: '<!--',
-            end: '-->',
+        commentSyntax: {
+          xyz: {
+            line: '##', // Define line comment syntax
+          },
+          abc: {
+            block: {
+              // Define block comment syntax
+              start: '<!--',
+              end: '-->',
+            },
           },
         },
       },
@@ -238,56 +246,203 @@ export default {
 } satisfies AwsNxPluginConfig;
 ```
 
-#### Excluding files
+#### Excluding Files from Header Sync
 
 By default, in a git repository, all `.gitignore` files are honored to ensure that only files managed by version control are synchronized. In non-git repositories, all files are considered unless explicitly excluded in configuration.
 
 You can exclude additional files from license header synchronization using glob patterns:
 
-```typescript title="aws-nx-plugin.config.mts" {12-16}
+```typescript title="aws-nx-plugin.config.mts" {13}
 export default {
   license: {
-    header: {
-      content: {
-        lines: ['My license header'],
-      },
-      format: {
-        '**/*.ts': {
-          lineStart: '// ',
+    source: {
+      header: {
+        content: {
+          lines: ['My license header'],
+        },
+        format: {
+          '**/*.ts': {
+            lineStart: '// ',
+          },
         },
+        exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
       },
-      exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
     },
   },
 } satisfies AwsNxPluginConfig;
 ```
 
-### Excluding project files from sync
+#### Excluding Projects from File Sync
 
 All `LICENSE` files, `package.json` files and `pyproject.toml` files are synchronised with the configured license by default.
 
 You can exclude specific projects or files from synchronization using glob patterns:
 
-```typescript title="aws-nx-plugin.config.mts" {3-10}
+```typescript title="aws-nx-plugin.config.mts" {4-11}
 export default {
   license: {
-    files: {
-      exclude: [
-        // do not sync LICENSE file, package.json or pyproject.toml
-        'packages/excluded-project',
-        // do not sync LICENSE file, but sync package.json and/or pyproject.toml
-        'apps/internal/LICENSE',
-      ];
+    source: {
+      files: {
+        exclude: [
+          // do not sync LICENSE file, package.json or pyproject.toml
+          'packages/excluded-project',
+          // do not sync LICENSE file, but sync package.json and/or pyproject.toml
+          'apps/internal/LICENSE',
+        ];
+      }
     }
   }
 } satisfies AwsNxPluginConfig;
 ```
 
-## Disabling license sync
+### Disabling License Sync
 
-To disable the license sync generator:
+License source sync is enabled by the presence of the `license.source` key in your configuration. To disable it:
 
-1. Remove the `license` section from your configuration in `aws-nx-plugin.config.mts` (or remove the `aws-nx-plugin.config.mts` file)
-2. Remove the `@aws/nx-plugin:license#sync` generator from `targetDefaults.lint.syncGenerators`
+1. Remove the `license.source` section from your configuration in `aws-nx-plugin.config.mts` (you can keep `license.dependencies` if you still want dependency license checking)
+2. If you also want to fully remove the sync generator, remove the `@aws/nx-plugin:license#sync` generator from `targetDefaults.lint.syncGenerators`
 
 To re-enable license sync, simply run the `license` generator again.
+
+## Dependency License Checks
+
+The `license` generator also configures a `license-check` target that fails when one of your project's dependencies (or any transitive dependency) declares a license that is not in your allowlist.
+
+### How it runs
+
+The generator writes a `license-check` target to your root `project.json`:
+
+```json title="project.json"
+{
+  "targets": {
+    "license-check": {
+      "executor": "@aws/nx-plugin:license-check",
+      "cache": true,
+      "inputs": [
+        "{workspaceRoot}/pnpm-lock.yaml",
+        "{workspaceRoot}/aws-nx-plugin.config.mts"
+      ],
+      "options": {}
+    }
+  }
+}
+```
+
+The `inputs` are computed for your workspace: only lockfiles that are actually present are included, along with `aws-nx-plugin.config.mts`, plus a `{workspaceRoot}/**/uv.lock` glob when Python dependency checking is enabled (i.e. a Python collector is configured).
+
+You can run the check directly:
+
+<NxCommands commands={['license-check']} />
+
+Results are cached against your lockfiles and `aws-nx-plugin.config.mts` — re-runs are instant when nothing has changed.
+
+Collectors determine what gets scanned. The `npmCollector` uses [license-checker-rseidelsohn](https://github.com/nicedoc/license-checker-rseidelsohn), and the `pythonCollector` uses [pip-licenses](https://github.com/raimon49/pip-licenses). If no installed dependencies are found, the check passes with nothing to inspect.
+
+### Running as part of lint/build
+
+The dependency license check runs automatically whenever you `lint` or `build` any project in your workspace. The `license` generator wires each project's `lint` target to depend on the root `license-check` target, and the project generators (`ts#*` and `py#*`) do the same when they run — so the check is wired up regardless of the order generators are run in.
+
+This means you don't need to run the check explicitly, though you can still do so with the `license-check` target:
+
+<NxCommands commands={['license-check']} />
+
+The wiring is a cross-project `dependsOn` on each project's `lint` target that points at the root `license-check` target. To skip the check during a lint or build, set the `LICENSE_DEPENDENCY_CHECK=skip` environment variable:
+
+<PackageManagerShortCommand commands={["LICENSE_DEPENDENCY_CHECK=skip lint"]} />
+
+### Configuration
+
+By default the check uses a built-in set of common permissive licenses (MIT, Apache-2.0, BSD, ISC, etc.) exported as `DEFAULT_LICENSE_ALLOWLIST`. You can extend or override this in your config:
+
+```typescript title="aws-nx-plugin.config.mts"
+import { AwsNxPluginConfig } from '@aws/nx-plugin';
+import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';
+
+export default {
+  license: {
+    // ...
+    dependencies: {
+      allow: [...DEFAULT_LICENSE_ALLOWLIST, { spdxId: 'LGPL-2.1-or-later', fullName: 'GNU Lesser General Public License v2.1 or later', aliases: [] }],
+      exceptions: [
+        { package: 'some-package', reason: 'Audited manually — ships MIT text without SPDX field' },
+      ],
+    },
+  },
+} satisfies AwsNxPluginConfig;
+```
+
+<Drawer title="Default License Allowlist" trigger="View the full list of licenses in DEFAULT_LICENSE_ALLOWLIST">
+<LicenseAllowlist />
+</Drawer>
+
+#### Customizing the allowlist
+
+To restrict the allowlist, replace `DEFAULT_LICENSE_ALLOWLIST` with your own array. To extend it, spread the default and add entries. Entries are matched by SPDX id, full license name, or any of the listed aliases (case-insensitive).
+
+#### Per-package exceptions
+
+Use `exceptions` for packages that fail the check — either because their license is not in the allowlist, or because they ship without detectable license metadata. The `reason` field is required so reviewers can see why the exception was granted.
+
+```typescript
+exceptions: [
+  {
+    package: 'union',
+    version: '0.5.0',
+    reason: 'Package ships verbatim MIT text without declaring license',
+  },
+];
+```
+
+Generators that introduce dependencies with problematic metadata (e.g. the MCP server generator) automatically add the required exceptions to your config when they run.
+
+#### Collectors
+
+Collectors discover dependencies and extract license metadata. The built-in collectors are `npmCollector()` (scans `node_modules`) and `pythonCollector()` (scans Python virtual environments). The license generator configures `npmCollector()` by default and adds `pythonCollector()` when Python projects are present.
+
+To implement a custom collector, conform to the `LicenseCollector` interface:
+
+```typescript
+import type { LicenseCollector } from '@aws/nx-plugin/sdk/license';
+
+const myCollector = (): LicenseCollector => ({
+  name: 'my-ecosystem',
+  traceCommand: 'my-tool why <package>',
+  async collect({ workspaceRoot }) {
+    return [
+      { name: 'some-dep', version: '1.0.0', rawLicense: 'MIT', ecosystem: 'my-ecosystem' },
+    ];
+  },
+});
+```
+
+#### The onDependency hook
+
+`license.dependencies` accepts an optional `onDependency` callback that is invoked once for every discovered dependency, regardless of whether it passes or fails the check. It receives `{ package, spdx }`, where `package` is the package name and `spdx` is the resolved SPDX license expression. An exception's `spdx` takes precedence over the raw declared license, and `spdx` may be an empty string if no license was declared.
+
+This is a handy way to print out all of the licenses across your project. Run the `license-check` target to see the output:
+
+```typescript title="aws-nx-plugin.config.mts"
+import { AwsNxPluginConfig } from '@aws/nx-plugin';
+import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';
+
+export default {
+  license: {
+    dependencies: {
+      allow: DEFAULT_LICENSE_ALLOWLIST,
+      onDependency: ({ package: pkg, spdx }) => {
+        console.log(`${pkg} - ${spdx}`);
+      },
+    },
+  },
+} satisfies AwsNxPluginConfig;
+```
+
+### Disabling Dependency Checks
+
+Dependency license checking is enabled by the presence of the `license.dependencies` key in your configuration.
+
+To disable the checks for a single run, set the `LICENSE_DEPENDENCY_CHECK=skip` environment variable:
+
+<PackageManagerShortCommand commands={["LICENSE_DEPENDENCY_CHECK=skip lint"]} />
+
+To disable permanently, remove the `license.dependencies` key from your configuration in `aws-nx-plugin.config.mts`. You can also re-run the `license` generator with `--dependencyCheck=false` to scaffold without it.

package/docs/guides/local-development.mdx

@@ -0,0 +1,76 @@
+---
+title: Local Development
+description: How local development works with the serve and serve-local targets
+---
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+
+Connected projects expose two targets for running them on your machine: `serve` and `serve-local`. The difference is one of **scope** — how much of your application runs locally versus pointing at deployed AWS infrastructure.
+
+Consider a workspace with the following connections: a website that calls a tRPC `api`, and also calls an `agent` which in turn calls an `mcp` server.
+
+## `serve`
+
+The `serve` target runs **only the targeted project** locally. Every other project it connects to is expected to be **deployed**, and is reached at its real AWS URL.
+
+<NxCommands commands={['serve website']} />
+
+Because the targeted project talks to deployed resources, it needs to know where they are. For a website this is provided by its `runtime-config.json` (see <Link path="guides/react-website#local-runtime-config">Local Runtime Config</Link>), which you load from a deployed application. For server-side projects (APIs and agents) that read <Link path="guides/runtime-config">Runtime Configuration</Link>, set the `RUNTIME_CONFIG_APP_ID` environment variable to point at your deployed AppConfig application.
+
+```d2
+direction: right
+
+local: Local {
+  style.stroke-dash: 3
+  website: website
+}
+deployed: Deployed {
+  style.stroke-dash: 3
+  api: api
+  agent: agent
+  mcp: mcp
+}
+
+local.website -> deployed.api
+local.website -> deployed.agent
+deployed.agent -> deployed.mcp
+```
+
+Use `serve` when you want to iterate on a single project against the "real", deployed versions of everything it depends on.
+
+## `serve-local`
+
+The `serve-local` target runs the **targeted project** and **every project connected to it transitively**, all on your machine. The connection generator wires this up automatically — running `serve-local` on the website also starts local servers for the `api`, the `agent`, and the `mcp` server it reaches through the agent.
+
+<NxCommands commands={['serve-local website']} />
+
+When run this way, the website's `runtime-config.json` is automatically overridden (via [Vite's `MODE`](https://vite.dev/guide/env-and-mode), set to `serve-local`) so that it points at your locally running servers instead of deployed URLs.
+
+```d2
+direction: right
+
+local: Local {
+  style.stroke-dash: 3
+  website: website
+  api: api
+  agent: agent
+  mcp: mcp
+
+  website -> api
+  website -> agent
+  agent -> mcp
+}
+```
+
+Every project runs locally, so there are no deployed dependencies.
+
+Use `serve-local` when you are working across several connected projects at once and want to iterate quickly without deploying your infrastructure.
+
+:::tip[`dev` shortcut]
+A root `dev` script is added as a shortcut for the first website you generate in your workspace, so you can spin up the website and all connected components with:
+
+<PackageManagerShortCommand commands={["dev"]} />
+:::
+
+For more detail on each project type's local development server, see the relevant guide — for example the <Link path="guides/react-website#local-development-server">React Website</Link> guide.

package/docs/guides/nx-generator.mdx

@@ -395,6 +395,10 @@ import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';
 await formatFilesInSubtree(tree, 'optional/path/to/format');
 ```
 
+:::note
+`formatFilesInSubtree` formats TypeScript, JavaScript, JSON and CSS files with [Biome](https://biomejs.dev/), and Python files with [Ruff](https://docs.astral.sh/ruff/). When the workspace already has a `biome.json` on disk, it uses your workspace's installed version of Biome and its configuration. Otherwise it falls back to a bundled Biome, applying any `biome.json` present in the virtual tree.
+:::
+
 #### Reading and Updating JSON Files
 
 ```typescript
@@ -579,6 +583,7 @@ When this generator is run in our repository, it'll generate the following files
   - docs/src/content/docs/guides/
     - \<name>.mdx Documentation page for your generator
   - packages/nx-plugin/generators.json Updated to include your generator
+  - packages/nx-plugin/sdk/\<prefix>.ts Updated to expose your generator from the SDK (for `ts#` and `py#` generators)
 </FileTree>
 
 You can then start to implement your generator.

package/docs/guides/py-agent.mdx

@@ -351,19 +351,58 @@ This command uses `uv run` to execute your Agent using the [Bedrock AgentCore Py
 
 ### 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 `<your-agent-name>-serve-local` first (in a separate terminal):
+
+<NxCommands commands={['run your-project:agent-serve-local']} />
+
+Then, in another terminal, start the chat:
 
 <NxCommands commands={['run your-project:agent-chat']} />
 
-For **HTTP** agents, the generator also emits:
+The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. 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).
+
+For **HTTP** agents, the chat script uses a type-safe TypeScript client generated from the agent's OpenAPI spec. The generator also emits:
 
 - `scripts/<your-agent-name>_openapi.py` — a small script that exports the agent's OpenAPI spec
 - An `<your-agent-name>-openapi` Nx target that runs it
 - An `<your-agent-name>-generate-client` Nx target that produces a type-safe TypeScript client under `scripts/<your-agent-name>/generated/`
-- `scripts/<your-agent-name>/chat.ts` — a thin wrapper around the generated client
 
 When you customize the agent's input shape (e.g. add new fields to `InvokeInput`), update `chat.ts` to pass the new fields when invoking the agent and the rest works automatically.
 
+<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