# 开始使用 CL AgentCore I
本教程向您展示如何使用 [AgentCore CLI](https://github.com/aws/agentcore-cli) 在 Amazon Bedrock AgentCore Runtime 上创建、部署和调用 Python 代理。
AgentCore CLI 是一个命令行工具，用于构建代理项目，将其部署到 Amazon B AgentCore edrock Runtime 并调用它们。你可以将 CLI 与流行的 Python 代理框架一起使用，例如 [Strands Agents LangChain/LangGraph、Google ADK 和 OpenAI 代](https://strandsagents.com/latest/documentation/docs/)理。本教程使用 Strands Agents。
有关代理使用的 HTTP 协议的信息，请参阅 [HTTP 协议合同](runtime-http-protocol-contract.md)。
**Topics**
+ [先决条件](#prerequisites)
+ [步骤 1：安装 AgentCore CLI](#setup-project)
+ [第 2 步：创建您的代理项目](#create-agent)
+ [步骤 3：在本地测试您的代理](#configure-agent)
+ [步骤 4：为代理启用可观察性](#enable-observability)
+ [第 5 步：部署到 Amazon 基岩运行 AgentCore 时](#deploy-runtime)
+ [步骤 6：测试已部署的代理](#test-deployed-agent)
+ [步骤 7：调用已部署的代理](#invoke-programmatically)
+ [步骤 8：清除](#stop-session-or-clean-up)
+ [查找资源](#find-resources)
+ [常见问题和解决方案](#common-issues)
+ [高级选项（可选）](#advanced-options)
## 先决条件
在开始之前，请确保你有：
+ AWS 已配置凭据的@@ **账户**。要配置您的 AWS 证书，请参阅 [AWS CLI 中的配置和凭证文件设置](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)。
+ Node.js 已安装 **20 多**个。C AgentCore LI 以 npm 包的形式分发。
+ 已@@ **安装 Python 3.10\+**。生成的代理代码是 Python。
+ ** AWS CDK** 已安装。CLI 使用 AWS CDK 来部署资源。有关信息，请参阅 [AWS CDK 入门](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)。
+ ** AWS 权限**：要使用 AgentCore CLI 创建和部署代理，必须具有相应的权限。有关信息，请参阅[使用 AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli)。
+ **模型访问权限**：在亚马逊 Bedrock 控制台中[启用](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) Anthropic Claude Sonnet 4.0（如果使用 Bedrock 作为模型提供商）。有关在 Strands Agents 中使用其他模型的信息，请参阅 Strands Agent [s SDK 文档](https://strandsagents.com/latest/documentation/docs/)中的*模型提供者*部分。
## 步骤 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`命令搭建一个新的代理项目：
**Example**
1. 直接传递标志以非交互方式创建项目：
```
agentcore create --name MyAgent --framework Strands --protocol HTTP --model-provider Bedrock --memory none
```
要接受所有默认值（Python、Strands、Bedrock、无内存），请使用以下`--defaults`标志：
```
agentcore create --name MyAgent --defaults
```
1. `agentcore create`不带标志运行以启动交互式向导：
```
agentcore create
```
1. 输入您的项目名称：
1. 选择您的代理框架和模型提供商：
1. 检查您的配置并确认：
该`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 --api-key-secret --wallet-secret
```
这将在您的代理`AgentCorePaymentsPlugin`中配置，并在部署时配置支付基础架构。有关完整的工作流程，请参阅 “[付款快速入门](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-getting-started.html)”。
## 步骤 3：在本地测试您的代理
在部署到之前 AWS，请使用开发服务器在本地测试您的代理。首先，进入项目目录：
```
cd MyAgent
```
如果您选择了需要 API 密钥的模型提供者（OpenAI、Anthropic 或 Gemini），请确保在中配置了密钥。`agentcore/.env.local`
启动本地开发服务器：
**Example**
1.
```
agentcore dev
```
1. 运行`agentcore`打开 TUI 主屏幕，然后选择 **dev** 启动本地开发服务器：
```
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 观测性](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html)可帮助您跟踪、调试和监控您在亚马逊 Bedro AgentCore ck Runtime 中托管的代理。首先按照启用 [Amazon Bedrock AgentCore 运行时可观察性中的说明启用 CloudWatch ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin)交易搜索。要观察您的代理，请参阅[查看您的 Amazon Bedrock AgentCore 代理的可观察性数据](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html)。
部署代理后，您可以使用 AgentCore CLI 流式传输日志和查看跟踪：
```
# Stream agent logs
agentcore logs
# List recent traces
agentcore traces list
```
## 第 5 步：部署到 Amazon 基岩运行 AgentCore 时
将您的代理部署到 Amazon Bedrock AgentCore 运行时：
**Example**
1.
```
agentcore deploy
```
1. 运行`agentcore deploy`开始部署。CLI 会在构建和部署项目时显示部署进度：
```
agentcore deploy
```
要在不进行更改的情况下预览部署，请使用以下`--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`用于在没有提示的情况下自动确认部署。
如果部署失败，请检查[常见问题](#common-issues)。
## 步骤 6：测试已部署的代理
部署完成后，调用已部署的代理：
**Example**
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 \
--auto-session \
--payment-user-id user@example.com
```
1. 运行`agentcore`打开 TUI 主屏幕，然后选择调用选项与已部署的代理聊天：
```
agentcore
```
如果您在响应中看到一个笑话，则说明您的代理正在 Amazon Bedrock AgentCore Runtime 中运行，并且可以被调用。如果不是，请检查[常见问题](#common-issues)。
## 步骤 7：调用已部署的代理
**Example**
1. 使用提示调用已部署的代理：
```
agentcore invoke --runtime MyAgent "Hello, what can you do?"
```
实时流式传输响应：
```
agentcore invoke --runtime MyAgent "Tell me a joke" --stream
```
在不提示打开交互式聊天 TUI `agentcore invoke` 的情况下运行，默认情况下，它会流式传输响应并自动维护您的会话。
1. 您也可以使用 AWS SDK [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)操作调用代理。要获取已部署代理的 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`。有关更多信息，请参阅[使用入站身份验证和出站身份验证进行身份验证和授权](runtime-oauth.md)。
## 步骤 8：清除
如果您不想再在 Amazon Bedrock AgentCore Runtime 中托管代理，请移除已部署的 AWS 资源。首先，从本地配置中删除所有资源：
**Example**
1.
```
agentcore remove all
```
1. 运行`agentcore`打开 TUI 主屏幕，然后选择删除选项以选择要删除的资源：
```
agentcore
```
然后再次部署以拆除 AWS 资源：
**Example**
1.
```
agentcore deploy
```
1. 在 AgentCore CLI 主屏幕上`deploy`，选择应用删除并删除 AWS 资源：
该`remove all`命令在保留`agentcore/aws-targets.json`和部署状态的同时重置`agentcore/agentcore.json`配置文件。随后会`deploy`检测已删除的资源并删除相应的 AWS 资源。
## 查找资源
部署后，您可以使用 AgentCore CLI 检查资源状态：
**Example**
1.
```
agentcore status
```
1. 运行`agentcore`并选择`status`查看包含所有已部署资源的实时仪表板：
```
agentcore
```
您还可以在 AWS 控制台中查看您的资源：
| 资源 | 位置 |
| --- | --- |
| **代理日志** | CloudWatch → 日志组 → `/aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT` |
| **CloudFormation 堆栈** | CloudFormation → Stacks → 搜索你的项目名称 |
| **IAM 角色** | IAM → 角色 → 搜索 “BedrockAgentCore” |
| **S3 资产 (CodeZip)** | S3 → 存储桶 → CDK 暂存存储桶 |
## 常见问题和解决方案
AgentCore CLI 入门时的常见问题和解决方案。有关更多疑难解答信息，请参阅 [Amazon Bedrock AgentCore 运行时疑难解答](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-troubleshooting.html)。
**权限被拒绝错误**
验证您的 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 文档](https://github.com/aws/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 时才能运行。