Python Agent

Tạo một Python AI agent để xây dựng các agent với các công cụ, và tùy chọn triển khai nó lên Amazon Bedrock AgentCore Runtime. Chọn framework agent với tùy chọn framework: Strands (mặc định) hoặc LangChain (được xây dựng trên LangGraph).

Generator expose agent của bạn qua một protocol server. Cả hai framework đều hỗ trợ HTTP (mặc định), giao thức Agent-to-Agent (A2A) để tương tác với các agent tương thích A2A khác, và giao thức AG-UI để tích hợp trực tiếp với frontend thông qua CopilotKit.

Cách sử dụng

Tạo một Agent

Bạn có thể tạo một Python Agent theo hai cách:

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - py#agent
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#agent

yarn

yarn nx g @aws/nx-plugin:py#agent

npm

npx nx g @aws/nx-plugin:py#agent

bun

bunx nx g @aws/nx-plugin:py#agent

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

pnpm nx g @aws/nx-plugin:py#agent --dry-run

yarn

yarn nx g @aws/nx-plugin:py#agent --dry-run

npm

npx nx g @aws/nx-plugin:py#agent --dry-run

bun

bunx nx g @aws/nx-plugin:py#agent --dry-run

Điều kiện tiên quyết dự án

Đầu tiên hãy sử dụng generator py#project để tạo một project để thêm Agent của bạn vào.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
project Bắt buộc	string	-	Dự án để thêm Agent vào
framework	strands | langchain	strands	SDK agent cần sử dụng.
name	string	-	Tên của Agent của bạn (mặc định: agent)
auth	iam | cognito	iam	Phương thức được sử dụng để xác thực với Agent của bạn. Chỉ áp dụng khi infra được thiết lập (bị bỏ qua khi infra là none).
protocol	http | a2a | ag-ui	http	Giao thức máy chủ cho Agent của bạn. HTTP cung cấp máy chủ HTTP FastAPI. A2A cung cấp máy chủ giao thức Agent-to-Agent. AG-UI cung cấp máy chủ giao thức Agent-User Interaction để tích hợp trực tiếp với frontend.
iac	inherit | cdk | terraform	inherit	Nhà cung cấp IaC ưu tiên. Mặc định giá trị này được kế thừa từ lựa chọn ban đầu của bạn.
infra	agentcore | none	agentcore	Loại hạ tầng để lưu trữ Agent của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Generator

Generator sẽ thêm các file sau vào Python project hiện có của bạn. Các file được tạo phụ thuộc vào protocol được chọn:

protocol = http

HTTP Protocol (mặc định)

• Thư mụcyour-project/

  • Thư mụcyour_module/

    • Thư mụcagent/ (hoặc tên tùy chỉnh nếu được chỉ định)

      • __init__.py Khởi tạo Python package
      • init.py Thiết lập ứng dụng FastAPI với CORS và middleware xử lý lỗi
      • agent.py Định nghĩa agent chính với các công cụ mẫu
      • main.py FastAPI entry point cho Bedrock AgentCore Runtime
      • Dockerfile Entry point để host agent của bạn (bị loại trừ khi infra được đặt thành None)
  • pyproject.toml Được cập nhật với các dependencies của Strands
  • project.json Được cập nhật với các target serve agent

protocol = a2a

A2A Protocol

Entry point expose agent của bạn qua giao thức A2A (Strands sử dụng Strands A2A Server; LangChain wrap graph trong một a2a-sdk executor), được mount lên một ứng dụng FastAPI:

• Thư mụcyour-project/

  • Thư mụcyour_module/

    • Thư mụcagent/ (hoặc tên tùy chỉnh nếu được chỉ định)

      • __init__.py Khởi tạo Python package
      • agent.py Định nghĩa agent chính với các công cụ mẫu
      • main.py A2A server entry point
      • Dockerfile Entry point để host agent của bạn (bị loại trừ khi infra được đặt thành None)
  • pyproject.toml Được cập nhật với các dependencies của framework và A2A
  • project.json Được cập nhật với các target serve agent

protocol = ag-ui

AG-UI Protocol

Entry point expose agent của bạn qua giao thức AG-UI để tích hợp trực tiếp với frontend thông qua CopilotKit. Các Strands agent sử dụng tích hợp ag-ui-strands; các LangChain agent sử dụng ag-ui-langgraph:

• Thư mụcyour-project/

  • Thư mụcyour_module/

    • Thư mụcagent/ (hoặc tên tùy chỉnh nếu được chỉ định)

      • __init__.py Khởi tạo Python package
      • agent.py Định nghĩa agent chính với các công cụ mẫu
      • main.py AG-UI server entry point
      • Dockerfile Entry point để host agent của bạn (bị loại trừ khi infra được đặt thành None)
  • pyproject.toml Được cập nhật với các dependencies của framework và AG-UI
  • project.json Được cập nhật với các target serve agent

Kết nối với React website

Các AG-UI agent có thể được kết nối với React frontend bằng cách sử dụng connection generator, sẽ thiết lập các component CopilotKit cho trải nghiệm chat phong phú.

Hạ tầng

infra = agentcore

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

Để triển khai Agent của bạn, các file sau được tạo:

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcagents

      • Thư mục<project-name>

        • <project-name>.ts CDK construct để triển khai agent của bạn

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcagents

      • Thư mục<project-name>

        • <project-name>.tf Module để triển khai agent của bạn
  • Thư mụccore

    • Thư mụcagent-core

      • runtime.tf Module chung để triển khai lên Bedrock AgentCore Runtime

infra = none

Nếu bạn chọn None cho infra, không có CDK construct hoặc Terraform module nào được tạo — Agent chỉ có thể chạy locally. Tùy chọn auth bị bỏ qua trong chế độ này vì không có endpoint được host để xác thực.

Kiến trúc

Bedrock AgentCore Runtime

Khi triển khai lên Bedrock AgentCore Runtime, agent được xây dựng thành container image, đẩy lên Amazon ECR và chạy trong AgentCore Runtime. Các client gọi đến AgentCore Runtime data plane endpoint, endpoint này chuyển tiếp các yêu cầu đến agent của bạn. Agent gọi Amazon Bedrock để suy luận mô hình và có thể gọi các công cụ, MCP server, hoặc các API downstream.

None (local only)

Với infra: None, không có cơ sở hạ tầng AWS nào được tạo ra. Agent chạy như một tiến trình cục bộ và gọi Amazon Bedrock để suy luận mô hình.

Làm việc với Agent của bạn

Bạn có thể chỉnh sửa agent.py để thêm công cụ, cấu hình model và tùy chỉnh system prompt. API phụ thuộc vào framework bạn đã chọn.

Thêm công cụ

Các công cụ là các hàm mà AI agent có thể gọi để thực hiện các hành động. Cả hai framework đều sử dụng phương pháp dựa trên decorator để định nghĩa các công cụ, lấy tên và mô tả công cụ từ tên hàm và docstring, và tạo input schema từ type hints của bạn.

Strands

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = Agent(
    system_prompt="You are a helpful assistant with access to various tools.",
    tools=[calculate_sum, get_weather],
)

LangChain

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="You are a helpful assistant with access to various tools.",
)

Sử dụng các công cụ có sẵn

Strands

Strands cung cấp một bộ sưu tập các công cụ có sẵn thông qua package strands-tools:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="You are a helpful assistant.",
    tools=[current_time, http_request, file_read],
)

LangChain

LangChain cung cấp một hệ sinh thái lớn các công cụ và tích hợp. Cài đặt package tích hợp liên quan, sau đó truyền các công cụ vào create_agent:

from langchain_community.tools import DuckDuckGoSearchRun

agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[DuckDuckGoSearchRun()],
    system_prompt="You are a helpful assistant.",
)

Cấu hình Model

Strands

Mặc định, các Strands agent sử dụng Claude 4 Sonnet, nhưng bạn có thể tùy chỉnh model provider. Xem tài liệu Strands về model providers để biết các tùy chọn cấu hình:

from strands import Agent
from strands.models import BedrockModel

# Create a BedrockModel
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

LangChain

Các LangChain agent sử dụng một model ChatBedrockConverse. Agent được tạo đọc model id và region từ các biến môi trường MODEL_ID và AWS_REGION, nhưng bạn có thể cấu hình model trực tiếp trong agent.py:

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

Sử dụng MCP Servers

Để sử dụng các MCP Server mà bạn đã tạo bằng generator py#mcp-server hoặc ts#mcp-server, bạn có thể sử dụng connection generator, kết nối các công cụ của MCP server vào agent của bạn cho cả hai framework.

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

Đối với các MCP server khác, hãy tham khảo tài liệu MCP của Strands hoặc LangChain.

Thêm nữa

Để có hướng dẫn chuyên sâu hơn về viết agent, hãy tham khảo tài liệu Strands hoặc LangChain.

Protocol

