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

# 开始使用 AgentCore CLI
<a name="runtime-get-started-cli"></a>

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

在同一 CLI 上 AgentCore构建代理的两种方法：
+  **托管式安全带**。你在配置文件（模型、提示、工具、内存）中声明代理，然后为你 AgentCore 运行循环。没有框架，没有编排代码。当你想以最快的方法从创意到运行代理时，这是一条不错的路径。[了解更多](harness.md)。
+  **Code-based 代理人**。你可以使用你已经知道的框架（Strands、 LangGraph谷歌 ADK 或 OpenAI 代理）在 Python 中编写代理循环，然后将其部署到运行时中。 AgentCore 完全控制编排逻辑。

本页介绍了基于代码的流程。有关安全带，请参阅[什么是 AgentCore 安全带](harness.md)。

## 注册参加 Amazon 账户
<a name="sign_up_for_an_shared_id_aws_account"></a>

### 注册参加 Amazon 账户
<a name="sign-up-for-aws"></a>

要开始使用 Amazon，您需要一个 Amazon 帐户。有关创建 Amazon 账户的信息，请参阅《 Amazon 账户管理参考指南》[中的* Amazon 账户*](https://docs.amazonaws.cn/accounts/latest/reference/getting-started.html)入门。

## 先决条件
<a name="agentcore-cli-prerequisites"></a>
+  **Node.js 20 或更高版本。**C AgentCore LI 作为 npm 包分发。与... 核对`node --version`。如果需要，从 [ nodejs.org ](https://nodejs.org) 安装。
+  **npm。**包含在 Node.js.
+  **配置了凭据的 Amazon 账户。**通过 Amazon CLI、环境变量或配置 Amazon 文件进行配置。请参阅[配置 Amazon CLI ](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-files.html)。
+  **Python 3.10 或更高版本**（用于代理代码）。与... 核对`python3 --version`。
+  **IAM 权限**。您的身份需要权限才能进行 AgentCore API 调用和承担部署期间使用的 CDK 引导角色。请参阅[使用 AgentCore CLI ](runtime-permissions.md#runtime-permissions-cli)。
+  **模型访问权限。**默认情况下，亚马逊 Bedrock 允许访问基础模型。可用模型包括亚马逊 Nova、Anthropic Claude、Meta Llama 和 Mistral AI 模型。要使用非基础模型，请按照[模型访问步骤](https://docs.amazonaws.cn/bedrock/latest/userguide/model-access.html#model-access-sdk-step4)进行操作。
+  **搬运工人。**仅在选择`Container`构建类型时才需要。默认编`CodeZip`译类型不需要 Docker。

## 第 1 步：安装 AgentCore CLI
<a name="agentcore-cli-install"></a>

```
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 ](https://github.com/aws/agentcore-cli)

## 第 2 步：创建您的项目
<a name="agentcore-cli-create"></a>

```
agentcore create
```

交互式向导首先询问你要构建什么：
+  **Har ** ness-基于托管配置的代理循环。无需框架或编排代码。参见[什么是 AgentCore 安全带](harness.md)。
+  **代理 **-使用您选择的框架的基于代码的代理，部署到 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 参考](agentcore-cli-reference.md)。

### 编译类型
<a name="deployment-modes"></a>
+  `CodeZip`（默认）将您的代码打包到压缩文件中并将其上传到 Amazon S3。这种编译类型不需要 Docker。
+  `Container`构建和部署容器镜像。这种编译类型需要一个正在运行的 Docker 守护程序。

### 项目结构
<a name="agentcore-cli-project-structure"></a>

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

**Example**  

```
MyProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyAgent/
        ├── main.py
        ├── pyproject.toml
        ├── README.md
        ├── model/
        ├── mcp_client/
        └── skills/
```

```
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`-用于部署的 Amazon 账户和区域。
+  `agentcore/.env.local`-本地机密，例如模型提供者的 API 密钥。
+  `app/`-应用程序目录。基于代码的代理包含入口点和依赖关系。安全带包含`harness.json`和`system-prompt.md`。

## 第 3 步：在本地测试
<a name="agentcore-cli-test"></a>

```
cd MyProject
agentcore dev
```

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

## 第 4 步：部署您的代理
<a name="agentcore-cli-deploy"></a>

```
agentcore deploy
```

部署：

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

1. 在幕后使用 Amazon CDK 来合成和配置资源

1. 为您的代理创建 AgentCore 运行时终端节点

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

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

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

```
agentcore deploy --dry-run
```

检查状态：

```
agentcore status
```

## 第 5 步：调用已部署的代理
<a name="agentcore-cli-invoke"></a>

```
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 dev``agentcore deploy`、使用调用`agentcore invoke`。

### 以编程方式调用代理
<a name="invoke-programmatically"></a>

您可以使用 Amazon SDK [ InvokeAgentRuntime ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) 操作调用已部署的代理。获取代理运行时 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`而不是使用软件开发工具包。 Amazon 有关更多信息，请参阅[使用入站和出站授权进行身份验证和授权](runtime-oauth.md)。

## 为您的项目添加功能
<a name="agentcore-cli-add-capabilities"></a>

 `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`，运行配置。

深入了解您可以附加的功能：
+  [AgentCore 记忆 ](memory.md)-短期和长期记忆，检索策略
+  [AgentCore 网关 ](gateway.md)-与 API 和 MCP 服务器的受控连接
+  [AgentCore 浏览器 ](browser-tool.md)-代理的托管网页浏览
+  [AgentCore 代码解释器 ](code-interpreter-tool.md)-沙盒代码执行
+  [AgentCore 身份 ](identity.md)-OAuth、API 密钥凭证提供商、工作负载身份
+  [AgentCore 可观测性 ](observability.md)-中的跟踪、日志和指标 CloudWatch
+  [AgentCore VPC ](agentcore-vpc.md)-在您的 VPC 内运行代理
+  [AgentCore 付款 ](payments.md)-通过 x402 向代理商进行微交易付款

## 查看日志和跟踪
<a name="agentcore-cli-logs"></a>

```
# 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>
```

## 故障排除
<a name="common-issues"></a>

 **权限被拒绝错误 **   
使用验证您的证书`aws sts get-caller-identity`。确保您的身份具有 “[使用 AgentCore CLI” 中的权限](runtime-permissions.md#runtime-permissions-cli)。

 **模型访问被拒绝 **   
默认情况下，亚马逊 Bedrock 允许访问基础模型。要使用非基础模型，请按照[模型访问步骤](https://docs.amazonaws.cn/bedrock/latest/userguide/model-access.html#model-access-sdk-step4)进行操作。

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

 **端口已在使用中 **   
运行`agentcore dev --port 3000`以使用不同的本地端口。

 **配置验证错误 **   
运行`agentcore validate`以检查项目配置。

有关更多信息，请参阅 Amazon Bedrock AgentCore 运行时[AgentCore 运行时故障排除](runtime-troubleshooting.md)疑难解答。

## 清理
<a name="agentcore-cli-cleanup"></a>

```
agentcore remove all
agentcore deploy
```

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

## 后续步骤
<a name="agentcore-cli-next-steps"></a>
+  [什么是 AgentCore 安全带 ](harness.md)-运行代理的基于配置的路径。使用任何模型，连接到工具，保持状态，在您的 VPC 中部署，并在需要时升级到代码。
+  [AgentCore 代码示例 ](https://github.com/awslabs/amazon-bedrock-agentcore-samples)-跨框架和功能的端到端示例。