agents-get-started

快速入门

引导开发者从零开始，在 AWS 上运行 Agent。

适用场景

• 开发者想在 AWS 上构建 Agent，但不知道从何入手
• 开发者想创建新的 AgentCore 项目
• 开发者正在选择框架（Strands、LangGraph、GoogleADK、OpenAI Agents）
• 开发者刚运行了 agentcore create，想知道接下来该做什么

请勿用于：

• 环境／先决条件问题（找不到 CLI、凭证有问题）→ 使用 agents-debug
• 为现有项目添加功能（记忆、工具、策略）→ 使用 agents-build 或 agents-connect
• 迁移现有的 Bedrock Agent → 使用 agents-build（会加载 references/migrate.md）

输入

$ARGUMENTS 可以是：

• 框架偏好：“使用 LangGraph”“搭配 Strands”
• 协议：“MCP 服务”“A2A”
• 对 Agent 功能的描述：“客户支持 Agent”
• 留空——此技能将引导框架选择

流程

步骤 0：验证 CLI 版本

agentcore --version

此技能需要 v0.9.0 或更高版本。

如果版本较旧：

你的 AgentCore CLI 已过时（当前版本为 vX.Y.Z，需要 v0.9.0+）。

提出运行更新：agentcore update。更新完成后，重新检查版本，确认其 ≥0.9.0，再继续操作。保留开发者已经提供的上下文（框架偏好、项目名称、想构建的内容），这样他们就不必重复说明。

如果找不到 agentcore：

尚未安装 AgentCore CLI。运行 npm install -g @aws/agentcore（需要 Node.js 20+）。 如果安装遇到问题，我可以运行 agents-debug 技能（会加载 references/doctor.md）来诊断你的环境。

步骤 1：确定意图——正在探索还是准备创建？

在开始选择框架之前，先了解开发者目前的阶段：

询问开发者：“你是在探索选项（比较框架、了解 AgentCore 的功能），还是准备创建项目？”

• 正在探索 → 前往步骤 2（框架比较）。介绍各个选项、回答问题，并等待回应。在他们表示准备好之前，不要构造 create 命令。
• 准备创建 → 跳到步骤 3（创建项目）。如果他们已经指定了框架，则完全跳过步骤 2。
• 已有项目 → 在当前目录中查找 agentcore/agentcore.json。如果找到，读取该文件并跳到步骤 5（接下来该做什么）。不要重新搭建项目脚手架。

如果开发者的意图已能从 $ARGUMENTS 中明确判断（例如，“创建一个名为 MyBot 的 Strands Agent”），则直接跳到步骤 3。

第 2 步：选择框架

先检查对话上下文。 如果开发者已在本次对话的前文讨论过框架（例如在之前调用技能时），不要再次展示完整表格。总结之前讨论的内容，并询问他们是否已做出决定，或是否有变化。

如果这是首次讨论框架，请展示以下选项：

支持的框架（通过 CLI 脚手架生成，Python）：

框架	CLI 值	适用场景
Strands	Strands	原生支持 AWS、上手路径最简单、与 AgentCore 的集成最佳
LangGraph	LangChain_LangGraph	复杂的基于图的工作流、已投入使用 LangChain
Google ADK	GoogleADK	已在使用 Google 智能体工具包的团队
OpenAI Agents	OpenAIAgents	已在使用 OpenAI 智能体 SDK 的团队

请开发者选择。 展示选项并等待他们选择。除非他们明确表示没有偏好，否则不要默认选择。

命名说明： CLI 标志值是传递给 --framework 的确切字符串。在说明文字中使用较短的名称。

默认推荐（仅当开发者表示“没有偏好”或“由你决定”时）：Strands——原生支持 AWS 的框架，与 AgentCore 集成最紧密，并且提供的示例和文档最多。

需要了解的关键决策点：

