@aws/nx-plugin-mcp 1.0.0-rc.3 → 1.0.0-rc.31

package/docs/guides/connection/py-mcp-server-dynamodb.mdx

@@ -0,0 +1,116 @@
+---
+title: Python MCP Server to DynamoDB
+description: Connect a Python MCP Server to a Python DynamoDB project
+when:
+  sourceType: py#mcp-server
+  targetType: py#dynamodb
+---
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/py-mcp-server">Python MCP Server</Link> to a <Link path="guides/py-dynamodb">Python DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-mcp-server">`py#mcp-server`</Link> project
+2. A <Link path="guides/py-dynamodb">`py#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your MCP server project as the source and your DynamoDB project as the target. If the project contains multiple MCP server components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the MCP server's `<mcp-server-name>-dev` target in `project.json` to depend on the DynamoDB project's `dev` target, and adds the DynamoDB package as a workspace dependency. No source files are modified.
+
+## Using DynamoDB in Tools
+
+Import entity classes from the DynamoDB package and use them inside your MCP server tools:
+
+```python title="packages/my_project/my_project/my_mcp_server/server.py"
+from my_scope.my_table.entities.example import ExampleModel
+
+@mcp.tool()
+def list_examples() -> str:
+    """List all example items."""
+    items = list(ExampleModel.scan())
+    return str([item.attribute_values for item in items])
+```
+
+## Infrastructure
+
+To allow the MCP server's Lambda function to access the DynamoDB table, grant the necessary permissions in your infrastructure.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from ':my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table');
+const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
+
+table.grantReadWriteData(myMcpServer);
+```
+
+`grantReadWriteData` grants both the DynamoDB and KMS permissions to the MCP server's execution role.
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+
+resource "aws_iam_role_policy" "dynamodb_access" {
+  role = module.my_mcp_server.lambda_role_name
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = [
+          "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem",
+          "dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan",
+          "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
+        ]
+        Resource = [
+          module.my_table.table_arn,
+          "${module.my_table.table_arn}/index/*",
+        ]
+      },
+      {
+        Effect = "Allow"
+        Action = [
+          "kms:Encrypt",
+          "kms:Decrypt",
+          "kms:ReEncrypt*",
+          "kms:GenerateDataKey*",
+          "kms:DescribeKey"
+        ]
+        Resource = [module.my_table.kms_key_arn]
+      },
+    ]
+  })
+}
+```
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+<Snippet name="connection/py-dynamodb-local-development" />

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

@@ -71,7 +71,7 @@ The following dependencies are added to the root `package.json`:
 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`)
+- **Local development**: `dev` 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.
 
@@ -218,13 +218,13 @@ Deeper overrides follow the same shape — e.g. replace just the copy button on
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration:
+The connection generator automatically configures `dev` integration:
 
-1. Running `nx serve-local <website>` will also start the agent's local server
+1. Running `nx dev <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>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 :::tip[Hot Reloading]
 The website and connected agent hot-reload together, enabling you to quickly iterate on both sides without deploying to AWS.

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

@@ -115,9 +115,9 @@ Whenever you make changes to your FastAPI, you need to rebuild your project in o
 :::
 
 :::tip[Auto-Regeneration]
-If you're actively working on both your React application and FastAPI together, use the React application's `serve-local` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local FastAPI server:
+If you're actively working on both your React application and FastAPI together, use the React application's `dev` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local FastAPI server:
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 For more fine-grained control, you can use the `watch-generate:<ApiName>-client` target for your React application to regenerate the client every time you make API changes:
 

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

@@ -177,13 +177,13 @@ function ChatComponent() {
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration:
+The connection generator automatically configures `dev` integration:
 
-1. Running `nx serve-local <website>` will also start the agent's local FastAPI server
+1. Running `nx dev <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>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 :::tip[Hot Reloading]
 The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.

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

@@ -21,7 +21,7 @@ The `connection` generator provides a way to quickly integrate your React websit
 Before using this generator, ensure your React application has:
 
 1. A `main.tsx` file that renders your application
-2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link>)
+2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `--framework=smithy`)
 3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link> if connecting an API which uses Cognito or IAM auth
 
 <details>
@@ -116,9 +116,9 @@ Whenever you make changes to your Smithy API model, you need to rebuild your pro
 :::
 
 :::tip[Auto-Regeneration]
