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 lên Amazon Bedrock AgentCore Runtime. Chọn framework agent bằng tùy chọn framework: Strands (mặc định) hoặc LangChain (được xây dựng trên LangGraph).

Generator hiển thị 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 frontend trực tiếp 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:

Chạy generator này@aws/nx-plugin:py#agent

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

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

Xây dựng lệnh của bạn9

projectBắt buộc

framework

authinfra = agentcore | agentcore-ecr

protocol

iac

infra

session

name

preferInstallDependencies

true

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

Tùy chọn

Tùy chọn của generator9 tùy chọn

projectBắt buộcstring: Dự án để thêm Agent vào
frameworkenumMặc định: strands: SDK agent cần sử dụng.
strandslangchain
authenuminfra = agentcore | agentcore-ecrMặc định: 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).
iamcognito
protocolenumMặc định: 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.
httpa2aag-ui
iacenumMặc định: 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.
inheritcdkterraform
infraenumMặc định: agentcore: Loại hạ tầng để lưu trữ Agent của bạn. agentcore triển khai mã của bạn dưới dạng zip tới runtime được quản lý bởi AgentCore để có chu kỳ build và deploy nhanh nhất. agentcore-ecr build và lưu trữ container image thay vào đó, để kiểm soát ở cấp độ hệ điều hành hoặc sử dụng pipeline container đã có sẵn.
agentcoreagentcore-ecrnone
sessionenumMặc định: 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.
s3dynamodb-s3in-memory
namestring: Tên của Agent của bạn (mặc định: agent)
preferInstallDependenciesbooleanMặc định: 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.

Đầu ra của Generator

Generator sẽ thêm các tệp sau vào dự án Python hiện có của bạn. Các tệp được tạo ra phụ thuộc vào protocol đã 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
    Thư mụcmiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with Strands dependencies
- project.json Updated with agent serve targets

Giao thức A2A

Điểm vào hiển thị agent của bạn qua giao thức A2A (Strands sử dụng Strands A2A Server; LangChain bọc graph trong một executor a2a-sdk), được gắn vào 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
    Thư mụcmiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py A2A server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and A2A dependencies
- project.json Updated with agent serve targets

Giao thức AG-UI

Điểm vào hiển thị agent của bạn qua giao thức AG-UI để tích hợp frontend trực tiếp 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
    Thư mụcmiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py AG-UI server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and AG-UI dependencies
- project.json Updated with agent serve targets

Hạ tầng

Tùy chọn infra chọn cách mã của bạn được đóng gói và lưu trữ trên Amazon Bedrock AgentCore Runtime:

agentcore (mặc định) sử dụng triển khai mã trực tiếp: mã đã build của bạn được đóng gói dưới dạng .zip, tải lên S3 và chạy trên runtime ngôn ngữ được quản lý bởi AgentCore. Không có container image để build, không có ECR repository để quản lý và không có image để push, điều này giúp chu kỳ build và deploy nhanh hơn đáng kể.
agentcore-ecr build một container image arm64 từ Dockerfile được cung cấp và lưu trữ nó từ registry core/asset-ecr được chia sẻ, cùng với mọi container khác trong workspace. Chọn tùy chọn này khi bạn cần kiểm soát image hệ điều hành — ví dụ để cài đặt các thư viện hệ thống gốc — hoặc khi bạn có một pipeline container đã thiết lập. Tùy chọn này cũng cung cấp thêm mục tiêu quét image Trivy (xem Image Scanning bên dưới).
none không tạo cơ sở hạ tầng nào cả, vì vậy dự án chỉ có thể chạy cục bộ.

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 tệp sau được tạo ra:

CDK
Terraform

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

Thư mụcpackages/common/terraform/src
- Thư mụcapp
  - Thư mụcagents
    Thư mục<agent-name>
    <agent-name>.tf Module for deploying your agent