• “你是否已有基于 LangGraph 或 OpenAI Agents 的智能体代码？”→ 使用对应框架
• “你是否需要带条件分支的复杂图工作流？”→ LangGraph
• “从头开始且没有偏好吗？”→ Strands

未列出的框架？

如果开发者询问上表中未列出的框架，请按以下方式处理：

他们询问的内容	回答
CrewAI、AutoGen、Semantic Kernel	CLI 不会为这些框架生成脚手架，但可以通过 BYO Container 路径（如下）使用它们。AgentCore Runtime 与框架无关——任何实现 HTTP 契约的代码都可以使用。
Anthropic SDK / Claude Agent SDK	这是模型 SDK，而非智能体框架。你可以在任何框架（Strands、LangGraph 等）中使用它，也可以单独使用。若要单独使用，请将其封装在实现 Runtime 契约的容器中。
Claude Code / Cursor / Copilot	这些是 IDE 工具，而非智能体框架。它们用于编写智能体代码，而不是部署智能体代码。请从上表中为智能体本身选择一个框架。
LangChain（不含 LangGraph）	LangChain 是一个库，LangGraph 是基于它构建的智能体框架。CLI 会生成 LangGraph 脚手架。如果你使用的是普通 LangChain 链，可采用 BYO Container 路径。
自定义 / 自建框架	使用 BYO Container 路径，见下文。

BYO Container 路径（任意框架、任意语言）：

对于 CLI 不会生成脚手架的框架或语言，AgentCore Runtime 接受任何实现 HTTP 契约（POST /invocations、GET /ping）的容器。工作流程：

1. 使用 agentcore create --name <ProjectName> --defaults 生成项目结构
2. 使用 agentcore add agent --type byo --build Container --language <Language> --code-location <path> 注册代码
3. 编写一个用于构建和运行智能体的 Dockerfile
4. agentcore deploy 会处理 ECR 推送、CDK 基础设施和 Runtime 创建

针对特定语言的说明：

语言	推荐路径
Java（Spring Boot）	AgentCore 的 Spring AI SDK——负责处理 Runtime 契约、SSE 流式传输和运行状况检查。使用 --language Other --build Container。
JavaScript / TypeScript	使用 Express/Fastify 等实现 Runtime 契约。使用 --language TypeScript --build Container。
Go、Rust、.NET、其他	实现 Runtime HTTP 契约。使用 --language Other --build Container。

只要容器能够正确构建，本技能的其余部分（部署、状态、日志、调用）均适用。

框架与模型提供商——常见的混淆

框架决定 Agent 如何编排（Strands、LangGraph 等）。模型提供商决定它调用哪个大模型（Bedrock、Anthropic、OpenAI、Gemini）。两者是相互独立的选择：

• Strands + Bedrock（默认）——所有环节均采用 AWS 原生方案
• Strands + Anthropic——使用 Strands 编排，直接通过 Anthropic API 调用模型
• LangGraph + Bedrock——使用 LangGraph 编排，使用 Bedrock 提供模型
• OpenAI Agents + OpenAI——所有环节均采用 OpenAI 方案

如果开发者说“我想使用 Claude”，指的是模型提供商（Bedrock 或 Anthropic），而不是框架。如果他们说“我想使用 LangGraph”，指的是框架。

步骤 3：创建项目

根据开发者的选择构建 agentcore create 命令。

构建命令前——验证项目名称。 CLI 会在较晚阶段才报错：如果名称无效，你可能要等到完成提示流程或构建完整命令后才会看到错误。提前检查以下规则，避免来回折腾。若不符合任何一条规则，请拒绝该名称并要求提供新名称：

• 长度 ≤ 23 个字符（比大多数开发者以为的要短——MyCustomerSupportAgent 有 22 个字符，符合要求；CustomerSupportChatbot 有 22 个字符，符合要求；MyCustomerSupportBotApp 有 23 个字符，刚好符合要求；MyCustomerSupportChatBot 有 24 个字符，不符合要求）
• 只能使用字母和数字——不能包含连字符、下划线、句点或空格
• 必须以字母开头

