Skip to main content
Version: latest (main)

Quick Start

This page takes you from nothing to a governed agent in a few minutes. Everything here is copy-paste; the snippets mirror the patterns the SDK's own test suite exercises.

1. Install​

pnpm add @agent-assembly/sdk

The package ships dual ESM/CJS entries and selects a prebuilt native binding for your platform during postinstall, so there is no extra build step for typical consumers.

Pre-1.0 / release candidate

The public surface (initAssembly, withAssembly) is stabilizing but may change between pre-releases. Pin an exact version for reproducible installs:

npm install @agent-assembly/sdk@0.0.1-rc.6

2. Make sure a gateway is reachable​

The SDK enforces policy by talking to an Agent Assembly gateway. You have two options:

  • Let the SDK auto-start a local gateway. If you have the aasm binary on your PATH (brew install ai-agent-assembly/tap/aasm, or curl -fsSL https://agent-assembly.com/install.sh | sh) and set AA_AUTO_START=1, a zero-config initAssembly() will probe http://localhost:7391 and start a local gateway for you if nothing is running. Auto-start is opt-in — without it, a missing gateway throws a ConfigurationError instead of spawning anything.
  • Point at a gateway you already run. Set AA_GATEWAY_URL (and AA_API_KEY if it requires auth), or pass gatewayUrl explicitly.
Local-mode transports: :7391 REST + :50051 gRPC

Starting the local gateway binds two loopback surfaces in one process:

aasm start --mode local

This exposes the REST API on http://localhost:7391 (what gatewayUrl points to, and what the SDK probes and, with AA_AUTO_START=1, auto-starts) and the gRPC AgentLifecycleService on 127.0.0.1:50051, which is the endpoint the native aa-sdk-client binding dials to register your agent. You don't configure :50051 yourself — registration dials it automatically — so a no-argument initAssembly() both connects and shows the agent in the dashboard once a gateway is reachable.

To confirm both surfaces are actually up rather than guessing from the SDK's behavior, check them directly:

curl http://localhost:7391/healthz   # REST — real JSON: mode, storage, version, uptime_secs
nc -z localhost 50051 && echo "gRPC port open"   # gRPC has no health endpoint yet; this only confirms the port accepts connections

See Configuration for the full resolution order.

3. Govern your first agent with withAssembly​

withAssembly wraps a map of tools so the local policy is enforced before each one runs: an allowed call executes normally, while a denied call throws a PolicyViolationError and the tool body never runs. Pick your framework below — each tab is the governance-wiring excerpt from that framework's runnable example, vendored into this repo and kept in lock-step with this page by a CI drift check — the check catches this page drifting from the vendored snippet, not the vendored snippet drifting from the upstream example. Copy the full, runnable script — imports, tools, and the agent run — from the linked example; the slice below is just the part that wires in governance.

LangChain.js is the validated path; the remaining frameworks are experimental. The excerpts are ESM / TypeScript; under CommonJS, swap the import for const { withAssembly } = require("@agent-assembly/sdk").

import { withAssembly } from "@agent-assembly/sdk";
import { createPolicyGatewayClient } from "./policy.js";
import { TOOLS } from "./tools.js";

const tools = withAssembly(
  {
    get_weather: {
      execute: async (args: Record<string, unknown>) => TOOLS.get_weather(args).output
    },
    delete_file: {
      execute: async (args: Record<string, unknown>) => TOOLS.delete_file(args).output
    }
  },
  { gatewayClient: createPolicyGatewayClient(), agentId: "langchain-js-example-agent" }
);
Version compatibility

Base tool abstractions like Tool moved out of the langchain monolith into @langchain/core when LangChain split the package in v0.1.0 (Jan 2024; @langchain/core first published to npm 2023-11-22).

  • langchain < 0.1.0: import { Tool } from "langchain/tools";
  • langchain / @langchain/core ≥ 0.1.0 (current): import { tool } from "@langchain/core/tools";

4. What to expect​

  • Allow. The tool runs normally and returns its result. A governance event is recorded in the audit trail.
  • Deny. The wrapped invoke() rejects with a PolicyViolationError whose message includes the tool name and the gateway's reason — the tool body never runs.
  • Pending (needs approval). The call waits up to langchain.approvalTimeoutMs (default applies if unset) for a human decision, then either proceeds or rejects.

That deny-on-policy behavior is the whole point: a denied tool call throws instead of executing. If you want to watch what would be blocked without actually blocking it while you tune policy, register the agent in observe mode:

const ctx = await initAssembly({
  agentId: "demo",
  enforcementMode: "observe", // dry-run: actions proceed, violations recorded as shadow events
  langchain: { tools: { searchWeb } }
});

Next steps​

  • Guides — the full LangChain walkthrough, the low-level withAssembly wrapper, experimental frameworks, and how to handle allow/deny decisions and errors.
  • Configuration — every AssemblyConfig field and the gateway/API-key resolution precedence.
  • Core Concepts — what the native binding, the adapter registry, and the initAssembly lifecycle actually do.