@wukonglabs/wukong-agent-sdk

Embeddable AI coding agent engine (ReAct loop + built-in tools + skill system) for library integration.

This is the core engine behind the Wukong CLI. Use this package to embed a full coding agent directly into your app.

CLI and SDK share the same createAgent entry point, so SDK users get identical capabilities (built-in tools, skill system, middleware pipeline, project context awareness, sub-agent, etc.) — no capability drift.

Install

npm install @wukonglabs/wukong-agent-sdk@latest

Requires Node.js >= 22. Pure JS/TS, no native addons.

Quick Start

loadConfig() → createAgent() → agent.run()

import { createAgent, loadConfig, getLogger } from "@wukonglabs/wukong-agent-sdk";

const config = await loadConfig();
const logger = getLogger();

const { agent } = await createAgent({ config, logger });

const result = await agent.run("Summarize the dependencies in package.json");
console.log(result.response);

Programmatic Config (No Config File)

import { createAgent, getLogger, type AppConfig } from "@wukonglabs/wukong-agent-sdk";

const config = {
  agent: {
    defaultModel: "deepseek-chat",
  },
  llm: {
    providers: {
      deepseek: {
        type: "openai-compatible",
        apiKey: process.env.MY_API_KEY,
        baseUrl: "https://api.deepseek.com/v1",
      },
    },
    models: {
      "deepseek-chat": {
        provider: "deepseek",
        id: "deepseek-chat",
      },
    },
  },
} as AppConfig;

const { agent } = await createAgent({ config, logger: getLogger() });
const result = await agent.run("List files in src/");
console.log(result.response);

Preferred approach: const base = await loadConfig() to get defaults-filled config, then override specific fields.

Streaming

Pass onStream for streaming; omit for non-streaming.

const { agent } = await createAgent({
  config,
  logger,
  onStream: (event) => {
    if (event.type === "text") process.stdout.write(event.text ?? "");
  },
});

await agent.run("Explain this project's architecture");

Multi-Turn Conversations

Use SessionManager + ContextBuilder to persist history:

import { createAgent, loadConfig, getLogger, SessionManager } from "@wukonglabs/wukong-agent-sdk";

const config = await loadConfig();
const { agent, contextBuilder } = await createAgent({ config, logger: getLogger() });

const sessions = new SessionManager("./.wukong/sessions");
const session = await sessions.getOrCreate("my-session");

const messages = contextBuilder.build(session, "Continue the last task");
const result = await agent.runWithMessages(messages);
console.log(result.response);

createAgent Options

| Option | Type | Description | | ------------- | ----------------------------- | -------------------------------------------------- | | config | AppConfig | Required. From loadConfig() or constructed | | logger | Logger | Required. Get default via getLogger() | | onStream | StreamCallback | Streaming callback; omit for non-streaming | | confirmMode | ConfirmMode | File edit confirmation mode, default smart | | model | string | Model alias declared in config.llm.models | | ciMode | boolean | CI mode (affects system prompt & verification) | | planMode | PlanMode | Planning mode, default auto | | thinking | ThinkingConfig | Model protocol thinking config (deepseek/hy/glm/anthropic) | | overrides | { maxSteps, contextWindow } | Override max steps / context window at runtime |

Returns { agent, llm, tools, contextBuilder, effectiveMaxSteps, resolvedModel, resolvedModelProfile }.

Key Exports

| Category | Exports | | ----------------- | ------------------------------------------------------------ | | Assembly | createAgent | | Agent Core | Agent (run / runWithMessages) | | LLM | createProvider, resolveProviderConfig | | Tools | ToolRegistry, allBuiltinTools, EditConfirmer | | Context / Session | ContextBuilder, SessionManager, compactIfNeeded | | Middleware | MiddlewarePipeline + 4 built-in middlewares | | Planning / Verify | AutoVerifier, collectSmartContext, buildSystemPrompt | | Skills | SkillRegistry | | Config / Logging | loadConfig, Logger, getLogger, setGlobalLogger |

Full config documentation (providers, Vision, Skills, etc.) is shared with the CLI — see @wukonglabs/wukong docs.

License

MIT