接近字符数上限时，请明确告知字符数：“这个名称有 24 个字符，CLI 限制项目名称最多为 23 个字符。要将它缩短为 <suggestion> 吗？”不要抱着“CLI 的错误消息会说清楚”的想法，用无效名称运行命令——错误消息不一定清楚，而且开发者对后续命令的理解也会因此出错。

构建命令后，先展示并征求确认，再让开发者运行。 展示包含所有标志的完整命令，并解释每项选择的含义。等待开发者确认或调整后再继续。

示例：

根据你告诉我的信息，我建议使用以下命令：

agentcore create --name MyAgent --framework Strands --model-provider Bedrock --build CodeZip --memory none

这会创建一个使用 Bedrock 模型的 Strands Agent，并以代码压缩包的形式部署（无需 Docker）。之后可再添加记忆功能。

要运行此命令，还是需要调整什么？

不要自动执行命令——先展示命令并等待确认。

最简配置（默认值——Strands、Bedrock、CodeZip、无记忆）：

agentcore create --name <ProjectName> --defaults

指定选项：

agentcore create \
  --name <ProjectName> \
  --framework <Framework> \
  --model-provider Bedrock \
  --build CodeZip \
  --memory none

标志参考：

标志	可选值	默认值
--name	仅限字母和数字，最多 23 个字符	通过提示输入
--framework	Strands、LangChain_LangGraph、GoogleADK、OpenAIAgents	通过提示输入
--protocol	HTTP、MCP、A2A	HTTP
--build	CodeZip、Container	CodeZip
--model-provider	Bedrock、Anthropic、OpenAI、Gemini	通过提示输入
--memory	none、shortTerm、longAndShortTerm	通过提示输入
--network-mode	PUBLIC、VPC	PUBLIC
--dry-run	—	预览但不创建

选项指南：

• 协议： 除非开发者明确需要提供 MCP 工具服务或进行 A2A Agent 间通信，否则使用 HTTP
• 构建方式： 除非开发者需要自定义系统依赖，否则使用 CodeZip（CodeZip 部署更快，且无需在本地安装 Docker）
• 模型提供商： 除非开发者有特殊理由选择其他提供商，否则使用 Bedrock（Bedrock 无需管理 API 密钥）
• 记忆： 从 none 开始——开发者需要时，可稍后通过 agents-build 添加记忆（加载 references/memory.md）

第 4 步：说明创建的内容

项目创建完成后，阅读 agentcore/agentcore.json 和生成的代码，说明项目结构。

下方结构对应 CLI v0.9.x。如果 CLI 版本不同，请运行 tree <ProjectName>/ -L 3 查看实际生成的结构，并据此进行说明。

