# @aws/agentcore 中文文档

规范地址：https://npmcn.com/package/%40aws/agentcore/

版本：1\.0\.2
npm 元数据更新时间：2026-11-06T18:01:48.664Z
中文译文更新时间：2026-11-07T12:37:29.596Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws/agentcore
原文对照：https://npmcn.com/package/%40aws/agentcore/?lang=original
项目主页：https://github.com/aws/agentcore-cli#readme
源码仓库：https://github.com/aws/agentcore-cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：11.4 MB，102 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.12\.0
- 运行依赖：41 个
- peer 依赖：typescript ^5
- 首次发布：2026-02-12T21:52:10.880Z
- 最新版本发布：2026-11-06T18:01:48.192Z
- 近 30 天下载量：81779（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：101（近 12 个月 101 个）

## 中文简介

`agentcore` 是一个命令行工具和交互式终端 UI(TUI),用于 **[亚马逊贝德洛克代理公司](https://aws.amazon.com/bedrock/agentcore/)**,用于构建和运行生产AI代理的平台(\[文件\] ([https://docs.aws.amazon.com/bed (中文(简体) )](https://docs.aws.amazon.com/bed)

## 安装

```sh
npm install @aws/agentcore
```

也可以使用：`pnpm add @aws/agentcore`、`yarn add @aws/agentcore`、`bun add @aws/agentcore`

## README

# Core CLI探员

`agentcore` 是一个命令行工具和交互式终端 UI(TUI),用于 **[亚马逊贝德洛克代理公司](https://aws.amazon.com/bedrock/agentcore/)**,用于建造的平台 并运行 AI 代理[文档](https://docs.aws.amazon.com/bedrock-agentcore/)) (中文(简体) ).

它给你两种工作方式, 从同一个包:

-   **可脚本的 CLI** ——旗下命令并带有JSON输出(`--json`对于编码代理, 剧本和CI.
-   **交互式 TUI** ——引导资金流用于创建项目,浏览资源和聊天 与探员.

```bash
agentcore               # launch the interactive TUI
agentcore status --json # scriptable, machine-readable output
```

使用AgentCore API直接表示呼叫多个服务,设置执行角色,以及 处理流式响应. `agentcore` 注意这些细节,以便你能够创建,部署,以及 从你的终端调来特工.

## 安装

您需要节点( Node.js) 20. 12 或 稍后, 并配置为 AWS CLI 的 AWS 证书 。 Python 模板 还需要 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)。 。 。 .

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

如果安装了基于 Python 的 Bedrok Agent Core Starter 工具箱,则解开它: 两者都提供 `agentcore` 命令.

## 快速启动

某一项目拥有一种代理,或两者兼有:

-   A 类 **节奏** 是您在 YAML 中配置的一个管理代理人——模型、系统提示、工具、技能,以及 科雷特工为你跑.
-   A 类 **运行时间** 是特工代码,你拥有, 脚手架从模板 并为你部署.

创建一个项目,在其中添加一个哈内斯,部署,并发送一个快件:

```bash
agentcore create --name MyProject
cd MyProject
agentcore add harness --name MyAssistant
agentcore deploy
agentcore invoke --harness MyAssistant --prompt "Hey, what can you do for me?"
```

以CUSTOM JWT Harness为例,提供AWS的Harness查取证书和A管 援引的无记名标志:

```bash
printf '%s' "$JWT" | agentcore invoke \
  --harness MyAssistant-AbCdEf1234 \
  --region us-east-1 --bearer-token - --prompt "Hello"
```

同样的旗帜工作 `agentcore harness invoke --id <harness-id>`。也可以选择一个 由ARN调用 `agentcore invoke --harness <harness-arn>`但是CLI仍然抬头 它的配置在引用它之前. `--bearer-token file://<path>` 从文件中读取一个符号.

要从您拥有的代码开始,请选择一个模板(`agentcore create --help` 列出他们:

```bash
agentcore create --name MyAgent --template agent-python-strands
```

`agentcore create --template` 脚手架 模板与其默认模式提供者( Amazon) Bedrock 用于模型后置模板. 要使用另一个提供者, 运行 `agentcore create` 没有 旗帜:用于使用模型提供者的模板(`agent-python-strands` 联 合 国 `-container` 变体, `a2a-python-strands`, (中文(简体) ), `agui-python-strands`, (中文(简体) ), `agent-typescript-strands`巫师问 供货商(Amazon Bedrock、Anthropic、OpenAI、一个与OpenAI兼容的终点、双子座或 LiteLLM,即"只用Python"),型号id,和一个API-key文件. API 密钥保存在其中 `agentcore/.env.local` 并作为特工提供 核心身份证书的部署.

要将自己的代码带入一个项目,请为它添加一个运行时间:

```bash
agentcore add runtime --name search --language python   # or --language typescript
```

`add runtime` 不生成代码。 它创造了 `app/search/` 带有 `README.md` 还有一个 `AGENTS.md` 说明守则对所选内容的规定 `--protocol` (单位:千美元)`HTTP` 以 默认,或 `MCP`, (中文(简体) ), `A2A`, (中文(简体) ), `AGUI`,并登记运行时间 `agentcore.json` 开始 值(代码Zip基于最新的 Python 或 Node.js, 切入点) `main.py` 或者说 `main.js`) (中文(简体) ). 若为 `app/search/` 已存在, 您的文件将被单独保存, 而只添加缺失的文档 .

`agentcore dev`, (中文(简体) ), `agentcore build`,以及 `agentcore deploy` 然后更新 `agentcore.json` 从 代码和打印什么改变了。 添加一个 `Dockerfile` 切换运行时间到 a 集装箱建造. `requires-python` 内 `pyproject.toml` 或者说 `engines.node` 内 `package.json` 限制运行时的版本 : 仅在区域排除当前版本时更改, 然后 到最大版本,范围允许。 Python的入口来自 `[tool.agentcore] entrypoint` 内 `pyproject.toml`; TypeScript 总是从 `main.ts` 联合国 `package.json` `"main"` 联 合 国 `main.ts` 或者说 `main.js` 同意这一点,任何其他价值均被忽略 )),该词的原意是: 如果代码不说,值在 `agentcore.json` 保留.

运行 `agentcore create` 在任何现有项目之外.

## 项目

`create` 创建目录控件 `agentcore/agentcore.json`,宣布项目 资源,以及 `agentcore/cdk/`,部署它们的AWS CDK应用程序. 部署目标——账户 各个区域——生活在 `agentcore/aws-targets.json`。工程命令通过行走查找工程 从当前目录起起.

`agentcore dev` 本地运行运行时间或部署调取和打印参考指导. 使用 `--mode browser` 代理探长, `--skip-deploy` 重新使用已部署的系带, 财务报告和审定财务报表 `--agent <name>` 在混合项目中选择代理.

新的支付证书接收支付连接器可以参考的提供者名称. 现有付款证明书保留供应商ARN的部署记录 目标。 如果 ARN 与手动连接器不相容, 请先部署停止 提供任何东西。 以不同的名称和点添加付款证书 它的连接者,是旧的供货者,直到你取消其信誉为止 并部署每个受影响的目标.

## 图标

| 命令 | 目的 |
| --- | --- |
| `create`, (中文(简体) ), `add`, (中文(简体) ), `remove`, (中文(简体) ), `export`, (中文(简体) ), `migrate` | 创建工程, 添加或移除其资源, 导出资源到代码, 迁移 v0 项目 |
| `dev`, (中文(简体) ), `build`, (中文(简体) ), `deploy`, (中文(简体) ), `status` | 在当地运行、建造、部署和检查部署什么 |
| `invoke`, (中文(简体) ), `logs`, (中文(简体) ), `traces` | 与部署的特工谈话,检查他们的日志和痕迹 |
| `runtime`, (中文(简体) ), `harness`, (中文(简体) ), `gateway`, (中文(简体) ), `memory`, (中文(简体) ), `identity`, (中文(简体) ), `payment` | 检查和管理部署的资源,不论有无项目 |
| `eval` | 评价代理、管理数据集和配置以及进行实验 |
| `feedback`, (中文(简体) ), `config`, (中文(简体) ), `update` | 发送反馈、读取和写入 CLI 设置, 更新 CLI |

在终端中,一个没有旗帜的命令会打开其交互流;通过旗帜并运行 非交互性. `--help` 列出其子命令和旗帜,以及 [命令引用](https://npmcn.com/package/%40aws/agentcore/command.md) 拥有他们全部.

全球旗帜, 在每个命令上可用 :

| 旗帜 | 目的 |
| --- | --- |
| `--region` | AWS地区. 从这旗下决定的 `AWS_REGION`, (中文(简体) ), `AWS_DEFAULT_REGION`,那么活动简介 `us-east-1`。 。 。 . |
| `--json` | Emit JSON 而不是打开TUI. |
| `--debug` | 调试日志 . |

## 扩展 CDK 应用程序

`agentcore/cdk/` 有两个源文件. `bin/cdk.ts` 读过一次工程 (单位:千美元)`readAgentCoreProject`),每个部署目标制造一叠 (单位:千美元)`resolveTargetStacks`旋转 `agentcore.json` 输入应用程序的道具 (单位:千美元)`transformAgentCoreJson`) (中文(简体) ). 三个都来自 `@aws/agentcore-cdk`,这样 逻辑通过库更新,而不是更改您的 CDK 应用程序 .

