operantid.js

v1.0.0

Published

12 days ago

<img src="operantid.PNG" alt="OperantID Banner" width="100%"> Universal Autonomous AI Agent Framework for High-Performance Browser Navigation and Automated Reasoning - Node.js Edition

0High
0Medium
0Low

juniormaia

ai browser-automation agent playwright llm

OperantID 🤖

OperantID é um framework de raciocínio autônomo que orquestra Large Language Models e automação de navegadores para executar tarefas complexas na Web com precisão semântica. Diferentemente de ferramentas de RPA tradicionais baseadas em seletores estáticos frágeis, o OperantID utiliza um loop de percepção-raciocínio-ação contínuo para se adaptar dinamicamente a qualquer interface, estado de página ou fluxo de autenticação. Agora disponível em JavaScript/Node.js.

Benchmarks Reais 🚀

O OperantID é otimizado para velocidade e baixo consumo de tokens. Abaixo está a comparação real entre modelos Gemini em tarefas de navegação e extração:

*Nota: O modelo 3.1 Pro Preview apresentou inconsistências no formato de resposta JSON durante os testes automatizados, resultando em falhas de validação. O modelo 2.5 Flash continua sendo o mais recomendado para tarefas que exigem alta resiliência e bypass de bot. Todos os testes foram realizados em modo headless com delay de 2s para estabilidade.

Índice

Por que OperantID?

A maioria das ferramentas de automação Web falha por um motivo fundamental: elas dependem de seletores CSS ou XPath hardcoded que quebram na primeira atualização de layout do site.

O OperantID resolve isso com um paradigma radicalmente diferente:

Percepção Semântica: Em vez de depender de IDs ou classes arbitrárias, o framework injeta um script de inspeção no DOM a cada passo, extraindo apenas os elementos visíveis e interativos. Isso elimina o ruído e fornece ao LLM apenas o que é relevante.
Raciocínio em Contexto: O histórico completo de ações anteriores é fornecido ao LLM a cada passo, permitindo que ele construa uma memória de curto prazo e raciocine sobre o estado atual da missão.
Auto-Correção: Se um clique por seletor falha, o agente automaticamente tenta localizar o elemento pelo seu texto visível, aumentando a resiliência da execução.
Provider-Agnostic: Uma única API para rodar Gemini, OpenAI, Mistral, Groq, Ollama, DeepSeek e qualquer provedor compatível com a especificação OpenAI.

Arquitetura IRE

O OperantID opera sobre o paradigma IRE (Inspect → Reason → Execute), um ciclo contínuo que opera de forma assíncrona:

┌─────────────────────────────────────────────────────────┐
│                    MISSÃO DO AGENTE                     │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
         ┌────────────────────────────────┐
         │  INSPECT (Percepção Semântica)│
         │  ─────────────────────────── │
         │  Injeta script JS no DOM      │
         │  Extrai: URL, título, h1/h2,  │
         │  inputs, buttons, links,      │
         │  elementos ARIA visíveis      │
         │  Atribui data-operant-id a    │
         │  cada elemento interativo     │
         └──────────────┬─────────────────┘
                        │
                        ▼
         ┌────────────────────────────────┐
         │   REASON (LLM Decision)        │
         │   ─────────────────────────── │
         │  Contexto enviado ao LLM:      │
         │  - Objetivo original           │
         │  - Histórico de ações (n-k)    │
         │  - Mapa de elementos atual     │
         │  - Credenciais, se relevante   │
         │  Output: JSON estruturado      │
         │  com action, status, reasoning │
         └──────────────┬─────────────────┘
                        │
                        ▼
         ┌────────────────────────────────┐
         │   EXECUTE (Playwright Action)  │
         │   ─────────────────────────── │
         │  Traduz decisão JSON para      │
         │  comandos físicos:             │
         │  navigate, click, type,        │
         │  scroll, pressEnter, wait...   │
         │  Fallback automático por texto │
         └──────────────┬─────────────────┘
                        │
               status == "completed"?
                   │           │
                  Não          Sim
                   │           └──► Retorna resultado
                   └──► Próximo Passo (step + 1)

Instalação

npm install operantid.js

Após instalar, é necessário baixar os binários do Playwright (apenas uma vez):