-If you're actively working on both your React application and Smithy API together, use the React application's `serve-local` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local Smithy API server:
+If you're actively working on both your React application and Smithy API together, use the React application's `dev` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local Smithy API server:
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 For more fine-grained control, you can use the `watch-generate:<ApiName>-client` target for your React application to regenerate the client every time you make API changes:
 

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

@@ -175,7 +175,7 @@ Subscriptions are only supported when the tRPC API uses `rest-lambda` (REST API)
 
 When connecting to a REST API tRPC backend, the generated client is automatically configured with a `splitLink` that routes subscription operations through `httpSubscriptionLink` (using SSE) and regular queries/mutations through `httpLink`. This means subscriptions work out of the box with no additional configuration.
 
-For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">`ts#trpc-api` generator guide</Link>.
+For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">tRPC API generator guide</Link>.
 
 #### Using the useSubscription Hook
 

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

@@ -64,13 +64,13 @@ Additionally, it installs the required dependencies:
 The generated client connects to your Agent via tRPC over WebSocket. The agent exposes a tRPC router (including the `invoke` subscription for streaming agent responses) over a WebSocket endpoint.
 
 - **Deployed**: The agent runtime ARN is loaded from <Link path="guides/runtime-config">Runtime Configuration</Link>. Running this connection generator also patches the agent's generated CDK/Terraform construct to publish its ARN to the website's `runtime-config.json` (under the `connection` namespace), so only agents you explicitly connect are exposed to the frontend. The ARN is converted to a WebSocket URL following the Bedrock AgentCore Runtime WebSocket protocol: `wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws`
-- **Local development**: When running with `serve-local`, the runtime config override sets the value to a local `ws://` URL (e.g., `ws://localhost:8081/ws`), and the client connects directly
+- **Local development**: When running with `dev`, the runtime config override sets the value to a local `ws://` URL (e.g., `ws://localhost:8081/ws`), and the client connects directly
 
 ### Authentication
 
 The generated code handles authentication depending on your agent's configuration:
 
-- **IAM** (default): Uses AWS SigV4 presigned URLs to authenticate the WebSocket connection. Credentials are obtained from the Cognito Identity Pool configured with your website's auth. In `serve-local` mode, signing is automatically skipped when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+- **IAM** (default): Uses AWS SigV4 presigned URLs to authenticate the WebSocket connection. Credentials are obtained from the Cognito Identity Pool configured with your website's auth. In `dev` mode, signing is automatically skipped when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
 - **Cognito**: Embeds the JWT access token in the `Sec-WebSocket-Protocol` header as a base64url-encoded bearer token, following the [AgentCore WebSocket auth protocol](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.html)
 
 