`lib/cdk-stack.ts` 即兴演奏 `AgentCoreApplication`这是你的档案 编辑以添加自己的资源。 执行运行时间和利用 `iam.IGrantable`, (中文(简体) ), 因此,你可以把它们传递给资源 的CDK 赠与方法 给您的代理. 使用 `addEnvironmentVariable` 以传递资源名称、 ARN 或端点给您的代理.

此示例给出生成的运行时间命名 `agent` 访问表格:

```ts
import { AgentCoreApplication, type AgentCoreApplicationProps } from "@aws/agentcore-cdk";
import { Stack, type StackProps } from "aws-cdk-lib";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export interface AgentCoreStackProps extends StackProps {
  application: AgentCoreApplicationProps;
}

export class AgentCoreStack extends Stack {
  public readonly application: AgentCoreApplication;

  constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
    super(scope, id, props);
    this.application = new AgentCoreApplication(this, "Application", props.application);

    const orders = new dynamodb.Table(this, "Orders", {
      partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
    });
    const agent = this.application.runtime("agent");
    orders.grantReadWriteData(agent);
    agent.addEnvironmentVariable("ORDERS_TABLE", orders.tableName);
  }
}
```

用于一个和谐,使用 `this.application.harness("<name>")` 换句话说.

运行 `agentcore deploy` 来应用您的更改。 名字传到 `runtime()` 或者说 `harness()` 必须匹配您工程中的名称.

