AgentCore Harness

Tạo một dự án Amazon Bedrock AgentCore Harness. Harness là một vòng lặp agent được quản lý, được hỗ trợ bởi Strands Agents: nó sở hữu các giá trị mặc định triển khai cho model, system prompt, tools, memory, skills, environments, truncation, authorization và execution limits, trong khi dịch vụ chấp nhận các ghi đè theo từng lần gọi cho các trường được hỗ trợ. Sử dụng lại cùng một Runtime Session ID sẽ tiếp tục cùng một phiên Harness.

Cách sử dụng

pnpm nx g @aws/nx-plugin:agentcore-harness

yarn nx g @aws/nx-plugin:agentcore-harness

npx nx g @aws/nx-plugin:agentcore-harness

bunx nx g @aws/nx-plugin:agentcore-harness

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:agentcore-harness --dry-run

yarn nx g @aws/nx-plugin:agentcore-harness --dry-run

npx nx g @aws/nx-plugin:agentcore-harness --dry-run

bunx nx g @aws/nx-plugin:agentcore-harness --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 - agentcore-harness
Đ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ả
name Bắt buộc	string	-	Tên của dự án AgentCore Harness của bạn. Phải chứa ít nhất một ký tự không phải khoảng trắng có thể được chuẩn hóa thành tên dự án dạng kebab-case (ví dụ: my-harness).
directory	string	-	Thư mục cha nơi đặt dự án harness. Mặc định là packages. Phải là đường dẫn tương đối không chứa các phân đoạn thư mục cha (..).
subDirectory	string	-	Thư mục con nơi đặt dự án. Mặc định là tên harness dạng kebab-case. Phải là đường dẫn tương đối không chứa các phân đoạn thư mục cha (..).
infra	agentcore \| none	agentcore	Loại hạ tầng cần tạo để lưu trữ harness của bạn. Mặc định là agentcore. Chọn none để không có lưu trữ.
iac	inherit \| cdk \| terraform	inherit	Nhà cung cấp IaC ưu tiên cho hạ tầng harness được tạo. Mặc định là inherit, sử dụng nhà cung cấp đã được cấu hình cho workspace của bạn.
preferInstallDependencies	boolean	-	Có nên ưu tiên cài đặt dependencies sau khi generator chạy hay không. Mặc định là true. Đặt thành false để hoãn cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn chạy nếu cần thiết để các generator tiếp theo có thể tính toán project graph của Nx); cài đặt một lần ở cuối.

Đầu ra của Generator

Generator tạo một dự án độc lập tại packages/<name>/. Vì AWS chạy vòng lặp agent cho bạn, dự án chỉ chứa prompt định hình nó và một script để giao tiếp với nó:

Thư mụcpackages/<name>/
- src/PROMPT.md The Harness system prompt
- scripts/chat.ts Multi-turn chat client for the deployed Harness
- project.json Adds the chat target
- README.md Chat and customization instructions

Hạ tầng

Hạ tầng được tạo khi infra là agentcore (mặc định). Với infra: none, không có hạ tầng nào được tạo — đặt HARNESS_ARN để gọi một Harness được quản lý ở nơi khác, và chạy lại generator với infra: agentcore sau để thêm hạ tầng; các tệp dự án hiện có (bao gồm các chỉnh sửa của bạn) được bảo toàn.

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

CDK
Terraform

Thư mụcpackages/common/constructs/src/app/harnesses/<name>/
- <name>.ts CDK construct containing the Harness and execution role

Hạ tầng được tạo quản lý Harness thông qua tài nguyên gốc (CDK aws_bedrockagentcore.CfnHarness, Terraform aws_bedrockagentcore_harness) với các giá trị mặc định được tạo của bạn, tạo một IAM execution role với các quyền cơ bản được mô tả bên dưới, và sử dụng IAM inbound authorization (không có custom JWT authorizer nào được cấu hình theo mặc định).

Harness ARN được đăng ký tại agentcore.harnesses.<ClassName> trong Runtime Configuration, bảo toàn mọi mục hiện có.

Triển khai AgentCore Harness của bạn

Generator tạo CDK hoặc Terraform infrastructure as code dựa trên nhà cung cấp iac bạn đã chọn. Bạn có thể sử dụng điều này để triển khai Harness của mình thông qua quy trình hạ tầng thông thường của bạn.

CDK
Terraform

CDK construct để triển khai Harness của bạn nằm trong thư mục common/constructs. Khởi tạo nó từ một ứng dụng CDK:

import { MyHarness } from '@my-scope/common-constructs';
import { Stack, type StackProps } from 'aws-cdk-lib';
import type { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyHarness(this, 'MyHarness');
  }
}

