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

Tạo một AgentCore Harness

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

CLI
VSCode

$ 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

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

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

nameBắt buộc

Tùy chọn

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

nameBắt buộcstring: 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).
directorystring: 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 (..).
subDirectorystring: 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 (..).
infraenumMặc định: 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ữ.
agentcorenone
iacenumMặc định: 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.
inheritcdkterraform
preferInstallDependenciesboolean: 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
- tsconfig.json TypeScript configuration used by the typecheck target
- project.json Adds the chat, build, lint, format and typecheck targets
- 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. Mặc định là không có, 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ị các biến sau:

model_id — Bedrock model hoặc inference profile mà Harness sử dụng theo mặc định.
allowed_tools — các công cụ mà Harness có thể sử dụng. Mặc định là không có, xem Configuring tools.
memory — cấu hình memory của Harness, xem Configuring memory.
environment_variables, max_iterations, timeout_seconds — các trường Harness gốc tương ứng.
execution_role_arn — 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ả role và baseline policy của nó đều không được tạo, vì vậy model_resource_arns và additional_execution_role_policy_statements không thể kết hợp với nó.
model_resource_arns — 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.
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 được tạo.
enable_vpc, vpc_id, subnet_ids — 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.
tags — các tag được áp dụng cho các tài nguyên mà module tạo ra.

Các trường gốc khác của nhà cung cấp được cấu hình bằng cách chỉnh sửa tài nguyên aws_bedrockagentcore_harness được tạo trong chính module, xem Customizing your Harness.

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

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.

Các biến của module bao gồm các trường mà hầu hết các triển khai cấu hình — model_id, allowed_tools, memory, environment_variables, max_iterations, timeout_seconds — cộng với execution role và vị trí VPC. Terraform không có tương đương với prop spread của CDK construct, vì vậy các trường gốc còn lại của nhà cung cấp được cấu hình bằng cách chỉnh sửa tài nguyên aws_bedrockagentcore_harness trong packages/common/terraform/src/app/harnesses/<name>/<name>.tf: các nhà cung cấp model thay thế (gemini_model_config, openai_model_config), các khối tool, các khối skill, environment_artifact, cấu hình filesystem và lifecycle trong environment, truncation, và authorizer_configuration với custom_jwt_authorizer.

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

module "my_harness" {
  source        = "../../common/terraform/src/app/harnesses/my-harness"
  allowed_tools = ["@builtin"]
}

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.

Cấu hình memory

Dịch vụ cung cấp managed memory cho Harness theo mặc định, và execution role được tạo được cấp quyền truy cập vào nó — giới hạn trong memory ARN mà dịch vụ chỉ định, và chỉ được cấp trong khi Harness sử dụng managed memory mà hạ tầng đã tạo. Cấu hình memory một cách rõ ràng để điều chỉnh managed memory đó, trỏ Harness đến một tài nguyên memory bạn sở hữu, hoặc tắt memory:

CDK
Terraform

new MyHarness(this, 'MyHarness', {
  memory: { managedMemoryConfiguration: { strategies: ['SUMMARIZATION'] } },
});

Cung cấp memory sẽ thay thế managed memory mặc định, vì vậy construct bỏ qua memory grant khỏi execution role: thêm bất cứ thứ gì mà cấu hình cần với addToRolePolicy.

module "my_harness" {
  source = "../../common/terraform/src/app/harnesses/my-harness"
  memory = {
    managed_memory_configuration = {
      strategies = ["SUMMARIZATION"]
    }
  }
}

Đặt chính xác một trong managed_memory_configuration (điều chỉnh managed memory của dịch vụ), agentcore_memory_configuration (sử dụng tài nguyên memory bạn sở hữu, theo ARN) hoặc disabled (không có memory). Chọn agentcore_memory_configuration hoặc disabled sẽ loại bỏ managed-memory grant khỏi execution role; đối với tài nguyên memory của riêng bạn, cấp quyền truy cập thông qua additional_execution_role_policy_statements.

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.

Đặt enable_vpc cùng với vpc_id và subnet_ids để chạy Harness bên trong một VPC, để nó có thể tiếp cận các tài nguyên riêng tư như cơ sở dữ liệu:

module "my_harness" {
  source     = "../../common/terraform/src/app/harnesses/my-harness"
  enable_vpc = true
  vpc_id     = var.vpc_id
  subnet_ids = var.private_subnet_ids
}

Module tạo một security group cho Harness, chỉ cho phép outbound HTTPS. Đầu ra security_group_id của nó là những gì các tài nguyên mà Harness phải tiếp cận tham chiếu trong các quy tắc ingress của riêng chúng:

resource "aws_vpc_security_group_ingress_rule" "harness_to_database" {
  security_group_id            = aws_security_group.database.id
  referenced_security_group_id = module.my_harness.security_group_id
  from_port                    = 5432
  to_port                      = 5432
  ip_protocol                  = "tcp"
  description                  = "Harness to database"
}

security_group_id là null trừ khi enable_vpc là true, và vpc_id và subnet_ids đều được yêu cầu khi nó là true.

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 đè.