⚙️ Avançado

OASIS (Open Agent Social Interaction Simulations) é um framework de simulação social generalista construído sobre a plataforma CAMEL-AI. Publicado no paper arXiv:2411.11581, ele permite criar ambientes de mídia social sintéticos com agentes LLM que interagem de forma autônoma, simulando dinâmicas reais como disseminação de informação, polarização e formação de opinião.

O OASIS é o motor central que alimenta as simulações do MiroFish. Compreender sua arquitetura permite criar simulações customizadas, ajustar parâmetros de escala e entender como cada agente toma decisões dentro do ambiente social simulado.

O OASIS introduz uma arquitetura de escalonamento que permite simular até 1 milhão de agentes simultaneamente através de paralelização de chamadas LLM, batching inteligente de ações e uso de group subscriptions para otimizar a propagação de informações entre agentes.

A escala muda fundamentalmente os fenômenos emergentes. Com 100 agentes você observa conversas; com 10.000 surgem bolhas; com 1M emergem padrões macro-sociológicos. Entender os limites de escala é essencial para projetar simulações significativas.

O OASIS define 23 ações sociais discretas que os agentes podem executar, mapeando o comportamento de redes sociais reais. Inclui ações de conteúdo (publicar, comentar, repostar), ações sociais (seguir, silenciar, bloquear), ações de engajamento (curtir, buscar) e ações passivas (scroll, visualizar).

Cada ação tem implicações na propagação de informação e na dinâmica social. Um "repost" amplifica exponencialmente, um "mute" cria filtros de bolha. Entender o espaço de ações permite configurar simulações mais realistas.

O OASIS suporta simulação simultânea de duas plataformas: um ambiente tipo Twitter (timeline-based, seguidores, retweets) e um tipo Reddit (subreddits, upvotes/downvotes, threading aninhado). Os agentes podem participar em ambas plataformas com comportamentos adaptados a cada contexto.

Fenômenos de migração de conteúdo entre plataformas são cruciais para entender desinformação. Um meme nasce no Reddit, viraliza no Twitter. A simulação dual-platform captura essa dinâmica cross-platform.

Cada plataforma simulada inclui um sistema de recomendação interno que determina quais posts aparecem no feed de cada agente. O Twitter usa timeline cronológica + interest-based ranking; o Reddit usa hot score (baseado em votos e tempo) para ordenar conteúdo em subreddits.

O sistema de recomendação é o fator mais importante na formação de bolhas de informação. Alterar o algoritmo de ranking muda drasticamente os fenômenos emergentes na simulação.

O paper arXiv:2411.11581 valida que o OASIS reproduz fenômenos sociológicos reais: cascatas de informação seguindo curvas power-law, polarização de grupo com convergência intra-grupo e divergência inter-grupo, e efeito manada (herd behavior) onde agentes LLM mostram conformidade ainda mais intensa que humanos reais.

A validação empírica dá credibilidade às simulações. Saber quais fenômenos são reproduzidos com fidelidade e quais são amplificados (como o efeito manada) permite calibrar interpretações dos resultados.

LLMs como GPT-4 e Claude processam cada request de forma isolada - não há memória persistente entre chamadas. Para simulações sociais que duram centenas de rounds, cada agente precisa "lembrar" de suas interações passadas, opiniões formadas e relações construídas. Este é o problema fundamental da memória em sistemas multi-agente.

Sem memória, agentes contradizem a si mesmos, repetem ações e não desenvolvem trajetórias coerentes. A memória é o que transforma uma sequência de chamadas LLM em uma simulação social significativa.

Zep Cloud é uma plataforma de engenharia de contexto para aplicações LLM. Seu motor central é o Graphiti, um engine de grafo temporal de conhecimento que armazena fatos, relacionamentos e eventos com timestamps, permitindo queries como "o que o agente X sabia no momento T?". Possui certificação SOC 2 Type II para segurança enterprise.

