本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 型号和说明书 使用模型、系统提示、工具、内存和执行限制的默认值定义一次。当你想进行实验时，只需一次调用即可覆盖其中任何一个。线束资源保持不变；只有该调用使用覆盖。 这是基于配置的模型的核心：**创建时的默认值，在调用时重写**。您可以在重新部署一次所需的时间内测试 N model/prompt /tool 组合。 **Example** 默认为`create-harness`： ``` aws bedrock-agentcore-control create-harness \ --harness-name "research-agent" \ --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \ --system-prompt '[{"text": "You are a research assistant."}]' \ --tools '[{"type": "agentcore_browser", "name": "browser"}]' ``` 每次调用的重写次数： ``` response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, # These apply only to this call; the harness defaults stay intact model={"bedrockModelConfig": {"modelId": "us.anthropic.claude-opus-4-5-20251101-v1:0"}}, systemPrompt=[{"text": "You are a terse research assistant. One paragraph answers only."}], tools=[ {"type": "agentcore_browser", "name": "browser"}, {"type": "agentcore_code_interpreter", "name": "code_interpreter"}, ], messages=[{"role": "user", "content": [{"text": "Summarize this paper as a bullet list."}]}], ) ``` 要永久更改默认值，请使用`update-harness`。 在创建或更新线束时设置默认值： ``` # Create an empty project if one does not already exist agentcore create --project-name ResearchAgentProject --no-agent cd ResearchAgentProject # Add a harness to the project agentcore add harness \ --name research-agent \ --model-id us.anthropic.claude-sonnet-4-6 \ --system-prompt "You are a research assistant." \ --tools agentcore_browser agentcore deploy ``` 在调用时覆盖： ``` # Switch the model for one call agentcore invoke --harness research-agent \ --model-id us.anthropic.claude-opus-4-5-20251101-v1:0 \ "Summarize this research paper" # Swap tools for one call agentcore invoke --harness research-agent \ --tools agentcore_browser,agentcore_code_interpreter \ "Plot the citation counts as a bar chart" ``` 在调用时可重写：`--model-id`、、`--tools`、`--system-prompt`、`--max-iterations`、`--max-tokens`、、`--harness-timeout``--skills`、`--allowed-tools`。`--actor-id`添加`--verbose`以打印原始流式传输 JSON 事件以进行调试。 要永久更改默认值，请编辑`app//harness.json`并运行`agentcore deploy`。 在项目目录`agentcore`中运行以打开 TUI，选择**添加，然后选择 H** arness **。**该向导将逐步引导您完成模型和指令配置。 1. 选择您的模型提供商。支持 Amazon Bedrock、OpenAI、Google Gemini 和 LiteLLM-compatible 任何提供商，每个提供商都有默认模型。 ![添加线束向导：选择模型提供商](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/images/tui/harness-model-01-provider.png) 1. 选择 API 格式。**对于 Amazon Bedrock 和 OpenAI，**请选择 “匡威**直播”（默认）**、** “回复” 或 “聊天完成”。**回复和聊天完成由 Bedrock Mantle 提供。 ![添加线束向导：选择 API 格式](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/images/tui/harness-model-03-api-format.png) 1. 如果您选择 **LitelLM**，向导会提示您输入 LiteLLM-specific 字段 — 可选的 API 密钥 ARN、 OpenAI-compatible 网关的可选 API 基本 URL 以及传递给提供商的可选其他参数。 ![添加 Harness 向导：LitelLM API 密钥 ARN、API 基础和其他参数步骤](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/images/tui/harness-model-02-litellm-flow.png) 继续完成其余步骤（环境、内存、高级设置）并确认。然后跑`agentcore deploy`去申请。 ## 使用任何型号，在会话中途切换 通过 LitelLM 使用来自亚马逊 Bedrock、OpenAI、Google Gemini 或其他提供商的模型，包括端点。 OpenAI-compatible 在同一会话的轮流之间切换提供商，对话就会继续。上下文会延续下去。 如果你没有指定型号，Amazon Bedrock (`global.anthropic.claude-sonnet-4-6`) 上的安全带默认为 Anthropic 的 Claude Sonnet 4.6，因此你可以立即开始使用。您可以随时更改每次调用的默认值或覆盖值。 将第三方 API 密钥作为 API 密钥凭[AgentCore 证提供商存储在 Id](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity.html) entity 的令牌库中。安全带在调用时会拉出钥匙。您的代理代码永远不会看到原始凭证。 **Example** 使用[AgentCore 身份](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity.html)注册 API 密钥： ``` aws bedrock-agentcore-control create-api-key-credential-provider \ --name my-openai-key \ --api-key "$OPENAI_API_KEY" ``` 在同一会话中轮流切换提供商： ``` # Turn 1: Bedrock (native Converse API) response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, model={"bedrockModelConfig": {"modelId": "us.anthropic.claude-sonnet-4-5-20250514-v1:0"}}, messages=[{"role": "user", "content": [{"text": "Analyze this codebase."}]}], ) # Turn 2: Bedrock Mantle (OpenAI Responses format, no API key needed) response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, model={ "bedrockModelConfig": { "modelId": "openai.gpt-4o", "apiFormat": "responses", "additionalParams": {"reasoning": {"effort": "high"}}, } }, messages=[{"role": "user", "content": [{"text": "Now suggest fixes for the top three issues."}]}], ) # Turn 3: OpenAI model via Bedrock Mantle (no API key needed) response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, model={ "openAiModelConfig": { "modelId": "gpt-5.4", "apiFormat": "responses", "endpoint": {"bedrockMantle": {}}, } }, messages=[{"role": "user", "content": [{"text": "Summarize the fixes as a bullet list."}]}], ) ``` `openAiModelConfig`与一起使用`"endpoint": {"bedrockMantle": {}}`，通过 Amazon Bedrock Mantle 调用 OpenAI 模型 — 不需要 API 密钥，使用你的执行角色证书。在直接调用 OpenAI 端点`apiKeyArn`时`openAiModelConfig`与一起使用。 要通过 OpenAI-compatible 网关、代理、自托管端点或区域端点路由直接 OpenAI 请求，请设置。`apiBase`该工具会将引用的 API 密钥发送`apiKeyArn`到此端点，因此请仅使用受信任的端点。如果省略`apiBase`，则该工具将使用默认的 OpenAI 端点。 ``` response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, model={ "openAiModelConfig": { "modelId": "gpt-5.4", "apiKeyArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-openai-key", "apiBase": "https://gateway.example.com/v1", "apiFormat": "responses", } }, messages=[{"role": "user", "content": [{"text": "Summarize this report."}]}], ) ``` 在 “[AgentCore 身份](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity.html)” 中添加 API 密钥： ``` agentcore add credential --type api-key --name my-openai-key --api-key $OPENAI_API_KEY agentcore deploy ``` 在之前创建的 AgentCore 项目目录中，添加第二个使用 Responses 格式的线束。然后部署项目： ``` agentcore add harness \ --name my-agent \ --model-provider bedrock \ --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \ --api-format responses agentcore deploy ``` 使用基岩斗篷召唤： ``` SESSION_ID="$(uuidgen)" # Turn 1: Bedrock Mantle (Responses format) agentcore invoke --harness my-agent \ --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \ --session-id "$SESSION_ID" \ "Analyze this codebase and identify performance bottlenecks." ``` 在同一个会话中直接切换到 OpenAI： ``` # Turn 2: OpenAI direct on the same session agentcore invoke --harness my-agent \ --model-provider open_ai \ --model-id gpt-5.4 \ --api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-openai-key \ --session-id "$SESSION_ID" \ "Now suggest fixes for the top three issues." ``` 了解更多：[AgentCore 身份](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity.html)、[API 密钥凭证提供商](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity-api-key.html)。 ### 选择模型 API 格式 Amazon Bedrock 和 OpenAI 模型配置均接受一个`apiFormat`可选字段，用于选择线束使用哪个 API 协议来调用模型。 对于`bedrockModelConfig`，同时`apiFormat`选择 API 协议和该工具调用的 Amazon Bedrock 终端节点： + `converse_stream`-由终端节点提供的 Amazon Bedrock Converse API。`bedrock-runtime`这是默认值。 + `responses`- OpenAI-compatible 响应 API，由`bedrock-mantle`端点提供。 + `chat_completions`- OpenAI-compatible 聊天完成 API，由`bedrock-mantle`端点提供。 该`bedrock-mantle`端点支持与默认`bedrock-runtime`端点不同的模型和功能集。有关详细信息，请参阅 [Amazon Bedrock 支持的终端节点](https://docs.amazonaws.cn/bedrock/latest/userguide/endpoints.html)。 因为`openAiModelConfig`，`apiFormat`可以是以下之一： + `responses`-OpenAI 响应 API。这是默认值。 + `chat_completions`-OpenAI 聊天完成 API。 两种配置还接受可选`additionalParams`字段。 Provider-specific 中的参数`additionalParams`会原封不动地传递给模型提供者。 **重要** 中的参数`additionalParams`可以改变提供商的行为，包括端点路由、凭据处理和区域选择。如果您的应用程序将调用方提供的模型配置转发给`InvokeHarness`，请在调用之前验证这些字段。请参阅[责任共担模式](harness-security.md#harness-shared-responsibility)。 **Example** 使用以下`--api-format`标志创建或更新安全带时设置 API 格式： ``` # Bedrock model through the OpenAI-compatible Responses API (bedrock-mantle endpoint) agentcore add harness --name research-agent \ --model-provider bedrock \ --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \ --api-format responses agentcore deploy ``` ``` # OpenAI model using the Chat Completions API agentcore add harness --name openai-agent \ --model-provider open_ai \ --model-id gpt-5.4 \ --api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-openai-key \ --api-format chat_completions agentcore deploy ``` `--api-format`接受`converse_stream`、`responses`、或 f `chat_completions` o `--model-provider bedrock` r 和 `responses` f `chat_completions` or `--model-provider open_ai`。它不适用于`gemini`或`lite_llm`。 ### 应用 Amazon Bedrock Guardrails 使用 Amazon Bedrock Guardrails 筛选模型输入和输出中的有害内容或屏蔽被拒绝的主题。要将护栏应用于每个模型请求，请向中添加一个`guardrailConfig`对象。`bedrockModelConfig.additionalParams`安全带会将此对象与每个模型请求一起传递给 Amazon Bedrock。 要将 Amazon Bedrock Guardrails 与安全带一起使用，请使用 API `bedrockModelConfig` 格式进行配置。`converse_stream`如果省略`apiFormat`，则`converse_stream`默认使用安全带。在`CreateHarness`或中设置此配置`UpdateHarness`，或者在一次呼入时将其覆盖`InvokeHarness`。 以下 Python 示例`InvokeHarness`使用护栏配置进行调用。{{HARNESS\_ARN}}替换为您的线束 ARN 和唯一{{SESSION\_ID}}的运行时会话 ID。 ``` import boto3 client = boto3.client("bedrock-agentcore") response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, model={ "bedrockModelConfig": { "modelId": "us.amazon.nova-micro-v1:0", "apiFormat": "converse_stream", "additionalParams": { "guardrailConfig": { "guardrailIdentifier": "arn:aws:bedrock:us-west-2:111122223333:guardrail/abc123def456", "guardrailVersion": "1", "trace": "enabled_full", } }, } }, messages=[{"role": "user", "content": [{"text": "Help me plan a trip."}]}], ) ``` 有关基准模型权限，请参阅[执行角色策略](harness-security.md#harness-execution-role-policy)。将以下 JSON 语句添加到线束执行角色策略中： ``` { "Effect": "Allow", "Action": "bedrock:ApplyGuardrail", "Resource": "arn:aws:bedrock:us-west-2:111122223333:guardrail/abc123def456" } ``` 在与模型请求相同的 Amazon 区域中使用护栏。当护栏干预时，响应流会报告`guardrail_intervened`为停止原因。 有关护栏配置字段的更多信息，请参阅通过 Conver [se API 使用护栏](https://docs.amazonaws.cn/bedrock/latest/userguide/guardrails-use-converse-api.html)。有关 IAM 权限的更多信息，请参阅[设置使用 Amazon Bedrock Guardrails 的权限](https://docs.amazonaws.cn/bedrock/latest/userguide/guardrails-permissions.html)。 ### 通过 LitelLM 使用模型 用于`liteLlmModelConfig`访问 Lit [elLM](https://docs.litellm.ai/) 支持的任何提供商，包括 OpenAI-compatible 端点。设置`modelId`为以 LitelLM 提供商为前缀的模型 ID，例如或。`gemini/gemini-2.5-pro` `anthropic/claude-sonnet-4-6` 使用 API 密钥进行身份验证的提供商（例如 Google 或 Anthropic）需要`apiKeyArn`。使用`bedrock/`前缀访问的 Amazon Bedrock 模型使用安全带执行角色的权限，不需要 API 密钥。 + `modelId`（必填）-以 LitellM 提供商为前缀的型号 ID。 + `apiKeyArn`-提供商 API 密钥的 ARN，以 API 密钥凭据提供者的[AgentCore 身份](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity.html)形式存储在 “身份” 中。端点必须接受此 API 密钥。 + `apiBase`- OpenAI-compatible 网关的自定义终端节点 URL，例如代理或自托管终端节点。 + `additionalParams`-传递给 LitelLM 的提供商特定参数保持不变。这包括可以覆盖终端节点 (`aws_bedrock_runtime_endpoint`)、担任 IAM 角色 (`aws_role_name`) 或更改请求路由的参数。请参阅[责任共担模式](harness-security.md#harness-shared-responsibility)。 `liteLlmModelConfig`还接受可选的`maxTokens``temperature`、和`topP`字段。 **Example** 配置 litelLM 模型： ``` response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, model={ "liteLlmModelConfig": { "modelId": "gemini/gemini-2.5-pro", "apiKeyArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-gemini-key", } }, messages=[{"role": "user", "content": [{"text": "Summarize this paper."}]}], ) ``` 使用以下命令配置 LitelLM 模型：`--model-provider lite_llm` ``` agentcore add harness --name research-agent \ --model-provider lite_llm \ --model-id gemini/gemini-2.5-pro \ --api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-gemini-key agentcore deploy ``` 使用以下方式访问 OpenAI-compatible 网关`--api-base`，并通过以下方式传递提供商特定的参数：`--additional-params` ``` agentcore add harness --name proxy-agent \ --model-provider lite_llm \ --model-id openai/gpt-5.4 \ --api-base https://my-llm-gateway.example.com/v1 \ --api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-gateway-key \ --additional-params '{"timeout": 30}' agentcore deploy ``` `--api-base`并且仅`--additional-params`适用于`--model-provider lite_llm`。带有`bedrock/`前缀的 Amazon Bedrock 模型使用执行角色的权限并且不需要`--api-key-arn`。 当您的安全工具使用 API 密钥凭据提供程序时，请向执行角色授予读取密钥的权限。请参阅[安全性和访问控制](harness-security.md)。 有关线束配置的更多信息，请参阅 [API 文档](harness-get-started.md#api-documentation) #### 相关主题 + [工具](harness-tools.md)-将工具连接到安全带 + [内存](harness-memory.md)-在会话之间保持对话 + [通过限制控制成本](harness-operations.md#harness-limits)-设置执行限制和截断策略