本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 开始使用
您可以通过 [AgentCore CLI](https://github.com/aws/agentcore-cli) 使用该工具，也可以直接使用 Amazon 软件开发工具包，`boto3`例如。对于大多数开发者来说，CLI 是最快的途径；SDK 供您自己的应用程序编程使用。
## 先决条件
+ Amazon 在其中一个[支持的区域](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/agentcore-regions.html)中配置的凭证。
+ 对于 CLI 来说： Node.js 20\+
+ 对于 SDK/boto3：[`boto3`已安装](https://docs.amazonaws.cn/boto3/latest/guide/quickstart.html)的 Python 3.10\+，以及该工具可以扮演的 IAM 执行角色。有关最低权限，请参阅[执行角色策略](harness-security.md#harness-execution-role-policy)。
## 开始使用
**Example**
创建具有名称和执行角色的线束：
```
aws bedrock-agentcore-control create-harness \
--harness-name "MyHarness" \
--execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole"
```
投票`get-harness`直到`"status": "READY"`. 记下响应中的 `arn`。
```
aws bedrock-agentcore-control get-harness \
--harness-id "MyHarness-XyZ123"
```
从 Python 中调用。如果你没有指定型号，Amazon Bedrock 上的安全带默认为 Anthropic Claude Sonnet 4.6：
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_harness(
harnessArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-XyZ123", # Replace with your harness ARN
runtimeSessionId="1234abcd-12ab-34cd-56ef-1234567890ab",
messages=[{
"role": "user",
"content": [{"text": "Research three tropical vacation options under $3k."}]
}],
)
for event in response["stream"]:
if "contentBlockDelta" in event:
delta = event["contentBlockDelta"].get("delta", {})
if "text" in delta:
print(delta["text"], end="", flush=True)
elif "runtimeClientError" in event:
print(f"\nError: {event['runtimeClientError']['message']}")
```
安装 C AgentCore LI：
```
npm install -g @aws/agentcore
```
使用旗帜以非交互方式创建线束项目：
```
agentcore create --name myresearchagent --model-provider bedrock
```
部署并调用：
```
agentcore deploy
agentcore invoke --harness myresearchagent \
--session-id "$(uuidgen)" \
"Research three tropical vacation options under $3k, within five hours of NYC."
```
响应会流向您的终端。在调用`--session-id`之间重复使用相同的内容，以便在相同的环境中继续对话。
要向现有项目添加更多线束，请使用`agentcore add harness`。要生成独立的 Python 调用脚本，请添加`--with-invoke-script`。
有用的标志：
+ `--no-browser`(`-b`)-使用终端 TUI 代替浏览器检查器
+ `--logs`(`-l`)-在非交互模式下运行，并将日志记录到 stdout
+ `--port `(`-p`)-设置开发服务器端口（默认 8080）
+ `--no-traces`-禁用本地 OTEL 跟踪采集
安装 C AgentCore LI：
```
npm install -g @aws/agentcore
```
`agentcore create`不带标志运行以启动交互式向导：
```
agentcore create
```
1. 输入您的项目名称：
1. 选择 H **ar** ness 作为项目类型：
1. 选择您的模型提供商：
1. 选择您的环境（默认、容器 URI 或 Dockerfile）：
1. 配置内存：
1. （可选）配置高级设置（工具、身份验证、网络、生命周期、限制、截断、会话存储）：
1. 检查您的配置并确认：
确认后，向导将为您的项目搭建脚手架。使用部署`agentcore deploy`，然后使用调用`agentcore invoke`。
随时通过`agentcore status`以下方式查看项目状态：
1. 本地开发
如果你想在本地环境中测试安全带，你可以运行开发服务器：
```
agentcore dev
```
当你运行时`agentcore dev`，CLI 会首先将你的线束资源部署到 Amazon，创建 IAM 角色、线束以及在你的项目中配置的任何内存或证书：
部署完成后，它会启动本地服务器并在浏览器中打开代理检查器，您可以在其中与工具聊天、检查跟踪和浏览项目资源：
展开 **Harn** ess Settings 以查看和覆盖当前会话的线束配置：
这就是让安全带运行所需要的全部。以下各节涵盖了您可以配置的所有内容。
**注意**
`runtimeSessionId`必须至少为 33 个字符。使用 UUID 或类似的标识符。在调用之间重复使用相同的会话 ID，以便在同一环境中继续对话。
## API 文档
如需了解更多详情，请参阅 API 参考：
+ [CreateHarness API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateHarness.html)
+ [GetHarness API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_GetHarness.html)
+ [UpdateHarness API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateHarness.html)
+ [DeleteHarness API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_DeleteHarness.html)
+ [ListHarnesses API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_ListHarnesses.html)
+ [ListHarnessVersions API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_ListHarnessVersions.html)
+ [InvokeHarness API](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)
+ [InvokeAgentRuntimeCommand API](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntimeCommand.html)
+ [CreateHarnessEndpoint API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateHarnessEndpoint.html)
+ [GetHarnessEndpoint API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_GetHarnessEndpoint.html)
+ [UpdateHarnessEndpoint API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateHarnessEndpoint.html)
+ [DeleteHarnessEndpoint API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_DeleteHarnessEndpoint.html)
+ [ListHarnessesEndpoints API](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_ListHarnessesEndpoint.html)
## 流媒体响应格式
`InvokeHarness`返回事件流。关键事件类型有：
+ `messageStart`-新留言的开头（包括`role`）
+ `contentBlockStart`-内容块的开头（文本`toolUse`、或`toolResult`）
+ `contentBlockDelta`-增量内容（`text`、`toolUse`输入、`toolResult`内容、`reasoningContent`）
+ `contentBlockStop`-内容块的结尾
+ `messageStop`-消息结尾（包括`stopReason`）
+ `metadata`-代币使用情况和延迟指标
+ `hookEvent`-已配置的生命周期挂钩已触发。Lambda 挂钩事件包括已应用的决策和可选原因。参见[生命周期挂钩](harness-lifecycle-hooks.md)。
+ `runtimeClientError`-执行过程中出错
`stopReason`in `messageStop` 表示当前直播消息结束的原因：
+ `end_turn`-代理正常完成
+ `tool_use`-模型要求使用一个或多个工具。使用安全带执行的工具可以继续使用安全带。如果这是已完成响应流`messageStop`中的最后一个，则线束正在等待内联函数结果。
+ `tool_result`-安全带流式传输了一个或多个工具结果；其他模型输出可能会随之而来
+ `max_tokens`-已达到模型的每回合代币上限
+ `max_iterations_exceeded`-已达到`maxIterations`极限
+ `timeout_exceeded`-已达到`timeoutSeconds`极限
+ `max_output_tokens_exceeded`-`maxTokens` 预算已用尽
+ `hook_stopped`-`before_invocation` 或 `after_tool_call` Lambda 挂钩的`deny`决定阻止了调用