View a markdown version of this page

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

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

开始使用 AgentCore CLI

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

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

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

  • Code-based 代理人。你可以使用你已经知道的框架（Strands、 LangGraph谷歌 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 文件进行配置。请参阅配置 AWS CLI 。

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

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

  • 模型访问权限。默认情况下，亚马逊 Bedrock 允许访问基础模型。可用模型包括亚马逊 Nova、Anthropic Claude、Meta Llama 和 Mistral AI 模型。要使用非基础模型，请按照模型访问步骤进行操作。

  • 搬运工人。仅在选择Container构建类型时才需要。默认编CodeZip译类型不需要 Docker。

第 1 步：安装 AgentCore CLI

npm install -g @aws/agentcore

验证:

agentcore --version
注意

如果这报告的是错误而不是版本号，则旧的 Python agentcore 命令会掩盖你PATH的 npm 命令。如果你之前安装了 bedrock-agentcore-starter-toolkit pip 包，就会发生这种情况，并且在 Windows 上最常见。运行pip uninstall bedrock-agentcore-starter-toolkit，然后打开一个新终端并重试。

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

第 2 步：创建您的项目

agentcore create

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

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

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

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

如果选择代理，向导将继续：

  • 框架 -Strands 代理（推荐） LangChain/LangGraph、谷歌代理开发套件或 OpenAI 代理 SDK

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

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

  • 编译类型 - CodeZip （默认）或容器

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

agentcore create \
  --project-name MyProject \
  --name MyAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

有关所有可用的命令和选项，请参阅 AgentCore CLI 参考。

编译类型

  • CodeZip（默认）将您的代码打包到压缩文件中并将其上传到 Amazon S3。这种编译类型不需要 Docker。

  • Container构建和部署容器镜像。这种编译类型需要一个正在运行的 Docker 守护程序。

项目结构

agentcore create为基于代码的代理和工具生成共享的项目配置和不同的应用程序结构：

例
Code-based agent
MyProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyAgent/
        ├── main.py
        ├── pyproject.toml
        ├── README.md
        ├── model/
        ├── mcp_client/
        └── skills/
Harness
MyHarnessProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyHarness/
        ├── harness.json
        └── system-prompt.md

密钥文件：

  • agentcore/agentcore.json-主配置文件。它定义了您的代理、线束、内存存储、网关、凭证和其他资源。agentcore add和agentcore remove命令管理此文件。

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

  • agentcore/.env.local-本地机密，例如模型提供者的 API 密钥。

  • app/-应用程序目录。基于代码的代理包含入口点和依赖关系。安全带包含harness.json和system-prompt.md。

第 3 步：在本地测试

cd MyProject
agentcore dev

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

第 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。

以编程方式调用代理

您可以使用 AWS SDK InvokeAgentRuntime 操作调用已部署的代理。获取代理运行时 ARN：

agentcore status

创建一个名为 invoke_agent.py的文件。Agent ARN替换为您的代理的 ARN：

import json
import uuid

import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": prompt}).encode(),
    qualifier="DEFAULT",
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode("utf-8"))

print(json.loads("".join(content)))

运行代码：

python invoke_agent.py

您的身份必须bedrock-agentcore:InvokeAgentRuntime获得许可。

注意

对于使用 OAuth 的代理，请向发出 HTTPS 请求，InvokeAgentRuntime而不是使用软件开发工具包。 AWS 有关更多信息，请参阅使用入站和出站授权进行身份验证和授权。

为您的项目添加功能

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>

故障排除

权限被拒绝错误

使用验证您的证书aws sts get-caller-identity。确保您的身份具有 “使用 AgentCore CLI” 中的权限。

模型访问被拒绝

默认情况下，亚马逊 Bedrock 允许访问基础模型。要使用非基础模型，请按照模型访问步骤进行操作。

部署错误

运行agentcore deploy --verbose以显示资源级部署事件。CLI 检查 AWS CDK 引导状态。如果需要引导，则交互式部署会要求确认。agentcore deploy --yes在没有提示的情况下批准引导操作。

端口已在使用中

运行agentcore dev --port 3000以使用不同的本地端口。

配置验证错误

运行agentcore validate以检查项目配置。

有关更多信息，请参阅 Amazon Bedrock AgentCore 运行时AgentCore 运行时故障排除疑难解答。

清理

agentcore remove all
agentcore deploy

remove all重置配置。后续行动deploy会检测到空白状态并销毁您账户中的资源。

后续步骤