Giao thức server của agent xác định cách nó giao tiếp. Tất cả các tùy chọn đều được phục vụ bởi FastAPI — entry point khác nhau:

• HTTP (mặc định): Một FastAPI server tiêu chuẩn với endpoint /invocations tùy chỉnh, CORS và streaming. Tốt nhất cho các tích hợp client tùy chỉnh.
• A2A: Một server Agent-to-Agent được mount lên một ứng dụng FastAPI (Strands sử dụng Strands A2A Server; LangChain sử dụng a2a-sdk framework-agnostic). Tốt nhất khi agent của bạn cần có thể được phát hiện và gọi bởi các agent tương thích A2A khác.
• AG-UI: Giao thức AG-UI qua SSE (Strands sử dụng ag-ui-strands; LangChain sử dụng ag-ui-langgraph). Tốt nhất cho tích hợp trực tiếp với frontend thông qua CopilotKit trong React website.

Entry point của server khác nhau theo framework (Strands tạo ra một Agent được quản lý bằng context, trong khi LangChain điều khiển một graph create_agent đã được biên dịch), nhưng hợp đồng bên ngoài cho mỗi giao thức là giống nhau.

Tất cả các giao thức đều expose /ping cho hợp đồng health check của AgentCore runtime. Các agent A2A lắng nghe trên port 9000; các agent HTTP và AG-UI lắng nghe trên port 8080. Dockerfile và infrastructure được tạo đã được cấu hình cho bạn.

protocol = http

FastAPI Server (HTTP protocol)

HTTP server được tạo bao gồm:

• Thiết lập ứng dụng FastAPI với CORS middleware
• Middleware xử lý lỗi
• Tạo OpenAPI schema
• Health check endpoint (/ping)
• Agent invocation endpoint (/invocations)

Tùy chỉnh Invoke Inputs và Outputs với Pydantic

Invocation endpoint của agent sử dụng các model Pydantic để định nghĩa và xác thực các schema request và response. Bạn có thể tùy chỉnh các model này trong main.py để phù hợp với yêu cầu của agent.

Định nghĩa Input Models

Model InvokeInput mặc định chấp nhận một message.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

Bạn có thể mở rộng model này để bao gồm bất kỳ trường bổ sung nào mà agent của bạn cần.

Session ID được trích xuất từ HTTP header x-amzn-bedrock-agentcore-runtime-session-id, phù hợp với hợp đồng session của Bedrock AgentCore Runtime. Nếu header không được cung cấp, một UUID ngẫu nhiên sẽ được tạo làm phương án dự phòng.

Tổ chức mã nguồn

Bạn có thể muốn trừu tượng hóa một phần hoặc toàn bộ session ID khỏi caller nếu người dùng gọi agent của bạn trực tiếp. Ví dụ, bạn có thể sử dụng ID người dùng đã xác thực như một phần của session ID.

Cũng đáng lưu ý rằng tùy thuộc vào use case của bạn, bạn có thể cần triển khai authorization cho các session, ví dụ đảm bảo rằng người dùng chỉ có thể truy cập các session của riêng họ chứ không phải của người dùng khác.

Định nghĩa Output Models

Đối với streaming responses, generator cung cấp JsonStreamingResponse tự động serialize các Pydantic model sang định dạng JSON Lines (application/jsonl). Định dạng này tương thích với đặc tả streaming của OpenAPI 3.2 và hoạt động liền mạch với TypeScript client được tạo.

Mặc định, agent yield các đối tượng StreamChunk chứa văn bản response của agent:

class StreamChunk(BaseModel):
    content: str

Bạn có thể tùy chỉnh model StreamChunk để phù hợp với nhu cầu của bạn:

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

Hạn chế streaming FastAPI

Lưu ý rằng vì FastAPI hiện không hỗ trợ tạo đặc tả OpenAPI cho streaming responses, chúng ta phải thiết lập rõ ràng response model cho mỗi streaming operation, ví dụ:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

Có một yêu cầu tính năng mở cho hỗ trợ native trong FastAPI.

Bedrock AgentCore Python SDK

Generator bao gồm một dependency trên Bedrock AgentCore Python SDK cho các hằng số PingStatus. Nếu muốn, việc sử dụng BedrockAgentCoreApp thay vì FastAPI là khá đơn giản, tuy nhiên lưu ý rằng type-safety sẽ bị mất.

Bạn có thể tìm thêm chi tiết về khả năng của SDK trong tài liệu tại đây.

Cơ sở hạ tầng dưới dạng mã