@@ -174,11 +174,11 @@ For more details on the vanilla tRPC client, see the [tRPC Vanilla Client docume
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration for your react website:
+The connection generator automatically configures `dev` integration for your react website:
 
-1. Running `nx serve-local <website>` will also start the agent's local server
+1. Running `nx dev <website>` will also start the agent's local server
 2. The runtime config is overridden to point to the local WebSocket URL (e.g., `ws://localhost:8081/ws`)
-3. Like with connected APIs, authentication is skipped in `serve-local` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+3. Like with connected APIs, authentication is skipped in `dev` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
 
 :::tip[Hot Reloading]
 The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.

package/docs/guides/connection/smithy-dynamodb.mdx

@@ -0,0 +1,68 @@
+---
+title: Smithy API to DynamoDB
+description: Connect a Smithy API to a TypeScript DynamoDB project
+when:
+  sourceType: smithy
+  targetType: ts#dynamodb
+---
+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 wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
+2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your Smithy API backend project as the source and your DynamoDB project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates your Smithy API's `project.json` to add a dependency from its `dev` target to the DynamoDB project's `dev` target. No source files are modified.
+
+## Using DynamoDB in Operations
+
+Import entity factories from the DynamoDB package and use them inside your operation implementations:
+
+```ts title="packages/api/src/operations/list-examples.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+import {
+  ListExamplesOperationInput,
+  ListExamplesOperationOutput,
+} from '../generated/ssdk/index.js';
+import { ServiceContext } from '../context.js';
+
+export const listExamples = async (
+  _input: ListExamplesOperationInput,
+  _ctx: ServiceContext,
+): Promise<ListExamplesOperationOutput> => {
+  const entity = await createExampleEntity();
+  const result = await entity.scan.go();
+  return { items: result.data };
+};
+```
+
+## Infrastructure
+
+<Snippet name="connection/lambda-dynamodb-access" />
+
+## Local Development
+
+<Snippet name="connection/dynamodb-local-development" />

package/docs/guides/connection/smithy-rdb.mdx

@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API<
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/ts-smithy-api">`ts#smithy-api`</Link> project (TypeScript backend)
+1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
 2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
 
 ## Usage
@@ -46,7 +46,7 @@ The generator modifies three existing files in your Smithy API backend:
 
 </FileTree>
 
-Additionally, it updates the API's `serve-local` target to start the database automatically.
+Additionally, it updates the API's `dev` target to start the database automatically.
 
 ## How It Works
 
@@ -156,6 +156,6 @@ const server = createServer(async function (req, res) {
 });
 ```
 
-<NxCommands commands={["serve-local <api-project-name>"]} />
+<NxCommands commands={["dev <api-project-name>"]} />
 
-This starts both the API and the local database. The `SERVE_LOCAL=true` environment variable is set automatically, so the Prisma client connects to the local Docker database instead of Aurora.
+This starts both the API and the local database. The `LOCAL_DEV=true` environment variable is set automatically, so the Prisma client connects to the local Docker database instead of Aurora.

package/docs/guides/connection/trpc-dynamodb.mdx

@@ -0,0 +1,62 @@
+---
+title: tRPC API to DynamoDB
+description: Connect a tRPC API to a TypeScript DynamoDB project
+when:
+  sourceType: ts#trpc-api
+  targetType: ts#dynamodb
+---
+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 wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
+2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your tRPC API project as the source and your DynamoDB project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates your tRPC API's `project.json` to add a dependency from its `dev` target to the DynamoDB project's `dev` target. No source files are modified.
+
+## Using DynamoDB in Procedures
+
+Import entity factories from the DynamoDB package and use them inside your tRPC procedures:
+
+```ts title="packages/api/src/procedures/example.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+import { publicProcedure } from '../init.js';
+
+export const listExamples = publicProcedure
+  .query(async () => {
+    const entity = await createExampleEntity();
+    const result = await entity.scan.go();
+    return result.data;
+  });
+```
+
+## Infrastructure
+
+<Snippet name="connection/lambda-dynamodb-access" />
+
+## Local Development
+
+<Snippet name="connection/dynamodb-local-development" />

package/docs/guides/connection/trpc-rdb.mdx

@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/trpc">`ts#trpc-api`</Link> project
+1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
 2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
 
 ## Usage
@@ -45,7 +45,7 @@ The generator creates a middleware file in your tRPC API project:
 
 </FileTree>
 
-Additionally, it updates your tRPC API's `serve-local` target to start the database automatically when running locally.
+Additionally, it updates your tRPC API's `dev` target to start the database automatically when running locally.
 
 ## Using the Middleware
 
@@ -120,8 +120,8 @@ export const dbProcedure = t.procedure
 
 ## Local Development
 
-The generator configures your tRPC API's `serve-local` target to depend on the database's `serve-local` target, so running:
+The generator configures your tRPC API's `dev` target to depend on the database's `dev` target, so running:
 
-<NxCommands commands={["serve-local <api-project-name>"]} />
+<NxCommands commands={["dev <api-project-name>"]} />
 
 will automatically start the local database alongside your API.

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

@@ -47,9 +47,12 @@ The generator creates a shared `agent-connection` package and modifies your agen
 - packages/common/agent-connection
   - src
     - app
-      - \<target-agent-name>-client.ts High-level client for the connected A2A agent
+      - \<target-agent-name>-client-strands.ts High-level Strands client for the connected A2A agent
     - core
-      - agentcore-a2a-client.ts Low-level AgentCore A2A client with SigV4 authentication
+      - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
+      - agentcore-a2a-client-config.ts Framework-agnostic A2A client config (signed `clientFactory`)
+      - agentcore-a2a-client-strands.ts Strands A2A client wrapping the config
     - index.ts Exports all clients
   - project.json
   - tsconfig.json
@@ -58,7 +61,7 @@ The generator creates a shared `agent-connection` package and modifies your agen
 
 Additionally, it:
 - Transforms your agent's `agent.ts` to register the remote A2A agent as a Strands `tool`
-- Updates the agent's `serve-local` target to depend on the target agent's `serve-local` target
+- Updates the agent's `dev` target to depend on the target agent's `dev` target
 - Installs required dependencies
 
 ## Using the Connected A2A Agent
@@ -67,11 +70,11 @@ The generator transforms your agent's `agent.ts` to wrap the remote A2A agent as
 
 ```ts title="packages/example/src/my-agent/agent.ts" {2,5-11,14}
 import { Agent, tool } from '@strands-agents/sdk';
-import { RemoteAgentClient } from ':my-scope/agent-connection';
+import { RemoteAgentClientStrands } from ':my-scope/agent-connection';
 import { z } from 'zod';
 
 export const getAgent = async (sessionId: string) => {
-  const remoteAgent = await RemoteAgentClient.create(sessionId);
+  const remoteAgent = await RemoteAgentClientStrands.create(sessionId);
   const remoteAgentTool = tool({
     name: 'askRemoteAgent',
     description: 'Delegate a question to the remote RemoteAgent A2A agent and return its reply.',
@@ -87,7 +90,7 @@ export const getAgent = async (sessionId: string) => {
 
 The `sessionId` 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(sessionId)` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
+Under the hood, `RemoteAgentClientStrands.create(sessionId)` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `LOCAL_DEV=true`. The signing and endpoint resolution live in the framework-agnostic `agentcore-a2a-client-config.ts`; only the thin `agentcore-a2a-client-strands.ts` depends on Strands.
 
 ## Infrastructure
 
@@ -95,12 +98,12 @@ Under the hood, `RemoteAgentClient.create(sessionId)` returns a Strands `A2AAgen
 
 ## Local Development
 
-The generator configures the host agent's `serve-local` target to:
+The generator configures the host agent's `dev` 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
+2. Set `LOCAL_DEV=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>"]} />
+<NxCommands commands={["<agent-name>-dev <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/ts-agent-dynamodb.mdx

@@ -0,0 +1,128 @@
+---
+title: TypeScript Agent to DynamoDB
+description: Connect a TypeScript Agent to a TypeScript DynamoDB project
+when:
+  sourceType: ts#agent
+  targetType: ts#dynamodb
+---
+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';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/ts-agent">TypeScript Agent</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/ts-agent">`ts#agent`</Link> project
+2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your Agent project as the source and your DynamoDB project as the target. If the project contains multiple agent components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the agent's `<agent-name>-dev` target in `project.json` to depend on the DynamoDB project's `dev` target. No source files are modified.
+
+## Using DynamoDB in Agents
+
+Import entity factories from the DynamoDB package and use them inside your agent definition:
+
+```ts title="packages/my-service/src/my-agent/agent.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+
+export const getAgent = async () => {
+  // ...
+  return new Agent({
+    tools: [
+      tool({
+        name: 'list_examples',
+        description: 'List all example items',
+        func: async () => {
+          const entity = await createExampleEntity();
+          const result = await entity.scan.go();
+          return result.data;
+        },
+      }),
+    ],
+  });
+};
+```
+
+## Infrastructure
+
+To allow the agent's Lambda function to access the DynamoDB table, grant the necessary permissions in your infrastructure.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from ':my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+table.grantReadWriteData(myAgent);
+```
+
+`grantReadWriteData` grants both the DynamoDB and KMS permissions to the agent's execution role.
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+
+resource "aws_iam_role_policy" "dynamodb_access" {
+  role = module.my_agent.lambda_role_name
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = [
+          "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem",
+          "dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan",
+          "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
+        ]
+        Resource = [
+          module.my_table.table_arn,
+          "${module.my_table.table_arn}/index/*",
+        ]
+      },
+      {
+        Effect = "Allow"
+        Action = [
+          "kms:Encrypt",
+          "kms:Decrypt",
+          "kms:ReEncrypt*",
+          "kms:GenerateDataKey*",
+          "kms:DescribeKey"
+        ]
+        Resource = [module.my_table.kms_key_arn]
+      },
+    ]
+  })
+}
+```
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+<Snippet name="connection/dynamodb-local-development" />