Universal LLM Agent 2.0: o agente Python de arquivo único que conecta LLMs locais e na nuvem a mais de 110 ferramentas reais

O que é o Universal LLM Agent e por que ele chama atenção?

No ecossistema atual de ferramentas de IA, a maioria dos agentes exige frameworks pesados, dezenas de dependências e configurações complexas antes de executar qualquer coisa útil. O Universal LLM Agent surge como uma alternativa deliberadamente enxuta: um único arquivo Python chamado ai_agent.py que conecta modelos de linguagem grandes (LLMs) — tanto locais quanto hospedados na nuvem — a um conjunto impressionante de mais de 110 ferramentas reais do sistema operacional.

A versão 2.0 representa uma fusão importante: o núcleo do antigo agente de console foi integrado a uma interface TUI completa construída com a biblioteca Textual. O resultado é um runtime de agente que você pode abrir, ler, modificar e executar sem precisar de infraestrutura adicional.

Dois modos de interface: TUI e Console

Uma das decisões de design mais interessantes do projeto é oferecer duas experiências completamente diferentes a partir do mesmo arquivo:

• Modo TUI (padrão): interface em tela cheia com chat, barra lateral, animações de céu estrelado e aparecimento suave de mensagens. Requer dependências como textual, rich, psutil e Pillow.
• Modo Console: um REPL clássico que funciona apenas com a biblioteca padrão do Python 3.11+. Ideal para servidores, ambientes minimalistas ou situações onde instalar pacotes não é desejável.

Para iniciar cada modo, basta executar python ai_agent.py para a TUI ou python ai_agent.py --console para o REPL clássico. Também é possível especificar o backend diretamente na linha de comando, o que torna a ferramenta extremamente flexível para diferentes fluxos de trabalho.

Tool Calling real: native e prompt-based

O diferencial técnico central do Universal LLM Agent está na sua abordagem ao tool calling. O agente opera em dois mundos simultaneamente:

• Modo native: utiliza a API de ferramentas compatível com OpenAI, passando os schemas de funções diretamente para modelos que suportam esse protocolo, como Ollama, LM Studio, vLLM, OpenAI, Groq, Mistral e OpenRouter.
• Modo prompt-based: para modelos sem suporte nativo a ferramentas — como KoboldCpp e llama.cpp — o agente injeta instruções no estilo Hermes com tags de tool_call no prompt do sistema, ensinando o modelo a chamar funções através do texto gerado.
• Modo auto: tenta o modo native primeiro e, se o backend não suportar, cai automaticamente para o fallback baseado em prompt.

Além disso, o agente consegue executar múltiplas chamadas de ferramentas independentes em paralelo usando ThreadPoolExecutor, o que acelera significativamente tarefas que envolvem operações simultâneas no sistema.

Mais de 110 ferramentas organizadas em categorias

O catálogo de ferramentas é um dos pontos mais impressionantes do projeto. São mais de 110 funções distribuídas em seis grandes categorias funcionais.

Arquivos e disco

São 21 ferramentas cobrindo leitura e escrita de arquivos com offset e limite, operações binárias com hex e Base64, patches em binários, verificação de checksums, compressão e descompressão de arquivos zip e tar, além de busca recursiva com proteção contra ReDoS no grep integrado.

Código e computação

25 ferramentas incluindo execução de Python em subprocesso com sandbox no Unix, comandos shell com lista de bloqueio para operações perigosas, PowerShell no Windows, calculadora segura via AST sem uso de eval, manipulação de CSV, XML, JSON Lines e SQLite, além de geração de UUID e senhas criptograficamente seguras.

Web e rede

8 ferramentas cobrindo busca no DuckDuckGo sem necessidade de chave de API, requisições HTTP arbitrárias com retry e backoff exponencial, verificação de portas TCP e listagem de perfis WiFi no Windows.

Automação do Desktop Windows

18 ferramentas para listagem e manipulação de janelas, envio de teclas, cliques em elementos de interface, capturas de tela via PrintWindow API, leitura e escrita no registro do Windows, gerenciamento de serviços, consultas WMI e notificações do sistema.

Memória e produtividade

14 ferramentas incluindo memória de longo prazo persistente entre sessões, armazenamento chave-valor em SQLite, lista de tarefas, bloco de notas em blocos, compressão de histórico via resumo, gerenciamento de segredos com keyring e a função ask_helper que solicita uma segunda opinião ao próprio LLM em diferentes papéis como crítico, planejador, revisor ou criativo.

Integrações e automação

20 ferramentas para envio de mensagens pelo Telegram e Discord via webhook, envio de e-mail por SMTP, cliente WebSocket, gerenciamento de containers Docker, sandbox isolada para experimentos perigosos, gerenciamento de ambientes virtuais Python, agendamento de tarefas no Windows e integração com Ansible e Kubernetes.

Backends suportados: do Ollama ao OpenAI

O agente foi projetado para ser agnóstico em relação ao backend. A lista de compatibilidade inclui Ollama em localhost:11434 com suporte nativo a ferramentas, LM Studio em localhost:1234, vLLM em localhost:8000 com parser Hermes, OpenAI com chave de API, Groq, Mistral, além de KoboldCpp e llama.cpp que operam sem suporte nativo usando o fallback de prompt. A Anthropic também pode ser integrada via proxy compatível com OpenAI.

Instalação e configuração

A instalação mais simples é via pip diretamente do repositório GitHub do projeto. Após isso, o comando ai-agent fica disponível globalmente no sistema. No Windows, existe um launcher chamado Start.bat que verifica e instala o Python automaticamente, instala as dependências, detecta o backend ativo via netstat e abre um menu de inicialização interativo. No Linux e no Termux para Android, a execução é feita manualmente via terminal.

Na primeira execução, o agente cria arquivos de configuração no diretório home do usuário, incluindo perfil com chave de API, prompt do sistema salvo, memória local, banco SQLite para armazenamento chave-valor e histórico da sessão TUI.

Segurança: o que está protegido e o que não está

O projeto é notavelmente honesto sobre seus limites de segurança. Existem várias camadas de proteção implementadas: calculadora segura via AST, lista de bloqueio para comandos shell destrutivos, timeouts em Python, shell e HTTP, validação de argumentos JSON, limite de 5 MB para payloads e uma sandbox Docker para experimentos isolados.

Porém, os próprios autores deixam claro que isso não é uma sandbox completa. O modelo pode alucinar, errar caminhos de arquivo ou gerar comandos incorretos. Um prompt mal formulado pode causar ações indesejadas mesmo com as proteções ativas. O projeto recomenda que o operador sempre revise o que o agente pretende fazer antes de autorizar ações em arquivos, shell ou requisições de rede.

Para quem é esse projeto?

O Universal LLM Agent é ideal para desenvolvedores que querem um agente que funcione localmente, sem depender de frameworks pesados, capaz de executar ações reais além de apenas conversar, com interfaces tanto gráfica quanto de texto, e que possa ser lido e modificado sem dificuldade. Não é para quem busca um sistema mágico que faça tudo de forma segura e autônoma sem supervisão humana.

Com licença MIT e desenvolvimento ativo, o projeto representa uma abordagem refrescantemente pragmática para agentes de IA: um arquivo, dependências mínimas, transparência total e foco em utilidade real no mundo do desenvolvimento de software.