Back to Details

agents-build

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

build

功能扩展

Add capabilities to your AgentCore agent project.
为你的AgentCore Agent项目添加功能。

When to use

使用场景

  • Adding cross-session memory to your agent
  • Calling your deployed agent from a web app, mobile app, or backend service
  • Configuring VPC networking for private resources (RDS, internal APIs)
  • Building multi-agent systems with orchestrator/specialist patterns
  • Migrating an existing Bedrock Agent to AgentCore
  • Adding the Browser tool so the agent can navigate websites
  • Adding the Code Interpreter so the agent can execute code in a sandbox
  • Removing resources from your project or tearing down a deployment
Do NOT use for:
  • Connecting to external tools/APIs via Gateway (OpenAPI specs, Lambda, MCP servers, credentials, policies) → use 
    agents-connect
  • Scaffolding a new project → use 
    agents-get-started
  • Deploying → use 
    agents-deploy
  • 为你的Agent添加跨会话内存
  • 从Web应用、移动应用或后端服务调用已部署的Agent
  • 为私有资源（RDS、内部API）配置VPC网络
  • 基于编排器/专用Agent模式构建多Agent系统
  • 将现有Bedrock Agent迁移至AgentCore
  • 添加浏览器工具，使Agent能够浏览网站
  • 添加代码解释器，使Agent能够在沙箱中执行代码
  • 从项目中移除资源或销毁部署
请勿用于以下场景：
  • 通过Gateway连接外部工具/API（OpenAPI规范、Lambda、MCP服务器、凭证、策略）→ 请使用
    agents-connect
  • 搭建新项目 → 请使用
    agents-get-started
  • 部署 → 请使用
    agents-deploy

Input

输入参数

$ARGUMENTS
can be:
  • A capability: "memory", "integrate", "vpc", "multi-agent", "migrate", "browser", "code-interpreter", "teardown"
  • A description of what they want: "remember user preferences", "call from React app", "scrape a website", "run pandas in the agent", "delete my agent", "clean up resources"
  • Empty — the skill will determine the workflow from context
$ARGUMENTS
可以是：
  • 功能类型："memory", "integrate", "vpc", "multi-agent", "migrate", "browser", "code-interpreter", "teardown"
  • 需求描述："记住用户偏好"、"从React应用调用"、"爬取网站"、"在Agent中运行pandas"、"删除我的Agent"、"清理资源"
  • 空值——该技能会根据上下文确定工作流程

Process

操作流程

Step 0: Verify CLI version

步骤0：验证CLI版本

Run 
agentcore --version
. This skill requires v0.9.0 or later.
If older: "Run 
agentcore update
to get the latest version."
运行
agentcore --version
。该技能需要v0.9.0或更高版本。
如果版本较低："运行
agentcore update
以获取最新版本。"

Step 1: Read project context

步骤1：读取项目上下文

Read 
agentcore/agentcore.json
to understand the current project — framework, existing resources, agent configuration.
If 
agentcore/agentcore.json
is not found:
  1. Check if the developer is in the wrong directory. Look for 
    agentcore/agentcore.json
    in parent directories (up to 3 levels). If found, tell them: "Found an AgentCore project at 
    <path>
    . Are you working in that project?"
  2. If no project exists anywhere nearby, ask what capability they wanted to add. Then offer two paths:
    • "I can walk you through creating a project first and then adding CAPABILITY — want to do that?" (run the get-started flow inline, then continue with the build workflow)
    • "If you already have a project elsewhere, 
      cd
      into it and try again."
Do not just say "go use agents-get-started" and stop — that loses the developer's context about what they actually wanted to do.
读取
agentcore/agentcore.json
以了解当前项目——包括框架、现有资源、Agent配置。
如果未找到
agentcore/agentcore.json
：
  1. 检查开发者是否处于错误目录。 在父目录中查找
    agentcore/agentcore.json
    （最多3级）。如果找到，告知他们："在
    <path>
    路径下发现一个AgentCore项目。你是否正在该项目中工作？"
  2. 如果附近没有任何项目，询问他们想要添加的功能。然后提供两个选项：
    • "我可以先引导你创建一个项目，然后再添加所需功能——是否要这样操作？"（先执行入门流程，然后继续功能扩展工作流程）
    • "如果你已经在其他位置有项目，请
      cd
      进入该目录后重试。"
