# alibabacloud-agentcore-sdk 中文文档

规范地址：https://npmcn.com/package/alibabacloud-agentcore-sdk/

版本：0\.1\.8
npm 元数据更新时间：2026-11-03T02:02:48.621Z
中文译文更新时间：2026-11-03T02:39:24.907Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.5 MB，219 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.3\.0
- 运行依赖：12 个
- peer 依赖：ai ^6\.0\.277，zod ^4\.5\.4，langchain ^1\.5\.10，@google/adk ^2\.0\.0，@mastra/core ^1\.64\.0，@google/genai ^2\.21\.0，@ai-sdk/openai ^3\.0\.109，@langchain/core ^1\.2\.9，@ai-sdk/provider ^3\.0\.15，@ai-sdk/anthropic ^3\.0\.116，@langchain/openai ^1\.5\.11，@langchain/anthropic ^1\.5\.9，@langchain/langgraph ^1\.4\.14，@ai-sdk/openai-compatible ^2\.0\.74
- 首次发布：2026-09-10T06:52:47.980Z
- 最新版本发布：2026-11-03T02:02:48.316Z
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

AgentCore运行时SDK用于Node.js

## 安装

```sh
npm install alibabacloud-agentcore-sdk
```

也可以使用：`pnpm add alibabacloud-agentcore-sdk`、`yarn add alibabacloud-agentcore-sdk`、`bun add alibabacloud-agentcore-sdk`

## README

# AgentCore SDK for Node.js

使用 TypeScript 或 JavaScript 构建 Agent，连接 AgentCore 云端资源或自有服务，并与常用 Agent 框架集成。

