Loopman LangChain SDK

Official TypeScript SDK for integrating Human-in-the-Loop (HITL) validation into LangChain AI agents via the Loopman platform.

📋 Table of Contents

• Overview
• What is Loopman?
• Features
• Prerequisites
• Installation
• Quick Start
• Examples
• LangGraph Integration
• Debugging
• Project Structure
• API Reference
• Development
• Related Resources
• License

🎯 Overview

The Loopman LangChain SDK enables you to add human validation and oversight to your AI agents built with LangChain v1.0+. It provides seamless integration with the Loopman platform, allowing humans to approve, modify, or reject AI decisions in real-time through a modern mobile and web interface.

🤖 What is Loopman?

Loopman is a Human-in-the-Loop platform that bridges AI agent orchestrators (LangChain, n8n, Zapier, Make) with human users for real-time validation, correction, or rejection of AI decisions.

Key capabilities:

• 📱 Mobile-first interface for rapid decision-making on-the-go
• 💻 Web dashboard for detailed review and oversight
• 🔔 Real-time push notifications when AI agents need approval
• 🔄 Feedback loop: Humans can reject decisions with feedback, enabling agents to learn and auto-correct
• 📊 Decision history and audit trails
• 🎯 Context-aware guidelines for consistent decision-making

Use cases: Email approval workflows, financial transaction validation, content moderation, data modification approval, critical operation oversight, compliance checkpoints.

✨ Features

🛡️ Human-in-the-Loop Validation

• ✅ Transparent Integration: Middleware handles validation automatically
• ✅ Selective Interruption: Configure which tools require approval
• ✅ Multiple Decision Types: Approve, Edit with modifications, or Reject with feedback
• ✅ Automatic Polling: Real-time decision retrieval with configurable intervals
• ✅ Timeout Handling: Built-in timeout and retry logic
• ✅ Context Enrichment: Automatic guidelines and decision history integration

🔄 Feedback Loop - Learn from Human Decisions

• ✅ Human Rejection with Feedback: When humans reject a decision, they can provide detailed feedback explaining why
• ✅ Automatic Agent Retry: The agent receives the feedback and automatically retries with corrections
• ✅ Context Learning: Feedback is stored in decision history and injected into future agent prompts
• ✅ Iterative Refinement: Agents learn from past mistakes and improve over time
• ✅ Workflow Routing: LangGraph conditional edges automatically route to retry logic on NEEDS_CHANGES status

Example workflow:

1. Agent proposes to send an email with incorrect tone
2. Human rejects with feedback: "Use a more professional tone"
3. Agent receives feedback and retries with corrected tone
4. Human approves the refined version
5. Future similar tasks benefit from this learned context

🔗 LangGraph Support

• ✅ Validation Nodes: Reusable nodes for human approval workflows
• ✅ Conditional Routing: Route based on human decisions (approve/reject/retry)
• ✅ Context Loading: Automatic guidelines and decision history retrieval
• ✅ State Management: Full integration with LangGraph state
• ✅ Helper Functions: enrichSystemPrompt() for context injection

🤖 Agent Capabilities

• ✅ High-Level Agent API: createLoopmanAgent() for quick setup
• ✅ Tool Calling: Dynamic tool execution with Zod validation
• ✅ Conversational Memory: Stateful conversations with checkpointers
• ✅ MCP Integration: Model Context Protocol support for advanced workflows
• ✅ Double Validation Layer: Global + tool-specific validation

🔧 Developer Experience

• ✅ TypeScript: Full type safety with comprehensive types
• ✅ Multiple Integration Patterns: Middleware, Agent API, LangGraph nodes
• ✅ Debugging: VSCode launch configurations
• ✅ Real-World Examples: Production-ready code samples
• ✅ Comprehensive Documentation: Inline comments and guides

📦 Prerequisites

• Node.js: 18+
• OpenAI API Key: Required for model calls
• Loopman Account: Sign up at https://app.loopman.ai to get your API key
• npm/yarn: Package manager

🚀 Installation

1. Install Dependencies

npm install

2. Configure Environment

Create a .env file in the project root:

cp env.example .env

Edit .env and add your API keys:

OPENAI_API_KEY=sk-your-openai-api-key-here
LOOPMAN_API_KEY=your-loopman-api-key-here  # Get your API key at https://app.loopman.ai

⚡ Quick Start

Basic Agent

import { createAgent, tool } from "langchain";
import { MemorySaver } from "@langchain/langgraph";
import * as z from "zod";

