@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.
- package/bin/aws-nx-mcp.js +4312 -3360
- package/docs/guides/agentcore-gateway.mdx +376 -0
- package/docs/guides/connection/agentcore-gateway-gateway.mdx +154 -0
- package/docs/guides/connection/agentcore-gateway-mcp.mdx +134 -0
- package/docs/guides/connection/py-agent-a2a.mdx +47 -15
- package/docs/guides/connection/py-agent-dynamodb.mdx +116 -0
- package/docs/guides/connection/py-agent-gateway.mdx +176 -0
- package/docs/guides/connection/py-agent-mcp.mdx +42 -13
- package/docs/guides/connection/py-fast-api-dynamodb.mdx +56 -0
- package/docs/guides/connection/py-mcp-server-dynamodb.mdx +116 -0
- package/docs/guides/connection/react-agui.mdx +4 -4
- package/docs/guides/connection/react-fastapi.mdx +2 -2
- package/docs/guides/connection/react-py-agent.mdx +3 -3
- package/docs/guides/connection/react-smithy.mdx +3 -3
- package/docs/guides/connection/react-trpc.mdx +1 -1
- package/docs/guides/connection/react-ts-agent.mdx +5 -5
- package/docs/guides/connection/smithy-dynamodb.mdx +68 -0
- package/docs/guides/connection/smithy-rdb.mdx +4 -4
- package/docs/guides/connection/trpc-dynamodb.mdx +62 -0
- package/docs/guides/connection/trpc-rdb.mdx +4 -4
- package/docs/guides/connection/ts-agent-a2a.mdx +12 -9
- package/docs/guides/connection/ts-agent-dynamodb.mdx +128 -0
- package/docs/guides/connection/ts-agent-gateway.mdx +141 -0
- package/docs/guides/connection/ts-agent-mcp.mdx +11 -8
- package/docs/guides/connection/ts-agent-rdb.mdx +3 -3
- package/docs/guides/connection/ts-mcp-server-dynamodb.mdx +125 -0
- package/docs/guides/connection/ts-mcp-server-rdb.mdx +3 -3
- package/docs/guides/connection.mdx +101 -0
- package/docs/guides/docker-bundling.mdx +13 -7
- package/docs/guides/fastapi.mdx +244 -4
- package/docs/guides/license.mdx +264 -109
- package/docs/guides/local-development.mdx +87 -0
- package/docs/guides/nx-generator.mdx +7 -2
- package/docs/guides/py-agent.mdx +204 -44
- package/docs/guides/py-dynamodb.mdx +476 -0
- package/docs/guides/py-mcp-server.mdx +57 -2
- package/docs/guides/react-website-auth.mdx +58 -1
- package/docs/guides/react-website.mdx +87 -19
- package/docs/guides/terraform-project.mdx +1 -1
- package/docs/guides/trpc.mdx +45 -9
- package/docs/guides/ts-agent.mdx +120 -6
- package/docs/guides/ts-dynamodb.mdx +187 -0
- package/docs/guides/ts-mcp-server.mdx +62 -2
- package/docs/guides/ts-rdb.mdx +98 -20
- package/docs/guides/ts-smithy-api.mdx +183 -4
- package/docs/guides/typescript-infrastructure.mdx +9 -1
- package/docs/guides/typescript-project.mdx +5 -10
- package/docs/guides/workspace.mdx +8 -2
- package/docs/snippets/agent/bedrock-deployment.mdx +4 -0
- package/docs/snippets/api/access-logging.mdx +33 -0
- package/docs/snippets/api/type-safe-api-integrations.mdx +31 -0
- package/docs/snippets/api/waf-configuration.mdx +1 -1
- package/docs/snippets/connection/dynamodb-local-development.mdx +7 -0
- package/docs/snippets/connection/lambda-dynamodb-access.mdx +80 -0
- package/docs/snippets/connection/py-dynamodb-local-development.mdx +7 -0
- package/docs/snippets/dynamodb/deploying-table.mdx +171 -0
- package/docs/snippets/dynamodb/gsi-config.mdx +38 -0
- package/docs/snippets/dynamodb/infrastructure.mdx +33 -0
- package/docs/snippets/dynamodb/local-dev-start.mdx +13 -0
- package/docs/snippets/dynamodb/local-dev-windows.mdx +15 -0
- package/docs/snippets/mcp/bedrock-deployment.mdx +4 -0
- package/docs/snippets/mcp/config.mdx +2 -1
- package/docs/snippets/required-prerequisites.mdx +1 -1
- package/generators.json +100 -1
- package/package.json +1 -1
- package/src/agentcore-gateway/gateway-connection/schema.json +31 -0
- package/src/agentcore-gateway/mcp-connection/schema.json +31 -0
- package/src/agentcore-gateway/schema.json +70 -0
- package/src/connection/schema.json +5 -0
- package/src/infra/app/schema.json +5 -0
- package/src/license/schema.json +11 -0
- package/src/preset/schema.json +10 -5
- package/src/py/agent/a2a-connection/schema.json +5 -0
- package/src/py/agent/gateway-connection/schema.json +31 -0
- package/src/py/agent/mcp-connection/schema.json +5 -0
- package/src/py/agent/react-connection/schema.json +5 -0
- package/src/py/agent/schema.json +6 -1
- package/src/py/api/schema.json +5 -0
- package/src/py/dynamodb/agent-connection/schema.json +27 -0
- package/src/py/dynamodb/fast-api-connection/schema.json +23 -0
- package/src/py/dynamodb/mcp-server-connection/schema.json +27 -0
- package/src/py/dynamodb/schema.json +75 -0
- package/src/py/fast-api/react/schema.json +5 -0
- package/src/py/fast-api/schema.json +5 -0
- package/src/py/lambda-function/schema.json +5 -0
- package/src/py/mcp-server/schema.json +5 -0
- package/src/py/project/schema.json +5 -0
- package/src/smithy/project/schema.json +5 -0
- package/src/smithy/react-connection/schema.json +5 -0
- package/src/smithy/ts/api/schema.json +5 -0
- package/src/terraform/project/schema.json +5 -0
- package/src/trpc/backend/schema.json +5 -0
- package/src/trpc/react/schema.json +5 -0
- package/src/ts/agent/a2a-connection/schema.json +5 -0
- package/src/ts/agent/gateway-connection/schema.json +31 -0
- package/src/ts/agent/mcp-connection/schema.json +5 -0
- package/src/ts/agent/react-connection/schema.json +5 -0
- package/src/ts/agent/schema.json +5 -0
- package/src/ts/api/schema.json +5 -0
- package/src/ts/astro-docs/schema.json +3 -3
- package/src/ts/docs/schema.json +3 -3
- package/src/ts/dynamodb/agent-connection/schema.json +27 -0
- package/src/ts/dynamodb/mcp-server-connection/schema.json +27 -0
- package/src/ts/dynamodb/schema.json +75 -0
- package/src/ts/dynamodb/smithy-connection/schema.json +23 -0
- package/src/ts/dynamodb/trpc-connection/schema.json +23 -0
- package/src/ts/lambda-function/schema.json +5 -0
- package/src/ts/lib/schema.json +5 -0
- package/src/ts/mcp-server/schema.json +5 -0
- package/src/ts/nx-generator/schema.json +5 -0
- package/src/ts/nx-plugin/schema.json +5 -0
- package/src/ts/rdb/agent-connection/schema.json +5 -0
- package/src/ts/rdb/mcp-server-connection/schema.json +5 -0
- package/src/ts/rdb/schema.json +5 -0
- package/src/ts/rdb/smithy-connection/schema.json +5 -0
- package/src/ts/rdb/trpc-connection/schema.json +5 -0
- package/src/ts/react-website/app/schema.json +11 -6
- package/src/ts/react-website/cognito-auth/schema.json +5 -0
- package/src/ts/react-website/runtime-config/schema.json +5 -0
- package/src/ts/website/app/schema.json +11 -6
- package/src/ts/website/auth/schema.json +5 -0
package/docs/guides/py-agent.mdx
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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="
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
144
|
+
### Adding Tools
|
|
152
145
|
|
|
153
|
-
|
|
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
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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
|
|
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**:
|
|
234
|
-
- **AG-UI**: The [
|
|
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
|
|
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
|
|
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`
|
|
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/
|
|
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
|
-
|
|
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-
|
|
406
|
+
<NxCommands commands={['agent-dev your-project']} />
|
|
349
407
|
|
|
350
|
-
This
|
|
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
|
|
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
|
-
|
|
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/
|
|
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>
|