:AgentCore Node.js SDK User Guide

This topic is the Node.js volume of AgentCore SDK Overview, which covers language selection, capability boundaries, and an overview of the preparations. The cloud resource examples run in the AgentCore managed runtime, and the custom resource examples use connection settings that your application provides.

Prerequisites

Install the SDK

Install the base SDK:

npm install alibabacloud-agentcore-sdk@0.1.2

Install framework dependencies separately. The LangChain example in this topic requires Node.js 22.22 or later and uses the following dependencies:

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

The examples in this topic use Node.js SDK 0.1.2. For later versions, see the alibabacloud-agentcore-sdk npm package page.

Choose an integration path based on where your resources come from. When your resources are registered in AgentCore as platform resources (model connections, MCP servers, Skills, MemoryStores, and credentials), you call them by name and the examples run in the AgentCore managed runtime. See the sections from "Call cloud models" through "Use credentials and MCP headers". When your resources come from your own services or ship with your application, your application provides the connection settings and no platform registration is required. See "Connect custom resources".

Call cloud models

Specify the model connection name and the model name in your code. The SDK looks up the model connection in the Workspace that the current Agent belongs to, so you do not need to construct the model endpoint yourself.

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: 'Describe Hangzhou in one sentence.' }],
    { temperature: 0.2 },
  );
  console.log(response);
} finally {
  await core.close();
}

The try/finally pattern in this example is the Core lifecycle that the snippets later in this topic reuse: AgentCore.auto() creates the Core, and await core.close() in the finally block releases its resources.

for await (const chunk of model.stream([{ role: 'user', content: 'Describe Hangzhou in one sentence.' }])) {
  console.log(chunk);
}

Use MCP tools

The following snippet runs within the lifecycle of an existing core. Listing tools only discovers them; it does not run any tool.

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);
}

// Replace these with the tool name and parameters that the MCP server actually provides.
const result = await mcp.callTool('<tool-name>', { '<parameter-name>': '<parameter-value>' });

To let the model select and run tools, use the framework integration example later in this topic. A model call by itself does not run MCP tools.

Use Skills

A Skill contains task instructions and optional supporting files or scripts. After you load a Skill, connect it to your Agent through a framework adapter.

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

1.0.0 must be a version of the Skill that is in the Published state. If you omit the version, the platform resolves the default version. Specify a version explicitly when you need to keep the behavior of your application fixed.

Use memory

A MemoryStore saves and retrieves long-term memory. It is a different capability from the conversation history that you send to a model: after you retrieve memories, your application code or a framework adapter must pass them to the model as reference information.

const store = core.memoryStore('my-memory');
await store.addMemories({
  scope: { userId: 'example-user', sessionId: 'example-session' },
  text: 'The user prefers short answers in Chinese.',
});

const result = await store.searchMemories('What response preferences does the user have?', {
  scope: { userId: 'example-user' },
  topK: 5,
});
for (const hit of result.memories) {
  console.log(hit.memory.content.text);
}

Use credentials and MCP headers

const credential = await core.credentials.get('my-api-key');
const apiKey = credential.value; // Pass this to the client that needs the credential. Do not print it.

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' },
});

Connect custom resources

Your own models, MCP servers, and Skills that ship with your application do not need to be registered as platform resources. Your application provides the following settings, and the environment variables in the example are not configuration items that the SDK reads automatically.

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: 'Hello' }]));

  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();
}

When a directly connected MCP server requires authentication, provide headers through headersProvider. The stdio transport does not use HTTP headers.

Build an Agent service with LangChain

The following example connects a cloud model, an MCP server, and a Skill to LangChain and serves them through AgentCoreServer. Before you start, prepare my-model-connection, my-mcp, and my-skill, install the framework dependencies described earlier, and make sure that the application runs on Node.js 22.22 or later.

The example handles only the latest user text message and does not store conversation history. For multi-turn conversations, your application or framework must maintain the history and the checkpoints.

Save the following code as app.ts. This example uses the ES module configuration that is described in the "Runtime environment" section.

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: 'Use the tools to complete the request. Do not fabricate tool results.',
  });
}

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('This example supports only user text messages.');
    }
    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;
    });
  });
}

The example code has four logical parts: import the dependencies; build the Agent in buildAgent, which connects the model, MCP tools, and the Skill; configure the AgentCoreServer lifecycle and request handling with startup, shutdown, readiness, and invoke; and start the server and handle exit signals.

Run the following start command in the application runtime, and make sure that tsx is installed:

npx tsx app.ts

Call the Agent service

Replace https://<agent-endpoint> in the following examples with the actual access address of your application, and add the authentication information that your application requires. This address is the address of the Agent application, not the address of a model provider.

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": "List the available Skills and complete a demonstration as instructed."}],
    "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": "Hello"}],
    "stream": true
  }'

Framework integrations

All entry points in the table are prefixed with alibabacloud-agentcore-sdk/. These framework entry points also provide execution event converters, and the input must be the complete event stream of the corresponding framework: LangChain and LangGraph use streamEvents(..., {version: 'v2'}), and AI SDK uses fullStream instead of textStream.

Different frameworks have different event inputs and output timing, so do not reuse the event handling approach of another framework directly.

FAQ

References

• AgentCore SDK Overview: an overview of SDK capabilities, development language selection, and service protocol comparison.

• Manage Workspace: create and switch Workspaces. All resources in the examples in this topic belong to a Workspace.

• Manage Models: add a model connection and configure models in that connection.

• Manage MCP Servers: create and manage MCP servers for a Workspace.

• Manage Skill: create a Skill, enable it, and publish a version.

• Manage credentials: create an API key credential or an MCP header credential and grant it to your application.

• alibabacloud-agentcore-sdk npm package page: check the latest version of the Node.js SDK.

• AgentCore product page: learn about the positioning and core features of AgentCore.