View a markdown version of this page

开始使用 CL AgentCore I - Amazon Bedrock AgentCore
先决条件步骤 1：安装 AgentCore CLI第 2 步：创建您的代理项目步骤 3：在本地测试您的代理步骤 4：为代理启用可观察性第 5 步：部署到 Amazon 基岩运行 AgentCore 时步骤 6：测试已部署的代理步骤 7：调用已部署的代理步骤 8：清除查找资源常见问题和解决方案高级选项（可选）

开始使用 CL AgentCore I

本教程向您展示如何使用 AgentCore CLI 在 Amazon Bedrock AgentCore Runtime 上创建、部署和调用 Python 代理。

AgentCore CLI 是一个命令行工具，用于构建代理项目，将其部署到 Amazon B AgentCore edrock Runtime 并调用它们。你可以将 CLI 与流行的 Python 代理框架一起使用，例如 Strands Agents LangChain/LangGraph、Google ADK 和 OpenAI 代理。本教程使用 Strands Agents。

有关代理使用的 HTTP 协议的信息，请参阅 HTTP 协议合同。

先决条件

在开始之前，请确保你有：

  • AWS 已配置凭据的@@ 账户。要配置您的 AWS 证书，请参阅 AWS CLI 中的配置和凭证文件设置。

  • Node.js 已安装 20 多个。C AgentCore LI 以 npm 包的形式分发。

  • 已@@ 安装 Python 3.10+。生成的代理代码是 Python。

  • AWS CDK 已安装。CLI 使用 AWS CDK 来部署资源。有关信息，请参阅 AWS CDK 入门。

  • AWS 权限：要使用 AgentCore CLI 创建和部署代理，必须具有相应的权限。有关信息，请参阅使用 AgentCore CLI。

  • 模型访问权限：在亚马逊 Bedrock 控制台中启用 Anthropic Claude Sonnet 4.0（如果使用 Bedrock 作为模型提供商）。有关在 Strands Agents 中使用其他模型的信息，请参阅 Strands Agent s SDK 文档中的模型提供者部分。

步骤 1：安装 AgentCore CLI

在全球范围内安装 AgentCore CLI：

npm install -g @aws/agentcore

验证安装：

agentcore --help

您应该可以看到类似于如下所示的输出内容：

Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

第 2 步：创建您的代理项目

使用agentcore create命令搭建一个新的代理项目：

例
AgentCore CLI

  1. 直接传递标志以非交互方式创建项目：

    agentcore create --name MyAgent --framework Strands --protocol HTTP --model-provider Bedrock --memory none

    要接受所有默认值（Python、Strands、Bedrock、无内存），请使用以下--defaults标志：

    agentcore create --name MyAgent --defaults
Interactive

  1. agentcore create不带标志运行以启动交互式向导：

    agentcore create

  2. 输入您的项目名称：

    创建向导：输入项目名称

  3. 选择您的代理框架和模型提供商：

    创建向导：选择框架

  4. 检查您的配置并确认：

    创建向导：查看并确认

该agentcore create命令接受以下标志：

  • --name— 项目名称（字母数字，以字母开头，最多 36 个字符）。

  • --framework— 代理框架。支持的值：Strands、LangChain_LangGraph、GoogleADK、OpenAIAgents。

  • --protocol— 协议模式。支持的值：HTTP（默认）、MCP、A2A。

  • --build— 构建类型。支持的值：CodeZip（默认）、Container。

  • --model-provider— 模型提供商。支持的值：Bedrock、Anthropic、OpenAI、Gemini。

  • --memory— 内存配置。支持的值：none、shortTerm、longAndShortTerm。

该命令生成一个具有以下结构的项目目录：

MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

该agentcore/agentcore.json文件包含您的项目和代理配置。该app/MyAgent/main.py文件包含使用所选框架的入门代理代码。

要为项目添加支付功能，请运行：

agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

这将在您的代理AgentCorePaymentsPlugin中配置，并在部署时配置支付基础架构。有关完整的工作流程，请参阅 “付款快速入门”。

步骤 3：在本地测试您的代理

在部署到之前 AWS，请使用开发服务器在本地测试您的代理。首先，进入项目目录：

cd MyAgent

如果您选择了需要 API 密钥的模型提供者（OpenAI、Anthropic 或 Gemini），请确保在中配置了密钥。agentcore/.env.local

启动本地开发服务器：

例
AgentCore CLI

  1. agentcore dev
