@agent-assembly/sdk

TypeScript/Node.js SDK for Agent Assembly, licensed under Apache 2.0.

Prerequisites

Before installing or contributing, ensure your environment has:

• Node.js ≥ 18.18.0 (LTS). The active LTS lines (18, 20, 22, 24) are exercised in CI.
• pnpm ≥ 10. The repository enforces pnpm via engines and ships a pnpm-lock.yaml.
• Rust toolchain (only required when rebuilding the native aa-ffi-node binding from source — most consumers receive a prebuilt platform binary via optionalDependencies).

Installation

pnpm add @agent-assembly/sdk
# or
npm install @agent-assembly/sdk
# or
yarn add @agent-assembly/sdk

The SDK ships dual ESM/CJS entries and selects a prebuilt native binding for your platform during postinstall. No additional build step is required for typical consumers.

Quickstart

ESM (import)

import { initAssembly, withAssembly } from "@agent-assembly/sdk";
import { ChatOpenAI } from "@langchain/openai";

const ctx = await initAssembly({ gatewayUrl: "http://localhost:8080", agentId: "demo" });
const governedTools = withAssembly(myTools, { context: ctx });
const model = new ChatOpenAI({ model: "gpt-4o-mini" }).bindTools(governedTools);

CJS (require)

const { initAssembly, withAssembly } = require("@agent-assembly/sdk");
const { ChatOpenAI } = require("@langchain/openai");

const ctx = await initAssembly({ gatewayUrl: "http://localhost:8080", agentId: "demo" });
const governedTools = withAssembly(myTools, { context: ctx });
const model = new ChatOpenAI({ model: "gpt-4o-mini" }).bindTools(governedTools);

Both entrypoints resolve to the same governance pipeline; the package's exports field selects ESM or CJS automatically based on how the consumer imports it.

initAssembly() registers the LangChain callback handler and the AdapterRegistry, so any tool wrapped by withAssembly() is checked against gateway policy before invocation.

Supported Node.js versions

The SDK is tested against every active Node.js LTS line on every supported operating system. The matrix is enforced by .github/workflows/test-matrix.yml:

Node.js	Linux (ubuntu-latest)	macOS (macos-latest)	Windows (windows-latest)
18	✅	✅	✅
20	✅	✅	✅
22	✅	✅	✅
24	✅	✅	✅

Older Node.js lines (≤ 16) are unsupported because the napi-rs ABI used by the native binding requires Node 18.18 or newer.

Goal

Provide a thin wrapper around the Agent Assembly Rust runtime through:

• gRPC sidecar client (default)
• native in-process binding (napi-rs)

The primary entrypoint is initAssembly(), which prepares runtime governance and registers framework hooks for supported tool ecosystems.

Public Entrypoints

• initAssembly(config)
• withAssembly(tools, options)

Policy Matching Constraint

Vercel AI SDK tools do not expose a .name field. Governance policies must match by tool description content (or tool map key in wrapper context), not by strict framework-level tool name.

LangChain Blocking Model

LangChain callback handleToolStart cannot preempt execution by return value, so this SDK applies a two-layer model:

• callback layer (AssemblyCallbackHandler) tracks deferred denials and redacts at handleToolEnd
• wrapper layer (wrapToolWithAssembly) enforces true pre-execution deny/pending checks

initAssembly() auto-registers the callback handler and auto-wraps configured LangChain tools.

Current Architecture Layout

src/
  index.ts
  core/
    init-assembly.ts
  adapters/
    adapter.ts
    adapter-registry.ts
    langchain/
      assembly-callback-handler.ts
      wrap-tool-with-assembly.ts
  gateway/
    client.ts
  wrappers/
    with-assembly.ts
  errors/
    policy-violation-error.ts
  types/
    assembly-mode.ts
    assembly-config.ts
    assembly-context.ts
    gateway-governance.ts
    langchain-adapter.ts
    tool-map.ts
tests/
  architecture/
.github/workflows/

Native napi-rs Binding (AAASM-60)

The aa-ffi-node Rust crate is located at native/aa-ffi-node.

Build commands:

• pnpm native:build (debug/local)
• pnpm native:build:release (release + platform artifact)
• pnpm native:check-types (strict check for generated napi .d.ts)

Native integration acceptance test:

• AA_NATIVE_TEST=1 pnpm vitest run tests/native-napi-integration.test.ts

The build-addon GitHub workflow produces prebuilt index.node artifacts for Node 18/20/22 on Linux/macOS/Windows.

Packaging Layout (AAASM-61)

The package now publishes dual module outputs with explicit conditional exports:

• ESM entry: ./dist/esm/index.js
• CJS entry: ./dist/cjs/index.js
• Type declarations: ./dist/types/index.d.ts

Platform-native binaries are declared via optionalDependencies and selected during postinstall based on process.platform and process.arch.

Package verification checks include:

• ESM and CJS entry smoke tests
• export types mapping assertion
• npm pack content and package size guard tests

Documentation

Full guides, architecture deep-dives, and the complete API reference are published at:

https://ai-agent-assembly.github.io/node-sdk/

The site is built from the docs/ (content) and website/ (Docusaurus app) directories and is re-published on every push to master via the publish-docs.yml workflow.