[AgentCore 官网](https://www.aliyun.com/product/agentcore) · [官方文档](https://help.aliyun.com/zh/agentcore/) · [示例指南](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/README.md)

## 从这里开始

| 你想做什么 | 入口 |
| --- | --- |
| 连接平台上的模型、MCP 和 Skill | [云端资源](https://npmcn.com/package/alibabacloud-agentcore-sdk/#readme-%E4%BD%BF%E7%94%A8%E4%BA%91%E7%AB%AF%E8%B5%84%E6%BA%90) |
| 在部署时选择模型、模版、MCP 和 Skill | [环境变量配置](https://npmcn.com/package/alibabacloud-agentcore-sdk/#readme-%E9%80%9A%E8%BF%87%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E9%80%89%E6%8B%A9%E8%B5%84%E6%BA%90) |
| 使用自己的模型、MCP 或本地 Skill | [自定义资源](https://npmcn.com/package/alibabacloud-agentcore-sdk/#readme-%E4%BD%BF%E7%94%A8%E8%87%AA%E5%AE%9A%E4%B9%89%E8%B5%84%E6%BA%90) |
| 为 Agent 添加长期记忆 | [Memory](https://npmcn.com/package/alibabacloud-agentcore-sdk/#readme-%E4%BD%BF%E7%94%A8-memory) |
| 配置 MCP 凭证与固定 Header | [凭证与 Header](https://npmcn.com/package/alibabacloud-agentcore-sdk/#readme-%E5%87%AD%E8%AF%81%E4%B8%8E-mcp-header) |
| 接入已有 Agent 框架 | [框架集成](https://npmcn.com/package/alibabacloud-agentcore-sdk/#readme-%E6%A1%86%E6%9E%B6%E9%9B%86%E6%88%90) |
| 将 Agent 发布为 HTTP 服务 | [服务协议](https://npmcn.com/package/alibabacloud-agentcore-sdk/#readme-%E6%8F%90%E4%BE%9B-agent-%E6%9C%8D%E5%8A%A1) |

## 功能

-   **模型**：访问托管模型，或连接自定义模型服务。
-   **工具与 Skill**：接入 MCP 服务，使用云端或随应用分发的 Skill。
-   **记忆**：检索和保存长期记忆，接入框架的 Agent 执行流程。
-   **凭证**：按名称获取托管 API Key，或为 MCP 显式绑定 Header 凭证。
-   **服务协议**：通过 AG-UI 或 OpenAI Chat Completions 提供 Agent 服务。

支持 LangChain、LangGraph、Google ADK、Mastra 和 AI SDK。

## 安装

基础 SDK 需要 Node.js 20.3+；使用全部框架示例建议 Node.js 22.22+。

```bash
npm install alibabacloud-agentcore-sdk
```

框架依赖按需安装，见 [示例指南](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/README.md#%E6%A1%86%E6%9E%B6%E4%BE%9D%E8%B5%96)。

## 快速开始

### 使用云端资源

先参考[官方文档](https://help.aliyun.com/zh/agentcore/)创建 Workspace，再按需准备模型连接、MCP 和 Skill，并为 Agent 授予访问权限。以下代码在部署到 AgentCore 的应用中运行；将资源名称替换为当前 Workspace 中自己的资源名称。只使用模型时，无需创建 MCP 或 Skill。

```typescript
import { AgentCore } from 'alibabacloud-agentcore-sdk';

const core = AgentCore.auto();
try {
  const model = await core.model('test-mc', { model: 'qwen3.8-max' });
  const response = await model.completion([{ role: 'user', content: '你好' }]);
  console.log(response);

  const mcp = await core.mcp('test-mcp');
  console.log((await mcp.listTools()).map(tool => tool.name));

  const skill = await core.skills.managed('test-skill');
  console.log(skill.name);
} finally {
  await core.close();
}
```

### 凭证与 MCP Header

在平台创建凭证并授权后，使用 `await core.credentials.get(name)` 按名称获取。API Key 凭证通过 `credential.value` 读取；MCP Header 凭证通过 `credential.asHeaders()` 读取。不要将凭证值写入日志或提交到代码仓库。

托管 MCP 可在创建时显式绑定 MCP Header 凭证，并追加固定 Header。只有该 MCP 在凭证允许的应用范围内时才能使用：

```typescript
const mcp = await core.mcp('test-mcp', {
  credentialName: 'my-mcp-credential', // 可省略；须在平台创建并允许访问该 MCP
  headers: { 'x-business-id': 'my-app' }, // 可省略
});
```

Header 作用于该客户端的握手、工具发现和工具调用，不是请求级身份上下文。 SDK 会复制配置，不同 Header 配置使用不同客户端和 Session；不传时保持原有行为。 合并顺序为平台 Header → 凭证 Header → 自定义 Header；名称大小写不敏感，冲突直接报错，不做覆盖。 `Authorization`、平台已配置的 Header，以及 `Host`、`Mcp-Session-Id`、`Mcp-Protocol-Version` 等协议维护字段不可覆盖。 HTTP Header provider 在每次发送请求时求值，Session 复用不影响 Header 更新。 托管 MCP 使用 Streamable HTTP；直连 MCP 保留 `headersProvider`，stdio 不承载 HTTP Header。 不要修改共享客户端来切换用户身份。Header 的内容由业务明确选择，不自动透传入站请求头。 固定 Header 不等于可信身份。完整示例见 [MCP 凭证与 Header](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/mcp-credentials.ts)。

### 使用自定义资源

连接自有模型、MCP 服务，无需在 AgentCore 注册资源：

```typescript
import { AgentCore } from 'alibabacloud-agentcore-sdk';

const core = new AgentCore();
try {
  const model = core.directModel({
    provider: 'openai',
    model: process.env.CUSTOM_MODEL_NAME!,
    baseURL: process.env.CUSTOM_MODEL_BASE_URL!,
    apiKey: process.env.CUSTOM_MODEL_API_KEY!,
  });
  console.log(await model.completion([{ role: 'user', content: '你好' }]));

  const mcp = core.directMCP({ url: process.env.CUSTOM_MCP_URL! });
  console.log((await mcp.listTools()).map(tool => tool.name));
} finally {
  await core.close();
}
```

本地 Skill 加载方式及完整配置见 [自定义资源示例](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/direct-resources.ts)。

## 使用 Agent 模版

在当前 Workspace 中准备一个已发布的 Agent 模版，并授予应用相应的模版和 Skill 读取权限：

```typescript
const template = await core.templates.get('my-agent-template', { version: '1.0.0' });
const instruction = template.instruction;
const skills = await template.loadSkills();
```

`instruction` 是模版主 Agent 的 Prompt 字符串。`loadSkills()` 按需加载随包 Skill 和引用的云端 Skill，返回现有 `Skill` 对象，可直接交给各框架的 `skillTools()`。模型由应用独立配置。

省略模版版本时使用 `latest` 标签；同一个模版对象成功加载 Skill 后会复用结果，不自动跟随引用标签变化。请在 Core 的生命周期内加载和使用 Skill。完整用法见 [Agent 模版示例](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/agent-template.ts)。

## 通过环境变量选择资源

部署时可通过进程环境变量配置一个默认模型、一个 Agent 模版（AgentSpec），以及多个 MCP 和 Skill，不必把资源名称写死在代码中。先在当前 Workspace 准备对应资源并授予应用访问权限。

| 环境变量 | 内容 |
| --- | --- |
| `AGENTCORE_MODEL_CONNECTION_NAME` | 默认模型连接名称 |
| `AGENTCORE_MODEL_NAME` | 默认连接下的模型名称，可选；省略时沿用连接的模型选择规则 |
| `AGENTCORE_AGENT_SPEC_NAME` | 默认 AgentSpec 名称 |
| `AGENTCORE_AGENT_SPEC_VERSION` | AgentSpec 版本，可选；省略时使用 `latest` 标签 |
| `AGENTCORE_MCP_NAMES` | MCP 名称的 JSON 字符串数组 |
| `AGENTCORE_SKILLS` | Skill 的 JSON 对象数组；每项包含 `name` 和可选的 `version`，省略版本时使用 `latest` 标签 |

例如，将下列名称和版本替换为自己 Workspace 中的资源：

```bash
export AGENTCORE_MODEL_CONNECTION_NAME=test-mc
export AGENTCORE_MODEL_NAME=qwen3.8-max
export AGENTCORE_AGENT_SPEC_NAME=my-agent-spec
export AGENTCORE_AGENT_SPEC_VERSION=1.0.0
export AGENTCORE_MCP_NAMES='["test-mcp","another-mcp"]'
export AGENTCORE_SKILLS='[{"name":"test-skill"},{"name":"another-skill","version":"1.0.0"}]'
```

```typescript
const core = AgentCore.auto();
try {
  const model = await core.model();
  const mcps = await core.mcpsFromEnv();
  const skills = await core.skills.fromEnv();
  const template = await core.templates.get();
  const instruction = template.instruction;
} finally {
  await core.close();
}
```

[完整示例](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/environment-resources.ts)。框架适配器继续接收已经解析的 Model Client、MCP 工具和 Skill。

显式传资源名时保持原有行为，不继承默认连接的模型名称或默认 AgentSpec 的版本；省略资源名时，也可显式传模型名称或版本覆盖对应默认值。MCP／Skill 未配置时批量入口返回空列表，配置为 `[]` 也表示不加载；非法 JSON 或列表项会在调用相应入口时报错。

只需配置实际使用的资源。SDK 不自动加载这些资源，也不自动将 AgentSpec 内的 Skill 与环境变量 Skill 合并。同一个已初始化客户端不会随环境变量变化自动切换资源；修改后请重新创建客户端或重新部署。认证与访问权限的配置方式不变。

## 使用 Memory

Memory 用于保存和检索长期记忆，也支持查询、更新、删除记忆以及查看会话消息。使用前，在 AgentCore 中创建 MemoryStore 并授予应用访问权限。

```typescript
import { AgentCore } from 'alibabacloud-agentcore-sdk';

const core = AgentCore.auto();
try {
  const store = core.memoryStore('test-memory');
  const submission = await store.addMemories({
    scope: { userId: 'example-user', sessionId: 'session-1' },
    text: '用户喜欢简短的中文回答。',
  });

  console.log('Memory task:', submission.taskId);
  const task = await store.getMemoryTask(submission.taskId);
  console.log('Task status:', task.status);

  // 检索已有记忆；刚提交的任务可能尚未完成。
  const result = await store.searchMemories('用户有哪些回答偏好？', {
    scope: { userId: 'example-user' },
    topK: 5,
  });
  for (const hit of result.memories) {
    console.log(hit.memory.content.text);
  }
} finally {
  await core.close();
}
```

-   `userId`、`agentId`、`sessionId` 是独立的记忆范围字段；写入时都可省略，服务端会使用默认范围。
-   查询时只指定需要精确匹配的字段，未指定字段按通配范围查询；响应中的默认范围字段表现为 `undefined`。
-   `listMemorySessionMessages(sessionId, { userId, agentId })` 要求会话 ID，且 `userId`、`agentId` 至少提供一个。
-   分区标识由可信业务上下文提供，不替代访问权限控制。

示例会写入真实数据，建议使用测试记忆空间。新写入的记忆可能需要一定时间才能检索到，首次查询可能为空。

`addMemories()` 返回任务 ID，通过 `getMemoryTask(taskId)` 查询处理进度。任务成功后可从 `memoryIds` 读取记忆 ID；失败时可从 `error` 查看原因。

如需等待提取完成并直接读取 `memoryIds`，显式传入 `sync: true`：

```typescript
const result = await store.addMemories({ text: '用户喜欢简短回答。', sync: true });
console.log(result.memoryIds);
```

完整代码见 [Memory 基础示例](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/memory.ts)。框架接入见 [LangChain](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/langchain-server.ts)、[Google ADK](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/google-adk.ts) 和 [Mastra](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/mastra.ts) 示例。

## 框架集成

将模型、MCP 和 Skill 接入现有框架，不必重写 Agent 的业务逻辑。

| 框架 | 使用指南 | 示例 |
| --- | --- | --- |
| LangChain | [LangChain / LangGraph](https://npmcn.com/package/alibabacloud-agentcore-sdk/docs/langchain.md) | [Agent 服务与 Memory](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/langchain-server.ts) |
| LangGraph | [LangChain / LangGraph](https://npmcn.com/package/alibabacloud-agentcore-sdk/docs/langchain.md) | [模型与工具循环](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/langgraph.ts) |
| Google ADK | [Google ADK](https://npmcn.com/package/alibabacloud-agentcore-sdk/docs/google-adk.md) | [Runner 与 Memory](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/google-adk.ts) |
| Mastra | [Mastra](https://npmcn.com/package/alibabacloud-agentcore-sdk/docs/mastra.md) | [Agent 与 Memory](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/mastra.ts) |
| AI SDK 6 | [AI SDK](https://npmcn.com/package/alibabacloud-agentcore-sdk/docs/ai-sdk.md) | [模型与工具循环](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/ai-sdk.ts) |

## 提供 Agent 服务

`AgentCoreServer` 支持 AG-UI、OpenAI Chat Completions 和自定义 `ProtocolHandler`。

在仓库中运行 [最小服务示例](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/server.ts)：

```bash
npm ci
npm run build
npx tsx examples/server.ts
```

示例监听 9000 端口，默认接口为 `POST /ag-ui/agent` 和 `POST /openai/v1/chat/completions`，支持流式响应。

示例使用公开包名导入，在仓库中运行前需要构建本地包。完整模型、MCP、Skill 和 Memory 服务见 [LangChain 示例](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/langchain-server.ts)，AG-UI/OpenAI 请求示例见 [调用 Agent 服务](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/README.md#%E8%B0%83%E7%94%A8-agent-%E6%9C%8D%E5%8A%A1)。

框架执行流应使用对应的[事件转换器](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/execution-events.md)，不要只提取文本。AG-UI 可表达消息边界、工具调用和工具结果；OpenAI Chat Completions 按其标准表达文本和工具调用，不提供独立的工具结果流式事件。会话历史的保存与恢复仍由应用或所用框架负责。完整配置见 [Agent 服务指南](https://npmcn.com/package/alibabacloud-agentcore-sdk/docs/server.md)。

## 使用提示

`AgentCoreServer` 在当前执行上下文中保留入站网关设置的 `X-AgentCore-Accessor-WAT`。 `core.mcp()` 调用平台 MCP 时自动携带该原始值，同一次入站请求内复用 MCP Session， 不同入站请求隔离，请求结束（包括失败或取消）后关闭 Session。已有网关 `Authorization` 继续保留； 直连 MCP 不会自动收到平台 WAT。不要把 Accessor JWT、WAT 或 Matrix ID 配成固定 MCP Header。自行启动的后台任务或跨进程执行需要显式传播可信请求上下文。 `listTools({ headers: { "X-Trace-ID": "..." } })`、`callTool(name, args, { headers: {...} })` 支持逐次传入业务 Header，不改变 MCP Session；身份、Authorization 和协议 Header 不可覆盖。 手动管理 `RequestContext` 时，在请求结束后调用 `await context.close()` 释放 Session。 WAT 兑换、到期恢复和工具权限校验由网关负责，SDK 不会自动重试工具调用。

-   在应用生命周期内复用 Core，退出时调用 `await core.close()`。
-   模型的工具调用、Responses 和 Embedding 支持情况取决于所选模型。
-   仅加载可信 Skill；不需要执行命令时设置 `ALLOW_EXECUTE_COMMAND=false`。
-   使用 `AgentCore.auto({ logger: console })` 开启日志，不要记录 API Key 等敏感信息。

更多资源配置、框架依赖与运行命令见 [示例指南](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/README.md)。

执行流接入参见 [框架事件转换器与协议边界](https://npmcn.com/package/alibabacloud-agentcore-sdk/examples/execution-events.md)。展示工具执行过程时，不要只转发文本 chunk。

## 常见问题

### alibabacloud-agentcore-sdk 是什么？

AgentCore运行时SDK用于Node\.js

### 如何安装 alibabacloud-agentcore-sdk？

在项目目录运行 npm install alibabacloud-agentcore-sdk，或使用 pnpm add / yarn add / bun add。

### alibabacloud-agentcore-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### alibabacloud-agentcore-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### alibabacloud-agentcore-sdk 需要什么版本的 Node\.js？

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

### alibabacloud-agentcore-sdk 可以商用吗？

alibabacloud-agentcore-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### alibabacloud-agentcore-sdk 还在维护吗？

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