智能体构建和治理平台：AgentCore Node.js SDK 使用指南

前提条件

1. 已开通 AgentCore，并创建 Workspace。具体操作，请参见管理 Workspace。

2. 已根据需要在 Agent 所属的 Workspace 中准备资源，并确认 Agent 具有相应访问权限。

3. 使用云端资源的示例在 AgentCore 托管的应用运行环境中执行。SDK 从运行环境获取访问配置，无需在业务代码中填写平台访问密钥。

本文使用以下示例资源名称。请替换为您实际创建的资源名称。

只调用模型时，无需创建 MCP、Skill、MemoryStore 或额外凭证。

安装 SDK

基础 SDK 支持 Node.js 20.3 及以上版本。本文的 LangChain 服务示例使用 Node.js 22.22 及以上版本。

npm install alibabacloud-agentcore-sdk@0.1.2

框架依赖需要单独安装。本文 LangChain 示例使用以下依赖：

npm install langchain@^1 @langchain/core@^1 @langchain/langgraph@^1 @langchain/openai@^1 zod@^4
npm install --save-dev tsx typescript @types/node

本文示例使用 Node.js SDK 0.1.2。

调用云端模型

在代码中指定模型连接名称和模型名称。SDK 根据当前 Agent 所属的 Workspace 查找模型连接，无需手动拼接模型访问地址。

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

const core = AgentCore.auto();
try {
  const model = await core.model('my-model-connection', { model: 'qwen3.8-max' });
  const response = await model.completion(
    [{ role: 'user', content: '用一句话介绍杭州。' }],
    { temperature: 0.2 },
  );
  console.log(response);
} finally {
  await core.close();
}

for await (const chunk of model.stream([{ role: 'user', content: '用一句话介绍杭州。' }])) {
  console.log(chunk);
}

使用 MCP 工具

以下片段在已创建的 core 生命周期内执行。获取工具列表只用于发现工具，不会执行工具。

const mcp = await core.mcp('my-mcp');
const availableTools = await mcp.listTools();
for (const tool of availableTools) {
  console.log(tool.name, tool.description, tool.parameters);
}

// 替换为该 MCP 实际提供的工具名称和参数。
const result = await mcp.callTool('<工具名称>', { '<参数名称>': '<参数值>' });

如需让模型选择并执行工具，请使用后文的框架集成示例。模型调用本身不会自动执行 MCP 工具。

使用 Skill

Skill 包含任务说明和可选的辅助文件或脚本。加载 Skill 后，通过框架适配器将其接入 Agent。

const skill = await core.skills.managed('my-skill', '1.0.0');
console.log(skill.name, skill.version);

1.0.0 必须是该 Skill 已发布的版本。省略版本时使用平台解析出的默认版本。需要固定应用行为时，建议显式指定版本。

重要：加载 Skill 不等于执行 Skill。Skill 工具可能执行包内脚本或命令，仅使用可信来源的 Skill。不需要命令执行能力时，在应用运行环境中设置 ALLOW_EXECUTE_COMMAND=false。Skill 执行所需的程序和依赖仍需包含在应用运行环境中。

使用记忆

MemoryStore 用于保存和检索长期记忆。它与模型输入的对话历史是不同的能力：检索到记忆后，需要由业务代码或框架适配器将其作为参考信息提供给模型。

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

const result = await store.searchMemories('用户有哪些回答偏好？', {
  scope: { userId: 'example-user' },
  topK: 5,
});
for (const hit of result.memories) {
  console.log(hit.memory.content.text);
}

使用凭证和 MCP Header

const credential = await core.credentials.get('my-api-key');
const apiKey = credential.value; // 交给需要该凭证的客户端，不要输出。

const headerCredential = await core.credentials.get('my-mcp-header');
const headers = headerCredential.asHeaders();

const mcp = await core.mcp('my-mcp', {
  credentialName: 'my-mcp-header',
  headers: { 'x-business-id': 'my-app' },
});

接入自定义资源