O Zep é a solução de memória padrão do OASIS original e do BettaFish upstream. Entender o Graphiti permite otimizar queries de memória e reduzir custos de token ao injetar apenas o contexto relevante no prompt.

KuzuDB é um banco de dados de grafo embutido (embedded), similar ao SQLite mas para grafos. O fork inematds do BettaFish substituiu o Zep Cloud pelo KuzuDB, eliminando dependência de serviços externos. Funciona como um arquivo local, sem servidor separado, e é completamente gratuito e open-source.

O KuzuDB permite rodar simulações complexas sem custos de cloud e sem dependência de APIs externas. É a escolha ideal para ambientes isolados, pesquisa acadêmica e prototipagem rápida.

A busca híbrida combina dois métodos de retrieval: busca semântica (embeddings vetoriais que capturam significado) e BM25 (busca lexical clássica que matcha palavras exatas). O score final é calculado como 0.7 × similaridade_semântica + 0.3 × score_BM25, equilibrando compreensão de significado com precisão lexical.

Busca puramente semântica perde termos técnicos; busca puramente lexical perde sinonímia. A abordagem híbrida captura ambos, sendo crucial para recuperar memórias relevantes de agentes em simulações complexas.

O sistema de memória organiza informações em três categorias inspiradas na neurociência cognitiva: memória episódica (eventos específicos - "ontem discuti com AgentX sobre política"), memória semântica (fatos gerais - "AgentX é conservador") e memória temporal (sequência e timing - "a discussão aconteceu no round 47, antes da mudança de opinião").

Cada tipo de memória serve a uma função diferente no raciocínio do agente. A episódica permite aprender com experiências, a semântica provê contexto geral, e a temporal permite raciocínio causal sobre sequência de eventos.

O sistema de memória do Zep Cloud alcança latência P95 inferior a 200ms para queries de recuperação, e 80.32% de precisão no benchmark LoCoMO (Long Context Memory Optimization). Isso significa que 95% das buscas em memória retornam em menos de 200ms, com alta acurácia na recuperação de informações relevantes.

Em simulações com milhares de agentes, cada agente precisa consultar sua memória a cada round. Se cada consulta leva 1 segundo, 10.000 agentes exigiriam 2.7 horas por round. A performance sub-200ms viabiliza simulações em escala.

O OasisProfileGenerator é o componente que gera automaticamente perfis de agentes a partir de dados do grafo social. Ele utiliza distribuições demográficas configuráveis (idade, gênero, localização, interesses) para criar personas diversificadas. Cada persona inclui personalidade (Big Five traits), perspectiva política, estilo de comunicação e nível de atividade.

A qualidade das personas determina a qualidade da simulação. Personas mal construídas produzem comportamentos homogêneos e irrealistas. O gerador automatiza a criação de populações diversificadas em escala.

Cada agente no OASIS é composto por quatro pilares: personalidade (traços de comportamento), perspectiva (visão de mundo e vieses), posicionamento (opinião sobre tópicos específicos em escala Likert 1-7) e memória (histórico de interações). Juntos, esses pilares são injetados no system prompt do LLM a cada round de decisão.

Entender a estrutura interna do agente permite fazer ajustes finos: criar agentes mais ou menos influenciáveis, mais ou menos ativos, com opiniões mais ou menos polarizadas. Cada pilar é configurável independentemente.

O OASIS usa formatos diferentes de perfis para cada plataforma. O Twitter usa profiles.csv com colunas tabulares (username, bio, followers_count, interests), enquanto o Reddit usa profiles.json com estrutura aninhada que inclui subreddits de interesse, karma e histórico de posts. Cada formato reflete as particularidades da plataforma simulada.

Para criar simulações customizadas, você precisa gerar perfis no formato correto. Erros de formato são a causa mais comum de falhas na inicialização de simulações OASIS.