Vì generator tạo ra hạ tầng CDK hoặc Terraform để quản lý việc triển khai agent của bạn, bạn không cần sử dụng bedrock-agentcore-starter-toolkit mà tài liệu đề cập để triển khai agent của bạn.

protocol = a2a

A2A Server (A2A protocol)

File main.py được tạo mount một A2A server lên một ứng dụng FastAPI cha cũng expose /ping. Các Strands agent sử dụng Strands A2AServer; các LangChain agent wrap compiled graph trong một a2a-sdk AgentExecutor. Khi được triển khai lên AgentCore, entry point phân giải ARN công khai của runtime từ AppConfig và quảng cáo nó trong agent card.

Hầu hết người dùng sẽ không cần sửa đổi file này; chỉnh sửa agent.py để thay đổi các công cụ hoặc system prompt. A2A server điền agent card (/.well-known/agent-card.json) từ name và description của agent.

protocol = ag-ui

AG-UI Server (AG-UI protocol)

File main.py được tạo expose một POST endpoint duy nhất stream các sự kiện AG-UI qua Server-Sent Events (SSE), cũng như /ping cho health check của AgentCore runtime. Cách kết nối phụ thuộc vào framework:

• Strands: wrap Agent của bạn trong một ag_ui_strands.StrandsAgent và tạo ứng dụng FastAPI thông qua create_strands_app().
• LangChain: wrap compiled graph trong một ag_ui_langgraph.LangGraphAgent và phục vụ nó từ một vòng lặp FastAPI /invocations được viết thủ công.

Hầu hết người dùng sẽ không cần sửa đổi file này — chỉnh sửa agent.py để thay đổi các công cụ hoặc system prompt.

Kết nối với React website

Các AG-UI agent được thiết kế để được sử dụng trực tiếp bởi frontend. Sử dụng connection generator để kết nối React website của bạn với agent thông qua provider CopilotKit và client AG-UI HttpAgent.

Chạy Agent của bạn

Phát triển Local

Để chạy Agent của bạn (và mọi thứ kết nối với nó) locally, sử dụng target dev của project:

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

Nếu bạn đã thêm nhiều component vào project của mình (agents, MCP servers, v.v.), lệnh này sẽ khởi động tất cả. Để chỉ chạy agent này, hãy target vào target <your-agent-name>-dev của nó:

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

Lệnh này sử dụng uv run để thực thi Agent của bạn bằng Bedrock AgentCore Python SDK.

Chat với Agent của bạn

Generator cấu hình một target Nx <your-agent-name>-chat đưa bạn vào một terminal chat tương tác với agent của bạn.

Target chat chạy độc lập. Mặc định nó kết nối với agent đang chạy locally của bạn, vì vậy hãy khởi động target <your-agent-name>-dev của agent trước (trong một terminal riêng):

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

Sau đó, trong một terminal khác, khởi động chat:

pnpm

pnpm nx run your-project:agent-chat

yarn

yarn nx run your-project:agent-chat

npm

npx nx run your-project:agent-chat

bun

bunx nx run your-project:agent-chat

Generator tạo ra một scripts/<your-agent-name>/chat.ts cho mỗi protocol. Nó kết nối với agent local theo mặc định, hoặc với agent đã triển khai của bạn khi RUNTIME_CONFIG_APP_ID được thiết lập (xem Chat với agent đã triển khai của bạn bên dưới).

Đối với các agent HTTP, script chat sử dụng một TypeScript client type-safe được tạo từ OpenAPI spec của agent. Generator cũng tạo ra:

• scripts/<your-agent-name>_openapi.py — một script nhỏ export OpenAPI spec của agent
• Một target Nx <your-agent-name>-openapi để chạy nó
• Một target Nx <your-agent-name>-generate-client tạo một TypeScript client type-safe trong scripts/<your-agent-name>/generated/

Khi bạn tùy chỉnh input shape của agent (ví dụ: thêm các trường mới vào InvokeInput), hãy cập nhật chat.ts để truyền các trường mới khi gọi agent và phần còn lại sẽ hoạt động tự động.

infra = agentcore

Chat với agent đã triển khai của bạn

Để chat với agent của bạn đã triển khai lên Bedrock AgentCore, hãy thiết lập biến môi trường RUNTIME_CONFIG_APP_ID thành AppConfig application id của deployment (được xuất ra dưới dạng RuntimeConfigApplicationId bởi stack đã triển khai). Script chat sẽ phân giải runtime ARN của agent từ runtime configuration và kết nối với endpoint đã triển khai:

IAM

Đối với các agent được xác thực bằng IAM, các request được ký bằng SigV4 sử dụng AWS credentials mặc định của bạn. Đảm bảo môi trường có AWS credentials với quyền gọi runtime:

pnpm

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

yarn

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

npm

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

bun

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Cognito

Đối với các agent được xác thực bằng Cognito, cung cấp Cognito access token thông qua biến môi trường AGENT_ACCESS_TOKEN, được gửi dưới dạng bearer token:

pnpm

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

yarn

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

npm

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

bun

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

Bạn có thể lấy access token bằng lệnh cognito-idp admin-initiate-auth của AWS CLI, ví dụ:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

infra = agentcore

Triển khai Agent của bạn lên Bedrock AgentCore Runtime

Infrastructure as Code

Nếu bạn đã chọn agentcore cho infra, cơ sở hạ tầng CDK hoặc Terraform liên quan sẽ được tạo ra mà bạn có thể sử dụng để triển khai Agent của mình lên Amazon Bedrock AgentCore Runtime.

CDK

Một CDK construct được tạo ra cho agent của bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc mặc định là <ProjectName>Agent.

Bạn có thể sử dụng CDK construct này trong một ứng dụng CDK:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

CDK Construct

Construct này sử dụng module aws-cdk-lib/aws-bedrockagentcore.

Terraform

Một module Terraform được tạo ra cho bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc mặc định là <ProjectName>-agent.

Truyền các output của module runtime_config_appconfig được chia sẻ vào module agent:

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Quyền Bedrock Model