Interactive

  1. 运行agentcore打开 TUI 主屏幕，然后选择 dev 启动本地开发服务器：

    agentcore
    AgentCore 带有聊天提示的代理检查员

agentcore dev命令：

  • 在 Web 浏览器中打开代理检查器

  • 自动创建 Python 虚拟环境并安装依赖关系

  • 启动模仿 AgentCore 运行时环境的本地服务器

  • http://localhost:8080默认情况下运行（用于-p更改端口）

要实时查看服务器日志（非交互模式），请使用以下--logs标志：

agentcore dev --logs

在单独的终端中，调用您的本地代理：

agentcore dev "Hello, tell me a joke"

传递提示会将其发送到正在运行的本地开发服务器。用于--stream查看实时流式传输的响应。

步骤 4：为代理启用可观察性

Amazon Bedrock 可 AgentCore 观测性可帮助您跟踪、调试和监控您在亚马逊 Bedro AgentCore ck Runtime 中托管的代理。首先按照启用 Amazon Bedrock AgentCore 运行时可观察性中的说明启用 CloudWatch 交易搜索。要观察您的代理，请参阅查看您的 Amazon Bedrock AgentCore 代理的可观察性数据。

部署代理后，您可以使用 AgentCore CLI 流式传输日志和查看跟踪：

# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

第 5 步：部署到 Amazon 基岩运行 AgentCore 时

将您的代理部署到 Amazon Bedrock AgentCore 运行时：

例
AgentCore CLI

  1. agentcore deploy
Interactive

  1. 运行agentcore deploy开始部署。CLI 会在构建和部署项目时显示部署进度：

    agentcore deploy
    部署进度： CloudFormation 资源创建和部署状态

要在不进行更改的情况下预览部署，请使用以下--dry-run标志：

agentcore deploy --dry-run

agentcore deploy命令：

  • 读取您的agentcore/agentcore.json和agentcore/aws-targets.json配置

  • 打包您的代理代码（作为 CodeZip 存档或 Docker 容器，具体取决于您的构建类型）

  • 使用 AWS CDK 合成和部署资源 CloudFormation

  • 创建必要的 AWS 资源（IAM 角色、Amazon Bedrock AgentCore 运行时等）

-v用于显示资源级部署事件的详细输出。-y用于在没有提示的情况下自动确认部署。

如果部署失败，请检查常见问题。

步骤 6：测试已部署的代理

部署完成后，调用已部署的代理：

例
AgentCore CLI

  1. agentcore invoke "Tell me a joke"

    你也可以使用--prompt标志传递提示，使用指定运行时间--runtime，或者使用以下命令实时流式传输响应--stream：

    agentcore invoke --prompt "Tell me a joke" --stream

    要在多个调用之间保持对话，请使用以下--session-id标志：

    agentcore invoke --session-id my-session "What else can you tell me?"

    如果您的代理已配置付款，请提供付款背景：

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

  1. 运行agentcore打开 TUI 主屏幕，然后选择调用选项与已部署的代理聊天：

    agentcore
    调用 TUI 屏幕显示聊天界面

如果您在响应中看到一个笑话，则说明您的代理正在 Amazon Bedrock AgentCore Runtime 中运行，并且可以被调用。如果不是，请检查常见问题。

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

例
AgentCore CLI

  1. 使用提示调用已部署的代理：

    agentcore invoke --runtime MyAgent "Hello, what can you do?"

    实时流式传输响应：

    agentcore invoke --runtime MyAgent "Tell me a joke" --stream

    在不提示打开交互式聊天 TUI agentcore invoke 的情况下运行，默认情况下，它会流式传输响应并自动维护您的会话。

AWS Python SDK (Boto3)

  1. 您也可以使用 AWS SDK InvokeAgentRuntime操作调用代理。要获取已部署代理的 ARN，请使用以下命令：agentcore status

    agentcore status

    使用以下 boto3（AWS 适用于 Python 的 SDK）代码来调用您的代理。Agent ARN替换为代理的 ARN。确保您拥有bedrock-agentcore:InvokeAgentRuntime权限。创建一个名为的文件invoke_agent.py并添加以下代码：

    import json