O Environment Configuration Agent é um meta-agente que define as regras da simulação antes dela começar. Ele configura parâmetros como número de rounds, ações permitidas por round, tópicos seed, eventos programados (inserção de notícias) e regras de moderação (quais conteúdos são filtrados). Funciona como o "game master" da simulação.

A configuração do ambiente determina completamente o tipo de simulação que será executada. Sem entender o Environment Configuration Agent, você está limitado a cenários pré-definidos.

Cada chamada LLM para um agente inclui um prompt cuidadosamente estruturado: system prompt com persona, user prompt com o estado atual do feed, memórias relevantes injetadas via RAG, e instruções de ação formatadas como tool calls. O prompt engineering determina quão "fiel" o agente é à sua persona.

O prompt é a interface entre a persona abstrata e o comportamento concreto do LLM. Prompts mal construídos resultam em agentes que ignoram sua personalidade ou tomam ações incoerentes.

O paper do OASIS demonstra que agentes LLM exibem "herd behavior" mais intenso que humanos reais - eles tendem a convergir mais rapidamente para opiniões majoritárias. Isso é um viés inerente dos LLMs treinados com RLHF, que favorece respostas "socialmente aceitáveis". As personas podem mitigar parcialmente este efeito, mas não eliminá-lo completamente.

Conhecer os vieses da simulação é tão importante quanto conhecer suas capacidades. Sem essa consciência, você pode interpretar consenso simulado como evidência de consenso real, cometendo erros de análise graves.

ReACT (Reasoning + Acting) é um paradigma onde o LLM alterna entre pensar (raciocinar sobre o que fazer) e agir (executar uma ferramenta). Em cada iteração, o agente gera um "Thought" (raciocínio), escolhe uma "Action" (ferramenta para usar), observa o "Observation" (resultado), e repete até ter informação suficiente para gerar a resposta final.

O padrão ReACT é a espinha dorsal do ReportAgent do BettaFish. Sem ele, o agente teria que gerar relatórios apenas com o que está no context window. Com ReACT, ele busca ativamente informações, entrevista outros agentes e analisa traces.

O ReportAgent tem acesso a três ferramentas especializadas: insight_forge (análise profunda de padrões nos dados coletados, identificando tendências e anomalias), panorama_search (busca ampla em todas as fontes disponíveis para contexto geral) e interview_agents (interrogação direta de agentes individuais sobre suas decisões e motivações).

Cada ferramenta serve a um propósito analítico diferente. O insight_forge encontra o "quê", o panorama_search provê o "contexto", e o interview_agents explica o "porquê". Juntas, produzem relatórios multi-dimensionais.

O processo de geração de relatório é bifásico: primeiro, o ReportAgent cria um outline em JSON com a estrutura do relatório (seções, subseções, pontos-chave). Depois, cada seção é expandida em Markdown completo com dados, citações dos agentes e visualizações. Isso garante coerência estrutural mesmo em relatórios longos.

O pipeline bifásico é uma técnica reutilizável para qualquer geração de documentos longos com LLM. Evita o problema de "perder o fio" em documentos extensos e permite paralelização da escrita de seções.

O ReportAgent analisa os traces de execução da simulação para identificar pontos de virada (moments onde a dinâmica muda drasticamente), formação de coalizões (grupos de agentes que convergem em opinião) e cascatas de influência (sequências de ações que desencadeiam reações em cadeia). Cada trace contém o histórico completo de ações de cada agente.

A análise de traces transforma dados brutos em insights acionáveis. Sem ela, uma simulação com 10.000 ações é apenas ruído. Com análise de traces, emergem narrativas e padrões compreensíveis.

A ferramenta interview_agents permite que o ReportAgent faça perguntas diretas a agentes individuais pós-simulação. O agente é "re-instanciado" com toda sua memória e persona, e responde perguntas como "por que você mudou de opinião no round 47?" ou "qual post mais influenciou sua decisão?". Funciona como uma entrevista qualitativa automatizada.

