AgentCore：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 安裝包