Pular para conteúdo

LangChain / LangGraph Adapter

O adaptador @elroi/langchain-adapter converte qualquer squad AIOS em uma StructuredTool LangChain, compatível com LangGraph, CrewAI e qualquer agente que suporte o protocolo de ferramentas.

Instalação

# No seu projeto
npm install @langchain/core @langchain/anthropic zod
# Importar direto do monorepo
import { ElroiSquadTool, ElroiAgentRunnable, loadSquadFromYaml }
  from "../../elroi-core/adapters/langchain/src/index.js";

Uso básico

import { ElroiSquadTool } from "@elroi/langchain-adapter";
import { loadSquadFromYaml } from "@elroi/langchain-adapter";

// Carregar squad do sistema de arquivos
const { config, agents } = loadSquadFromYaml("./squads/_tier-2-revenue/copywriting");

// Criar tool LangChain
const tool = new ElroiSquadTool(config, agents);

// Usar diretamente
const result = await tool._call({
  input: "Crie 5 headlines para um SaaS de produtividade"
});

import { ElroiAgentRunnable } from "@elroi/langchain-adapter";
import { ChatAnthropic } from "@langchain/anthropic";
import { StringOutputParser } from "@langchain/core/output_parsers";

// Criar runnable a partir de um diretório de squad
const copywriting = ElroiAgentRunnable.fromDirectory(
  "./squads/_tier-2-revenue/copywriting"
);

// Encadear com LCEL
const chain = copywriting.pipe(new StringOutputParser());

const result = await chain.invoke({
  input: "Escreva um email de vendas para devs sênior"
});

import { StateGraph } from "@langchain/langgraph";
import { ElroiSquadTool, loadSquadFromYaml } from "@elroi/langchain-adapter";

// Carregar múltiplas squads como ferramentas
const squads = ["copywriting", "branding", "design"].map(name => {
  const { config, agents } = loadSquadFromYaml(
    `./squads/_tier-2-revenue/${name}`
  );
  return new ElroiSquadTool(config, agents);
});

// Criar grafo de execução
const graph = new StateGraph({...});
// squads disponíveis como tools para o agente orquestrador

Circuit Breaker

O adaptador implementa circuit breaker com 3 tentativas antes de abortar:

stateDiagram-v2
    [*] --> Closed
    Closed --> Closed : Sucesso
    Closed --> HalfOpen : Falha (tentativa 1 ou 2)
    HalfOpen --> Closed : Sucesso
    HalfOpen --> Open : Falha (tentativa 3)
    Open --> [*] : Throw Error
// Configuração no squad.yaml
quality_gate:
  min_axioma_score: 70  # score mínimo para aceitar o output

Se o output tiver score < 70, o circuit breaker tenta novamente (até 3x).

Quality Gate Numérico

Todo output passa por validação antes de ser retornado:

Score Ação
≥ 70 Aceitar e retornar
< 70 Retry (até 3x)
Falha após 3x Circuit breaker → throw Error

Envelope Tipado (INTER-AGENT-CONTRACT)

Toda execução usa o envelope padrão AIOS:

interface ExecutionEnvelope {
  schema_version: "1.0.0";
  request_id: string;           // UUID único por execução
  timestamp: string;            // ISO 8601
  sender: {
    agent_id: string;           // quem enviou
    tenant_id: string;          // isolamento por tenant
  };
  contract: {
    squad_id: string;
    agent_id: string;
    input: string;
    model: string;              // LLM selecionado pelo routing
    options?: Record<string, unknown>;
  };
  result?: {
    output: string;
    quality_score: number;      // 0-100
    tokens_used: number;
    latency_ms: number;
    model_used: string;
  };
  circuit_breaker?: {
    attempt: number;            // 1, 2 ou 3
    last_error?: string;
    status: "open" | "closed" | "half-open";
  };
}

Variáveis de ambiente

Variável Padrão Descrição
ELROI_GATEWAY_URL http://localhost:3000 URL do API Gateway
ELROI_API_KEY — JWT para autenticação no gateway

Se ELROI_API_KEY não estiver definido, o adapter retorna uma resposta simulada (modo desenvolvimento).

Compatibilidade de plataformas

Plataforma Compatibilidade Como
LangChain.js Nativa ElroiSquadTool extends StructuredTool
LangGraph Nativa ElroiAgentRunnable extends Runnable
CrewAI Via schema JSON Exportar definição do tool
AutoGen Via API Gateway Chamar /v1/squads/{squad}/run
n8n Via webhook Rota HTTP do API Gateway
Flowise Via API HTTP Rota HTTP do API Gateway