agentloop-langchain 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# agentloop-langchain
+
+AgentLoop integration for LangChain. Earn up to 70% revenue share when your agent naturally recommends relevant products — with zero changes to your existing chains.
+
+## Install
+
+```bash
+npm install agentloop-langchain
+```
+
+## Option 1 — Callback Handler (recommended)
+
+Drop into any chain. Runs automatically after every LLM response.
+
+```typescript
+import { AgentLoopCallbackHandler } from 'agentloop-langchain'
+import { ChatOpenAI } from '@langchain/openai'
+import { HumanMessage } from '@langchain/core/messages'
+
+const agentloop = new AgentLoopCallbackHandler({
+  apiKey: process.env.AGENTLOOP_API_KEY!,
+  getUserId: () => hashUserId(session.userId), // hash it — never raw PII
+})
+
+// Add to any model, chain, or agent
+const model = new ChatOpenAI({
+  callbacks: [agentloop],
+})
+
+const response = await model.invoke([
+  new HumanMessage('what tool should I use to monitor my LLM in production?')
+])
+
+// response.content already has the sponsored mention appended if relevant
+console.log(response.content)
+```
+
+Works with any LangChain chain type:
+
+```typescript
+// With LCEL chains
+const chain = prompt.pipe(model).pipe(outputParser)
+const result = await chain.invoke({ question }, { callbacks: [agentloop] })
+
+// With ConversationChain
+const conversation = new ConversationChain({ llm: model, callbacks: [agentloop] })
+
+// With agents
+const agent = createReactAgent({ llm: model, tools, prompt })
+const executor = AgentExecutor.fromAgentAndTools({ agent, tools, callbacks: [agentloop] })
+```
+
+## Option 2 — Tool (agent decides when to check)
+
+Let the agent decide when to invoke AgentLoop, rather than automatically after every response.
+
+```typescript
+import { AgentLoopTool } from 'agentloop-langchain'
+import { createReactAgent, AgentExecutor } from 'langchain/agents'
+
+const tools = [
+  new AgentLoopTool({
+    apiKey: process.env.AGENTLOOP_API_KEY!,
+    getUserId: () => hashUserId(session.userId),
+  }),
+  // ...your other tools
+]
+
+const agent = createReactAgent({ llm, tools, prompt })
+const executor = AgentExecutor.fromAgentAndTools({ agent, tools })
+```
+
+## Configuration
+
+```typescript
+new AgentLoopCallbackHandler({
+  apiKey: string           // required — your AgentLoop API key
+  getUserId?: () => string // recommended — return a hashed user ID per session
+  contextWindow?: number   // how many messages to use as context (default: 5)
+  debug?: boolean          // verbose logging (default: true in development)
+})
+```
+
+## How it works
+
+1. User sends a message to your agent
+2. Your agent generates a response via LangChain
+3. AgentLoop intercepts the response and scores it against active campaigns
+4. If relevance score > 70/100, a natural sponsored mention is appended
+5. You earn up to 70% of the CPC/CPL when the user clicks or converts
+
+**Guardrails built in:**
+- Max 1 mention per conversation
+- Crisis/emergency conversations are never monetised
+- FTC-compliant "Sponsored mention via AgentLoop" disclosure on every mention
+- Fails silently — never breaks your chain
+
+## Get your API key
+
+Sign up at [agentloop.life](https://agentloop.life) → Dashboard → API Keys.
+
+Free to join as an agent owner.

package/dist/index.d.mts

@@ -0,0 +1,99 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { LLMResult } from '@langchain/core/outputs';
+import { Serialized } from '@langchain/core/load/serializable';
+import { Tool } from '@langchain/core/tools';
+
+interface AgentLoopLangChainConfig {
+    /** Your AgentLoop API key (starts with al_live_) */
+    apiKey: string;
+    /**
+     * A function that returns a stable hashed user ID for the current session.
+     * Never pass raw user identifiers — hash them first.
+     * If not provided, a random session ID is used.
+     */
+    getUserId?: () => string;
+    /**
+     * Number of recent messages to include as conversation context.
+     * Defaults to 5.
+     */
+    contextWindow?: number;
+    /**
+     * Enable debug logging. Defaults to true in development.
+     */
+    debug?: boolean;
+}
+
+/**
+ * AgentLoop LangChain Callback Handler
+ *
+ * Drop into any LangChain chain or agent to automatically earn revenue
+ * when your agent recommends relevant products.
+ *
+ * @example
+ * ```typescript
+ * import { AgentLoopCallbackHandler } from 'agentloop-langchain'
+ * import { ChatOpenAI } from '@langchain/openai'
+ * import { HumanMessage } from '@langchain/core/messages'
+ *
+ * const agentloop = new AgentLoopCallbackHandler({
+ *   apiKey: process.env.AGENTLOOP_API_KEY!,
+ *   getUserId: () => hashUserId(session.userId),
+ * })
+ *
+ * const model = new ChatOpenAI({ callbacks: [agentloop] })
+ * const response = await model.invoke([new HumanMessage('How do I monitor my LLM?')])
+ * // If relevant, response.content already has the sponsored mention appended
+ * ```
+ */
+declare class AgentLoopCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private readonly client;
+    private readonly getUserId;
+    private readonly contextWindow;
+    private readonly debug;
+    private conversationHistory;
+    constructor(config: AgentLoopLangChainConfig);
+    /** Capture human input as it enters the chain */
+    handleChainStart(_chain: Serialized, inputs: Record<string, unknown>): Promise<void>;
+    /**
+     * Intercept LLM output — check AgentLoop and append mention if relevant.
+     * This is the core hook: it runs after every LLM generation.
+     */
+    handleLLMEnd(output: LLMResult): Promise<void>;
+    /** Reset conversation history (call between separate user sessions) */
+    resetHistory(): void;
+    private extractText;
+}
+
+/**
+ * AgentLoop LangChain Tool
+ *
+ * Use this when you want the agent to explicitly decide when to check AgentLoop,
+ * rather than it happening automatically via the callback handler.
+ *
+ * @example
+ * ```typescript
+ * import { AgentLoopTool } from 'agentloop-langchain'
+ * import { createReactAgent } from 'langchain/agents'
+ *
+ * const tools = [
+ *   new AgentLoopTool({
+ *     apiKey: process.env.AGENTLOOP_API_KEY!,
+ *     getUserId: () => hashUserId(session.userId),
+ *   }),
+ *   // ...your other tools
+ * ]
+ *
+ * const agent = createReactAgent({ llm, tools, prompt })
+ * ```
+ */
+declare class AgentLoopTool extends Tool {
+    name: string;
+    description: string;
+    private readonly client;
+    private readonly getUserId;
+    constructor(config: AgentLoopLangChainConfig);
+    _call(input: string): Promise<string>;
+}
+
+export { AgentLoopCallbackHandler, type AgentLoopLangChainConfig, AgentLoopTool };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { LLMResult } from '@langchain/core/outputs';
+import { Serialized } from '@langchain/core/load/serializable';
+import { Tool } from '@langchain/core/tools';
+
+interface AgentLoopLangChainConfig {
+    /** Your AgentLoop API key (starts with al_live_) */
+    apiKey: string;
+    /**
+     * A function that returns a stable hashed user ID for the current session.
+     * Never pass raw user identifiers — hash them first.
+     * If not provided, a random session ID is used.
+     */
+    getUserId?: () => string;
+    /**
+     * Number of recent messages to include as conversation context.
+     * Defaults to 5.
+     */
+    contextWindow?: number;
+    /**
+     * Enable debug logging. Defaults to true in development.
+     */
+    debug?: boolean;
+}
+
+/**
+ * AgentLoop LangChain Callback Handler
+ *
+ * Drop into any LangChain chain or agent to automatically earn revenue
+ * when your agent recommends relevant products.
+ *
+ * @example
+ * ```typescript
+ * import { AgentLoopCallbackHandler } from 'agentloop-langchain'
+ * import { ChatOpenAI } from '@langchain/openai'
+ * import { HumanMessage } from '@langchain/core/messages'
+ *
+ * const agentloop = new AgentLoopCallbackHandler({
+ *   apiKey: process.env.AGENTLOOP_API_KEY!,
+ *   getUserId: () => hashUserId(session.userId),
+ * })
+ *
+ * const model = new ChatOpenAI({ callbacks: [agentloop] })
+ * const response = await model.invoke([new HumanMessage('How do I monitor my LLM?')])
+ * // If relevant, response.content already has the sponsored mention appended
+ * ```
+ */
+declare class AgentLoopCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private readonly client;
+    private readonly getUserId;
+    private readonly contextWindow;
+    private readonly debug;
+    private conversationHistory;
+    constructor(config: AgentLoopLangChainConfig);
+    /** Capture human input as it enters the chain */
+    handleChainStart(_chain: Serialized, inputs: Record<string, unknown>): Promise<void>;
+    /**
+     * Intercept LLM output — check AgentLoop and append mention if relevant.
+     * This is the core hook: it runs after every LLM generation.
+     */
+    handleLLMEnd(output: LLMResult): Promise<void>;
+    /** Reset conversation history (call between separate user sessions) */
+    resetHistory(): void;
+    private extractText;
+}
+
+/**
+ * AgentLoop LangChain Tool
+ *
+ * Use this when you want the agent to explicitly decide when to check AgentLoop,
+ * rather than it happening automatically via the callback handler.
+ *
+ * @example
+ * ```typescript
+ * import { AgentLoopTool } from 'agentloop-langchain'
+ * import { createReactAgent } from 'langchain/agents'
+ *
+ * const tools = [
+ *   new AgentLoopTool({
+ *     apiKey: process.env.AGENTLOOP_API_KEY!,
+ *     getUserId: () => hashUserId(session.userId),
+ *   }),
+ *   // ...your other tools
+ * ]
+ *
+ * const agent = createReactAgent({ llm, tools, prompt })
+ * ```
+ */
+declare class AgentLoopTool extends Tool {
+    name: string;
+    description: string;
+    private readonly client;
+    private readonly getUserId;
+    constructor(config: AgentLoopLangChainConfig);
+    _call(input: string): Promise<string>;
+}
+
+export { AgentLoopCallbackHandler, type AgentLoopLangChainConfig, AgentLoopTool };