不要只说"去使用agents-get-started"就结束对话——这会丢失开发者的实际需求上下文。

Step 2: Determine the workflow

步骤2：确定工作流程

Important disambiguation — before routing to a build reference, check if the prompt is actually a connect or debug concern:
  • If the phrase mentions external APIs, Lambda functions, OpenAPI specs, gateways, credentials, MCP servers, or policies → this is 
    agents-connect
    , not build
  • If the developer says something is broken (wrong answers, errors, tool failures) → this is 
    agents-debug
    , not build
  • Build is for adding new capabilities to a working project, not fixing broken ones
Based on the developer's prompt and 
$ARGUMENTS
, load the appropriate reference:
Developer intentReference to load
Add memory, remember things, user preferences, cross-session
references/memory.md
Call agent from app, invoke from code, streaming, SDK client, agent URL, execute shell in session
references/integrate.md
VPC, private network, RDS, internal API, subnet, security group
references/vpc.md
Multi-agent, orchestrator, specialist, A2A, delegation, agent handoff
references/multi-agent.md
Custom headers from caller to agent, header allowlist, tenant ID/correlation ID/trace propagation
references/request-headers.md
Migrate Bedrock Agent, import agent, move to AgentCore
references/migrate.md
Browser tool, web navigation, form filling, scraping, Nova Act, Playwright, live view
references/browser.md
Code Interpreter, execute code, sandbox, run Python/JS/TS, data analysis in agent, pandas
references/code-interpreter.md
Delete agent, remove resource, tear down, clean up, destroy, start fresh
references/teardown.md
Change model, switch model, use Haiku/Sonnet/Nova, different modelInline — see "Changing the model" below
If the developer asks about the difference between local dev and deployed (e.g., "why does my memory work after deploy but not locally?"), load 
references/local-vs-deployed.md
 alongside the specific workflow reference.
Read the matching file into context and follow its Process section step by step — do not summarize.
If the intent is ambiguous, ask the developer which capability they want to add.
重要歧义消除——在跳转至功能扩展参考文档之前，检查请求是否实际上属于连接或调试问题：
  • 如果请求中提及外部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、编排器、专用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
代码解释器、执行代码、沙箱、运行Python/JS/TS、Agent内数据分析、pandas
references/code-interpreter.md
删除Agent、移除资源、销毁部署、清理、重置、重新开始
references/teardown.md
更换模型、切换模型、使用Haiku/Sonnet/Nova、不同模型内联说明——请查看下方"更换模型"部分
如果开发者询问本地开发与部署后的差异（例如："为什么我的内存功能在部署后可用，但本地不可用？"），除了加载对应工作流程的参考文档外，还需加载
references/local-vs-deployed.md
。
将匹配的文档加载至上下文，并严格按照其流程部分逐步执行——请勿概括。
如果意图不明确，请询问开发者想要添加的功能类型。

Changing the model

更换模型

The model is configured in 
app/<AgentName>/model/load.py
(scaffolded by 
agentcore create
). To change it:
  1. Open 
    app/<AgentName>/model/load.py
  2. Change the 
    model_id
    parameter in the 
    BedrockModel()
    constructor
python
undefined
模型配置在
app/<AgentName>/model/load.py
文件中（由
agentcore create
命令生成）。更换模型步骤如下：
  1. 打开
    app/<AgentName>/model/load.py
  2. 修改
    BedrockModel()
    构造函数中的
    model_id
    参数
python
undefined

Default (scaffolded by CLI)

Default (scaffolded by CLI)

return BedrockModel(model_id="global.anthropic.claude-sonnet-4-5-20250929-v1:0")
return BedrockModel(model_id="global.anthropic.claude-sonnet-4-5-20250929-v1:0")

Switch to Haiku for cost savings

