agents-build

build

为 AgentCore Agent 项目添加功能。

适用场景

• 为 Agent 添加跨会话记忆
• 通过 Web 应用、移动应用或后端服务调用已部署的 Agent
• 为私有资源（RDS、内部 API）配置 VPC 网络
• 使用编排者/专家模式构建多 Agent 系统
• 将现有的 Bedrock Agent 迁移到 AgentCore
• 添加 Browser 工具，让 Agent 能够浏览网站
• 添加 Code Interpreter，让 Agent 能够在沙箱中执行代码
• 添加 AgentCore Payments，让 Agent 能够为受 x402 或 MPP 保护的 API、工具或内容付费
• 从项目中移除资源或拆除部署

请勿用于：

• 通过 Gateway 连接外部工具/API（OpenAPI 规范、Lambda、MCP 服务、凭证、策略）→ 使用 agents-connect
• 搭建新项目 → 使用 agents-get-started
• 部署 → 使用 agents-deploy

输入

$ARGUMENTS 可以是：

• 一项功能：“memory”、“integrate”、“vpc”、“multi-agent”、“migrate”、“browser”、“code-interpreter”、“payments”、“teardown”
• 对所需功能的描述：“记住用户偏好”、“通过 React 应用调用”、“抓取网站”、“在 Agent 中运行 pandas”、“删除我的 Agent”、“清理资源”
• 空值 — 技能会根据上下文确定工作流

流程

步骤 0：验证 CLI 版本

运行 agentcore --version。此技能要求版本为 v0.9.0 或更高。

如果版本较旧：“运行 agentcore update 以获取最新版本。”

步骤 1：读取项目上下文

读取 agentcore/agentcore.json，了解当前项目，包括框架、现有资源和 Agent 配置。

如果未找到 agentcore/agentcore.json：

1. 检查开发者是否位于错误的目录。 在父目录中查找 agentcore/agentcore.json（最多向上 3 层）。如果找到，请告知：“在 <path> 找到了一个 AgentCore 项目。你是在该项目中工作吗？”
2. 如果附近没有任何项目，询问他们想添加什么功能。然后提供两个选择：
   • “我可以先引导你创建项目，再添加 CAPABILITY——要这样做吗？”（内联运行入门流程，然后继续 build 工作流）
   • “如果你已有其他位置的项目，请先 cd 到该项目目录，然后重试。”

不要只说“去使用 agents-get-started”然后就此结束——这样会丢失开发者原本想做什么的上下文。

步骤 2：确定工作流

重要的区分说明——在跳转到构建参考文档之前，请先确认提示实际询问的是连接还是调试问题：

• 如果提到外部 API、Lambda 函数、OpenAPI 规范、网关、凭证、MCP 服务或策略 → 这是 agents-connect，而不是构建
• 如果开发者表示某些内容无法正常工作（答案错误、出现错误、工具故障）→ 这是 agents-debug，而不是构建
• 构建适用于为正常运行的项目添加新功能，而不是修复故障

根据开发者的提示和 $ARGUMENTS，加载相应的参考文档：

开发者意图	要加载的参考文档
添加记忆、记住信息、用户偏好、跨会话	references/memory.md
在应用中调用 Agent、从代码中调用、流式处理、SDK 客户端、Agent URL、在会话中执行 shell	references/integrate.md
VPC、私有网络、RDS、内部 API、子网、安全组	references/vpc.md
多 Agent、编排器、专家、A2A、委派、Agent 移交	references/multi-agent.md
从调用方传递给 Agent 的自定义标头、标头允许列表、租户 ID/关联 ID/跟踪信息传播	references/request-headers.md
迁移 Bedrock Agent、导入 Agent、迁移到 AgentCore	references/migrate.md
浏览器工具、网页导航、填写表单、抓取数据、Nova Act、Playwright、实时视图	references/browser.md
Code Interpreter、执行代码、沙箱、运行 Python/JS/TS、在 Agent 中进行数据分析、pandas	references/code-interpreter.md
付款、为 x402 或 MPP 内容付费、402 Payment Required、Machine Payments Protocol、WWW-Authenticate: Payment、微支付、付费 API/工具、付款管理器/连接器	references/payments.md
删除 Agent、移除资源、拆除、清理、销毁、重新开始	references/teardown.md
更改模型、切换模型、使用 Haiku/Sonnet/Nova、使用其他模型	内嵌——参见下方“更改模型”

如果开发者询问本地开发与已部署环境之间的差异（例如，“为什么我的记忆在部署后有效，但在本地无效？”），请同时加载 references/local-vs-deployed.md 和相应的工作流参考文档。

将匹配的文件读入上下文，并逐步遵循其 Process 部分——不要总结。

如果意图不明确，请询问开发者想要添加哪项功能。

更改模型

模型在 app/<AgentName>/model/load.py 中配置（由 agentcore create 生成）。更改方法如下：

1. 打开 app/<AgentName>/model/load.py
2. 更改 BedrockModel() 构造函数中的 model_id 参数

# Default (scaffolded by CLI)
return BedrockModel(model_id="global.anthropic.claude-sonnet-4-5-20250929-v1:0")

# Switch to Haiku for cost savings
return BedrockModel(model_id="us.anthropic.claude-3-5-haiku-20241022-v1:0")

# Switch to Nova Lite
return BedrockModel(model_id="amazon.nova-lite-v1:0")

跨区域推理配置文件前缀（us.、eu.、apac.、global.）用于控制推理运行的位置。使用 global. 可获得最高吞吐量，或使用地理区域前缀以满足数据驻留要求。并非所有模型都支持所有前缀——请查看 Bedrock 推理配置文件文档。

更改模型后：

• 确认模型已在你的区域启用：AWS Console → Amazon Bedrock → Model access
• 对于跨区域配置文件，请在所有目标区域启用
• 如果使用 agents-harden，请更新 IAM 策略，将权限范围限定到新的模型 ARN
• 运行 agentcore dev 在本地测试，然后运行 agentcore deploy 更新已部署的 Agent

无需更改 agentcore.json——模型在代码中配置，而不是在项目配置中。

预检：生成 CLI 命令前验证所有 --name

无论加载哪个参考，大多数最终都会生成 agentcore add <resource> --name <something> 命令。CLI 会在较晚阶段才因名称无效而失败——你会在走完提示流程后才看到错误，而不是在运行命令前看到。请提前验证：

资源	最大字符数	允许的字符	起始字符
Agent（add agent）	48	字母数字 + _	字母
Memory、gateway、gateway-target、credential、evaluator、online-eval、policy、policy-engine、payment-manager、payment-connector	48	字母数字 + _	字母

构造命令前先统计字符数。如果名称超出限制，或包含连字符、点号或空格，请提出异议：“<name> 有 N 个字符／使用了 -，CLI 不接受。建议使用 <suggestion>？”切勿抱着 CLI 错误提示会说清楚的想法，使用无效名称运行命令。

注意：agentcore create --name（项目名称）的限制更严格，为 23 个字符，且不允许使用下划线。agents-get-started 中有相关说明；如果你看到开发者重新运行 create，请明确指出 23 个字符的限制。

输出

视工作流而定——具体输出请参阅已加载的参考。

质量标准

• 根据开发者的意图加载了正确的参考
• 所有输出均符合已加载参考的质量标准
• 在适当情况下包含对其他技能（agents-connect、agents-deploy）的交叉引用