// Define a tool
const greetTool = tool(({ name }) => `Hello, ${name}!`, {
  name: "greet",
  description: "Greet a user by name",
  schema: z.object({
    name: z.string(),
  }),
});

// Create agent
const agent = createAgent({
  model: "openai:gpt-4o-mini",
  tools: [greetTool],
  checkpointer: new MemorySaver(),
});

// Run agent
const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "Greet Alice" }],
  },
  { configurable: { thread_id: "demo" } }
);

Middleware Integration (Standard HITL Process)

import { createAgent } from "langchain";
import { loopmanMiddleware } from "@loopman/langchain-sdk";
import { MemorySaver } from "@langchain/langgraph";

// Create agent with Loopman middleware
const agent = createAgent({
  model: "openai:gpt-4o-mini",
  tools: [sendEmail, readEmail],
  middleware: [
    loopmanMiddleware({
      apiKey: process.env.LOOPMAN_API_KEY!,
      workflowId: "email-workflow",
      mode: "tool-validation", // or "prompt-enhancement" or "full"
      interruptOn: {
        send_email: true, // Requires validation
        read_email: false, // Auto-approved
      },
      timeout: 5 * 60 * 1000, // 5 minutes
      pollingInterval: 5000, // Poll every 5 seconds
      debug: true,
    }),
  ],
  checkpointer: new MemorySaver(),
});

// Usage - No manual interruption handling needed!
const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "Send email to alice" }],
  },
  { configurable: { thread_id: "demo" } }
);
// ✅ Middleware handles HITL transparently

Loopman Agent (Complete Solution - Ready to Use)

What's the difference with Middleware?

The Middleware requires you to build and configure your own agent, then add validation on top.

The Loopman Agent is a ready-to-use agent that includes everything:

• ✅ Pre-built agent with validation already integrated
• ✅ Automatic loading of guidelines and past decisions (feedback loop)
• ✅ Simple API: just call processWithHumanValidation()
• ✅ No manual configuration needed

Perfect for: Quick start, prototyping, or when you want a complete solution out-of-the-box.

import { createLoopmanAgent } from "@loopman/langchain-sdk";

const agent = createLoopmanAgent({
  apiKey: process.env.LOOPMAN_API_KEY!,
  workflowId: "email-workflow",
  model: "openai:gpt-4o-mini",
  systemPrompt: "You are a helpful email assistant",
  additionalTools: [sendEmail, readEmail],
  requireApprovalForTools: ["send_email"], // Only email sending requires approval
  debug: true,
});

// Usage - Simple and transparent!
const result = await agent.processWithHumanValidation({
  input: "Send email to [email protected] about the meeting",
});
// ✅ Agent automatically handles validation via Loopman platform (https://app.loopman.ai)

LangGraph Integration (Recommended)

import {
  LoopmanGraphState,
  createLoopmanContextNode,
  createLoopmanValidationNode,
  createLoopmanConditionalEdge,
  enrichSystemPrompt,
} from "@loopman/langchain-sdk";
import { StateGraph, START, END } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";

// 1. Create context node to load guidelines and decision history
const contextNode = createLoopmanContextNode({
  apiKey: process.env.LOOPMAN_API_KEY!,
  workflowId: "my-workflow",
  category: "email",
  debug: true,
});

// 2. Create validation node for human approval
const validationNode = createLoopmanValidationNode({
  apiKey: process.env.LOOPMAN_API_KEY!,
  workflowId: "my-workflow",
  debug: true,
});

// 3. Agent node with context-enriched prompts
async function agentNode(state: typeof LoopmanGraphState.State) {
  const { messages, guidelines, decisionContext } = state;

  // ✨ Automatically enrich system prompt with Loopman context
  const systemPrompt = enrichSystemPrompt(
    "You are a helpful email assistant.",
    { guidelines, decisionContext },
    { maxDecisions: 3 } // Show last 3 decisions
  );

  const model = new ChatOpenAI({ model: "gpt-4o-mini" });
  const modelWithTools = model.bindTools([sendEmail]);

  const messagesWithContext = [
    { role: "system", content: systemPrompt },
    ...messages,
  ];

  const response = await modelWithTools.invoke(messagesWithContext);

  return {
    messages: [response],
    requiresValidation: response.tool_calls && response.tool_calls.length > 0,
  };
}