Giao diện props của construct (MyHarnessProps) mở rộng Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>, vì vậy bất kỳ thuộc tính Harness gốc nào cũng có thể được cung cấp và được ưu tiên hơn các giá trị mặc định được tạo:

const harness = new MyHarness(this, 'MyHarness', {
  maxIterations: 20,
  timeoutSeconds: 600,
});

Construct cũng chấp nhận:

allowedTools — các công cụ mà Harness có thể sử dụng. Harness triển khai mà không có công cụ nào trừ khi bạn cung cấp chúng, xem Configuring tools.
executionRole — một IAM role hiện có để sử dụng thay vì role được tạo. Một role được cung cấp được sử dụng nguyên trạng: các quyền cơ bản không được thêm vào nó, và ARN của nó luôn cung cấp cho Harness (chuỗi executionRoleArn thô không thể bị ghi đè).
modelResourceArns — các ARN của Bedrock model và inference-profile mà execution role được tạo có thể gọi, thay thế danh sách mặc định.
vpc, vpcSubnets và securityGroups — chạy Harness trong một VPC để nó có thể tiếp cận các tài nguyên riêng tư, xem Running in a VPC.

Các thành viên công khai của nó là harness (CfnHarness), executionRole, grantPrincipal, getter harnessArn, connections (trong một VPC), addToRolePolicy(statement) cho các mở rộng execution role, và grantInvokeAccess(grantee) để ủy quyền cho người gọi.

Triển khai stack với dự án hạ tầng của bạn như thường lệ — xem hướng dẫn hạ tầng CDK.

Module Terraform để triển khai Harness của bạn nằm trong thư mục common/terraform. Tham chiếu nó từ một cấu hình Terraform:

module "my_harness" {
  source = "../../common/terraform/src/app/harnesses/my-harness"
}

Module hiển thị ba biến:

model_id — Bedrock model hoặc inference profile mà Harness sử dụng theo mặc định.
model_resource_arns — các ARN của Bedrock model và inference-profile mà execution role có thể gọi, thay thế danh sách mặc định.
additional_execution_role_policy_statements — một danh sách các đối tượng IAM statement (Effect, Action, Resource, Sid và Condition tùy chọn) được thêm vào execution role policy.

Mọi thứ khác được cấu hình trên tài nguyên aws_bedrockagentcore_harness được tạo trong chính module.

Module xuất ra harness_id, harness_arn, và execution_role_arn.

Triển khai với quy trình plan/apply của dự án Terraform của bạn như thường lệ — xem hướng dẫn dự án Terraform.

Cấp quyền truy cập để gọi harness

Bạn có thể cấp cho người gọi quyền để gọi harness như sau:

CDK
Terraform

const harness = new MyHarness(this, 'MyHarness');

harness.grantInvokeAccess(caller);

# Attach to the calling principal's role
resource "aws_iam_role_policy" "invoke_my_harness" {
  name = "InvokeMyHarness"
  role = aws_iam_role.caller.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeHarness",
        "bedrock-agentcore:InvokeAgentRuntime",
      ]
      Resource = [module.my_harness.harness_arn]
    }]
  })
}

Người gọi cần cả bedrock-agentcore:InvokeHarness và bedrock-agentcore:InvokeAgentRuntime trên Harness ARN, đó chính xác là những gì grantInvokeAccess cấp.

Trò chuyện với Harness của bạn

Target chat được tạo chạy scripts/chat.ts, đưa bạn vào một cuộc trò chuyện terminal tương tác với Harness đã triển khai của bạn:

pnpm nx run <project>:chat

yarn nx run <project>:chat

npx nx run <project>:chat

bunx nx run <project>:chat

Mỗi lượt của một lần chạy chia sẻ một phiên, vì vậy Harness giữ ngữ cảnh cuộc trò chuyện cho đến khi bạn thoát. Thông tin xác thực đến từ chuỗi nhà cung cấp thông tin xác thực AWS SDK tiêu chuẩn, và AWS Region được lấy từ Harness ARN.

Harness ARN được giải quyết theo thứ tự này:

HARNESS_ARN (không rỗng): được sử dụng trực tiếp, không đọc Runtime Configuration:

HARNESS_ARN=<harness-arn> pnpm nx run <project>:chat

HARNESS_ARN=<harness-arn> yarn nx run <project>:chat

HARNESS_ARN=<harness-arn> npx nx run <project>:chat

HARNESS_ARN=<harness-arn> bunx nx run <project>:chat

RUNTIME_CONFIG_APP_ID: giải quyết ARN từ mục agentcore.harnesses.<ClassName> được xuất bản bởi hạ tầng đã triển khai:

RUNTIME_CONFIG_APP_ID=<application-id> pnpm nx run <project>:chat

RUNTIME_CONFIG_APP_ID=<application-id> yarn nx run <project>:chat

