Python Strands Agent

Tạo một Python Strands Agent để xây dựng các AI agent với các công cụ, và tùy chọn triển khai nó lên Amazon Bedrock AgentCore Runtime. Mặc định, generator sử dụng FastAPI để expose một HTTP server. Ngoài ra, bạn có thể chọn giao thức Agent-to-Agent (A2A) để tương tác với các agent tương thích A2A khác, hoặc giao thức AG-UI để tích hợp trực tiếp với frontend thông qua CopilotKit.

Strands là gì?

Strands là một framework Python nhẹ, sẵn sàng cho production để xây dựng các AI agent. Các tính năng chính bao gồm:

• Nhẹ và có thể tùy chỉnh: Vòng lặp agent đơn giản không cản trở bạn
• Sẵn sàng cho production: Khả năng quan sát đầy đủ, theo dõi và các tùy chọn triển khai cho quy mô lớn
• Không phụ thuộc vào model và provider: Hỗ trợ nhiều model khác nhau từ các provider khác nhau
• Công cụ được cộng đồng đóng góp: Bộ công cụ mạnh mẽ do cộng đồng đóng góp
• Hỗ trợ đa agent: Các kỹ thuật nâng cao như nhóm agent và agent tự động
• Chế độ tương tác linh hoạt: Hỗ trợ hội thoại, streaming và non-streaming

Cách sử dụng

Tạo một Strands Agent

Bạn có thể tạo một Python Strands 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#strands-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#strands-agent

yarn

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

npm

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

bun

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:py#strands-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 Strands 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 Strands Agent vào
computeType	string	BedrockAgentCoreRuntime	Loại compute để host Strands Agent của bạn.
name	string	-	Tên của Strands Agent của bạn (mặc định: agent)
auth	string	IAM	Phương thức được sử dụng để xác thực với Strands Agent của bạn. Chọn giữa IAM (mặc định) hoặc Cognito.
protocol	string	HTTP	Giao thức máy chủ cho Strands 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.
iacProvider	string	Inherit	Nhà cung cấp IaC ưa thích. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.

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:

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 computeType đượ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

A2A Protocol

Khi protocol được đặt thành A2A, entry point sử dụng Strands A2A Server thay vì 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 computeType đượ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

AG-UI Protocol

Khi protocol được đặt thành AG-UI, entry point sử dụng tích hợp ag-ui-strands, 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:

• 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 sử dụng ag-ui-strands
      • Dockerfile Entry point để host agent của bạn (bị loại trừ khi computeType được đặt thành None)
  • pyproject.toml Được cập nhật với các dependencies của Strands 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

Triển khai serverless

Nếu bạn chọn None cho computeType, generator sẽ không tạo bất kỳ infrastructure as code nào.

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

Làm việc với Strands Agent của bạ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. Framework Strands sử dụng phương pháp dựa trên decorator đơn giản để định nghĩa các công cụ.

Bạn có thể thêm các công cụ mới trong file agent.py:

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

Framework Strands tự động xử lý:

• Xác thực kiểu dựa trên type hints của hàm
• Tạo JSON schema cho tool calling
• Xử lý lỗi và định dạng response

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

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

Cấu hình Model

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)

Sử dụng MCP Servers

Bạn có thể thêm các công cụ từ MCP servers vào Strands agent của bạn.

Để 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.

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, vui lòng tham khảo Tài liệu Strands.

Thêm nữa

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

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: Strands A2A Server được mount lên một ứng dụng FastAPI. 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: Tích hợp ag-ui-strands, expose giao thức AG-UI qua SSE. Tốt nhất cho tích hợp trực tiếp với frontend thông qua CopilotKit trong React website.

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.

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.

A2A Server (A2A protocol)

Khi protocol=A2A, file main.py được tạo mount A2AServer.to_fastapi_app() lên một ứng dụng FastAPI cha cũng expose /ping. 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ác công cụ hoặc system prompt. A2A server điền thông tin agent card (/.well-known/agent-card.json) từ name và description trong constructor của Agent.

AG-UI Server (AG-UI protocol)

Khi protocol=AG-UI, file main.py được tạo wrap Strands Agent của bạn trong một ag_ui_strands.StrandsAgent và tạo một ứng dụng FastAPI thông qua create_strands_app(). Ứng dụng kết quả 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.

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 Strands Agent của bạn

Phát triển Local

Generator cấu hình một target có tên <your-agent-name>-serve, khởi động Strands Agent của bạn locally để phát triển và kiểm thử.

pnpm

pnpm nx agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

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

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

Infrastructure as Code

Nếu bạn đã chọn BedrockAgentCoreRuntime cho computeType, 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 Strands 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 Alpha

Construct này sử dụng module @aws-cdk/aws-bedrock-agentcore-alpha.

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.

Bạn có thể sử dụng module terraform này trong một dự án 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"
}

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 Strands 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 Strands 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, Strands 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"
}

Để 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#react-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"

  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.

Bundle và Docker Targets

Để build Strands 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 Strands 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 Strands Agent của bạn

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

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.

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

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

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.