本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 配置包入门
本演练将您从零变为代理在运行时读取的版本控制配置包。您将创建一个包，对其进行更新以生成新版本，读取配置并查看版本历史记录。
**Topics**
+ [开始前的准备工作](#cfg-gs-before-you-begin)
+ [步骤 1：创建配置包](#cfg-gs-step1)
+ [第 2 步：更新捆绑包](#cfg-gs-step2)
+ [第 3 步：阅读捆绑包](#cfg-gs-step3)
+ [第 4 步：比较版本](#cfg-gs-step4)
+ [后续步骤](#cfg-gs-next-steps)
+ [附录：集成了配置包的代理代码](#cfg-gs-appendix)
## 开始前的准备工作
请确保：
+ 将代理部署到 AgentCore Runtime 的 AgentCore CLI 项目（或按照以下附录创建支持配置包的项目）
+ Amazon 具有`bedrock-agentcore`和权限的证书`bedrock-agentcore-control`（请参阅[先决条件](optimization-prereqs.md)）
boto3 示例中使用了以下常量。用你自己的值替换它们：
```
REGION = "us-west-2"
BUNDLE_ID = "myAgentConfig-a1b2c3d4e5" # from create response
COMPONENT_ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-abc123"
```
## 步骤 1：创建配置包
使用代理的初始配置创建捆绑包。该套件存储由组件 ARN 键入的键值对（系统提示、型号、温度、工具描述）。
**Example**
```
agentcore add config-bundle \
--name myAgentConfig \
--components '{"arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-abc123": {"configuration": {"system_prompt": "You are a helpful customer support assistant for Acme Store.", "model_id": "global.anthropic.claude-sonnet-4-5-20250929-v1:0"}}}'
agentcore deploy
```
部署后，CLI 会打印捆绑包 ID 和初始版本 ID。
```
import boto3
import uuid
client = boto3.client("bedrock-agentcore-control", region_name=REGION)
response = client.create_configuration_bundle(
bundleName="myAgentConfig",
components={
COMPONENT_ARN: {
"configuration": {
"system_prompt": "You are a helpful customer support assistant for Acme Store.",
"model_id": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
"temperature": 0.7,
}
}
},
description="Acme Store agent configuration",
commitMessage="Initial configuration",
clientToken=str(uuid.uuid4()),
)
bundle_id = response["bundleId"]
version_id = response["versionId"]
print(f"Created bundle: {bundle_id}")
print(f"Initial version: {version_id}")
```
## 第 2 步：更新捆绑包
运行批量评估并发现代理的响应过于冗长后，更新系统提示符。每次更新都会创建一个新的不可变版本。
**Example**
在中编辑包配置`agentcore.json`，然后重新部署：
```
# Edit the system_prompt in agentcore.json, then:
agentcore deploy
```
CLI 会检测现有捆绑包并自动创建新版本。
```
response = client.update_configuration_bundle(
bundleId=bundle_id,
components={
COMPONENT_ARN: {
"configuration": {
"system_prompt": (
"You are a helpful customer support assistant for Acme Store. "
"Be concise. Confirm actions taken in one sentence."
),
"model_id": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
"temperature": 0.5,
}
}
},
parentVersionIds=[version_id],
commitMessage="Reduce verbosity: shorter prompt, lower temperature",
clientToken=str(uuid.uuid4()),
)
new_version_id = response["versionId"]
print(f"New version: {new_version_id}")
```
## 第 3 步：阅读捆绑包
检索当前配置以验证更新是否生效。
**Example**
```
agentcore config-bundle versions --name myAgentConfig
```
输出显示了带有提交消息的版本历史记录：
```
Version Branch Created Message
────────────────────────────────────────────────────────────────────────────────
a1b2c3d4-... mainline 2026-04-28 03:00 Reduce verbosity: shorter prompt, lower temperature
e5f6a7b8-... mainline 2026-04-28 02:30 Initial configuration
```
```
response = client.get_configuration_bundle(bundleId=bundle_id)
config = response["components"][COMPONENT_ARN]["configuration"]
print(f"Version: {response['versionId']}")
print(f"System prompt: {config['system_prompt']}")
print(f"Model: {config['model_id']}")
print(f"Temperature: {config.get('temperature')}")
```
## 第 4 步：比较版本
比较两个版本，看看到底发生了什么变化：
**Example**
```
agentcore config-bundle diff --name myAgentConfig --from --to
```
```
# Fetch both versions
v1 = client.get_configuration_bundle_version(bundleId=bundle_id, versionId=version_id)
v2 = client.get_configuration_bundle_version(bundleId=bundle_id, versionId=new_version_id)
# Compare
v1_config = v1["components"][COMPONENT_ARN]["configuration"]
v2_config = v2["components"][COMPONENT_ARN]["configuration"]
for key in set(list(v1_config.keys()) + list(v2_config.keys())):
if v1_config.get(key) != v2_config.get(key):
print(f"{key}:")
print(f" before: {v1_config.get(key)}")
print(f" after: {v2_config.get(key)}")
```
## 后续步骤
+ **运行批量评估**以衡量配置更改的影响。请参阅[批量评估](batch-evaluations.md)。
+ **使用建议**让服务自动生成优化的提示。请参阅 “[建议](optimization-recommendations.md)”。
+ **设置 A/B 测试**，将两个套装版本与实时流量进行比较。参见[A/B 测试](ab-testing.md)。
+ **在不影响主线的情况下将配置分支**用于实验。请参阅[更新配置包](configuration-bundles-update.md)。
## 附录：集成了配置包的代理代码
以下代理代码使用`BeforeModelCallEvent`挂钩模式在运行时读取活动配置包。代理在模块级别创建一次，挂接会在每次模型调用之前动态更新系统提示符。配置包更改无需重新启动即可立即生效。
+ **SDK 要求：**需要 1.8 或更高`bedrock-agentcore-sdk-python`版本。该`get_config_bundle()`方法从此版本开始可用。`BedrockAgentCoreContext`
将其另存为您的代理的`main.py`：
```
"""Agent with Configuration Bundle integration — hooks pattern."""
from strands import Agent, tool
from strands.models.bedrock import BedrockModel
from strands.hooks.events import BeforeModelCallEvent
from bedrock_agentcore.runtime import BedrockAgentCoreApp, BedrockAgentCoreContext
app = BedrockAgentCoreApp()
DEFAULT_MODEL_ID = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
DEFAULT_SYSTEM_PROMPT = (
"You are a helpful customer support assistant for Acme Store. "
"Help customers with their orders, returns, and shipping questions."
)
@tool
def lookup_order(order_id: str) -> str:
"""Look up an order by ID."""
orders = {
"ORD-1001": {"status": "delivered", "item": "Blue T-Shirt (L)", "total": "$29.99"},
"ORD-1002": {"status": "in_transit", "item": "Running Shoes (10)", "total": "$89.99"},
"ORD-1003": {"status": "delayed", "item": "Wireless Headphones", "days_late": 5, "total": "$59.99"},
}
return str(orders.get(order_id, {"error": f"Order {order_id} not found"}))
@tool
def check_shipping_status(order_id: str) -> str:
"""Check detailed shipping status for an order."""
statuses = {
"ORD-1002": "Package is with carrier, on schedule for April 5.",
"ORD-1003": "Package delayed 5 days. Policy: 3+ days late qualifies for 15% discount.",
}
return statuses.get(order_id, f"No active shipment found for {order_id}.")
TOOLS = [lookup_order, check_shipping_status]
def dynamic_config_hook(event: BeforeModelCallEvent):
"""Read config bundle and apply system prompt before every model call."""
config_bundle = BedrockAgentCoreContext.get_config_bundle()
event.agent.system_prompt = config_bundle.get("system_prompt", DEFAULT_SYSTEM_PROMPT)
agent = Agent(
model=BedrockModel(model_id=DEFAULT_MODEL_ID),
tools=TOOLS,
system_prompt=DEFAULT_SYSTEM_PROMPT,
)
agent.hooks.add_callback(BeforeModelCallEvent, dynamic_config_hook)
@app.entrypoint
def invoke(payload, context):
result = agent(str(payload.get("prompt", "Hello")))
return {"response": str(result)}
if __name__ == "__main__":
app.run()
```