Python Agent

Tạo một Python AI agent để xây dựng các agent với 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 này expose agent của bạn qua một protocol máy chủ. 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 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:

CLI
VSCode

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

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

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

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 nx g @aws/nx-plugin:py#agent --dry-run

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

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

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

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

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.
session	s3 \| dynamodb-s3 \| in-memory	s3	Bộ nhớ được sử dụng để lưu trữ phiên làm việc cho Agent của bạn. LangChain hỗ trợ 's3' hoặc 'dynamodb-s3'; Strands hỗ trợ 's3'; 'in-memory' hợp lệ cho cả hai.
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ả từ Generator

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

Giao thức HTTP (mặc định)

Thư mụcyour-project/
- Thư mụcyour_module/
  - Thư mụcagent/ (or custom name if specified)
    __init__.py Python package initialization
    init.py FastAPI application setup with CORS and error handling middleware
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with Strands dependencies
- project.json Updated with agent serve targets

Giao thức A2A

Entry point expose agent của bạn qua giao thức A2A (Strands sử dụng Strands A2A Server; LangChain bọc 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/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py A2A server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with framework and A2A dependencies
- project.json Updated with agent serve targets

Giao thức AG-UI

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

Thư mụcyour-project/
- Thư mụcyour_module/
  - Thư mụcagent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py AG-UI server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with framework and AG-UI dependencies
- project.json Updated with agent serve targets

Hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iac 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
Terraform

Thư mụcpackages/common/constructs
- Thư mụcsrc
  - Thư mụcapp/ Constructs for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Thư mụcpackages/common/terraform
- Thư mụcsrc
  - Thư mụcapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

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

CDK
Terraform

Thư mụcpackages/common/constructs/src
- Thư mụcapp
  - Thư mụcagents
    Thư mục<project-name>
    <project-name>.ts CDK construct for deploying your agent

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 cục bộ. Tùy chọn auth bị bỏ qua trong chế độ này vì không có endpoint được host để xác thực.

Khi được triển khai lên Bedrock AgentCore Runtime, agent được xây dựng thành một container image, đẩy lên Amazon ECR và chạy trong AgentCore Runtime. Các client gọi đến data plane endpoint của AgentCore Runtime, 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.

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ô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 cách tiếp cận dựa trên decorator để định nghĩa 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 hint của bạn.

Strands
LangChain

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],
)

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
LangChain

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 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
LangChain

Theo mặc định, các agent Strands 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 provider để 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)

Các agent LangChain sử dụng 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 Server

Để 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, nó kết nối các công cụ của MCP server vào agent của bạn cho cả hai framework.

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

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 nx g @aws/nx-plugin:connection --dry-run

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

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

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

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

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, tham khảo tài liệu MCP của Strands hoặc LangChain.

Thêm

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

Giao thức

Giao thức máy chủ 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 máy chủ FastAPI tiêu chuẩn với endpoint /invocations tùy chỉnh, CORS và streaming. Tốt nhất cho tích hợp client tùy chỉnh.
A2A: Một máy chủ 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 không phụ thuộc framework). 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 frontend với CopilotKit trong một website React.