// 4. Tool execution node
async function toolNode(state: typeof LoopmanGraphState.State) {
  const { messages } = state;
  const lastMessage = messages[messages.length - 1];

  if (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0) {
    return {};
  }

  const toolCall = lastMessage.tool_calls[0];
  const result = await sendEmail.invoke(toolCall.args);

  return {
    messages: [
      new ToolMessage({
        content: typeof result === "string" ? result : JSON.stringify(result),
        tool_call_id: toolCall.id,
      }),
    ],
    requiresValidation: false,
  };
}

// 5. Build workflow with validation and conditional routing
const workflow = new StateGraph(LoopmanGraphState)
  .addNode("load_context", contextNode)
  .addNode("agent", agentNode)
  .addNode("loopman_validation", validationNode)
  .addNode("tools", toolNode)

  .addEdge(START, "load_context")
  .addEdge("load_context", "agent")
  .addEdge("agent", "loopman_validation")
  .addConditionalEdges(
    "loopman_validation",
    createLoopmanConditionalEdge({ debug: true }),
    {
      execute: "tools", // APPROVED → execute tool
      rejected: END, // REJECTED → end workflow
      retry: "agent", // NEEDS_CHANGES with feedback → retry agent (FEEDBACK LOOP!)
      timeout: END, // TIMEOUT → end workflow
      error: END, // ERROR → end workflow
    }
  )
  .addEdge("tools", END);

const app = workflow.compile({ checkpointer: new MemorySaver() });

Task Options

Pass task-specific options when invoking the validation node:

const validationNode = createLoopmanValidationNode({
  apiKey: process.env.LOOPMAN_API_KEY!,
  workflowId: "my-workflow",
  debug: true,
});

workflow.addNode("loopman_validation", (state, config) =>
  validationNode(state, {
    taskTitle: `Approve ${state.currentAction}`,
    taskMessage: `Review action for user ${state.userId}`,
    businessContext: `Risk: ${state.riskLevel}, Cost: $${state.estimatedCost}`,
    proposedDecision: `Execute ${state.currentAction} on ${state.targetResource}`,
  })
);

Options:

• taskTitle, taskMessage - Custom task information
• businessContext, proposedDecision, decisionReasoning - Context strings

🔄 Feedback Loop in Action:

When a human rejects a decision with status NEEDS_CHANGES:

1. The validation node stores the human's feedback in decisionContext
2. The conditional edge routes to retry: "agent" instead of ending
3. The agent node receives the feedback via enrichSystemPrompt()
4. The agent corrects its decision based on human feedback
5. The workflow loops back to validation until approved

This creates a continuous learning cycle where agents improve through human guidance.

📚 Examples

Comprehensive examples are organized in the examples/ directory by complexity level:

Quick Start Examples

1. Basics (examples/1-basics/)

• 01-simple-agent.ts - Basic agent with tools and memory
• 02-memory-and-context.ts - Conversational memory deep dive

2. Loopman Integration (examples/2-loopman-integration/)

• 01-middleware-basic.ts - Transparent HITL with Loopman middleware
• 02-middleware-modes.ts - Three operation modes (tool-validation, prompt-enhancement, full)
• 03-loopman-agent.ts - High-level Loopman agent API
• 04-loopman-agent-and-tool-validation.ts - Double validation layer

3. Real-World Examples (examples/3-real-world-examples/)

• task-management/task-approval.ts - CRUD operations with selective approval
• data-processing/data-validation.ts - ETL with quality checks
• content-workflow/content-review.ts - Draft/publish workflow
• content-workflow/reddit-news-writer.ts - Automated news curation

4. Advanced Patterns (examples/4-advanced-patterns/)

• conditional-hitl.ts - Context-aware, intelligent validation

5. LangGraph Integration (examples/5-langgraph-integration/)

• loopman-validation-graph.ts - Complete LangGraph workflow with validation node, context enrichment and feedback loop

Running Examples

# Basics
npx tsx examples/1-basics/01-simple-agent.ts
npx tsx examples/1-basics/02-memory-and-context.ts

# Loopman Integration
npx tsx examples/2-loopman-integration/01-middleware-basic.ts
npx tsx examples/2-loopman-integration/03-loopman-agent.ts

# Real-World
npx tsx examples/3-real-world-examples/content-workflow/reddit-news-writer.ts
npx tsx examples/3-real-world-examples/task-management/task-approval.ts

# Advanced
npx tsx examples/4-advanced-patterns/conditional-hitl.ts

# LangGraph Integration
npx tsx examples/5-langgraph-integration/loopman-validation-graph.ts