- Thư mụccore
  - Thư mụcagent-core
    runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
  - Thư mụcagent-core-code (when infra is agentcore)
    runtime.tf Packages your agent’s code and delegates to agent-core
  - Thư mụcagent-core-container (when infra is agentcore-ecr)
    runtime.tf Builds and publishes your agent’s image and delegates to agent-core

Nếu bạn chọn none cho infra, không có CDK construct hay Terraform module nào được tạo ra — 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 lưu trữ để xác thực.

Kiến trúc

Khi được triển khai lên Bedrock AgentCore Runtime, mã nguồn của agent được đóng gói dưới dạng zip và chạy trong AgentCore managed 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.

Loading the diagram…

Với infra: agentcore-ecr, agent được xây dựng thành một container image, đẩy lên Amazon ECR và chạy trong AgentCore Runtime. Điều này cho phép bạn kiểm soát môi trường runtime ở cấp độ hệ điều hành, với chi phí là chu kỳ build và deploy dài hơn so với cách đóng gói zip ở trên.

Loading the diagram…

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.

Loading the diagram…

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 mô hình 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 schema đầu vào từ các type hint của bạn.

Định nghĩa công cụ, sau đó thêm nó vào danh sách tools bên trong get_agent():

Strands
LangChain

from contextlib import contextmanager

from strands import Agent, tool
from strands.hooks import HookCallback, HookProvider
from strands_tools import current_time
from my_scope_agent_connection import log_model_errors, log_tool_errors

from .session import get_session_manager


@tool
def subtract(a: int, b: int) -> int:
    return a - b


@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"


AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]


@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant with access to various tools.",
        tools=[subtract, current_time, get_weather],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

import os

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

from .session import get_checkpointer

REGION = os.environ.get("AWS_REGION", "us-east-1")
MODEL_ID = os.environ.get("MODEL_ID", "global.anthropic.claude-haiku-4-5-20251001-v1:0")


@tool
def subtract(a: int, b: int) -> int:
    """Subtract b from a."""
    return a - b


@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"


def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[subtract, get_weather],
        system_prompt="You are a helpful assistant with access to various tools.",
        checkpointer=get_checkpointer(),
    )

Strands cung cấp một bộ sưu tập các công cụ dựng sẵn thông qua gói strands-agents-tools, mà generator đã thêm vào pyproject.toml của dự án bạn. Import các công cụ bạn muốn và thêm chúng vào get_agent():

from strands_tools import current_time, file_read, http_request

# ...

@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[current_time, file_read, http_request],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

LangChain cung cấp một hệ sinh thái lớn các công cụ và tích hợp, mỗi công cụ được phân phối trong gói riêng của nó. Generator không thêm những công cụ này, vì vậy hãy cài đặt công cụ bạn cần trước — ví dụ langchain-community, nơi công cụ tìm kiếm bên dưới đến từ:

pnpm nx run <project-name>:add langchain-community

yarn nx run <project-name>:add langchain-community

npx nx run <project-name>:add langchain-community

bunx nx run <project-name>:add langchain-community

Sau đó import các công cụ và thêm chúng vào get_agent():

from langchain_community.tools import DuckDuckGoSearchRun

# ...

def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[DuckDuckGoSearchRun()],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

Cấu hình Mô hình

Strands
LangChain

Agent được tạo ra sử dụng mô hình Strands mặc định trên Amazon Bedrock. Để cấu hình nó, truyền một model vào Agent. Xem tài liệu Strands về nhà cung cấp mô hình để biết các nhà cung cấp có sẵn và các tùy chọn của chúng:

from strands.models import BedrockModel

# ...

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