Entrevistas com agentes são a ponte entre dados quantitativos e compreensão qualitativa. Elas explicam o "porquê" por trás dos padrões numéricos, adicionando profundidade interpretativa aos relatórios.

O relatório final segue uma estrutura padronizada: Executive Summary (resumo de 3 parágrafos), Tendências Identificadas (padrões macro com dados), Atores-Chave (agentes mais influentes e suas trajetórias), Pontos de Virada (momentos críticos), Dinâmicas de Grupo (coalizões e conflitos), e Cenários Prováveis (projeções baseadas em tendências observadas).

A estrutura do relatório é o produto final visível ao usuário. Ela determina se os insights da simulação são compreensíveis e acionáveis. Um bom relatório transforma dados complexos em narrativa clara.

O BettaFish opera com 5 agentes especializados: QueryEngine (decompõe perguntas complexas em sub-queries), MediaEngine (coleta dados de fontes externas via crawling), InsightEngine (analisa e sintetiza os dados coletados), ReportEngine (gera relatórios estruturados) e ForumEngine (promove debate entre agentes com perspectivas divergentes para stress-test de conclusões).

A arquitetura de 5 agentes é um padrão de design avançado onde cada agente tem uma responsabilidade única. Entender como eles se comunicam é essencial para depurar problemas e estender funcionalidades.

O ForumEngine implementa "chain-of-thought collision" - múltiplos agentes com perspectivas diferentes debatem uma questão, cada um expondo seu raciocínio completo. Os agentes podem concordar, discordar, ou refinar suas posições com base nos argumentos dos outros. O resultado é um debate estruturado que expõe pontos fracos em conclusões e força consideração de múltiplos ângulos.

O ForumEngine é o diferencial do BettaFish em relação a outros sistemas multi-agente. Enquanto a maioria dos sistemas produz uma única perspectiva, o debate revela incertezas, contradições e nuances que um agente sozinho não capturaria.

A comunicação entre agentes no BettaFish segue o padrão publish-subscribe: cada agente publica suas conclusões em um log compartilhado, e os outros agentes se inscrevem para receber atualizações relevantes. Um moderador LLM filtra e organiza as mensagens, impedindo loops de concordância vazia e garantindo que o debate progride substancialmente.

O padrão pub-sub com moderação LLM é uma arquitetura escalável para sistemas multi-agente. Ele desacopla os agentes, permite adição de novos participantes sem refatoração, e a moderação previne degeneração da conversa.

O BettaFish implementa 5 modelos de análise de sentimento intercambiáveis: (1) Transformer pré-treinado (rápido, baseline), (2) BERT com LoRA fine-tuning (alta precisão, médio custo), (3) GPT-2 com LoRA (geração + classificação), (4) Qwen3 via API (multilíngue, custo variável), e (5) SVM clássico com TF-IDF (rápido, sem GPU). A escolha depende de requisitos de precisão, custo e latência.

A análise de sentimento é fundamental para medir polarização, satisfação e tendências em simulações sociais. Ter 5 opções permite otimizar o trade-off entre qualidade e custo para cada caso de uso.

O pipeline completo do BettaFish segue 5 estágios: (1) Query: decomposição da pergunta do usuário em sub-queries. (2) Collection: crawling de fontes + dados internos. (3) Forum: N ciclos de debate entre agentes com perspectivas divergentes. (4) IR (Information Retrieval): consolidação e ranking de evidências. (5) Rendering: geração do relatório final em Markdown com citações e dados.

Entender o pipeline end-to-end permite identificar gargalos de performance, otimizar custos (reduzindo ciclos de forum quando desnecessário) e customizar estágios específicos para casos de uso particulares.

