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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/bin/aws-nx-mcp.js +4312 -3360
  2. package/docs/guides/agentcore-gateway.mdx +376 -0
  3. package/docs/guides/connection/agentcore-gateway-gateway.mdx +154 -0
  4. package/docs/guides/connection/agentcore-gateway-mcp.mdx +134 -0
  5. package/docs/guides/connection/py-agent-a2a.mdx +47 -15
  6. package/docs/guides/connection/py-agent-dynamodb.mdx +116 -0
  7. package/docs/guides/connection/py-agent-gateway.mdx +176 -0
  8. package/docs/guides/connection/py-agent-mcp.mdx +42 -13
  9. package/docs/guides/connection/py-fast-api-dynamodb.mdx +56 -0
  10. package/docs/guides/connection/py-mcp-server-dynamodb.mdx +116 -0
  11. package/docs/guides/connection/react-agui.mdx +4 -4
  12. package/docs/guides/connection/react-fastapi.mdx +2 -2
  13. package/docs/guides/connection/react-py-agent.mdx +3 -3
  14. package/docs/guides/connection/react-smithy.mdx +3 -3
  15. package/docs/guides/connection/react-trpc.mdx +1 -1
  16. package/docs/guides/connection/react-ts-agent.mdx +5 -5
  17. package/docs/guides/connection/smithy-dynamodb.mdx +68 -0
  18. package/docs/guides/connection/smithy-rdb.mdx +4 -4
  19. package/docs/guides/connection/trpc-dynamodb.mdx +62 -0
  20. package/docs/guides/connection/trpc-rdb.mdx +4 -4
  21. package/docs/guides/connection/ts-agent-a2a.mdx +12 -9
  22. package/docs/guides/connection/ts-agent-dynamodb.mdx +128 -0
  23. package/docs/guides/connection/ts-agent-gateway.mdx +141 -0
  24. package/docs/guides/connection/ts-agent-mcp.mdx +11 -8
  25. package/docs/guides/connection/ts-agent-rdb.mdx +3 -3
  26. package/docs/guides/connection/ts-mcp-server-dynamodb.mdx +125 -0
  27. package/docs/guides/connection/ts-mcp-server-rdb.mdx +3 -3
  28. package/docs/guides/connection.mdx +101 -0
  29. package/docs/guides/docker-bundling.mdx +13 -7
  30. package/docs/guides/fastapi.mdx +244 -4
  31. package/docs/guides/license.mdx +264 -109
  32. package/docs/guides/local-development.mdx +87 -0
  33. package/docs/guides/nx-generator.mdx +7 -2
  34. package/docs/guides/py-agent.mdx +204 -44
  35. package/docs/guides/py-dynamodb.mdx +476 -0
  36. package/docs/guides/py-mcp-server.mdx +57 -2
  37. package/docs/guides/react-website-auth.mdx +58 -1
  38. package/docs/guides/react-website.mdx +87 -19
  39. package/docs/guides/terraform-project.mdx +1 -1
  40. package/docs/guides/trpc.mdx +45 -9
  41. package/docs/guides/ts-agent.mdx +120 -6
  42. package/docs/guides/ts-dynamodb.mdx +187 -0
  43. package/docs/guides/ts-mcp-server.mdx +62 -2
  44. package/docs/guides/ts-rdb.mdx +98 -20
  45. package/docs/guides/ts-smithy-api.mdx +183 -4
  46. package/docs/guides/typescript-infrastructure.mdx +9 -1
  47. package/docs/guides/typescript-project.mdx +5 -10
  48. package/docs/guides/workspace.mdx +8 -2
  49. package/docs/snippets/agent/bedrock-deployment.mdx +4 -0
  50. package/docs/snippets/api/access-logging.mdx +33 -0
  51. package/docs/snippets/api/type-safe-api-integrations.mdx +31 -0
  52. package/docs/snippets/api/waf-configuration.mdx +1 -1
  53. package/docs/snippets/connection/dynamodb-local-development.mdx +7 -0
  54. package/docs/snippets/connection/lambda-dynamodb-access.mdx +80 -0
  55. package/docs/snippets/connection/py-dynamodb-local-development.mdx +7 -0
  56. package/docs/snippets/dynamodb/deploying-table.mdx +171 -0
  57. package/docs/snippets/dynamodb/gsi-config.mdx +38 -0
  58. package/docs/snippets/dynamodb/infrastructure.mdx +33 -0
  59. package/docs/snippets/dynamodb/local-dev-start.mdx +13 -0
  60. package/docs/snippets/dynamodb/local-dev-windows.mdx +15 -0
  61. package/docs/snippets/mcp/bedrock-deployment.mdx +4 -0
  62. package/docs/snippets/mcp/config.mdx +2 -1
  63. package/docs/snippets/required-prerequisites.mdx +1 -1
  64. package/generators.json +100 -1
  65. package/package.json +1 -1
  66. package/src/agentcore-gateway/gateway-connection/schema.json +31 -0
  67. package/src/agentcore-gateway/mcp-connection/schema.json +31 -0
  68. package/src/agentcore-gateway/schema.json +70 -0
  69. package/src/connection/schema.json +5 -0
  70. package/src/infra/app/schema.json +5 -0
  71. package/src/license/schema.json +11 -0
  72. package/src/preset/schema.json +10 -5
  73. package/src/py/agent/a2a-connection/schema.json +5 -0
  74. package/src/py/agent/gateway-connection/schema.json +31 -0
  75. package/src/py/agent/mcp-connection/schema.json +5 -0
  76. package/src/py/agent/react-connection/schema.json +5 -0
  77. package/src/py/agent/schema.json +6 -1
  78. package/src/py/api/schema.json +5 -0
  79. package/src/py/dynamodb/agent-connection/schema.json +27 -0
  80. package/src/py/dynamodb/fast-api-connection/schema.json +23 -0
  81. package/src/py/dynamodb/mcp-server-connection/schema.json +27 -0
  82. package/src/py/dynamodb/schema.json +75 -0
  83. package/src/py/fast-api/react/schema.json +5 -0
  84. package/src/py/fast-api/schema.json +5 -0
  85. package/src/py/lambda-function/schema.json +5 -0
  86. package/src/py/mcp-server/schema.json +5 -0
  87. package/src/py/project/schema.json +5 -0
  88. package/src/smithy/project/schema.json +5 -0
  89. package/src/smithy/react-connection/schema.json +5 -0
  90. package/src/smithy/ts/api/schema.json +5 -0
  91. package/src/terraform/project/schema.json +5 -0
  92. package/src/trpc/backend/schema.json +5 -0
  93. package/src/trpc/react/schema.json +5 -0
  94. package/src/ts/agent/a2a-connection/schema.json +5 -0
  95. package/src/ts/agent/gateway-connection/schema.json +31 -0
  96. package/src/ts/agent/mcp-connection/schema.json +5 -0
  97. package/src/ts/agent/react-connection/schema.json +5 -0
  98. package/src/ts/agent/schema.json +5 -0
  99. package/src/ts/api/schema.json +5 -0
  100. package/src/ts/astro-docs/schema.json +3 -3
  101. package/src/ts/docs/schema.json +3 -3
  102. package/src/ts/dynamodb/agent-connection/schema.json +27 -0
  103. package/src/ts/dynamodb/mcp-server-connection/schema.json +27 -0
  104. package/src/ts/dynamodb/schema.json +75 -0
  105. package/src/ts/dynamodb/smithy-connection/schema.json +23 -0
  106. package/src/ts/dynamodb/trpc-connection/schema.json +23 -0
  107. package/src/ts/lambda-function/schema.json +5 -0
  108. package/src/ts/lib/schema.json +5 -0
  109. package/src/ts/mcp-server/schema.json +5 -0
  110. package/src/ts/nx-generator/schema.json +5 -0
  111. package/src/ts/nx-plugin/schema.json +5 -0
  112. package/src/ts/rdb/agent-connection/schema.json +5 -0
  113. package/src/ts/rdb/mcp-server-connection/schema.json +5 -0
  114. package/src/ts/rdb/schema.json +5 -0
  115. package/src/ts/rdb/smithy-connection/schema.json +5 -0
  116. package/src/ts/rdb/trpc-connection/schema.json +5 -0
  117. package/src/ts/react-website/app/schema.json +11 -6
  118. package/src/ts/react-website/cognito-auth/schema.json +5 -0
  119. package/src/ts/react-website/runtime-config/schema.json +5 -0
  120. package/src/ts/website/app/schema.json +11 -6
  121. package/src/ts/website/auth/schema.json +5 -0