Entry point máy chủ khác nhau theo framework (Strands tạo ra một Agent được quản lý 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 kiểm tra sức khỏe của AgentCore runtime. Các agent A2A lắng nghe trên cổng 9000; các agent HTTP và AG-UI lắng nghe trên cổng 8080. Dockerfile và hạ tầng được tạo đã được cấu hình sẵn cho bạn.

Máy chủ FastAPI (giao thức HTTP)

Máy chủ HTTP được tạo bao gồm:

Thiết lập ứng dụng FastAPI với CORS middleware
Error handling middleware
Tạo OpenAPI schema
Health check endpoint (/ping)
Agent invocation endpoint (/invocations)

Tùy chỉnh Invoke Input và Output với Pydantic

Endpoint invocation 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 Model

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

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: 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 được tạo làm dự phòng.

Định nghĩa Output Model

Đối với các response streaming, generator cung cấp JsonStreamingResponse tự động serialize các model Pydantic 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.

Theo mặc định, agent tạo ra 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

Lưu ý rằng vì FastAPI hiện không hỗ trợ tạo đặc tả OpenAPI cho các response streaming, chúng ta phải đặt response model một cách rõ ràng cho mỗi thao tác streaming, tức là:

@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 vào 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à đơn giản, tuy nhiên lưu ý rằng type-safety 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.

Máy chủ A2A (giao thức A2A)

main.py được tạo mount một máy chủ A2A lên một ứng dụng FastAPI cha cũng expose /ping. Các agent Strands sử dụng Strands A2AServer; các agent LangChain bọc graph đã biên dịch trong một AgentExecutor của a2a-sdk. Khi được triển khai lên AgentCore, entry point resolve 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ông cụ hoặc system prompt. Máy chủ A2A điền agent card (/.well-known/agent-card.json) từ name và description của agent.

Máy chủ AG-UI (giao thức AG-UI)

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 kiểm tra sức khỏe của AgentCore runtime. Cách kết nối phụ thuộc vào framework:

Strands: bọc Agent của bạn trong một ag_ui_strands.StrandsAgent, được xây dựng bên trong một handler lifespan của FastAPI (để việc xây dựng xảy ra khi khởi động container/session thay vì thời gian import), và được phục vụ từ một vòng lặp /invocations FastAPI được viết thủ công.
LangChain: bọc graph đã biên dịch trong một ag_ui_langgraph.LangGraphAgent, được xây dựng theo cách tương tự bên trong lifespan, và được phục vụ từ một vòng lặp /invocations FastAPI đượ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ông cụ hoặc system prompt.

Chạy Agent của bạn

Phát triển cục bộ

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

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

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

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Điều 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 Nx target <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. Theo mặc định, nó kết nối với agent đang chạy cục bộ 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 nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

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

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

Generator tạo ra một scripts/<your-agent-name>/chat.ts cho mỗi giao thức. Nó kết nối với agent cục bộ theo mặc định, hoặc với agent đã triển khai của bạn khi RUNTIME_CONFIG_APP_ID được đặt (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 Nx target <your-agent-name>-openapi chạy nó
Một Nx target <your-agent-name>-generate-client tạo ra một TypeScript client type-safe dưới scripts/<your-agent-name>/generated/

Khi bạn tùy chỉnh input shape của agent (ví dụ: thêm trường mới vào InvokeInput), 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 hoạt động tự động.

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, đặt 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 resolve ARN runtime của agent từ cấu hình runtime và kết nối với endpoint đã triển khai:

IAM
Cognito

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

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

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

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

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

Đối với các agent được xác thực 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:

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

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

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

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

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
Terraform

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 generator, hoặc <ProjectName>Agent theo mặc định.

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');
  }
}

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

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

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
}

Docker là bắt buộc để build và triển khai Agent của bạn. Đả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

Generator cung cấp một 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ỳ đối số nào:

CDK
Terraform

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);
  }
}

# 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, generator sẽ cấu hình agent để sử dụng Cognito cho xác thực.

CDK
Terraform

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 ra bằng cách sử dụng ts#website#auth generator, hoặc bạn có thể tạo UserPool và UserPoolClient CDK của riêng mình.

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]
}

Bundle và Docker Target

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

Export các dependency Python của bạn vào file requirements.txt bằng uv export
Cài đặt các dependency 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, nó 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.

Quét Image

Docker image được xây dựng cho dự án này có thể được quét để tìm các lỗ hổng bảo mật bằng cách sử dụng Trivy, chạy từ ECR-hosted Trivy image.

Một target trivy được thêm vào dự án của bạn để quét image đã xây dựng và thoát với mã khác không nếu phát hiện bất kỳ lỗ hổng bảo mật mức độ nghiêm trọng HIGH hoặc CRITICAL nào. Dockerfile được tạo ra sử dụng một base image không có lỗ hổng bảo mật có thể sửa chữa nào ở các mức độ nghiêm trọng này tại thời điểm tạo, và nâng cấp các công cụ đi kèm (chẳng hạn như npm) để duy trì trạng thái đó.