See Examples README for detailed documentation and learning paths.

🔀 LangGraph Integration

The SDK provides complete LangGraph support with reusable nodes for building stateful validation workflows.

Key Components

1. Context Node (createLoopmanContextNode): Loads guidelines and decision history
2. Validation Node (createLoopmanValidationNode): Sends actions for human approval and polls for decisions
3. Conditional Edge (createLoopmanConditionalEdge): Routes workflow based on human decisions
4. Helper Functions (enrichSystemPrompt): Injects context into agent prompts

Complete Workflow Example

See the Quick Start section above for a complete LangGraph workflow example with validation nodes and conditional routing.

Decision Routing & Feedback Loop

The conditional edge routes your workflow based on human decisions:

• execute: Human approved → Continue to tool execution
• rejected: Human rejected → End workflow
• retry: Human requested changes → Retry agent with feedback (FEEDBACK LOOP) 🔄
• timeout: No decision within timeout → End workflow (or fallback)
• error: API error → End workflow (or fallback)

The retry route enables the feedback loop: When a human rejects with status NEEDS_CHANGES and provides feedback (e.g., "Use a more professional tone"), the workflow automatically routes back to the agent node. The feedback is injected into the agent's context via enrichSystemPrompt(), allowing the agent to learn and correct its decision. This creates an iterative refinement cycle that improves agent performance over time.

Running the Example

npx tsx examples/5-langgraph-integration/loopman-validation-graph.ts

🐛 Debugging

VSCode launch configurations are provided in .vscode/launch.json.

Available Configurations

1. Debug Current Example: Debug the currently open TypeScript file
2. Debug Simple Agent: Launch examples/1-basics/01-simple-agent.ts
3. Debug HITL Agent: Launch examples/1-basics/03-langchain-native-hitl.ts
4. Debug Loopman Middleware: Launch examples/2-loopman-integration/01-middleware-basic.ts

Usage

1. Open an example file
2. Press F5 or click the debug icon
3. Select a configuration
4. Set breakpoints as needed

📁 Project Structure

loopman-langchain-sdk-typescript/
├── src/
│   ├── agents/
│   │   └── loopman-agent.ts        # High-level Loopman agent API
│   ├── client/
│   │   └── loopman-api.ts          # Loopman API client
│   ├── helpers/
│   │   └── prompt-orchestrator.ts  # Prompt building utilities
│   ├── mcp/
│   │   ├── loopman-mcp-client.ts   # MCP client integration
│   │   └── tool-registry.ts        # Tool registry for MCP
│   ├── services/
│   │   ├── loopman.service.ts      # Main Loopman service
│   │   ├── polling.service.ts      # Polling logic
│   │   └── logger.service.ts       # Logging service
│   ├── loopman-middleware.ts       # Core middleware implementation
│   ├── loopman-agent-wrapper.ts    # Wrapper helpers (invokeWithRetry)
│   ├── index.ts                    # Main export entry point
│   └── types.ts                    # TypeScript type definitions
├── examples/
│   ├── 1-basics/                   # LangChain fundamentals
│   ├── 2-loopman-integration/      # Loopman HITL integration
│   ├── 3-real-world-examples/      # Production use cases
│   └── 4-advanced-patterns/       # Advanced HITL patterns
├── docs/                           # Detailed documentation
├── dist/                           # Compiled JavaScript (generated)
├── .env                            # Environment variables (root)
├── env.example                     # Example environment file
├── package.json                    # Dependencies and scripts
├── tsconfig.json                   # TypeScript configuration
└── README.md                       # This file

📖 API Reference

LangGraph API

createLoopmanContextNode(config)

Creates a LangGraph node that loads guidelines and decision history.

Parameters:

• config.apiKey (string, required): Loopman API key
• config.workflowId (string, required): Workflow identifier
• config.category (string, optional): Category filter for guidelines
• config.debug (boolean, optional): Enable debug logging

Returns: LangGraph node function

createLoopmanValidationNode(config)

Creates a LangGraph node that handles human validation.

Configuration:

• apiKey (string, required): Loopman API key
• workflowId (string, required): Workflow identifier
• executionId (string, optional): Execution ID (auto-generated)
• category (string, optional): Category filter for guidelines
• timeout (number, optional): Timeout in ms (default: 5 min)
• pollingInterval (number, optional): Polling interval (default: 5 sec)
• debug (boolean, optional): Enable debug logging

Task Options (passed at invocation):