@@ -4,7 +4,9 @@ description: Generate a Python Agent for building AI agents with tools and deplo
4
4
  generator: py#agent
5
5
  ---
6
6
 
7
- import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
7
+ import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
8
+ import Astro from '@astrojs/react';
9
+ import ConnectionCard from '@components/connection-card.astro';
8
10
  import RunGenerator from '@components/run-generator.astro';
9
11
  import NxCommands from '@components/nx-commands.astro';
10
12
  import Link from '@components/link.astro';
@@ -14,18 +16,9 @@ import GeneratorParameters from '@components/generator-parameters.astro';
14
16
  import Drawer from '@components/drawer.astro';
15
17
  import OptionFilter from '@components/option-filter.astro';
16
18
 
17
- Generate a Python [Strands Agent](https://strandsagents.com/) for building AI agents with tools, and optionally deploy it to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/). By default, the generator uses [FastAPI](https://fastapi.tiangolo.com/) to expose an HTTP server. Alternatively, you can choose the [Agent-to-Agent (A2A)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) protocol for interoperability with other A2A-compatible agents, or the [AG-UI](https://docs.ag-ui.com/) protocol for direct frontend integration via [CopilotKit](https://docs.copilotkit.ai/aws-strands).
19
+ Generate a Python AI agent for building agents with tools, and optionally deploy it to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/). Choose the agent framework with the `framework` option: [Strands](https://strandsagents.com/) (the default) or [LangChain](https://docs.langchain.com/oss/python/langchain/overview) (built on [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview)).
18
20
 
19
- ## What is Strands?
20
-
21
- [Strands](https://strandsagents.com/docs/user-guide/quickstart/overview/) is a lightweight, production-ready Python framework for building AI agents. Key features include:
22
-
23
- - **Lightweight and customizable**: Simple agent loop that gets out of your way
24
- - **Production ready**: Full observability, tracing, and deployment options for scale
25
- - **Model and provider agnostic**: Supports many different models from various providers
26
- - **Community-driven tools**: Powerful set of community-contributed tools
27
- - **Multi-agent support**: Advanced techniques like agent teams and autonomous agents
28
- - **Flexible interaction modes**: Conversational, streaming, and non-streaming support
21
+ The generator exposes your agent over a server `protocol`. Both frameworks support [HTTP](https://fastapi.tiangolo.com/) (the default), the [Agent-to-Agent (A2A)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) protocol for interoperability with other A2A-compatible agents, and the [AG-UI](https://docs.ag-ui.com/) protocol for direct frontend integration via [CopilotKit](https://docs.copilotkit.ai/).
29
22
 
30
23
  ## Usage
31
24
 
@@ -64,10 +57,10 @@ The generator will add the following files to your existing Python project. The
64
57
  </FileTree>
65
58
  </OptionFilter>
66
59
 
67
- <OptionFilter when={{ protocol: 'a2a' }} description="Strands A2A server layout">
60
+ <OptionFilter when={{ protocol: 'a2a' }} description="A2A server layout">
68
61
  ### A2A Protocol
69
62
 
70
- The entry point uses the [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) instead of FastAPI:
63
+ The entry point exposes your agent over the A2A protocol (Strands uses the [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent); LangChain wraps the graph in an [`a2a-sdk`](https://a2a-protocol.org/) executor), mounted onto a FastAPI app:
71
64
 
72
65
  <FileTree>
73
66
  - your-project/
@@ -77,7 +70,7 @@ The entry point uses the [Strands A2A Server](https://strandsagents.com/docs/use
77
70
  - agent.py Main agent definition with sample tools
78
71
  - main.py A2A server entry point
79
72
  - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
80
- - pyproject.toml Updated with Strands dependencies
73
+ - pyproject.toml Updated with framework and A2A dependencies
81
74
  - project.json Updated with agent serve targets
82
75
  </FileTree>
83
76
  </OptionFilter>
@@ -85,7 +78,7 @@ The entry point uses the [Strands A2A Server](https://strandsagents.com/docs/use
85
78
  <OptionFilter when={{ protocol: 'ag-ui' }} description="AG-UI / CopilotKit server layout">
86
79
  ### AG-UI Protocol
87
80
 
88
- The entry point uses the [ag-ui-strands](https://docs.ag-ui.com/) integration, which exposes your agent via the AG-UI protocol for direct frontend integration with [CopilotKit](https://docs.copilotkit.ai/aws-strands):
81
+ The entry point exposes your agent via the [AG-UI](https://docs.ag-ui.com/) protocol for direct frontend integration with [CopilotKit](https://docs.copilotkit.ai/). Strands agents use the [ag-ui-strands](https://docs.ag-ui.com/) integration; LangChain agents use [ag-ui-langgraph](https://docs.ag-ui.com/):
89
82
 
90
83
  <FileTree>
91
84
  - your-project/
@@ -93,14 +86,14 @@ The entry point uses the [ag-ui-strands](https://docs.ag-ui.com/) integration, w
93
86
  - agent/ (or custom name if specified)
94
87
  - \_\_init\_\_.py Python package initialization
95
88
  - agent.py Main agent definition with sample tools
96
- - main.py AG-UI server entry point using ag-ui-strands
89
+ - main.py AG-UI server entry point
97
90
  - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
98
- - pyproject.toml Updated with Strands and AG-UI dependencies
91
+ - pyproject.toml Updated with framework and AG-UI dependencies
99
92
  - project.json Updated with agent serve targets
100
93
  </FileTree>
101
94
 
102
95
  :::tip[Connect to a React website]
103
- AG-UI agents can be connected to a React frontend using the <Link path="/guides/connection/react-agui">`connection` generator</Link>, which will set up [CopilotKit](https://docs.copilotkit.ai/aws-strands) components for a rich chat experience.
96
+ AG-UI agents can be connected to a React frontend using the <Link path="/guides/connection/react-agui">`connection` generator</Link>, which will set up [CopilotKit](https://docs.copilotkit.ai/) components for a rich chat experience.
104
97
  :::
105
98
  </OptionFilter>
106
99
 
@@ -146,12 +139,14 @@ If you selected `none` for `infra`, no CDK constructs or Terraform modules are g
146
139
 
147
140
  ## Working with Your Agent
148
141
 
149
- ### Adding Tools
142
+ You can edit `agent.py` to add tools, configure the model and customize the system prompt. The API depends on the framework you chose.
150
143
 
151
- Tools are functions that the AI agent can call to perform actions. The Strands framework uses a simple decorator-based approach for defining tools.
144
+ ### Adding Tools
152
145
 
153
- You can add new tools in the `agent.py` file:
146
+ Tools are functions that the AI agent can call to perform actions. Both frameworks use a decorator-based approach for defining tools, derive the tool name and description from the function name and docstring, and generate the input schema from your type hints.
154
147
 
148
+ <Tabs syncKey="agent-framework">
149
+ <TabItem label="Strands" _filter={{ framework: 'strands' }}>
155
150
  ```python
156
151
  from strands import Agent, tool
157
152
 
@@ -172,14 +167,38 @@ agent = Agent(
172
167
  tools=[calculate_sum, get_weather],
173
168
  )
174
169
  ```
170
+ </TabItem>
171
+ <TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
172
+ ```python
173
+ from langchain.agents import create_agent
174
+ from langchain_aws import ChatBedrockConverse
175
+ from langchain_core.tools import tool
176
+
177
+ @tool
178
+ def calculate_sum(numbers: list[int]) -> int:
179
+ """Calculate the sum of a list of numbers"""
180
+ return sum(numbers)
175
181
 
176
- The Strands framework automatically handles:
177
- - Type validation based on your function's type hints
178
- - JSON schema generation for tool calling
179
- - Error handling and response formatting
182
+ @tool
183
+ def get_weather(city: str) -> str:
184
+ """Get weather information for a city"""
185
+ # Your weather API integration here
186
+ return f"Weather in {city}: Sunny, 25°C"
187
+
188
+ # Add tools to your agent
189
+ agent = create_agent(
190
+ model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
191
+ tools=[calculate_sum, get_weather],
192
+ system_prompt="You are a helpful assistant with access to various tools.",
193
+ )
194
+ ```
195
+ </TabItem>
196
+ </Tabs>
180
197
 
181
198
  ### Using Pre-built Tools
182
199
 
200
+ <Tabs syncKey="agent-framework">
201
+ <TabItem label="Strands" _filter={{ framework: 'strands' }}>
183
202
  Strands provides a collection of pre-built tools through the `strands-tools` package:
184
203
 
185
204
  ```python
@@ -190,9 +209,26 @@ agent = Agent(
190
209
  tools=[current_time, http_request, file_read],
191
210
  )
192
211
  ```
212
+ </TabItem>
213
+ <TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
214
+ LangChain provides a large ecosystem of [tools and integrations](https://docs.langchain.com/oss/python/integrations/tools). Install the relevant integration package, then pass the tools to `create_agent`:
215
+
216
+ ```python
217
+ from langchain_community.tools import DuckDuckGoSearchRun
218
+
219
+ agent = create_agent(
220
+ model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
221
+ tools=[DuckDuckGoSearchRun()],
222
+ system_prompt="You are a helpful assistant.",
223
+ )
224
+ ```
225
+ </TabItem>
226
+ </Tabs>
193
227
 
194
228
  ### Model Configuration
195
229
 
230
+ <Tabs syncKey="agent-framework">
231
+ <TabItem label="Strands" _filter={{ framework: 'strands' }}>
196
232
  By default, Strands agents use Claude 4 Sonnet, but you can customize the model provider. See the [Strands documentation on model providers](https://strandsagents.com/docs/user-guide/concepts/model-providers/) for configuration options:
197
233
 
198
234
  ```python
@@ -208,30 +244,45 @@ bedrock_model = BedrockModel(
208
244
 
209
245
  agent = Agent(model=bedrock_model)
210
246
  ```
247
+ </TabItem>
248
+ <TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
249
+ LangChain agents use a [`ChatBedrockConverse`](https://docs.langchain.com/oss/python/integrations/chat/bedrock_converse) model. The generated agent reads the model id and region from the `MODEL_ID` and `AWS_REGION` environment variables, but you can configure the model directly in `agent.py`:
211
250
 
212
- ### Consuming MCP Servers
251
+ ```python
252
+ from langchain_aws import ChatBedrockConverse
253
+
254
+ model = ChatBedrockConverse(
255
+ model="anthropic.claude-sonnet-4-20250514-v1:0",
256
+ region_name="us-west-2",
257
+ temperature=0.3,
258
+ )
259
+ ```
260
+ </TabItem>
261
+ </Tabs>
213
262
 
214
- You can [add tools from MCP servers](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) to your Strands agent.
263
+ ### Consuming MCP Servers
215
264
 
216
- For consuming MCP Servers which you have created using the <Link path="/guides/py-mcp-server">`py#mcp-server`</Link> or <Link path="/guides/ts-mcp-server">`ts#mcp-server`</Link> generators you can make use of the <Link path="/guides/connection/py-agent-mcp">`connection` generator</Link>.
265
+ For consuming MCP Servers which you have created using the <Link path="/guides/py-mcp-server">`py#mcp-server`</Link> or <Link path="/guides/ts-mcp-server">`ts#mcp-server`</Link> generators you can make use of the <Link path="/guides/connection/py-agent-mcp">`connection` generator</Link>, which wires the MCP server's tools into your agent for both frameworks.
217
266
 
218
267
  <RunGenerator generator="connection" />
219
268
 
220
269
  Refer to the <Link path="/guides/connection/py-agent-mcp">`connection` generator guide</Link> for details about how the connection is set up.
221
270
 
222
- For other MCP servers, please refer to the [Strands Documentation](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/).
271
+ For other MCP servers, refer to the [Strands](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) or [LangChain](https://docs.langchain.com/oss/python/langchain/mcp) MCP documentation.
223
272
 
224
273
  ### More
225
274
 
226
- For a more in-depth guide to writing Strands agents, refer to the [Strands documentation](https://strandsagents.com/docs/user-guide/quickstart/overview/).
275
+ For a more in-depth guide to writing agents, refer to the [Strands](https://strandsagents.com/docs/user-guide/quickstart/overview/) or [LangChain](https://docs.langchain.com/oss/python/langchain/overview) documentation.
227
276
 
228
277
  ## Protocol
229
278
 
230
279
  Your agent's server protocol determines how it communicates. All options are served by [FastAPI](https://fastapi.tiangolo.com/) — the entry point differs:
231
280
 
232
281
  - **HTTP** (default): A standard FastAPI server with a custom `/invocations` endpoint, CORS, and streaming. Best for custom client integrations.
233
- - **A2A**: The [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) mounted onto a FastAPI app. Best when your agent needs to be discoverable and invokable by other A2A-compatible agents.
234
- - **AG-UI**: The [ag-ui-strands](https://docs.ag-ui.com/) integration, which exposes the [AG-UI protocol](https://docs.ag-ui.com/) over SSE. Best for direct frontend integration with [CopilotKit](https://docs.copilotkit.ai/aws-strands) in a React website.
282
+ - **A2A**: An [Agent-to-Agent](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) server mounted onto a FastAPI app (Strands uses the [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent); LangChain uses the framework-agnostic [`a2a-sdk`](https://a2a-protocol.org/)). Best when your agent needs to be discoverable and invokable by other A2A-compatible agents.
283
+ - **AG-UI**: The [AG-UI protocol](https://docs.ag-ui.com/) over SSE (Strands uses `ag-ui-strands`; LangChain uses `ag-ui-langgraph`). Best for direct frontend integration with [CopilotKit](https://docs.copilotkit.ai/) in a React website.
284
+
285
+ The server entry point differs by framework (Strands yields a context-managed `Agent`, while LangChain drives a compiled `create_agent` graph), but the external contract for each protocol is the same.
235
286
 
236
287
  All protocols expose `/ping` for the AgentCore runtime health check contract. A2A agents listen on port `9000`; HTTP and AG-UI agents listen on port `8080`. The generated Dockerfile and infrastructure are configured for you.
237
288
 
@@ -322,20 +373,23 @@ Since the generator vends CDK or Terraform infrastructure which manages deployin
322
373
  <OptionFilter when={{ protocol: 'a2a' }} description="A2A server details">
323
374
  ## A2A Server (A2A protocol)
324
375
 
325
- The generated `main.py` mounts `A2AServer.to_fastapi_app()` onto a parent FastAPI app that also exposes `/ping`. When deployed to AgentCore, the entry point resolves the runtime's public ARN from AppConfig and advertises it in the agent card.
376
+ The generated `main.py` mounts an A2A server onto a parent FastAPI app that also exposes `/ping`. Strands agents use the Strands `A2AServer`; LangChain agents wrap the compiled graph in an [`a2a-sdk`](https://a2a-protocol.org/) `AgentExecutor`. When deployed to AgentCore, the entry point resolves the runtime's public ARN from AppConfig and advertises it in the agent card.
326
377
 
327
- Most users will not need to modify this file — edit `agent.py` to change tools or the system prompt. The A2A server populates the agent card (`/.well-known/agent-card.json`) from the `Agent` constructor's `name` and `description`.
378
+ Most users will not need to modify this file; edit `agent.py` to change tools or the system prompt. The A2A server populates the agent card (`/.well-known/agent-card.json`) from the agent's `name` and `description`.
328
379
  </OptionFilter>
329
380
 
330
381
  <OptionFilter when={{ protocol: 'ag-ui' }} description="AG-UI / CopilotKit server details">
331
382
  ## AG-UI Server (AG-UI protocol)
332
383
 
333
- The generated `main.py` wraps your Strands `Agent` in an `ag_ui_strands.StrandsAgent` and creates a FastAPI app via `create_strands_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.
384
+ The generated `main.py` 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 wiring depends on the framework:
385
+
386
+ - **Strands**: wraps your `Agent` in an `ag_ui_strands.StrandsAgent` and creates the FastAPI app via `create_strands_app()`.
387
+ - **LangChain**: wraps the compiled graph in an `ag_ui_langgraph.LangGraphAgent` and serves it from a hand-rolled FastAPI `/invocations` loop.
334
388
 
335
389
  Most users will not need to modify this file — edit `agent.py` to change tools or the system prompt.
336
390
 
337
391
  :::tip[Connecting to a React website]
338
- 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.
392
+ 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/) provider and [AG-UI HttpAgent](https://docs.ag-ui.com/) client.
339
393
  :::
340
394
  </OptionFilter>
341
395
 
@@ -343,27 +397,70 @@ AG-UI agents are designed to be consumed directly by a frontend. Use the <Link p
343
397
 
344
398
  ### Local Development
345
399
 
346
- The generator configures a target named `<your-agent-name>-serve`, which starts your Agent locally for development and testing.
400
+ To run your Agent (and everything connected to it) locally, use the project's `dev` target:
401
+
402
+ <NxCommands commands={['dev your-project']} />
403
+
404
+ 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:
347
405
 
348
- <NxCommands commands={['agent-serve your-project']} />
406
+ <NxCommands commands={['agent-dev your-project']} />
349
407
 
350
- This command uses `uv run` to execute your Agent using the [Bedrock AgentCore Python SDK](https://github.com/aws/bedrock-agentcore-sdk-python).
408
+ This uses `uv run` to execute your Agent using the [Bedrock AgentCore Python SDK](https://github.com/aws/bedrock-agentcore-sdk-python).
351
409
 
352
410
  ### Chat with Your Agent
353
411
 
354
- 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:
412
+ The generator configures a `<your-agent-name>-chat` Nx target that drops you into an interactive terminal chat with your agent.
413
+
414
+ 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):
415
+
416
+ <NxCommands commands={['agent-dev your-project']} />
417
+
418
+ Then, in another terminal, start the chat:
355
419
 
356
420
  <NxCommands commands={['run your-project:agent-chat']} />
357
421
 
358
- For **HTTP** agents, the generator also emits:
422
+ 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).
423
+
424
+ For **HTTP** agents, the chat script uses a type-safe TypeScript client generated from the agent's OpenAPI spec. The generator also emits:
359
425
 
360
426
  - `scripts/<your-agent-name>_openapi.py` — a small script that exports the agent's OpenAPI spec
361
427
  - An `<your-agent-name>-openapi` Nx target that runs it
362
428
  - An `<your-agent-name>-generate-client` Nx target that produces a type-safe TypeScript client under `scripts/<your-agent-name>/generated/`
363
- - `scripts/<your-agent-name>/chat.ts` — a thin wrapper around the generated client
364
429
 
365
430
  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.
366
431
 
432
+ <OptionFilter when={{ infra: 'agentcore' }} description="Deployed agent chat details">
433
+ #### Chat with your deployed agent
434
+
435
+ 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:
436
+
437
+ <Tabs syncKey="auth">
438
+ <TabItem label="IAM" _filter={{ auth: 'iam' }}>
439
+ 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:
440
+
441
+ <NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>' }} />
442
+ </TabItem>
443
+
444
+ <TabItem label="Cognito" _filter={{ auth: 'cognito' }}>
445
+ For Cognito-authenticated agents, provide a Cognito access token via the `AGENT_ACCESS_TOKEN` environment variable, which is sent as a bearer token:
446
+
447
+ <NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>', AGENT_ACCESS_TOKEN: '<access-token>' }} />
448
+
449
+ You can obtain an access token using the AWS CLI's `cognito-idp admin-initiate-auth` command, for example:
450
+
451
+ ```bash
452
+ aws cognito-idp admin-initiate-auth \
453
+ --user-pool-id <user-pool-id> \
454
+ --client-id <user-pool-client-id> \
455
+ --auth-flow ADMIN_NO_SRP_AUTH \
456
+ --auth-parameters USERNAME=<username>,PASSWORD=<password> \
457
+ --query 'AuthenticationResult.AccessToken' \
458
+ --output text
459
+ ```
460
+ </TabItem>
461
+ </Tabs>
462
+ </OptionFilter>
463
+
367
464
  <OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
368
465
  ## Deploying Your Agent to Bedrock AgentCore Runtime
369
466
 
@@ -475,9 +572,72 @@ Refer to the <Link path="/guides/connection/py-agent-a2a">`connection` generator
475
572
  <OptionFilter when={{ protocol: 'ag-ui' }} description="AG-UI / React connection details">
476
573
  ### Invoking an AG-UI Agent
477
574
 
478
- To invoke your AG-UI agent from a React website, use the <Link path="/guides/connection/react-agui">`connection` generator</Link>, which wires up a [CopilotKit](https://docs.copilotkit.ai/aws-strands) client configured for your deployed agent with the correct authentication (IAM or Cognito).
575
+ To invoke your AG-UI agent from a React website, use the <Link path="/guides/connection/react-agui">`connection` generator</Link>, which wires up a [CopilotKit](https://docs.copilotkit.ai/) client configured for your deployed agent with the correct authentication (IAM or Cognito).
479
576
 
480
577
  <RunGenerator generator="connection" />
481
578
 
482
579
  Refer to the <Link path="/guides/connection/react-agui">`connection` generator guide</Link> for details about how the connection is set up.
483
580
  </OptionFilter>
581
+
582
+ ## Connections
583
+
584
+ Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
585
+
586
+ <CardGrid>
587
+ <ConnectionCard
588
+ title="React to Python Agent"
589
+ description="Call a Python Agent from a React website"
590
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-py-agent`}
591
+ source="react"
592
+ target="strands"
593
+ targetBadge="python"
594
+ />
595
+ <ConnectionCard
596
+ title="React to AG-UI Agent"
597
+ description="Call an Agent exposing the AG-UI protocol from a React website via CopilotKit"
598
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agui`}
599
+ source="react"
600
+ target="copilotkit"
601
+ />
602
+ <ConnectionCard
603
+ title="Python Agent to MCP"
604
+ description="Connect a Python Agent to an MCP server"
605
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-mcp`}
606
+ source="strands"
607
+ sourceBadge="python"
608
+ target="mcp"
609
+ />
610
+ <ConnectionCard
611
+ title="Python Agent to A2A Agent"
612
+ description="Connect a Python Agent to a remote A2A agent"
613
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-a2a`}
614
+ source="strands"
615
+ sourceBadge="python"
616
+ target="a2a"
617
+ />
618
+ <ConnectionCard
619
+ title="TypeScript Agent to A2A Agent"
620
+ description="Connect a TypeScript Agent to a remote A2A agent"
621
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-a2a`}
622
+ source="strands"
623
+ sourceBadge="typescript"
624
+ target="a2a"
625
+ />
626
+ <ConnectionCard
627
+ title="Python Agent to Python DynamoDB"
628
+ description="Connect a Python Agent to a DynamoDB table"
629
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-dynamodb`}
630
+ source="strands"
631
+ sourceBadge="python"
632
+ target="dynamodb"
633
+ targetBadge="python"
634
+ />
635
+ <ConnectionCard
636
+ title="Python Agent to AgentCore Gateway"
637
+ description="Connect a Python Agent to an AgentCore Gateway"
638
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-gateway`}
639
+ source="strands"
640
+ sourceBadge="python"
641
+ target="agentcore"
642
+ />
643
+ </CardGrid>