O BettaFish suporta 4 modos de execução: (1) Multi-agente completo (todos os 5 engines ativos, maior custo e qualidade). (2) Agente isolado (apenas 1 engine, para debug e testes rápidos). (3) Apenas crawler (coleta dados sem análise, útil para construir datasets). (4) Apenas relatório (usa dados pré-coletados, útil para re-gerar relatórios com parâmetros diferentes).

Diferentes cenários exigem diferentes modos. Debug requer agente isolado, produção requer multi-agente completo, e preparação de dados requer apenas crawler. Saber escolher o modo correto otimiza custo e tempo.

O fork inematds é uma versão extensivamente modificada do BettaFish original. As principais mudanças incluem: substituição do Zep Cloud por KuzuDB (eliminando dependência de cloud), suporte a múltiplos provedores de LLM (OpenAI, Anthropic, Ollama, Groq), tradução completa para PT-BR dos prompts e interface, e funcionalidade de stop/resume para builds Docker longas.

O fork inematds é a base do MiroFish. Entender suas mudanças em relação ao upstream permite contribuir com melhorias, resolver conflitos de merge e adaptar funcionalidades futuras do upstream.

O MiroFish-Offline é um fork que opera 100% localmente, sem nenhuma chamada a APIs externas. Usa Ollama para inferência LLM local (com modelos como Llama 3, Mistral, Qwen), Neo4j Community Edition para grafo de conhecimento, e embeddings locais via sentence-transformers. Ideal para ambientes air-gapped ou com restrições de privacidade.

Nem todos os ambientes permitem enviar dados para APIs cloud. Organizações com dados sensíveis, militares, governamentais ou acadêmicas com orçamento limitado precisam de uma solução 100% local.

O MIGRATION-GUIDE documenta 7 bugs críticos encontrados no BettaFish upstream e corrigidos nos forks: (1) race condition no shared log, (2) memory leak no KuzuDB connection pool, (3) encoding UTF-8 quebrado em prompts PT-BR, (4) timeout silencioso em crawling, (5) duplicação de embeddings no índice vetorial, (6) inconsistência no formato de datas entre agentes, e (7) overflow em contagem de tokens para modelos com context window pequeno.

Esses bugs são armadilhas para qualquer pessoa que tente usar o upstream diretamente ou criar seu próprio fork. Conhecê-los previne horas de debug em problemas já resolvidos.

Os forks adicionam endpoints REST que o upstream não possui: PATCH /simulation/{id}/rename (renomear simulações em andamento), POST /simulation/{id}/pause (pausar simulação preservando estado completo), POST /simulation/{id}/resume (retomar simulação do ponto exato onde parou), e POST /simulation/{id}/snapshot (criar checkpoint para rollback).

Simulações longas (horas ou dias) precisam de controle operacional. Pausar para reduzir custos, retomar após manutenção, e snapshots para experimentar variações a partir de um mesmo ponto são funcionalidades essenciais em produção.

A configuração Docker customizada consolida todos os serviços (API, frontend, KuzuDB, workers) em um único container com multi-stage build. Inclui Traefik como reverse proxy com SSL automático via Let's Encrypt, health checks integrados, e persistent volumes para dados de simulação. O Dockerfile usa cache layers otimizados para rebuilds rápidos.

Deploy em produção requer containerização robusta. A configuração com Traefik e SSL automático permite deploy em VPS com HTTPS sem configuração manual de certificados, reduzindo a barreira para colocar o sistema em produção.

Guia passo-a-passo para criar um fork customizado do BettaFish: (1) Fork do repositório inematds (não do upstream). (2) Configuração de CI/CD com GitHub Actions. (3) Pontos de extensão: como adicionar novos engines, novos modelos de sentimento, novas fontes de dados. (4) Convenções de código e testes. (5) Como manter sincronização com o upstream via rebases periódicos.

A capacidade de criar e manter um fork próprio é o que transforma o MiroFish de uma ferramenta pronta em uma plataforma extensível. Cada organização pode ter seu fork com customizações específicas enquanto se beneficia de melhorias do upstream.