agents

Multi-agent orchestration — state graphs, conditional routing, and human-in-the-loop

Overview

The agents module wraps LangGraph.js for building stateful multi-agent systems with typed state, conditional routing, and human-in-the-loop patterns.

Peer dependencies: @langchain/langgraph, @langchain/core

npm install @langchain/langgraph @langchain/core

yarn add @langchain/langgraph @langchain/core

pnpm add @langchain/langgraph @langchain/core

Quick Start

import { createAgent, createGraph, route } from '@jamaalbuilds/ai-toolkit/agents';

const researcher = createAgent({
  name: 'researcher',
  systemPrompt: 'You research topics thoroughly.',
  tools: [searchTool],
});

const writer = createAgent({
  name: 'writer',
  systemPrompt: 'You write clear, concise content.',
});

const graph = await createGraph({
  agents: [researcher, writer],
  edges: [
    { from: '__start__', to: 'researcher' },
    { from: 'researcher', to: 'writer' },
    { from: 'writer', to: '__end__' },
  ],
});

const result = await graph.invoke({
  messages: [{ role: 'user', content: 'Write about AI agents' }],
});

API Reference

createAgent(config)

Define an agent node with a name, system prompt, and optional tools.

function createAgent(config: AgentConfig): AgentNode

const agent = createAgent({
  name: 'classifier',
  systemPrompt: 'Classify the user intent.',
});

createGraph(config)

Build a state graph from agents and edges. Returns a compiled graph ready for invocation.

async function createGraph(config: GraphConfig): Promise<GraphInstance>

const graph = await createGraph({
  agents: [researcher, writer],
  edges: [
    { from: '__start__', to: 'researcher' },
    { from: 'researcher', to: route(
      (state) => state.metadata?.done ? 'writer' : 'researcher',
      ['researcher', 'writer'],
    )},
    { from: 'writer', to: '__end__' },
  ],
});

const result = await graph.invoke({
  messages: [{ role: 'user', content: 'Research and write about AI' }],
});

route(condition, targets)

Create a conditional routing function for graph edges.

function route(condition: RouteCondition, targets: string[]): RouteResult

const routing = route(
  (state) => {
    if (state.metadata?.needsReview) return 'reviewer';
    return 'publisher';
  },
  ['reviewer', 'publisher'],
);

Types

• AgentNode — agent definition with name, systemPrompt, tools, process
• GraphInstance — compiled graph with invoke() method
• GraphState — { messages: GraphMessage[], metadata?: Record<string, unknown> }
• GraphEdge — { from: string, to: string | RouteResult }
• GraphMessage — { role: string, content: string }