如果您使用已有的执行角色通过 `executionRoleArn`,CDK 无法 更改权限。 你需要在角色中加入必要的权限 你自己来.

请注意: `agentcore status` 仅报告资源 `agentcore.json` 声明,不是你们在堆放的.

## 文档

-   [命令参考](https://npmcn.com/package/%40aws/agentcore/command.md):每个命令和旗帜.
-   [策略项目配置](https://npmcn.com/package/%40aws/agentcore/docs/harness-project-configuration.md): 利用YAML,提示,工具,技能和环境设置.
-   [中国各区域](https://npmcn.com/package/%40aws/agentcore/docs/china-regions.md):那里有什么可用,限制是如何执行的.
-   [亚马逊 Bedrock Agent Core 文档](https://docs.aws.amazon.com/bedrock-agentcore/):服务指南和API参考.
-   [捐款](https://npmcn.com/package/%40aws/agentcore/CONTRIBUTING.md):开发、建设、建筑和测试.
-   [警卫](https://npmcn.com/package/%40aws/agentcore/SECURITY.md) • 妇女 [许可证](https://npmcn.com/package/%40aws/agentcore/LICENSE): Apache–2.0 (英语).

## 常见问题

### @aws/agentcore 是什么？

agentcore 是一个命令行工具和交互式终端 UI\(TUI\),用于 亚马逊贝德洛克代理公司,用于构建和运行生产AI代理的平台\(\[文件\] \(https://docs\.aws\.amazon\.com/bed \(中文\(简体\) \)

### 如何安装 @aws/agentcore？

在项目目录运行 npm install @aws/agentcore，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 agentcore，可以用 npx agentcore 直接运行。

### @aws/agentcore 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aws\_\_agentcore 是否存在。

### @aws/agentcore 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aws/agentcore 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws/agentcore 可以商用吗？

@aws/agentcore 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @aws/agentcore 的下载量有多少？

根据 npm 官方下载统计，@aws/agentcore 在 2026/10/08 – 2026/11/06 这 30 天内被下载 81,779 次，日均约 2,726 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws/agentcore 还在维护吗？

最新版本 1\.0\.2 发布于 2026/11/07（1 天前）；至今共发布 101 个版本，其中过去 12 个月发布了 101 个；首次发布于 2026/02/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。