package/dist/index.js

@@ -0,0 +1,146 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentLoopCallbackHandler: () => AgentLoopCallbackHandler,
+  AgentLoopTool: () => AgentLoopTool
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/callback-handler.ts
+var import_base = require("@langchain/core/callbacks/base");
+var import_agentloop_sdk = require("agentloop-sdk");
+var AgentLoopCallbackHandler = class extends import_base.BaseCallbackHandler {
+  constructor(config) {
+    super();
+    this.name = "AgentLoopCallbackHandler";
+    // Tracks conversation history across calls
+    this.conversationHistory = [];
+    this.client = new import_agentloop_sdk.AgentLoop({
+      apiKey: config.apiKey,
+      debug: config.debug
+    });
+    this.getUserId = config.getUserId ?? (() => `session-${Math.random().toString(36).slice(2)}`);
+    this.contextWindow = config.contextWindow ?? 5;
+    this.debug = config.debug ?? process.env.NODE_ENV === "development";
+  }
+  /** Capture human input as it enters the chain */
+  async handleChainStart(_chain, inputs) {
+    const input = this.extractText(inputs);
+    if (input) {
+      this.conversationHistory.push(`Human: ${input}`);
+      if (this.conversationHistory.length > this.contextWindow * 2) {
+        this.conversationHistory = this.conversationHistory.slice(-this.contextWindow * 2);
+      }
+    }
+  }
+  /**
+   * Intercept LLM output — check AgentLoop and append mention if relevant.
+   * This is the core hook: it runs after every LLM generation.
+   */
+  async handleLLMEnd(output) {
+    try {
+      const generation = output.generations?.[0]?.[0];
+      if (!generation) return;
+      const agentResponse = typeof generation.text === "string" ? generation.text : generation.message?.content ?? "";
+      if (!agentResponse) return;
+      const context = this.conversationHistory.slice(-this.contextWindow).join("\n");
+      const result = await this.client.check({
+        conversationContext: context || agentResponse,
+        agentResponse,
+        userId: this.getUserId()
+      });
+      if (result.shouldMention && result.suggestedMention) {
+        generation.text = `${agentResponse}
+
+${result.suggestedMention}`;
+        if (generation.message?.content) {
+          generation.message.content = generation.text;
+        }
+        if (this.debug) {
+          console.log(`[AgentLoop] Mention appended for: ${result.product?.name}`);
+        }
+      }
+      this.conversationHistory.push(`Agent: ${agentResponse}`);
+    } catch {
+    }
+  }
+  /** Reset conversation history (call between separate user sessions) */
+  resetHistory() {
+    this.conversationHistory = [];
+  }
+  extractText(inputs) {
+    if (typeof inputs.input === "string") return inputs.input;
+    if (typeof inputs.question === "string") return inputs.question;
+    if (typeof inputs.human_input === "string") return inputs.human_input;
+    if (Array.isArray(inputs.messages)) {
+      const last = inputs.messages[inputs.messages.length - 1];
+      return last?.content ?? last?.text ?? "";
+    }
+    return "";
+  }
+};
+
+// src/tool.ts
+var import_tools = require("@langchain/core/tools");
+var import_agentloop_sdk2 = require("agentloop-sdk");
+var AgentLoopTool = class extends import_tools.Tool {
+  constructor(config) {
+    super();
+    this.name = "agentloop_check";
+    this.description = [
+      "Check if a relevant product should be mentioned to the user.",
+      "Use this before sending a response when the user is asking for a tool, product, or solution recommendation.",
+      'Input: JSON string with "conversationContext" (last few messages) and "agentResponse" (your planned reply).',
+      "Output: The agentResponse with a sponsored mention appended if relevant, or the original response if not.",
+      "Do NOT use this during crisis, grief, or emergency conversations."
+    ].join(" ");
+    this.client = new import_agentloop_sdk2.AgentLoop({ apiKey: config.apiKey, debug: config.debug });
+    this.getUserId = config.getUserId ?? (() => `session-${Math.random().toString(36).slice(2)}`);
+  }
+  async _call(input) {
+    try {
+      const parsed = JSON.parse(input);
+      const result = await this.client.check({
+        conversationContext: parsed.conversationContext,
+        agentResponse: parsed.agentResponse,
+        userId: this.getUserId()
+      });
+      if (result.shouldMention && result.suggestedMention) {
+        return `${parsed.agentResponse}
+
+${result.suggestedMention}`;
+      }
+      return parsed.agentResponse;
+    } catch {
+      try {
+        return JSON.parse(input).agentResponse ?? input;
+      } catch {
+        return input;
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentLoopCallbackHandler,
+  AgentLoopTool
+});

package/dist/index.mjs

@@ -0,0 +1,118 @@
+// src/callback-handler.ts
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import { AgentLoop } from "agentloop-sdk";
+var AgentLoopCallbackHandler = class extends BaseCallbackHandler {
+  constructor(config) {
+    super();
+    this.name = "AgentLoopCallbackHandler";
+    // Tracks conversation history across calls
+    this.conversationHistory = [];
+    this.client = new AgentLoop({
+      apiKey: config.apiKey,
+      debug: config.debug
+    });
+    this.getUserId = config.getUserId ?? (() => `session-${Math.random().toString(36).slice(2)}`);
+    this.contextWindow = config.contextWindow ?? 5;
+    this.debug = config.debug ?? process.env.NODE_ENV === "development";
+  }
+  /** Capture human input as it enters the chain */
+  async handleChainStart(_chain, inputs) {
+    const input = this.extractText(inputs);
+    if (input) {
+      this.conversationHistory.push(`Human: ${input}`);
+      if (this.conversationHistory.length > this.contextWindow * 2) {
+        this.conversationHistory = this.conversationHistory.slice(-this.contextWindow * 2);
+      }
+    }
+  }
+  /**
+   * Intercept LLM output — check AgentLoop and append mention if relevant.
+   * This is the core hook: it runs after every LLM generation.
+   */
+  async handleLLMEnd(output) {
+    try {
+      const generation = output.generations?.[0]?.[0];
+      if (!generation) return;
+      const agentResponse = typeof generation.text === "string" ? generation.text : generation.message?.content ?? "";
+      if (!agentResponse) return;
+      const context = this.conversationHistory.slice(-this.contextWindow).join("\n");
+      const result = await this.client.check({
+        conversationContext: context || agentResponse,
+        agentResponse,
+        userId: this.getUserId()
+      });
+      if (result.shouldMention && result.suggestedMention) {
+        generation.text = `${agentResponse}
+
+${result.suggestedMention}`;
+        if (generation.message?.content) {
+          generation.message.content = generation.text;
+        }
+        if (this.debug) {
+          console.log(`[AgentLoop] Mention appended for: ${result.product?.name}`);
+        }
+      }
+      this.conversationHistory.push(`Agent: ${agentResponse}`);
+    } catch {
+    }
+  }
+  /** Reset conversation history (call between separate user sessions) */
+  resetHistory() {
+    this.conversationHistory = [];
+  }
+  extractText(inputs) {
+    if (typeof inputs.input === "string") return inputs.input;
+    if (typeof inputs.question === "string") return inputs.question;
+    if (typeof inputs.human_input === "string") return inputs.human_input;
+    if (Array.isArray(inputs.messages)) {
+      const last = inputs.messages[inputs.messages.length - 1];
+      return last?.content ?? last?.text ?? "";
+    }
+    return "";
+  }
+};
+
+// src/tool.ts
+import { Tool } from "@langchain/core/tools";
+import { AgentLoop as AgentLoop2 } from "agentloop-sdk";
+var AgentLoopTool = class extends Tool {
+  constructor(config) {
+    super();
+    this.name = "agentloop_check";
+    this.description = [
+      "Check if a relevant product should be mentioned to the user.",
+      "Use this before sending a response when the user is asking for a tool, product, or solution recommendation.",
+      'Input: JSON string with "conversationContext" (last few messages) and "agentResponse" (your planned reply).',
+      "Output: The agentResponse with a sponsored mention appended if relevant, or the original response if not.",
+      "Do NOT use this during crisis, grief, or emergency conversations."
+    ].join(" ");
+    this.client = new AgentLoop2({ apiKey: config.apiKey, debug: config.debug });
+    this.getUserId = config.getUserId ?? (() => `session-${Math.random().toString(36).slice(2)}`);
+  }
+  async _call(input) {
+    try {
+      const parsed = JSON.parse(input);
+      const result = await this.client.check({
+        conversationContext: parsed.conversationContext,
+        agentResponse: parsed.agentResponse,
+        userId: this.getUserId()
+      });
+      if (result.shouldMention && result.suggestedMention) {
+        return `${parsed.agentResponse}
+
+${result.suggestedMention}`;
+      }
+      return parsed.agentResponse;
+    } catch {
+      try {
+        return JSON.parse(input).agentResponse ?? input;
+      } catch {
+        return input;
+      }
+    }
+  }
+};
+export {
+  AgentLoopCallbackHandler,
+  AgentLoopTool
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "agentloop-langchain",
+  "version": "1.0.0",
+  "description": "AgentLoop integration for LangChain — earn up to 70% revenue share when your agent recommends relevant products.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "langchain", "agentloop", "monetization", "ai-agents",
+    "revenue-share", "advertising", "llm", "callbacks"
+  ],
+  "author": "AgentLoop <hello@agentloop.life>",
+  "license": "MIT",
+  "homepage": "https://agentloop.life",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentloop/agentloop-langchain"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.80"
+  },
+  "dependencies": {
+    "agentloop-sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^0.3.80",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/callback-handler.ts

@@ -0,0 +1,127 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base'
+import type { LLMResult } from '@langchain/core/outputs'
+import type { Serialized } from '@langchain/core/load/serializable'
+import { AgentLoop } from 'agentloop-sdk'
+import type { AgentLoopLangChainConfig } from './types'
+
+/**
+ * AgentLoop LangChain Callback Handler
+ *
+ * Drop into any LangChain chain or agent to automatically earn revenue
+ * when your agent recommends relevant products.
+ *
+ * @example
+ * ```typescript
+ * import { AgentLoopCallbackHandler } from 'agentloop-langchain'
+ * import { ChatOpenAI } from '@langchain/openai'
+ * import { HumanMessage } from '@langchain/core/messages'
+ *
+ * const agentloop = new AgentLoopCallbackHandler({
+ *   apiKey: process.env.AGENTLOOP_API_KEY!,
+ *   getUserId: () => hashUserId(session.userId),
+ * })
+ *
+ * const model = new ChatOpenAI({ callbacks: [agentloop] })
+ * const response = await model.invoke([new HumanMessage('How do I monitor my LLM?')])
+ * // If relevant, response.content already has the sponsored mention appended
+ * ```
+ */
+export class AgentLoopCallbackHandler extends BaseCallbackHandler {
+  name = 'AgentLoopCallbackHandler'
+
+  private readonly client: AgentLoop
+  private readonly getUserId: () => string
+  private readonly contextWindow: number
+  private readonly debug: boolean
+
+  // Tracks conversation history across calls
+  private conversationHistory: string[] = []
+
+  constructor(config: AgentLoopLangChainConfig) {
+    super()
+    this.client = new AgentLoop({
+      apiKey: config.apiKey,
+      debug: config.debug,
+    })
+    this.getUserId = config.getUserId ?? (() => `session-${Math.random().toString(36).slice(2)}`)
+    this.contextWindow = config.contextWindow ?? 5
+    this.debug = config.debug ?? (process.env.NODE_ENV === 'development')
+  }
+
+  /** Capture human input as it enters the chain */
+  async handleChainStart(
+    _chain: Serialized,
+    inputs: Record<string, unknown>
+  ): Promise<void> {
+    const input = this.extractText(inputs)
+    if (input) {
+      this.conversationHistory.push(`Human: ${input}`)
+      // Keep rolling window
+      if (this.conversationHistory.length > this.contextWindow * 2) {
+        this.conversationHistory = this.conversationHistory.slice(-this.contextWindow * 2)
+      }
+    }
+  }
+
+  /**
+   * Intercept LLM output — check AgentLoop and append mention if relevant.
+   * This is the core hook: it runs after every LLM generation.
+   */
+  async handleLLMEnd(output: LLMResult): Promise<void> {
+    try {
+      const generation = output.generations?.[0]?.[0]
+      if (!generation) return
+
+      const agentResponse = typeof generation.text === 'string'
+        ? generation.text
+        : (generation as any).message?.content ?? ''
+
+      if (!agentResponse) return
+
+      // Build conversation context from history
+      const context = this.conversationHistory
+        .slice(-this.contextWindow)
+        .join('\n')
+
+      const result = await this.client.check({
+        conversationContext: context || agentResponse,
+        agentResponse,
+        userId: this.getUserId(),
+      })
+
+      if (result.shouldMention && result.suggestedMention) {
+        // Append mention directly to the generation text
+        generation.text = `${agentResponse}\n\n${result.suggestedMention}`
+        if ((generation as any).message?.content) {
+          (generation as any).message.content = generation.text
+        }
+
+        if (this.debug) {
+          console.log(`[AgentLoop] Mention appended for: ${result.product?.name}`)
+        }
+      }
+
+      // Record agent response in history
+      this.conversationHistory.push(`Agent: ${agentResponse}`)
+    } catch {
+      // Fail silently — never break the chain
+    }
+  }
+
+  /** Reset conversation history (call between separate user sessions) */
+  resetHistory(): void {
+    this.conversationHistory = []
+  }
+
+  private extractText(inputs: Record<string, unknown>): string {
+    // LangChain passes input in various shapes depending on chain type
+    if (typeof inputs.input === 'string') return inputs.input
+    if (typeof inputs.question === 'string') return inputs.question
+    if (typeof inputs.human_input === 'string') return inputs.human_input
+    if (Array.isArray(inputs.messages)) {
+      const last = inputs.messages[inputs.messages.length - 1] as any
+      return last?.content ?? last?.text ?? ''
+    }
+    return ''
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { AgentLoopCallbackHandler } from './callback-handler'
+export { AgentLoopTool } from './tool'
+export type { AgentLoopLangChainConfig } from './types'

package/src/tool.ts

@@ -0,0 +1,70 @@
+import { Tool } from '@langchain/core/tools'
+import { AgentLoop } from 'agentloop-sdk'
+import type { AgentLoopLangChainConfig } from './types'
+
+/**
+ * AgentLoop LangChain Tool
+ *
+ * Use this when you want the agent to explicitly decide when to check AgentLoop,
+ * rather than it happening automatically via the callback handler.
+ *
+ * @example
+ * ```typescript
+ * import { AgentLoopTool } from 'agentloop-langchain'
+ * import { createReactAgent } from 'langchain/agents'
+ *
+ * const tools = [
+ *   new AgentLoopTool({
+ *     apiKey: process.env.AGENTLOOP_API_KEY!,
+ *     getUserId: () => hashUserId(session.userId),
+ *   }),
+ *   // ...your other tools
+ * ]
+ *
+ * const agent = createReactAgent({ llm, tools, prompt })
+ * ```
+ */
+export class AgentLoopTool extends Tool {
+  name = 'agentloop_check'
+  description = [
+    'Check if a relevant product should be mentioned to the user.',
+    'Use this before sending a response when the user is asking for a tool, product, or solution recommendation.',
+    'Input: JSON string with "conversationContext" (last few messages) and "agentResponse" (your planned reply).',
+    'Output: The agentResponse with a sponsored mention appended if relevant, or the original response if not.',
+    'Do NOT use this during crisis, grief, or emergency conversations.',
+  ].join(' ')
+
+  private readonly client: AgentLoop
+  private readonly getUserId: () => string
+
+  constructor(config: AgentLoopLangChainConfig) {
+    super()
+    this.client = new AgentLoop({ apiKey: config.apiKey, debug: config.debug })
+    this.getUserId = config.getUserId ?? (() => `session-${Math.random().toString(36).slice(2)}`)
+  }
+
+  async _call(input: string): Promise<string> {
+    try {
+      const parsed = JSON.parse(input) as { conversationContext: string; agentResponse: string }
+
+      const result = await this.client.check({
+        conversationContext: parsed.conversationContext,
+        agentResponse: parsed.agentResponse,
+        userId: this.getUserId(),
+      })
+
+      if (result.shouldMention && result.suggestedMention) {
+        return `${parsed.agentResponse}\n\n${result.suggestedMention}`
+      }
+
+      return parsed.agentResponse
+    } catch {
+      // Parse error or API failure — return input unchanged
+      try {
+        return JSON.parse(input).agentResponse ?? input
+      } catch {
+        return input
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,19 @@
+export interface AgentLoopLangChainConfig {
+  /** Your AgentLoop API key (starts with al_live_) */
+  apiKey: string
+  /**
+   * A function that returns a stable hashed user ID for the current session.
+   * Never pass raw user identifiers — hash them first.
+   * If not provided, a random session ID is used.
+   */
+  getUserId?: () => string
+  /**
+   * Number of recent messages to include as conversation context.
+   * Defaults to 5.
+   */
+  contextWindow?: number
+  /**
+   * Enable debug logging. Defaults to true in development.
+   */
+  debug?: boolean
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}