Agent construct được tạo ra cấp quyền gọi tất cả các foundation model và inference profile của Bedrock theo mặc định (bedrock:InvokeModel và bedrock:InvokeModelWithResponseStream trên arn:aws:bedrock:*:*:foundation-model/* và arn:aws:bedrock:*:*:inference-profile/*).

Bạn có thể muốn thu hẹp phạm vi này xuống các model cụ thể mà agent của bạn sử dụng. Bạn có thể tìm thấy model mặc định được sử dụng bởi Strands agent trong tài liệu Strands; xem hướng dẫn model provider của Strands để cấu hình một model khác.

Yêu cầu Docker

Docker là bắt buộc để xây dựng và triển khai Agent của bạn. Hãy đảm bảo bạn đã cài đặt và khởi chạy Docker để tránh các lỗi như:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Xác thực

Trình tạo cung cấp tùy chọn auth để cấu hình xác thực cho Agent của bạn. Bạn có thể chọn giữa xác thực IAM (mặc định) hoặc Cognito khi tạo agent của mình.

IAM

Theo mặc định, Agent của bạn sẽ được bảo mật bằng xác thực IAM, chỉ cần triển khai nó mà không cần bất kỳ tham số nào:

CDK

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Bạn có thể cấp quyền truy cập để gọi agent của mình trên Bedrock AgentCore Runtime bằng phương thức grantInvokeAccess, ví dụ:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Để cấp quyền truy cập gọi agent của bạn, bạn sẽ cần thêm một policy như sau, tham chiếu đến output module.my_project_agent.agent_core_runtime_arn:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Xác thực Cognito

Khi bạn chọn xác thực Cognito, trình tạo sẽ cấu hình agent để sử dụng Cognito cho xác thực.

CDK

Construct được tạo ra chấp nhận một prop identity để cấu hình xác thực Cognito:

import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

Construct UserIdentity có thể được tạo bằng trình tạo ts#website#auth, hoặc bạn có thể tạo UserPool và UserPoolClient CDK của riêng mình.

Terraform

Module được tạo ra chấp nhận các biến user_pool_id và user_pool_client_ids cho xác thực Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Nhà cung cấp OIDC tùy chỉnh

Nếu bạn yêu cầu xác thực JWT tùy chỉnh với nhà cung cấp OIDC không phải Cognito, bạn có thể chỉnh sửa trực tiếp CDK construct hoặc module Terraform được tạo cho agent của mình. Lưu ý rằng trình tạo kết nối sẽ chỉ hỗ trợ xác thực IAM hoặc Cognito.

Thực hành Bảo mật Tốt nhất

Khi triển khai logic nghiệp vụ cho agent của bạn, hãy xem xét các thực hành bảo mật tốt nhất của Bedrock AgentCore Runtime.

Bundle và Docker Targets

Để build Agent của bạn cho Bedrock AgentCore Runtime, một target bundle được thêm vào project của bạn, thực hiện:

• Export các Python dependencies của bạn vào file requirements.txt bằng uv export
• Cài đặt dependencies cho nền tảng đích (aarch64-manylinux_2_28) bằng uv pip install

Một target docker cụ thể cho Agent của bạn cũng được thêm vào, sao chép Dockerfile và các artifact đã bundle vào một thư mục docker context. Điều này đặt Dockerfile cùng với output đã build, cho phép CDK build Docker image trực tiếp bằng AgentRuntimeArtifact.fromAsset.

Khả năng quan sát

Agent của bạn được tự động cấu hình với khả năng quan sát bằng cách sử dụng AWS Distro for Open Telemetry (ADOT), bằng cách cấu hình auto-instrumentation trong Dockerfile của bạn.

Bạn có thể tìm thấy các trace trong AWS Console CloudWatch, bằng cách chọn “GenAI Observability” trong menu. Lưu ý rằng để các trace được điền, bạn sẽ cần bật Transaction Search.

Để biết thêm chi tiết, hãy tham khảo tài liệu AgentCore về observability.

Gọi Agent của bạn

protocol = http

Gọi Local Server

Để gọi một Agent đang chạy locally thông qua target <your-agent-name>-serve, bạn có thể gửi một POST request đơn giản tới /invocations trên port mà local agent của bạn đang chạy. Ví dụ, với curl:

curl -N -X POST http://localhost:8081/invocations \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

Cờ streaming Curl

Tham số -N được cung cấp cho curl vô hiệu hóa việc buffer output stream, để bạn có thể xem streaming response theo thời gian thực.

Gọi Agent đã triển khai

Để gọi Agent của bạn đã triển khai lên Bedrock AgentCore Runtime, bạn có thể gửi một yêu cầu POST đến điểm cuối dataplane của Bedrock AgentCore Runtime với ARN runtime đã được mã hóa URL.

Bạn có thể lấy ARN runtime từ cơ sở hạ tầng của mình như sau:

CDK

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

ARN sẽ có định dạng như sau: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Sau đó, bạn có thể mã hóa URL cho ARN bằng cách thay thế : bằng %3A và / bằng %2F.

Console trình duyệt

Điều này rất đơn giản trong console trình duyệt hoặc Node REPL bằng cách sử dụng phương thức encodeURIComponent có sẵn:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

URL dataplane của Bedrock AgentCore Runtime để gọi agent như sau:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

Cách chính xác để gọi URL này phụ thuộc vào phương thức xác thực được sử dụng.

IAM

Xác thực IAM

Đối với Xác thực IAM, request phải được ký bằng AWS Signature Version 4 (SigV4).

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"message": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

Click here for more details on configuring the above acurl command

Cognito

Xác thực JWT / Cognito

Đối với Xác thực Cognito, truyền Cognito Access Token trong header Authorization:

curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

Bạn có thể lấy access token bằng lệnh cognito-idp admin-initiate-auth của AWS CLI, ví dụ:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Browser / React Website

Để gọi Agent của bạn từ một React website, bạn có thể sử dụng connection generator, tự động thiết lập một client với xác thực chính xác (IAM hoặc Cognito).

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

protocol = a2a

Gọi một A2A Agent như một Tool

Để ủy thác công việc từ agent này sang một A2A agent từ xa (có thể là TypeScript hoặc Python), hãy sử dụng connection generator. Nó cung cấp một client được xác thực SigV4 cho agent đích và AST-transform file agent.py của agent này để đăng ký A2A agent từ xa như một delegate được trang trí bằng @tool.

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

protocol = ag-ui

Gọi một AG-UI Agent

Để gọi AG-UI agent của bạn từ một React website, hãy sử dụng connection generator, thiết lập một client CopilotKit được cấu hình cho agent đã triển khai của bạn với xác thực chính xác (IAM hoặc Cognito).

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

Kết nối

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

React to Python Agent Gọi Python Agent từ một trang web React

React to AG-UI Agent Gọi Agent hỗ trợ giao thức AG-UI từ một trang web React thông qua CopilotKit

Python Agent to MCP Kết nối Python Agent với MCP server

Python Agent to A2A Agent Kết nối Python Agent với A2A agent từ xa

TypeScript Agent to A2A Agent Kết nối TypeScript Agent với A2A agent từ xa

Python Agent to Python DynamoDB Kết nối Python Agent với bảng DynamoDB

Python Agent to AgentCore Gateway Kết nối Python Agent với AgentCore Gateway