<ProjectName>/
├── agentcore/
│   ├── agentcore.json      ← Project config (agents, resources)
│   ├── aws-targets.json    ← AWS account + region
│   ├── .env.local          ← Local environment variables (gitignored)
│   └── cdk/                ← CDK infrastructure (auto-managed, don't edit)
└── app/
    └── <AgentName>/
        ├── main.py          ← Your agent code — this is where you build
        ├── mcp_client/      ← Pre-wired example MCP client (see note below)
        └── pyproject.toml   ← Python dependencies

需要重点介绍的文件：

• app/<AgentName>/main.py — Agent 的入口。开发者在此添加工具、系统提示词和逻辑。
• agentcore/agentcore.json — 项目配置。通过 agentcore add 命令在此添加资源。
• agentcore/.env.local — 本地环境变量。部署后，资源 ID 会写入此文件，供本地开发使用。

关于脚手架生成的 MCP 客户端，请注意。 main.py 从 mcp_client/client.py 导入 get_streamable_http_mcp_client()，并将其添加到 tools。在全新项目中，该客户端指向一个公开的示例 MCP 端点，因此 agentcore dev 可以立即运行。需要说明两点：

1. 如果将它改为指向尚未部署的网关，它会静默地变成空操作。 常见做法是将示例端点替换为 os.getenv("AGENTCORE_GATEWAY_<NAME>_URL")。该环境变量只有在 agentcore deploy 后才会填充。如果开发者替换后、部署前运行 agentcore dev，get_streamable_http_mcp_client() 会返回一个 URL 为 None 的客户端，Agent 启动时不会有任何 MCP 工具——既不报错，也不发出警告。有关防护模式，请参阅 agents-connect 中的“本地开发缺口”部分：if not GATEWAY_URL: tools = []。
2. **如果开发者完全不需要 MCP 工具，**请移除 mcp_clients 列表，以及将其添加到 tools 的循环。脚手架中包含它只是为了方便，并非必需。

agents-connect 中的参考客户端代码（路径 A）展示了部署完成后使用网关的 MCP 客户端的正确模式。

第 5 步：本地开发

agentcore dev

这会启动本地开发服务器。开发者可以立即与自己的 Agent 交互。

开发服务器绑定的端口（如果要编写 curl 调用脚本或从其他进程进行测试，这一点很重要）：

协议	默认端口
HTTP	8080
MCP	8000
A2A	9000

CLI 启动时会打印绑定的端口和 URL——请始终读取 CLI 输出中的实际值，而不要硬编码。如果默认端口已被占用，CLI 会自动递增端口（例如，8080 → 8081 → 8082），因此，第二个开发会话或上次运行遗留的进程可能会在不发出警告的情况下改变端口。使用 agentcore dev --port <N> 指定固定端口；如果调用因连接被拒绝或退出代码 7 错误而失败，请检查 ps 的输出或 CLI 启动信息。

需要说明的重要限制：

• agentcore dev 中无法使用记忆功能——需要先部署
• 本地无法使用网关 URL——需要先部署
• 本地服务器使用项目中配置的模型提供商

第 6 步：首次部署

开发者准备好部署时：

agentcore deploy

该命令将：

1. 显示即将创建的 AWS 资源预览
2. 请求确认
3. 通过 CDK 构建并部署

首次部署需要 3–5 分钟。 后续部署会更快。

部署后，向他们展示如何调用：

agentcore invoke "Hello, what can you do?"

以及如何检查状态：

agentcore status

步骤 7：接下来做什么

根据开发者表示想构建的内容，建议合理的下一项技能：

开发者意图	下一项技能	命令提示
“如何从我的应用中调用它？”	agents-build	agentcore fetch access
“我希望它能记住信息”	agents-build	agentcore add memory
“我希望它能调用外部 API”	agents-connect	agentcore add gateway
“我希望限制它能执行的操作”	agents-connect	agentcore add policy-engine
“我希望衡量质量”	agents-optimize	agentcore add evaluator
“我希望将它投入生产”	agents-harden	生产就绪检查清单
“我希望多个 Agent 协同工作”	agents-build	agentcore create --protocol A2A
“我需要在 VPC 中运行它”	agents-build	agentcore create --network-mode VPC

不要一次提供太多建议——根据开发者实际提出的需求，建议一到两个后续步骤。

示例演练

对于以任务为导向的提示词（例如“构建一个客户支持 Agent”），加载匹配的示例参考：

开发者任务	参考
客户支持、聊天机器人、回答有关政策的问题	references/example-support-agent.md

随着常见模式逐渐显现，可以在此技能的 references 目录中添加更多示例。

输出

• 从“我想构建一个 Agent”到运行已部署 Agent 的清晰路径
• 根据开发者的选择定制的 agentcore create 命令
• 对生成的项目结构的说明
• 根据开发者意图给出的具体后续步骤

质量标准

• agentcore create 命令仅使用 CLI v0.9.1 中有效的标志
• 框架建议基于开发者的具体情况，而非通用默认选项
• 开发者了解每个生成文件的用途
• 后续步骤针对开发者想构建的内容，而非罗列所有功能