• taskTitle (string): Task title
• taskMessage (string): Task description
• businessContext (string): Business context
• proposedDecision (string): Proposed decision
• decisionReasoning (string): Decision reasoning

Returns: Node function (state, options?) => Promise<StateUpdate>

createLoopmanConditionalEdge(config)

Creates a conditional edge for routing based on validation results.

Parameters:

• config.debug (boolean, optional): Enable debug logging

Returns: Conditional edge function

enrichSystemPrompt(basePrompt, context, options)

Enriches a system prompt with Loopman context.

Parameters:

• basePrompt (string): Base system prompt
• context.guidelines (array, optional): Guidelines to inject
• context.decisionContext (array, optional): Decision history to inject
• options.maxDecisions (number, optional): Max number of decisions to include

Returns: Enriched system prompt string

Loopman Agent API

createLoopmanAgent(config)

Creates a complete Loopman agent with MCP integration and double validation layer.

Parameters:

• config.apiKey (string, required): Loopman API key
• config.workflowId (string, required): Workflow identifier
• config.model (string, required): Model identifier (e.g., "openai:gpt-4o-mini")
• config.systemPrompt (string, required): System prompt for the agent
• config.additionalTools (array, optional): Custom tools to add
• config.category (string, optional): Category for guidelines organization
• config.language (string, optional): Language for human review interface
• config.requireApprovalForTools (array, optional): Tools requiring approval (['*'] for all)
• config.manualExecutionMode (boolean, optional): Manual execution mode
• config.pollingIntervalMs (number, optional): Polling interval
• config.pollingTimeoutMs (number, optional): Polling timeout
• config.debug (boolean, optional): Enable debug logging

Returns: LoopmanAgent

Example:

const agent = createLoopmanAgent({
  apiKey: process.env.LOOPMAN_API_KEY!,
  workflowId: "my-workflow",
  model: "openai:gpt-4o-mini",
  systemPrompt: "Your instructions...",
  additionalTools: [myTool],
  debug: true,
});

const result = await agent.processWithHumanValidation({
  input: "Your task...",
});

🛠️ Development

Scripts

# Development
npm run build            # Compile TypeScript to JavaScript
npm run clean            # Remove dist/ folder

# Examples (run directly with tsx)
npx tsx examples/1-basics/01-simple-agent.ts
npx tsx examples/2-loopman-integration/01-middleware-basic.ts
npx tsx examples/3-real-world-examples/content-workflow/reddit-news-writer.ts

Adding New Tools

1. Define the tool with Zod schema:

const myTool = tool(
  ({ param }) => {
    // Tool logic here
    return "result";
  },
  {
    name: "my_tool",
    description: "What the tool does",
    schema: z.object({
      param: z.string().describe("Parameter description"),
    }),
  }
);

2. Add to agent:

const agent = createAgent({
  model: "openai:gpt-4o-mini",
  tools: [myTool, ...otherTools],
  // ... other config
});

Extending Loopman Middleware

The Loopman middleware is fully implemented with:

• ✅ Real Loopman API integration via HTTP calls
• ✅ Polling for decision responses with configurable intervals
• ✅ Timeout and retry logic
• ✅ Comprehensive error handling and logging
• ✅ Support for multiple operation modes (tool-validation, prompt-enhancement, full)

See src/loopman-middleware.ts for the complete implementation.

🔗 Related Resources

LangChain Documentation

• LangChain v1.0 Quickstart
• Human-in-the-Loop Guide
• Tools Documentation
• LangGraph Documentation

Loopman Platform

• Loopman Website - Official website and documentation
• Loopman Web App - Web interface for managing workflows
• Loopman Mobile App - Available on iOS and Android app stores

📄 License

MPL-2.0 (Mozilla Public License 2.0). See LICENSE.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests on our GitHub repository.

💡 Tips

Environment Variables

• Keep .env files out of version control
• Use env.example as a template
• Store sensitive keys in environment variables

Debugging

• Use VSCode debug configurations for step-through debugging
• Enable debug: true in middleware for detailed logging
• Check SDK debug logs (via LoggerService) for tool execution details

Performance

• Use MemorySaver for development only
• Use persistent checkpointers (PostgreSQL) in production
• Consider timeout values for HITL workflows

Best Practices

• Always validate tool schemas with Zod
• Handle errors gracefully in tools
• Use descriptive tool names and descriptions
• Test HITL workflows thoroughly

Built using LangChain v1.0 and TypeScript.