Quá trình quét sử dụng cùng container engine với quá trình xây dựng image của bạn (docker hoặc finch), do đó không cần công cụ bổ sung nào. Vì quá trình quét chỉ được chạy lại khi image thay đổi, một image không thay đổi sẽ không được quét lại. Script root trivy được cung cấp sẽ quét mọi image trong workspace:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Quá trình quét chạy với --ignore-unfixed, do đó các lỗ hổng bảo mật không có bản sửa lỗi khả dụng sẽ không làm thất bại quá trình build, vì chúng không thể được xử lý bằng cách nâng cấp công cụ trong Dockerfile của bạn — chúng không được báo cáo trong kết quả quét của build. Khi các lỗ hổng bảo mật mới được công bố, kết quả quét có thể thay đổi theo thời gian, vì vậy hãy xem xét image định kỳ bằng cách chạy trivy image <your-image> mà không có flag này, và xây dựng lại với base image mới hơn (hoặc thêm các bước container để áp dụng các bản vá khả dụng) khi một bản sửa lỗi được phát hành.

Loại Bỏ Các Phát Hiện Của Trivy

Có thể có những trường hợp bạn muốn loại bỏ một lỗ hổng bảo mật cụ thể, ví dụ như khi chưa có bản sửa lỗi và bạn đã đánh giá rủi ro là có thể chấp nhận được.

Thêm ID lỗ hổng bảo mật (mỗi dòng một ID) vào file .trivyignore trong thư mục gốc của dự án (tức là bên cạnh project.json của bạn):

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

Để biết thêm chi tiết về việc lọc các phát hiện, hãy tham khảo tài liệu lọc của Trivy.

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 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 CloudWatch AWS Console, 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, tham khảo tài liệu AgentCore về khả năng quan sát.

Quản lý Session

Tùy chọn session ánh xạ đến một khái niệm persistence cơ bản khác nhau tùy thuộc vào framework bạn chọn: khái niệm quản lý session của Strands cho framework strands, hoặc khái niệm checkpointer của LangGraph cho framework langchain.

Tùy chọn session kiểm soát cách agent của bạn duy trì trạng thái hội thoại (lịch sử tin nhắn, trạng thái công cụ, v.v.) qua các lần gọi, sử dụng SessionManager của Strands SDK:

s3 (mặc định): Hạ tầng CDK/Terraform cung cấp một S3 bucket chuyên dụng cho dữ liệu session, được mã hóa bằng KMS key chuyên dụng và với tất cả quyền truy cập công khai bị chặn; server access log được gửi đến CloudWatch Logs log group thông qua cùng một key. IAM role của agent được cấp quyền read/write/list/delete vào bucket và quyền decrypt/generate-data-key vào key, và tên bucket được đăng ký cùng với ARN của agent trong cấu hình runtime AppConfig.
in-memory: Không có bucket nào được cung cấp. Trạng thái hội thoại chỉ được giữ trong bộ nhớ trong suốt thời gian tồn tại của process đang chạy và không tồn tại qua các lần khởi động lại hoặc scale-in.

Điều này được triển khai trong session.py được tạo, nó export một hàm get_session_manager() resolve một SessionManager cho session hiện tại.

Bản thân session ID đến từ AgentCore Runtime session (được truyền qua header x-amzn-bedrock-agentcore-runtime-session-id) và được gắn với một context dựa trên contextvars.ContextVar để get_current_session_id() có thể resolve nó ở bất kỳ đâu trong request — bao gồm trong bất kỳ MCP hoặc A2A client downstream nào được kết nối thông qua connection generator, vì vậy toàn bộ chuỗi gọi chia sẻ một session nhất quán.

Tùy chọn session kiểm soát cách checkpointer LangGraph của agent duy trì trạng thái hội thoại:

s3 (mặc định): Agent đã triển khai sử dụng một S3CheckpointSaver với session bucket được cung cấp, lưu trữ các checkpoint và pending write dưới prefix checkpoints/. Class này nằm trong s3_checkpoint_saver_langchain.py trong project agent-connection được chia sẻ.
dynamodb-s3: Hạ tầng CDK/Terraform cung cấp một DynamoDB table cho các checkpoint, được cấu hình như được khuyến nghị trong tài liệu AWS về sử dụng DynamoDB làm checkpoint store cho các agent LangGraph (schema PK/SK thống nhất, billing PAY_PER_REQUEST, point-in-time recovery, và một thuộc tính ttl), cộng với một S3 bucket để offload các checkpoint trên 350KB. Cả hai đều được mã hóa bằng KMS key chuyên dụng; server access log của bucket được gửi đến CloudWatch Logs log group thông qua cùng một key. IAM role của agent được cấp quyền read/write vào table và bucket, và tên table/bucket được đăng ký cùng với ARN của agent trong cấu hình runtime AppConfig.
in-memory: Không có table hoặc bucket nào được cung cấp. Trạng thái hội thoại chỉ được giữ trong bộ nhớ trong suốt thời gian tồn tại của process đang chạy và không tồn tại qua các lần khởi động lại hoặc scale-in.

Điều này được triển khai trong session.py được tạo, nó export một hàm get_checkpointer() được gọi từ create_agent(..., checkpointer=get_checkpointer()) của agent.py.

Gọi Agent của bạn

Gọi Máy chủ cục bộ

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

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

Gọi Agent đã triển khai

Để gọi Agent của bạn đã được 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 runtime ARN được mã hóa URL của bạn.

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

CDK
Terraform

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,
    });
  }
}

# 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 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.

Điều này rất đơn giản trong browser console 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ơ sở hạ tầng của bạn cũng có thể xuất trực tiếp URL gọi đầy đủ, với việc mã hóa ARN được xử lý sẵn cho bạn:

CDK
Terraform

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

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
Cognito

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 '{"prompt": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

Nhấp vào đây để biết thêm chi tiết về cấu hình lệnh acurl ở trên

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 '{"prompt": "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

Trình duyệt / Website React

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

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

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 nx g @aws/nx-plugin:connection --dry-run

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

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

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

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

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.

Gọi Agent A2A như một Công cụ

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

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

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 nx g @aws/nx-plugin:connection --dry-run

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

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

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

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

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.

Gọi Agent AG-UI

Để gọi agent AG-UI của bạn từ một website React, sử dụng connection generator, nó kết nối 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).

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

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 nx g @aws/nx-plugin:connection --dry-run

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

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

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

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

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.

Bảo mật Agent của bạn

Các Agent hoạt động dựa trên đầu vào không đáng tin cậy và có thể thực hiện các hành động thực tế thông qua các công cụ của chúng, vì vậy đáng để xem xét bảo mật ngay từ đầu. Các thực hành sau đây áp dụng cho agent được tạo ra.

Coi đầu vào và đầu ra của mô hình là không đáng tin cậy

Các prompt có thể chứa các hướng dẫn đối nghịch (prompt injection), và đầu ra của mô hình là không xác định — cả hai đều không nên được tin cậy trong logic nhạy cảm về bảo mật:

Định nghĩa các schema đầu vào nghiêm ngặt cho các công cụ của bạn, như trong công cụ ví dụ được tạo ra. Hạn chế các giá trị theo những gì công cụ thực sự cần (enums, giới hạn độ dài, phạm vi số) thay vì chấp nhận các chuỗi tự do.
Không bao giờ truyền đầu ra của mô hình trực tiếp vào các lệnh shell, truy vấn SQL, đánh giá mã, hoặc HTML được render mà không có xác thực hoặc mã hóa.
Áp dụng các kiểm tra ủy quyền trong các công cụ và dịch vụ downstream của bạn — đừng dựa vào system prompt để ngăn mô hình sử dụng sai một công cụ mà nó có quyền truy cập.

Các hướng dẫn Prompt Engineering và Responsible AI của Strands bao gồm việc viết các system prompt mạnh mẽ, có ý thức về an toàn.

Phạm vi quyền công cụ chặt chẽ