自有模型、MCP 服务和随应用分发的 Skill 无需注册为平台资源。以下配置由应用自己提供，示例中的环境变量不是 SDK 自动读取的配置项。

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));
  const skills = await core.skills.local('./skills');
  console.log(skills.map(skill => skill.name));
} finally {
  await core.close();
}

直连 MCP 需要鉴权时，可通过 headersProvider 提供 Header；stdio 传输不使用 HTTP Header。

使用 LangChain 构建 Agent 服务

以下示例将云端模型、MCP 和 Skill 接入 LangChain，并通过 AgentCoreServer 提供服务。使用前请准备 my-model-connection、my-mcp、my-skill，并按前文安装框架依赖。

示例处理最新一条用户文本，未实现对话历史存储。多轮会话应由应用或框架维护历史和检查点。

保存为 app.ts。在应用的 package.json 中设置 "type": "module"。

import { createAgent } from 'langchain';
import { HumanMessage } from '@langchain/core/messages';
import { AgentCore } from 'alibabacloud-agentcore-sdk';
import { AgentCoreServer } from 'alibabacloud-agentcore-sdk/server';
import {
  AgentCoreConverter, model, tools, skillTools,
} from 'alibabacloud-agentcore-sdk/integrations/langchain';

const core = AgentCore.auto({ logger: console });

async function buildAgent() {
  const client = await core.model('my-model-connection', { model: 'qwen3.8-max' });
  const mcp = await core.mcp('my-mcp');
  const skill = await core.skills.managed('my-skill');
  return createAgent({
    model: await model(client),
    tools: [...tools(await mcp.listTools()), ...skillTools([skill])],
    systemPrompt: '使用工具完成请求，不要编造工具执行结果。',
  });
}

let agent: Awaited<ReturnType<typeof buildAgent>>;
const server = new AgentCoreServer({
  logger: console,
  startup: async () => {
    try { agent = await buildAgent(); }
    catch (error) { await core.close(); throw error; }
  },
  shutdown: () => core.close(),
  readiness: () => agent !== undefined,
  invoke: async function* (request) {
    const message = request.messages.at(-1);
    if (message?.role !== 'user' || typeof message.content !== 'string') {
      throw new Error('本示例仅支持用户文本消息');
    }
    const events = agent.streamEvents(
      { messages: [new HumanMessage(message.content)] },
      { version: 'v2', signal: request.signal },
    );
    yield* new AgentCoreConverter().stream(events);
  },
});

await server.start({ port: 9000, hostname: '0.0.0.0' });
for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    void server.close().catch(error => {
      console.error(error);
      process.exitCode = 1;
    });
  });
}

在应用运行环境中使用以下启动命令，并确保已安装 tsx：

npx tsx app.ts

调用 Agent 服务

将下面的 https://<agent-endpoint> 替换为应用实际访问地址，并按应用的访问要求补充认证信息。该地址是 Agent 应用地址，不是模型供应商地址。

curl -N 'https://<agent-endpoint>/ag-ui/agent' \
  -H 'Content-Type: application/json' \
  -d '{
    "threadId": "example-thread-1",
    "runId": "example-run-1",
    "messages": [{"id": "message-1", "role": "user", "content": "查看可用 Skill，并按其说明完成一个示范。"}],
    "state": {},


    "tools": [ ],



    "context": [ ],


    "forwardedProps": {}
  }'

curl -N 'https://<agent-endpoint>/openai/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "agentcore",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

其他框架集成

表中的入口均以 alibabacloud-agentcore-sdk/ 为前缀。上述框架入口也提供执行事件转换器，输入应使用对应框架的完整事件流。例如 LangChain/LangGraph 使用 streamEvents(..., {version: 'v2'})，AI SDK 使用 fullStream 而非 textStream。

不同框架的事件输入和输出时机不同，不应直接复用另一框架的事件处理方式。

常见问题

相关文档

• 管理 Workspace

• 管理模型

• 管理 MCP 工具

• 管理 Skill

• Node.js SDK 安装包