View a markdown version of this page

开始使用 Amazon Bedrock AgentCore - Amazon Bedrock AgentCore
注册获取 AWS 账户先决条件步骤 1：安装 AgentCore CLI第 2 步：创建您的项目第 3 步：在本地测试步骤 4：部署代理步骤 5：调用已部署的代理为您的项目添加功能查看日志和跟踪清理后续步骤

开始使用 Amazon Bedrock AgentCore

此快速入门可让您在几分钟内使用 AgentCore CLI 从零变为正在运行的代理。您将安装 CLI、搭建项目脚手架、本地测试、部署到 AWS代理并调用代理。

在相同的 CLI 上 AgentCore构建代理的两种方法：

  • 托管安全带。你在配置文件（模型、提示、工具、内存）中声明代理，然后为你 AgentCore 运行循环。没有框架，没有编排代码。当你想要从想法到正在运行的代理的最快路径时，这是不错的选择。了解更多。

  • Code-based 代理人。你可以使用你已经知道的框架（Strands、 LangGraph Google ADK 或 OpenAI 代理）在 Python 中编写代理循环，然后将其部署到运行时。 AgentCore 完全控制编排逻辑。

本页介绍基于代码的流程。有关安全带，请参阅什么是 AgentCore 安全带。

注册获取 AWS 账户

注册获取 AWS 账户

要开始使用 AWS，您需要一个 AWS 帐户。有关创建 AWS 账户的信息，请参阅《AWS 账户管理参考指南》中的 AWS 账户入门。

先决条件

  • Node.js 20 或更高版本。C AgentCore LI 以 npm 包的形式分发。请与... 核node --version对。如果需要，可以从 nodejs.org 进行安装。

  • npm。包含在 Node.js。

  • 配置了凭据的 AWS 账户。通过 AWS CLI、环境变量或配置 AWS 文件进行配置。参见配置 C AWS LI。

  • Python 3.10 或更高版本（用于代理代码）。请与... 核python3 --version对。

  • IAM 权限。您的身份需要权限才能进行 AgentCore API 调用和代入部署期间使用的 CDK 引导角色。请参阅 AgentCore CLI IAM 权限。

步骤 1：安装 AgentCore CLI

npm install -g @aws/agentcore

验证:

agentcore --version

要稍后更新，请重新运行安装命令或agentcore update。来源和问题：agentcor e-cli 已开启。 GitHub

第 2 步：创建您的项目

agentcore create

交互式向导首先询问你要构建什么：

  • Har ness-基于配置的托管代理循环。无需框架或编排代码。参见什么是 AgentCore 安全带。

  • 代理-基于代码的代理，使用您选择的框架，部署到 AgentCore 运行时。

  • 跳过-在没有代理的情况下创建项目结构。稍后再加一个agentcore add。

如果选择 “代理”，则向导会继续执行以下操作：

  • F ramework-Strands Agents（推荐） LangChain/LangGraph、Google 代理开发套件或 OpenAI Agents SDK

  • 模型提供商 ——亚马逊 Bedrock、Anthropic、OpenAI 或 Gemini

  • 记忆-无，仅限短期，或长期和短期

  • 构建类型- CodeZip （默认）或容器

你也可以直接传递标志来创建基于代码的代理：

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

项目结构

agentcore create生成：

MyAgent/
├── agentcore/
│   ├── agentcore.json      # Project and resource configuration
│   ├── aws-targets.json    # Deployment target (account and region)
│   └── cdk/                # CDK infrastructure (auto-managed)
└── app/
    └── MyAgent/            # Your agent code
        ├── main.py         # Agent entrypoint
        ├── pyproject.toml  # Python dependencies
        └── ...

关键文件：

  • agentcore/agentcore.json-主配置。定义您的代理、内存存储、网关、凭据和其他资源。由agentcore add和管理agentcore remove。

  • app/-你的代理代码。每个代理都有自己的子目录，其中包含一个入口点和. pyproject.toml

  • agentcore/aws-targets.json-要部署的 AWS 账户和区域。

第 3 步：在本地测试

cd MyAgent
agentcore dev

agentcore dev创建 Python 虚拟环境、安装依赖项、使用热重载启动本地服务器，并在浏览器中打开代理检查器，以便您可以与代理聊天、检查跟踪和浏览项目资源。代码更改会自动获取。

有用的标志：

  • --no-browser-使用基于终端的 TUI 而不是浏览器检查器。

  • --no-traces-禁用向写入痕迹agentcore/.cli/traces。

  • --logs-尾部服务器以非交互模式登录。

  • --port <N>-固定开发端口（HTTP 默认为 8080，MCP 默认为 8000，A2A 默认为 9000；忙时自动增量）。

步骤 4：部署代理

agentcore deploy

部署：

  1. 将你的代码打包到 zip 工件中（如果是则生成一个容器--build Container）

  2. 在幕后使用 AWS CDK 来合成和配置资源

  3. 为代理创建 AgentCore 运行时端点

  4. 配置 CloudWatch 日志记录和可观察性

首次部署需要几分钟，而 CDK 会引导您的帐户。后续部署速度更快。

无需部署即可预览将要更改的内容：

agentcore deploy --dry-run

检查状态：

agentcore status

步骤 5：调用已部署的代理

agentcore invoke --prompt "Hello, what can you do?"

如果您的代理已配置付款，请在调用时提供付款上下文：

agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com

这就是循环。迭代、使用测试app/MyAgent/main.py、使用部署agentcore devagentcore deploy、使用agentcore invoke调用。

为您的项目添加功能

agentcore add管理中的资源agentcore.json。在不带参数的情况下运行交互式菜单，或者直接定位资源。

agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider

每个 add 命令都会为配置提供支架，并提示输入所需的值。添加后agentcore deploy，运行配置。

深入了解您可以附加的功能：

查看日志和跟踪

# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>

清理

agentcore remove all
agentcore deploy

remove all重置配置。后续操作deploy会检测到空白状态并删除您账户中的资源。

后续步骤