RUNTIME_CONFIG_APP_ID=<application-id> npx nx run <project>:chat

RUNTIME_CONFIG_APP_ID=<application-id> bunx nx run <project>:chat

Nếu không đặt cả hai, script sẽ thất bại với lỗi nêu tên cả hai tùy chọn.

Tùy chỉnh Harness của bạn

src/PROMPT.md là system prompt của Harness: chỉnh sửa nó và triển khai lại để thay đổi cách Harness hoạt động. Mọi thứ khác được cấu hình nơi bạn khởi tạo hạ tầng, hoặc bằng cách chỉnh sửa construct hoặc module được tạo trực tiếp. Chạy lại generator không bao giờ ghi đè các tệp hiện có (nó chỉ thêm các tệp bị thiếu và hợp nhất metadata dự án), vì vậy các chỉnh sửa của bạn đối với prompt và hạ tầng được tạo được bảo toàn.

CDK
Terraform

Mọi thuộc tính Harness gốc của module aws-cdk-lib/aws-bedrockagentcore được ghim đều có sẵn thông qua props của construct — các nhà cung cấp model thay thế, định nghĩa công cụ, memory, skills, cấu hình environment, truncation, custom JWT authorization và execution limits — và các props rõ ràng được ưu tiên hơn các giá trị mặc định được tạo. Ngoài ra, chỉnh sửa construct được tạo trong packages/common/constructs/src/app/harnesses/<name>/<name>.ts.

Module được tạo giữ tài nguyên aws_bedrockagentcore_harness gốc có thể chỉnh sửa trực tiếp, vì vậy các trường gốc của nhà cung cấp — các nhà cung cấp model thay thế (gemini_model_config, openai_model_config), các khối tool, memory, các khối skill, environments (environment, environment_variables, environment_artifact), truncation, và authorizer_configuration với custom_jwt_authorizer — được cấu hình bằng cách chỉnh sửa packages/common/terraform/src/app/harnesses/<name>/<name>.tf.

Bỏ qua cấu hình authorizer (mặc định) có nghĩa là IAM inbound authorization; cấu hình custom JWT authorizer thông qua trường gốc để thay đổi điều đó.

Cấu hình công cụ

Harness triển khai mà không có công cụ nào, vì vậy nó bắt đầu với khả năng tối thiểu. Chọn tham gia các công cụ mà nó có thể sử dụng:

CDK
Terraform

new MyHarness(this, 'Harness', { allowedTools: ['@builtin'] });

resource "aws_bedrockagentcore_harness" "this" {
  # ...
  allowed_tools = ["@builtin"]
}

Thêm một biến allowed_tools vào module nếu bạn muốn đặt nó làm đối số module nơi bạn tham chiếu module.

Thu hẹp @builtin thành các mẫu cụ thể như @builtin/file_operations để hạn chế những gì vòng lặp agent có thể làm. Xem Harness tools cho các công cụ tích hợp sẵn mà bạn có thể thêm.

Chạy trong một VPC

CDK
Terraform

Cung cấp một vpc để chạy Harness bên trong nó, để nó có thể tiếp cận các tài nguyên riêng tư như cơ sở dữ liệu. Construct triển khai IConnectable, vì vậy các tài nguyên đó cấp quyền truy cập cho nó theo cách tương tự như bất kỳ tài nguyên nào khác:

const harness = new MyHarness(this, 'MyHarness', { vpc });

database.connections.allowDefaultPortFrom(harness, 'Harness to database');

Harness được đặt trong các subnet riêng tư của VPC với egress, trong một security group được tạo cho nó. Ghi đè một trong hai với vpcSubnets và securityGroups. Cả hai đều yêu cầu vpc, và connections chỉ khả dụng khi Harness chạy trong một VPC.

Thêm một khối network_configuration vào environment.agent_core_runtime_environment của tài nguyên aws_bedrockagentcore_harness được tạo, sau đó tham chiếu security group mà bạn đặt nó vào từ các quy tắc của các tài nguyên khác của bạn:

resource "aws_security_group" "harness" {
  vpc_id = var.vpc_id
}

resource "aws_bedrockagentcore_harness" "this" {
  # ...
  environment {
    agent_core_runtime_environment {
      network_configuration {
        network_mode = "VPC"
        network_mode_config {
          security_groups = [aws_security_group.harness.id]
          subnets         = var.subnet_ids
        }
      }
    }
  }
}

Ghi đè theo từng lần gọi

Các giá trị được cấu hình trong hạ tầng là các giá trị mặc định triển khai. Dịch vụ cũng chấp nhận các ghi đè theo từng lần gọi cho các trường Harness được hỗ trợ (như models, tools và skills) trong yêu cầu InvokeHarness; các giá trị mặc định triển khai áp dụng bất cứ nơi nào một trường không bị ghi đè.