@contextmanager
def get_agent():
    yield Agent(
        model=MODEL,
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[subtract, current_time],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

Các agent LangChain sử dụng mô hình ChatBedrockConverse. Agent được tạo ra đọc id mô hình và region từ các biến môi trường MODEL_ID và AWS_REGION, mà hạ tầng đặt cho agent đã triển khai. Để cấu hình mô hình thêm, thêm các đối số nơi nó được khởi tạo trong get_agent():

# ...

def get_agent():
    model = ChatBedrockConverse(
        model=MODEL_ID,
        region_name=REGION,
        temperature=0.3,
    )
    return create_agent(
        model=model,
        tools=[subtract],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

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

Chạy generator này@aws/nx-plugin:connection

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

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

Xây dựng lệnh của bạn5

sourceProjectBắt buộc

targetProjectBắt buộc

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

Đố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ề việc 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 — điểm vào 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 các tích hợp client tùy chỉnh.
A2A: Một máy chủ Agent-to-Agent được gắn vào 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 khám phá 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 frontend trực tiếp với CopilotKit trong một trang web React.

Điểm vào máy chủ khác nhau theo framework (Strands tạo ra một Agent được quản lý theo 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à như nhau.

Tất cả các giao thức đều hiển thị /ping cho hợp đồng kiểm tra sức khỏe runtime AgentCore. 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. Hạ tầng được tạo ra đã đượ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 ra bao gồm:

Thiết lập ứng dụng FastAPI với CORS middleware
Error handling middleware
Tạo schema OpenAPI
Endpoint kiểm tra sức khỏe (/ping)
Endpoint gọi agent (/invocations)

Tùy chỉnh Đầu vào và Đầu ra Invoke với Pydantic

Endpoint gọi của agent sử dụng các mô hình Pydantic để định nghĩa và xác thực schema yêu cầu và phản hồi. Bạn có thể tùy chỉnh các mô hình này trong main.py để phù hợp với yêu cầu của agent.

Định nghĩa Mô hình Đầu vào

Mô hình InvokeInput mặc định chấp nhận một prompt.

from pydantic import BaseModel, Field

class InvokeInput(BaseModel):
    prompt: str = Field(max_length=100000)

Bạn có thể mở rộng mô hình 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, nhất quán với hợp đồng session Bedrock AgentCore Runtime. Nếu header không được cung cấp, một UUID ngẫu nhiên được tạo ra như một phương án dự phòng.

Định nghĩa Mô hình Đầu ra

Đối với các phản hồi streaming, generator cung cấp JsonStreamingResponse tự động serialize các mô hình 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 ra.

Theo mặc định, agent tạo ra các đối tượng StreamChunk chứa văn bản phản hồi của agent:

class StreamChunk(BaseModel):
    content: str

Bạn có thể tùy chỉnh mô hình 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 tại không hỗ trợ tạo đặc tả OpenAPI cho các phản hồi streaming, chúng ta phải đặt rõ ràng mô hình phản hồi 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ở để hỗ trợ gốc trong FastAPI.

Bedrock AgentCore Python SDK

Generator bao gồm một phụ thuộc vào Bedrock AgentCore Python SDK cho các hằng số PingStatus. Nếu muốn, bạn có thể dễ dàng sử dụng BedrockAgentCoreApp thay vì FastAPI, tuy nhiên lưu ý rằng tính an toàn kiểu 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.

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

main.py được tạo ra gắn một máy chủ A2A vào một ứng dụng FastAPI cha cũng hiển thị /ping. Các agent Strands sử dụng A2AServer của Strands; các agent LangChain bọc graph đã biên dịch trong một AgentExecutor của a2a-sdk. URL được quảng cáo trong agent card đến từ biến môi trường AGENTCORE_RUNTIME_URL, quay lại http://localhost:<port>/ cho phát triển cục bộ.

Hầu hết người dùng sẽ không cần sửa đổi tệp này; chỉnh sửa agent.py để thay đổi công cụ hoặc system prompt. Máy chủ A2A điền vào 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 ra hiển thị một endpoint POST duy nhất streaming các sự kiện AG-UI qua Server-Sent Events (SSE), cũng như /ping cho kiểm tra sức khỏe runtime AgentCore. 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 FastAPI lifespan (để việc khởi tạo xảy ra khi container/session khởi động thay vì lúc import), và được phục vụ từ một vòng lặp FastAPI /invocations tự tạo.
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 FastAPI /invocations tự tạo.

Hầu hết người dùng sẽ không cần sửa đổi tệp 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ứ kết nối với nó) cục bộ, sử dụng target dev của dự án:

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 thành phần vào dự án 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 vào 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.

Agent lắng nghe trên một cổng được gán từ pool workspace khi nó được tạo ra. Đọc nó từ metadata.ports trong project.json của dự án, hoặc từ cờ --port trong lệnh của target <your-agent-name>-dev. Các ví dụ dưới đây sử dụng 8081, cổng mà một agent HTTP đầu tiên được gán trong một workspace mới.

Một target <your-agent-name>-serve cũng được tạo ra, chạy agent đối với hạ tầng đã triển khai của bạn và do đó yêu cầu RUNTIME_CONFIG_APP_ID được đặt. Xem hướng dẫn Phát triển Cục bộ để biết sự khác biệt giữa dev và serve.

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 phiên chat terminal 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 an toàn kiểu được tạo ra từ đặc tả OpenAPI của agent. Generator cũng tạo ra:

scripts/<your_agent_name>_openapi.py — một script nhỏ xuất đặc tả OpenAPI của agent (được đặt tên với tên agent của bạn trong snake_case)
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 an toàn kiểu dưới scripts/<your-agent-name>/generated/

Khi bạn tùy chỉnh hình dạng đầu vào 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 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 id ứng dụng AppConfig của việc triển khai (được xuất ra là RuntimeConfigApplicationId bởi stack đã triển khai). Script chat giải quyết 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 bằng IAM, các yêu cầu đượ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 bằng Cognito, cung cấp Cognito access token qua biến môi trường AGENT_ACCESS_TOKEN, được gửi như một 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 hoặc agentcore-ecr 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, cùng với shared artefact store mà packaging của nó sử dụng. Với packaging agentcore mặc định, code của agent được staged trong shared asset bucket, vì vậy hãy khởi tạo module core/asset-bucket một lần cho mỗi deployment, như các Lambda và API modules đã làm:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

Với agentcore-ecr, image của agent được publish lên shared asset registry thay vì bucket, vì vậy hãy truyền các outputs của core/asset-ecr thay vì của bucket. Một registry phục vụ mọi container trong workspace, vì vậy không agent nào cần repository riêng của mình:

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

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

  asset_ecr_repository_url = module.asset_ecr.repository_url
  asset_ecr_repository_arn = module.asset_ecr.repository_arn
}

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

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# 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

  # Under `agentcore-ecr`, pass `core/asset-ecr`'s outputs instead.
  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_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 Targets

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

Xuất các phụ thuộc Python của bạn sang tệp requirements.txt bằng uv export
Cài đặt các phụ thuộc cho nền tảng đích (aarch64-manylinux_2_28) bằng uv pip install

Một target <your-agent-name>-package cũng được thêm vào, tập hợp gói mã có thể triển khai: bundle phụ thuộc aarch64, cây module Python của bạn, và một điểm vào main.py gốc. Hạ tầng được tạo ra tải thư mục này lên dưới dạng .zip — thông qua AgentRuntimeArtifact.fromCodeAsset dưới CDK, hoặc được lưu trữ vào shared asset bucket dưới Terraform.

Một target docker dành riêng 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ị trí với đầu ra đã 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. Quá trình quét không được cache, vì image mà nó đọc tồn tại trong container engine thay vì trên đĩa — do đó nó luôn quét image thực tế, và thất bại rõ ràng thay vì báo cáo kết quả pass đã được cache cho một image không còn tồn tại. Do đó, mỗi lần chạy mất hàng chục giây cho mỗi image và làm mới cơ sở dữ liệu lỗ hổng bảo mật của Trivy, vì vậy nó cần truy cập mạng. 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 cách sử dụng AWS Distro for Open Telemetry (ADOT).

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 vào, 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 lưu trữ 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 lưu 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 một CloudWatch Logs log group qua cùng key. IAM role của agent được cấp quyền đọc/ghi/liệt kê/xóa 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 tiến trình đ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 ra, xuất một hàm get_session_manager() giải quyết một SessionManager cho session hiện tại.

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

Hạn chế session cho chủ sở hữu của chúng

Session ID đến từ người gọi, vì vậy bản thân nó xác định một cuộc hội thoại nhưng không xác định cuộc hội thoại thuộc về ai. AgentCore Runtime ủy quyền một lần gọi đối với ARN tài nguyên runtime agent thay vì đối với một session riêng lẻ, điều này để agent tự do quyết định session có ý nghĩa gì đối với ứng dụng của bạn.

Để hạn chế mỗi người dùng chỉ có thể truy cập các cuộc hội thoại của riêng họ:

Thêm một API để tạo session, sử dụng tRPC, FastAPI hoặc Smithy. Tạo một session ID không rõ ràng (ít nhất 33 ký tự) và lưu trữ nó cùng với ID người dùng đang gọi — ví dụ trong một bảng được tạo bằng generator py#dynamodb. Mỗi hướng dẫn API cho biết cách lấy ID người dùng đang gọi.
Trong agent của bạn, tra cứu ID người dùng đã lưu trữ cho session ID mà nó được cung cấp, và từ chối yêu cầu khi nó không khớp với người gọi. Với auth=cognito, JWT của người gọi đến mã agent của bạn, vì vậy claim sub của nó xác định họ.

Tạo session ID thay vì lấy nó từ các giá trị do người dùng cung cấp như tên cuộc hội thoại — bất cứ thứ gì người gọi có thể dự đoán, người gọi có thể gửi.

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

s3 (mặc định): Agent đã triển khai sử dụng S3CheckpointSaver với session bucket đã cung cấp, lưu trữ các checkpoint và pending write dưới tiền tố checkpoints/. Class này nằm trong s3_checkpoint_saver_langchain.py trong dự án agent-connection dùng chung.
dynamodb-s3: Hạ tầng CDK/Terraform cung cấp một bảng DynamoDB cho các checkpoint, được cấu hình theo 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, thanh toán PAY_PER_REQUEST, point-in-time recovery, và 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 một CloudWatch Logs log group qua cùng key. IAM role của agent được cấp quyền đọc/ghi vào bảng và bucket, và tên bảng/bucket được đăng ký cùng với ARN của agent trong cấu hình runtime AppConfig.
in-memory: Không có bảng hay 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 tiến trình đ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 ra, xuất 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ộ

Khởi động agent của bạn với target <your-agent-name>-dev:

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 đó gửi một yêu cầu POST đến /invocations trên cổng mà agent cục bộ của bạn đang chạy. Thay thế cổng được gán cho agent của bạn — đọc nó từ metadata.ports trong project.json của dự án, hoặc từ cờ --port trong lệnh của target <your-agent-name>-dev. Một agent HTTP đầu tiên trong một workspace mới được gán 8081:

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, yêu cầu 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'

Click here for more details on configuring the above acurl command

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 / Trang web React

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

Chạy generator này@aws/nx-plugin:connection

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

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

Xây dựng lệnh của bạn5

sourceProjectBắt buộc

targetProjectBắt buộc

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

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

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

Chạy generator này@aws/nx-plugin:connection

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

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

Xây dựng lệnh của bạn5

sourceProjectBắt buộc

targetProjectBắt buộc

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

Gọi một AG-UI Agent

Để gọi AG-UI agent của bạn từ một trang web React, sử dụng generator connection, 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 đúng (IAM hoặc Cognito).

Chạy generator này@aws/nx-plugin:connection

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

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

Xây dựng lệnh của bạn5

sourceProjectBắt buộc

targetProjectBắt buộc

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

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