@riv-io/langchain

Adapter LangChain.js do Riv — governança financeira para agentes, construído sobre @riv-io/sdk.

npm install @riv-io/langchain @langchain/core

Caminho recomendado: withRivGuard

Embrulhe sua tool de pagamento com o guard: o Riv é consultado antes de cada execução, deterministicamente — a governança não depende de o LLM lembrar de pedir autorização.

import { withRivGuard } from "@riv-io/langchain";

const guardedPay = withRivGuard(payInvoiceTool, {
  apiKey: process.env.RIV_API_KEY!,
  extract: (input) => ({ amount: input.total, currency: "BRL" }),
});

const agent = createReactAgent({ llm, tools: [guardedPay] });

• allow → a tool executa normalmente.
• block / require_approval → a tool nem executa; o agente recebe o veredito (decisão, motivo, activityId) como texto.
• Falha ao consultar o Riv (rede, credencial) → fail-closed: a tool não executa.
• extract mapeia o input da sua tool para { amount, currency, description? }.
• O guard preserva nome, descrição e schema da tool original — para o LLM, nada muda.

Para reusar um client: withRivGuard(tool, { riv: meuClient, extract }).

As opções aceitam também baseUrl — default http://localhost:3000 (dev local); em produção, aponte para https://riv-io.vercel.app: withRivGuard(tool, { apiKey, baseUrl: "https://riv-io.vercel.app", extract }) ou rivTools({ apiKey, baseUrl: "https://riv-io.vercel.app" }).

Complemento: rivTools

Tools prontas para a lista do agente — para consultar o ledger e para fluxos sem uma tool de pagamento a embrulhar:

import { rivTools } from "@riv-io/langchain";

const agent = createReactAgent({
  llm,
  tools: [...rivTools({ apiKey: process.env.RIV_API_KEY! }), ...outrasTools],
});

• riv_authorize({ amount, currency, description?, category? }) — pede a decisão de governança (mesma semântica do MCP server do Riv); category ativa mandatos por categoria.
• riv_get_activity({ activityId?, limit? }) — consulta pontual ou extrato.

Atenção: por este caminho, executar o gasto só quando ALLOW depende do LLM. Quando existir uma tool de pagamento, prefira o withRivGuard.

Desenvolvimento

cd adapters/langchain
npm install
npm run build        # tsup → dist/ (ESM + CJS + d.ts)
npm run typecheck
npm run test         # unitários (fetch mockado)

# E2E (a partir da raiz do repo; sobe a app em porta efêmera):
#   node --env-file=.env scripts/verify-langchain.mjs