# 开始使用 Amazon Bedrock AgentCore
<a name="agentcore-get-started-cli"></a>

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

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

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

## 注册获取 AWS 账户
<a name="sign_up_for_an_shared_id_aws_account"></a>

### 注册获取 AWS 账户
<a name="sign-up-for-aws"></a>

要开始使用 AWS，您需要一个 AWS 帐户。有关创建 AWS 账户的信息，请参阅《[AWS 账户*管理参考指南》中的 AWS 账户*入门](https://docs.aws.amazon.com/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。
+  **配置了凭据的 AWS 账户。**通过 AWS CLI、环境变量或配置 AWS 文件进行配置。参见[配置 C AWS LI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)。
+  **Python 3.10 或更高版本**（用于代理代码）。请与... 核`python3 --version`对。
+  **IAM 权限**。您的身份需要权限才能进行 AgentCore API 调用和代入部署期间使用的 CDK 引导角色。请参阅 [AgentCore CLI IAM 权限](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/security-iam.html)。

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

```
npm install -g @aws/agentcore
```

验证:

```
agentcore --version
```

要稍后更新，请重新运行安装命令或`agentcore update`。来源和问题：[agentcor](https://github.com/aws/agentcore-cli) e-cli 已开启。 GitHub

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

```
agentcore create
```

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

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

 `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 步：在本地测试
<a name="agentcore-cli-test"></a>

```
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：部署代理
<a name="agentcore-cli-deploy"></a>

```
agentcore deploy
```

部署：

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

1. 在幕后使用 AWS 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="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 记忆](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html)-短期和长期记忆、检索策略
+  [AgentCore 网关](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html)-与 API 和 MCP 服务器的连接受管制
+  [AgentCore 浏览器](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html)-代理的托管网页浏览
+  [AgentCore 代码解释器](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html)-沙盒代码执行
+  [AgentCore 身份](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html)-OAuth、API 密钥凭证提供商、工作负载身份
+  [AgentCore 可观察性](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html)-中的跟踪、日志和指标 CloudWatch
+  [AgentCore VPC](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html)-在您的 VPC 内运行代理
+  [AgentCore 付款](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html)-通过 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="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)-跨框架和功能的端到端示例。