Switch to Haiku for cost savings

return BedrockModel(model_id="us.anthropic.claude-3-5-haiku-20241022-v1:0")
return BedrockModel(model_id="us.anthropic.claude-3-5-haiku-20241022-v1:0")

Switch to Nova Lite

Switch to Nova Lite

return BedrockModel(model_id="amazon.nova-lite-v1:0")

Cross-region inference profile prefixes (`us.`, `eu.`, `apac.`, `global.`) control where inference runs. Use `global.` for maximum throughput, or a geographic prefix for data residency. Not all models support all prefixes — check the Bedrock inference profiles docs.

After changing the model:

- Verify the model is enabled in your region: AWS Console → Amazon Bedrock → Model access
- For cross-region profiles, enable in all destination regions
- If using `agents-harden`, update the IAM policy to scope to the new model ARN
- Run `agentcore dev` to test locally, then `agentcore deploy` to update the deployed agent

No `agentcore.json` change is needed — the model is configured in code, not in the project config.
return BedrockModel(model_id="amazon.nova-lite-v1:0")

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

更换模型后：

- 验证该模型在你的区域已启用：AWS控制台 → Amazon Bedrock → 模型访问权限
- 对于跨区域配置，请在所有目标区域启用该模型
- 如果使用`agents-harden`，请更新IAM策略以适配新模型的ARN
- 运行`agentcore dev`进行本地测试，然后运行`agentcore deploy`更新已部署的Agent

无需修改`agentcore.json`——模型配置在代码中，而非项目配置文件。

Pre-flight: validate any 
--name
before generating the CLI command

预检查：生成CLI命令前验证
--name
参数

Whichever reference you load, most end up producing an 
agentcore add <resource> --name <something>
command. The CLI fails late on invalid names — you'll see the error after walking through prompts, not before running the command. Validate up front:
ResourceMax charsAllowedStarts with
Agent (
add agent
)		48alphanumeric + 
_
letter
Memory, gateway, gateway-target, credential, evaluator, online-eval, policy, policy-engine48alphanumeric + 
_
letter
Count the characters before constructing the command. If the name is over the limit or contains hyphens, dots, or spaces, push back: "
<name>
is N characters / uses 
-
, which the CLI rejects. How about 
<suggestion>
?" Never run the command with an invalid name hoping the CLI message will be clear.
Note: 
agentcore create --name
(the project name) has a stricter 23-char limit and does not allow underscores. That's covered in 
agents-get-started
; if you see the developer re-running create, flag the 23-char limit specifically.
无论加载哪个参考文档，大多数场景最终都会生成
agentcore add <resource> --name <something>
命令。CLI会在后续步骤才报错（而非运行命令前），因此需要提前验证：
资源类型最大字符数允许字符起始要求
Agent（
add agent
）		48字母数字 + 
_
字母
Memory、gateway、gateway-target、credential、evaluator、online-eval、policy、policy-engine48字母数字 + 
_
字母
在构造命令前计算字符数。如果名称超过限制或包含连字符、点号或空格，请提示："
<name>
包含N个字符/使用了
-
，CLI会拒绝该名称。改用
<suggestion>
怎么样？" 切勿使用无效名称运行命令，寄希望于CLI给出清晰的错误提示。
注意：
agentcore create --name
（项目名称）有更严格的23字符限制，且不允许使用下划线。这部分内容在
agents-get-started
中说明；如果发现开发者重新运行create命令，请特别提醒23字符限制。

Output

输出结果

Depends on the workflow — see the loaded reference for specific outputs.
输出结果取决于工作流程——请查看加载的参考文档获取具体输出。

Quality criteria

质量标准

  • The correct reference was loaded based on the developer's intent
  • All output follows the loaded reference's quality criteria
  • Cross-references to other skills (agents-connect, agents-deploy) are included where relevant
  • 根据开发者的意图加载了正确的参考文档
  • 所有输出符合加载的参考文档的质量标准
  • 在相关场景中包含了对其他技能（agents-connect、agents-deploy）的交叉引用