npx playwright install chromium
# Opcional: instalar Firefox e Webkit também
npx playwright install firefox webkit

Quick Start

import { Agent } from 'operantid.js';

async function main() {
    const agent = new Agent({
        api_key: "SUA_API_KEY",
        provider: "gemini",
        model: "gemini-1.5-flash"
    });

    const result = await agent.execute(
        "Vá ao DuckDuckGo e pesquise as últimas notícias sobre inteligência artificial"
    );

    console.log(result);
}

main();

Provedores de IA

O OperantID abstrai a comunicação com qualquer LLM através de um único parâmetro provider.

Google Gemini

const agent = new Agent({
    api_key: "GOOGLE_API_KEY",
    provider: "gemini",
    model: "gemini-1.5-flash"
});

OpenAI e Compatíveis

const agent = new Agent({
    api_key: "OPENAI_API_KEY",
    provider: "openai",
    model: "gpt-4o"
});

OpenRouter

const agent = new Agent({
    api_key: "OPENROUTER_API_KEY",
    provider: "openai",
    model: "anthropic/claude-3.5-sonnet",
    base_url: "https://openrouter.ai/api/v1"
});

Ollama (Local)

const agent = new Agent({
    api_key: "ollama",
    provider: "openai",
    model: "llama3.2",
    base_url: "http://localhost:11434/v1"
});

Mistral AI

const agent = new Agent({
    api_key: "MISTRAL_API_KEY",
    provider: "mistral",
    model: "mistral-large-latest"
});

Guia Completo de Uso

Inicialização do Agente

const agent = new Agent({
    api_key: "SUA_API_KEY",
    provider: "gemini",           // gemini | openai | mistral
    model: "gemini-1.5-flash",    // Opcional
    base_url: null,               // Para endpoints customizados
    headless: false,              // True: navegador invisível
    email: null,                  // Login automático
    password: null,               // Login automático
    browser_config: {}            // Configurações avançadas
});

Automação de Login com Credenciais

O OperantID possui injeção de credenciais no prompt do agente.

const agent = new Agent({
    api_key: "SUA_API_KEY",
    provider: "gemini",
    email: "[email protected]",
    password: "SuaSenhaSegura123"
});

const result = await agent.execute(
    "Acesse meu painel no GitHub e liste os repositórios com mais estrelas"
);

Callback onStep e Observabilidade

const result = await agent.execute(
    "Pesquise por Python no Google",
    (data) => {
        console.log(`[PASSO ${data.step}] ${data.reasoning}`);
    }
);

Configurações Avançadas de Navegador

const agent = new Agent({
    api_key: "...",
    provider: "gemini",
    browser_config: {
        browserType: "firefox", // chromium | firefox | webkit
        userAgent: "Mozilla/5.0...",
        viewport: { width: 1920, height: 1080 },
        locale: "en-US",
        timezone: "America/New_York"
    }
});

Stealth Mode e Anti-Detecção

O OperantID.Js integra o playwright-extra e puppeteer-extra-plugin-stealth nativamente. A biblioteca aplica automaticamente um conjunto de patches que permitem navegar em sites com Cloudflare, reCAPTCHA e outros sistemas anti-bot sem configurações adicionais.

Playground WebUI

import { launchUI } from 'operantid.js';

launchUI(5000);

Acesse http://localhost:5000 para controlar o agente via interface gráfica com Live Browser Stream.

Referência Completa da API

Ações Disponíveis para a IA

| Ação | Descrição | |:-----|:----------| | navigate | Navega para uma URL | | click | Clica em um seletor ou texto | | type | Digita em campos de input | | scroll | Rola a página | | pressEnter| Pressiona a tecla Enter | | wait | Aguarda N milissegundos | | createTab | Abre nova aba | | switchTab | Troca para aba específica | | closeTab | Fecha uma aba | | talk | Envia mensagem ao usuário | | completed | Finaliza a missão com sucesso |

Exemplos Avançados

Pipeline de Pesquisa Comparativa Multi-Site

const result = await agent.execute(
    "Abra o Amazon.com.br e o Mercado Livre em abas separadas. " +
    "Em cada um, pesquise por 'Headset Gamer'. Compare os preços."
);

Licença

Este projeto está sob a licença ISC.