import uuid
import boto3

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

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

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

    打开终端窗口，使用以下命令运行代码：

    python invoke_agent.py

    如果成功，你应该会在回复中看到一个笑话。如果通话失败，请使用查看日志agentcore logs或在 Amazon 中查看 CloudWatch。

    注意

    如果您计划将代理与 OAuth 集成，则无法使用 AWS SDK 进行调用。InvokeAgentRuntime相反，请向发出 HTTPS 请求InvokeAgentRuntime。有关更多信息，请参阅使用入站身份验证和出站身份验证进行身份验证和授权。

步骤 8：清除

如果您不想再在 Amazon Bedrock AgentCore Runtime 中托管代理，请移除已部署的 AWS 资源。首先，从本地配置中删除所有资源：

例
AgentCore CLI

  1. agentcore remove all
Interactive

  1. 运行agentcore打开 TUI 主屏幕，然后选择删除选项以选择要删除的资源：

    agentcore
    移除资源选择 TUI

然后再次部署以拆除 AWS 资源：

例
AgentCore CLI

  1. agentcore deploy
Interactive

  1. 在 AgentCore CLI 主屏幕上deploy，选择应用删除并删除 AWS 资源：

    部署进度： CloudFormation 资源删除和拆卸状态

该remove all命令在保留agentcore/aws-targets.json和部署状态的同时重置agentcore/agentcore.json配置文件。随后会deploy检测已删除的资源并删除相应的 AWS 资源。

查找资源

部署后，您可以使用 AgentCore CLI 检查资源状态：

例
AgentCore CLI

  1. agentcore status
Interactive

  1. 运行agentcore并选择status查看包含所有已部署资源的实时仪表板：

    agentcore
    AgentCore CLI TUI 状态控制面板

您还可以在 AWS 控制台中查看您的资源：

资源 位置

代理日志

CloudWatch → 日志组 → /aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT

CloudFormation 堆栈

CloudFormation → Stacks → 搜索你的项目名称

IAM 角色

IAM → 角色 → 搜索 “BedrockAgentCore”

S3 资产 (CodeZip)

S3 → 存储桶 → CDK 暂存存储桶

常见问题和解决方案

AgentCore CLI 入门时的常见问题和解决方案。有关更多疑难解答信息，请参阅 Amazon Bedrock AgentCore 运行时疑难解答。

权限被拒绝错误

验证您的 AWS 凭证和权限：

  • 验证 AWS 凭据：aws sts get-caller-identity

  • 检查您是否附上了所需的政策

  • 查看来电者权限政策，了解详细要求

模型访问被拒绝

在 Bedrock 控制台中启用模型访问权限：

  • 在基岩控制台中启用 Anthropic Claude 4.0

  • 确保你位于正确的 AWS 区域（默认为 us-west-2）

CDK 部署错误

检查 CDK 设置和权限：

  • 确保你已经启动了 CDK AWS 账号：cdk bootstrap

  • 验证您的来电者权限包括 CloudFormation 和 CDK 访问权限

  • agentcore deploy -v用于详细输出以识别故障资源

正在使用端口 8080（仅限本地）

查找并停止使用端口 8080 的进程：

用于lsof -ti:8080获取使用端口 8080 的进程列表。

kill -9 PID用于停止进程。PID替换为进程 ID。

或者，在不同的端口上启动开发服务器：agentcore dev -p 3000

区域不匹配

使用验证 AWS 区域，aws configure get region并确保其中的区域与您的资源应部署位置agentcore/aws-targets.json相匹配。

配置验证错误

验证您的配置文件：

agentcore validate用于检查agentcore/agentcore.json和相关配置文件中的语法或架构错误。

高级选项（可选）

使用创建代理项目后agentcore create，您可以使用agentcore add命令对其进行扩展。有关完整的 CLI 参考，请参阅 AgentCore CLI 文档。

构建类型

创建项目时，请选择适合您需求的构建类型：

CodeZip （默认值）

您的代理代码打包为 zip 存档并上传到 S3。这是最简单的选项，不需要 Docker：

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

您的代理代码打包为 Docker 容器镜像。当您需要自定义系统级依赖项或特定的基础映像时，请使用此选项：

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

向您的项目添加资源

在创建项目后，您可以向项目添加其他资源：

# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

添加资源后，在中运行agentcore deploy配置新资源 AWS。

为什么 ARM64？

亚马逊 Bedrock AgentCore Runtime 在 ARM64（AWS Graviton）上运行。C AgentCore LI 会自动处理 CodeZip 和容器构建类型的架构兼容性。对于容器构建，只有为 ARM64 构建的映像在部署到 Amazon Bedrock AgentCore Runtime 时才能运行。