Chỉ cấp cho vai trò IAM của agent những quyền mà các công cụ của nó cần. Các cấu trúc CDK và mô-đun Terraform được cung cấp hiển thị các phương thức grant* và các chính sách có phạm vi cho mục đích này — ví dụ cấp cho một agent quyền truy cập để gọi một API cụ thể thay vì đính kèm các chính sách được quản lý rộng. Khi một công cụ hành động thay mặt cho người dùng, ưu tiên ủy quyền hành động bằng cách sử dụng danh tính của người dùng đang gọi (được truyền qua ngữ cảnh yêu cầu) thay vì các quyền môi trường của chính agent.

Cung cấp một công tắc tắt khẩn cấp

Bởi vì hành vi của mô hình có thể thay đổi theo những cách không mong đợi, hãy lên kế hoạch để nhanh chóng vô hiệu hóa hoặc thay đổi mô hình mà không cần thay đổi mã:

Đọc ID mô hình từ cấu hình (ví dụ một biến môi trường MODEL_ID) để các nhà vận hành có thể chuyển đổi hoặc quay lại một mô hình khác bằng cách cập nhật cấu hình.
Đặt agent phía sau một feature flag để chức năng AI của nó có thể bị vô hiệu hóa hoàn toàn. Khi bị vô hiệu hóa, trả về một thông báo chung thay vì một lỗi, và đảm bảo phần còn lại của ứng dụng của bạn giảm cấp một cách ổn định.

Ghi lại cách chuyển đổi các điều khiển này trong sổ tay vận hành của bạn.

Bảo vệ dữ liệu nhạy cảm

Tránh ghi log các prompt và completion, có thể chứa dữ liệu người dùng. Hook ghi log lỗi mô hình của agent được tạo ra chỉ ghi log metadata lỗi, không phải nội dung cuộc trò chuyện — giữ thuộc tính này khi thêm logging của riêng bạn.
Trả về các thông báo lỗi chung cho người dùng; ghi log các lỗi chi tiết ở phía máy chủ.
Cô lập trạng thái cuộc trò chuyện giữa người dùng và phiên, và ủy quyền truy cập vào bất kỳ dữ liệu phiên được lưu trữ nào.
Biên tập thông tin nhận dạng cá nhân (PII) khỏi các prompt và đầu ra — bằng bộ lọc thông tin nhạy cảm của Bedrock Guardrail (bên dưới) hoặc, đối với các agent Strands, các cách tiếp cận trong hướng dẫn PII Redaction.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails cung cấp các bộ lọc nội dung có thể cấu hình, các chủ đề bị từ chối, và các bộ lọc thông tin nhạy cảm (PII) được đánh giá trên đầu vào và đầu ra của mô hình. Bạn có thể đính kèm một guardrail vào mô hình được sử dụng bởi agent được tạo ra:

Strands
LangChain

import os

from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(
    model_id=os.environ.get("MODEL_ID"),
    guardrail_id=os.environ["GUARDRAIL_ID"],
    guardrail_version=os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
)

agent = Agent(model=model)

Xem hướng dẫn Guardrails của Strands để biết thêm chi tiết.

import os

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model=os.environ.get("MODEL_ID"),
    guardrail_config={
        "guardrailIdentifier": os.environ["GUARDRAIL_ID"],
        "guardrailVersion": os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
    },
)

Xem tài liệu ChatBedrockConverse cho các trường guardrail_config.

Kết nối

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

React to Python AgentGọi Python Agent từ một website React

React to AG-UI AgentGọi một Agent expose giao thức AG-UI từ một website React thông qua CopilotKit

Python Agent to MCPKết nối Python Agent với một MCP server

Python Agent to A2A AgentKết nối Python Agent với một agent A2A từ xa

TypeScript Agent to A2A AgentKết nối TypeScript Agent với một agent A2A từ xa

Python Agent to Python DynamoDBKết nối Python Agent với một DynamoDB table

Python Agent to AgentCore GatewayKết nối Python Agent với một AgentCore Gateway

AgentCore Gateway to AgentĐặt một agent phía trước với một AgentCore Gateway như một runtime target