Perguntas Frequentes

AgentOS é um runtime TypeScript open-source para construir agentes de IA em produção, desenvolvido pela Frame.dev. Oferece orquestração multi-agente, memória cognitiva, RAG multimodal, guardrails de segurança opcionais (redação de PII, moderação de conteúdo, verificação de grounding), pipelines de voz, 37 adaptadores de canal e 13 integrações de provedores de LLM. AgentOS também alimenta os sistemas de IA por trás do Wilds.ai, uma plataforma de jogos AI-native. Self-hostable e gratuito.

Sim. O runtime, as extensões curadas, os pacotes de guardrails e as skills curadas são todos licenciados sob Apache 2.0. Você pode usar o AgentOS comercialmente, modificá-lo e redistribuí-lo sob essa licença.

AgentOS suporta 13 provedores de LLM: OpenAI, Anthropic, Google Gemini, Groq, Together AI, Mistral, xAI (Grok), OpenRouter, Requesty, LiteLLM, Ollama, Claude Code CLI e Gemini CLI. Cadeias de fallback de provedor permitem failover automático.

AgentOS é escrito inteiramente em TypeScript e roda em Node.js. O pacote npm é @framers/agentos. Funciona com qualquer projeto TypeScript ou JavaScript.

AgentOS é nativo em TypeScript (não Python), inclui memória cognitiva com curvas de decaimento de Ebbinghaus e modelagem de personalidade HEXACO, oferece pacotes de guardrails opcionais para redação de PII, moderação de conteúdo e verificação de grounding, fornece 37 adaptadores de canal (Discord, Telegram, Slack, e-mail e mais) e suporta 6 estratégias de orquestração, incluindo DAGs de agentes baseados em grafo. Também inclui 88 skills curadas e um motor de descoberta de capacidades que coloca no contexto apenas as ferramentas e skills relevantes, dentro de um orçamento de tokens por camada.

Paracosm (https://paracosm.agentos.sh) é um motor de simulação de modelos de mundo estruturados construído sobre AgentOS. Ele compila um ScenarioPackage JSON mais um perfil de líder HEXACO em um loop de turnos sobre um kernel determinístico com seed, onde agentes AgentOS propõem eventos, forjam novas ferramentas JavaScript em tempo de execução, que o AgentOS executa em node:vm com limite de 10 segundos, e produzem um artefato contrafactual que você pode bifurcar e reproduzir. Três modos compartilham um esquema: simulações de civilização por turnos (Mars Genesis é o exemplo canônico), gêmeos digitais por trajetória em lote, e previsões Monte-Carlo por ponto em lote. Open-source sob Apache 2.0, npm install paracosm. Demo ao vivo: https://paracosm.agentos.sh/sim. Código fonte: https://github.com/framerslab/paracosm. Post de lançamento extenso (por que o construímos, a história do vault de wilds.ai, a referência do motor): https://agentos.sh/blog/paracosm-launch.

Wilds.ai (https://wilds.ai) é uma plataforma de jogos AI-nativa construída sobre AgentOS e Paracosm. Personagens IA com memória cognitiva persistente e traços de personalidade HEXACO habitam modelos de mundo compartilhados e divergem entre si com base em eventos LLM-como-juiz fundamentados. Os jogadores podem entrar em mundos existentes, bifurcá-los ou compilar novos no navegador. Wilds.ai é o deployment canônico de produção do stack AgentOS + Paracosm e o canal oficial de comunidade e suporte (https://wilds.ai/discord) para ambos os projetos.

Wunderland (https://wunderland.sh) é um projeto irmão em desenvolvimento ativo que empacota uma CLI batteries-included mais um daemon sobre os registros de extensões e skills do AgentOS. Ele oferece uma CLI de 60 comandos (setup, chat, rag, agency, workflows, evaluate, provenance, knowledge, marketplace e mais), um modelo de segurança de 5 níveis (dangerous / permissive / balanced / strict / paranoid), 9 presets de agente, autorização HITL com escalonamento, e a mesma arquitetura de memória cognitiva mais RAG baseada em grafo documentada nos docs do AgentOS. Use @framers/agentos quando quiser um SDK TypeScript para incorporar em sua aplicação; use Wunderland quando quiser uma CLI global que possa instalar com pnpm add -g wunderland e configurar com um assistente. Código fonte em github.com/jddunn/wunderland (Apache 2.0 desde 0.71.0). Versão preview; APIs e superfície da CLI ainda podem mudar. Guia de início: https://docs.agentos.sh/wunderland.

GMI significa Generalized Mind Instance. É o agente que o runtime do AgentOS cria para cada sessão: guarda a persona da sessão (traços HEXACO), o histórico da conversa, o humor e o rastro de raciocínio, executa cada turno passando por recuperação, montagem do prompt, chamada do modelo e chamadas de ferramentas, e pode receber memória cognitiva que persiste entre sessões. O helper leve agent() chama o modelo diretamente e não cria uma GMI, a menos que você passe runtime: 'gmi'; gmi() e o runtime completo (AgentOS.processRequest) criam GMIs.

HEXACO é um modelo de personalidade de 6 fatores oriundo da pesquisa em psicologia (Ashton & Lee, 2007). As seis dimensões são Honestidade-Humildade, Emocionalidade, Extroversão, Amabilidade, Conscienciosidade e Abertura à Experiência. No AgentOS, os traços HEXACO moldam como os agentes se comunicam e lembram. agent() escreve traços acima de 0.65 ou abaixo de 0.35 no prompt de sistema como diretivas de comportamento. Na memória cognitiva, alta Emocionalidade aumenta o quanto uma memória é reescrita quando é recordada (reconsolidação), enquanto alta Conscienciosidade fortalece o esquecimento induzido por recuperação de memórias concorrentes.

A memória cognitiva do AgentOS implementa 8 mecanismos da pesquisa em ciência cognitiva: reconsolidação, esquecimento induzido por recuperação, recordação involuntária, sensação de saber, extração de gist temporal, codificação de esquemas, decaimento de confiança da fonte e regulação emocional. As memórias decaem ao longo do tempo seguindo as curvas de esquecimento de Ebbinghaus (Ebbinghaus, 1885), e cada recuperação bem-sucedida torna uma memória mais estável, como na repetição espaçada. A memória de trabalho segue o modelo multicomponente de Baddeley (Baddeley, 2000) com 7 slots por padrão: alta Abertura acrescenta um, alta Conscienciosidade tira um, e o total fica entre 5 e 9. Uma nova memória é guardada como memória episódica por padrão e ocupa um slot da memória de trabalho. Quando os slots estão cheios, o slot menos ativo é liberado e a sua memória continua guardada. A consolidação depois transforma memórias episódicas antigas e muito recuperadas em memórias semânticas.

AgentOS tem seis pacotes de guardrails opcionais: redação de PII (nomes, e-mails, telefones, SSNs e mais), classificadores de ML para toxicidade, ameaças e conteúdo NSFW, análise estática de código gerado em busca de padrões perigosos, verificação de grounding contra documentos-fonte, aplicação de topicalidade para manter agentes na tarefa e um reescritor de política de conteúdo que reescreve ou bloqueia saídas que violam sua política. Cada pacote é uma extensão que você ativa no runtime do AgentOS. O pacote de classificadores só pontua prompt injection quando o seu modelo local não carrega; para frases de injeção conhecidas, use o guardrail de lista de frases embutido.

O motor de descoberta de capacidades encontra ferramentas e skills por busca semântica e as coloca no prompt em três camadas, cada uma com um orçamento fixo de tokens. A camada 0 mantém resumos de categoria no contexto (200 tokens por padrão). A camada 1 adiciona os 5 principais matches semânticos do turno (800 tokens). A camada 2 adiciona esquemas completos ou o texto do SKILL.md dos 2 melhores matches (2,000 tokens). Uma meta-ferramenta chamada discover_capabilities permite que agentes consultem as ferramentas disponíveis em tempo de execução.

O QueryRouter classifica cada consulta em uma de 4 camadas e busca de acordo: T0 responde a partir da conversa sem recuperação, T1 faz uma única busca vetorial (uma busca por palavras-chave quando não há provedor de embeddings configurado), T2 recupera 15 trechos, acrescenta trechos relacionados pela expansão do grafo e reordena o conjunto para ficar com os 5 melhores, e T3 divide a consulta por frases em até 5 subconsultas, recupera 10 trechos para cada uma, acrescenta trechos relacionados pela expansão do grafo, reordena o conjunto para ficar com os 10 melhores e depois, quando a pesquisa profunda está ativada (por padrão, quando SERPER_API_KEY está definida), faz uma etapa de pesquisa profunda cujos resultados ele mescla. Depois responde com base no que recuperou e devolve a resposta com as citações das fontes.

Inteligência adaptativa é como os agentes do AgentOS ajustam seu comportamento sem retreinamento. Cinco mecanismos trabalham juntos: (1) Montagem do prompt a cada turno: o PromptEngine de um GMI monta o prompt de sistema a cada turno a partir da persona, do humor, do histórico da conversa, das memórias recuperadas e das ferramentas disponíveis. (2) Autoavaliação: com o autoaperfeiçoamento ativado, a ferramenta self_evaluate pontua a própria resposta do agente e pode mudar a temperature ou a verbosidade da sessão, ou ajustar um traço via adapt_personality. (3) Memória modulada pela personalidade: os traços HEXACO ajustam os mecanismos de memória; alta Abertura torna a recordação involuntária mais provável, e alta Conscienciosidade fortalece o esquecimento induzido por recuperação de memórias concorrentes. (4) Consolidação de memória: as passagens de consolidação podam memórias decaídas, mesclam duplicatas, transformam memórias episódicas antigas e muito recuperadas em semânticas e, com um LLM configurado, derivam memórias de insight a partir de clusters. (5) Camadas do QueryRouter: a profundidade da recuperação acompanha a consulta, de nenhuma recuperação quando a conversa já contém a resposta até uma pesquisa profunda em todo o corpus para as mais difíceis.

Comportamentos emergentes são capacidades que os agentes desenvolvem em tempo de execução em vez de serem programadas explicitamente. AgentOS suporta cinco formas: (1) Forja de ferramentas em tempo de execução: com emergent: true no runtime do AgentOS, os agentes escrevem novas ferramentas em JavaScript via forge_tool. O EmergentCapabilityEngine executa cada uma em node:vm com limite de tempo, e um juiz LLM revisa o código e suas execuções de teste antes de a ferramenta ser registrada. (2) Personalidade autoajustável: adapt_personality move um traço HEXACO dentro de limites definidos para o agente em execução. Com persistWithDecay e um mutation store, cada mudança é registrada, e os registros armazenados perdem força no máximo uma vez por dia, quando o agente se adapta. (3) Gerenciamento dinâmico de skills: os agentes ativam ou desativam skills em tempo de execução via manage_skills, adaptando seu repertório comportamental à tarefa em questão. (4) Criação de workflows componíveis: os agentes compõem ferramentas registradas em pipelines de múltiplas etapas via create_workflow, construindo novas capacidades a partir de blocos existentes. (5) Promoção de ferramentas por camadas: uma ferramenta forjada começa na camada session. Após pelo menos 5 usos com taxa de sucesso de 0.8 ou mais, e a aprovação de dois revisores LLM, ela passa para a camada agent. Um host pode promover uma ferramenta para a camada shared com EmergentToolRegistry.promote().

Sim. AgentOS oferece dois mecanismos complementares de LLM-as-judge. No nível de agency, hitl.llmJudge() cria um handler de aprovação que delega decisões a um LLM. Ele avalia cada ApprovalRequest contra critérios configuráveis e retorna uma decisão estruturada com pontuação de confiança. Quando a confiança fica abaixo do limiar, a decisão escala para um handler de fallback (outro hitl handler ou um humano). No nível do graph, o builder humanNode() aceita uma opção judge que delega a decisão de interrupt a um LLM. Se o juiz estiver confiante, o graph continua sem suspensão. Se a confiança for baixa, a execução cai em um interrupt humano normal. Ambas as abordagens suportam model, provider, criteria e confidence threshold configuráveis.

Sim. Quando hitl.guardrailOverride está habilitado, os guardrails são executados após uma decisão de aprovação e ainda podem bloquear ações destrutivas ou sensíveis. Isso adiciona uma segunda camada de segurança após auto-aprovação, aprovação humana ou hitl.llmJudge(). Os guardrails padrão pós-aprovação incluem code-safety e pii-redaction, e você pode configurar a lista com hitl.postApprovalGuardrails. Desabilite o override apenas se você explicitamente quiser que o handler de aprovação tenha a palavra final.

Instale via npm: npm install @framers/agentos. AgentOS requer Node.js 22 ou superior. Para as ferramentas de CLI, instale o pacote complementar: npm install -g wunderland.

Import the agent function and configure it with a provider, instructions, and optional personality traits:

import { agent } from '@framers/agentos'

const myAgent = agent({
  provider: 'openai',
  instructions: 'You are a helpful assistant.',
  personality: {
    openness: 0.8,
    conscientiousness: 0.9,
  },
})

const reply = await myAgent.generate('Hello!')
console.log(reply.text)

AgentOS executa voz pelo VoicePipelineOrchestrator. Você fornece uma sessão de STT em streaming, uma sessão de TTS em streaming, um detector de fim de fala e um handler de interrupção (barge-in), e ele os conecta a uma sessão de agente por um transporte como um WebSocket. O catálogo de fala lista 13 provedores de STT e 13 provedores de TTS. Desses, estão disponíveis 11 provedores de STT, incluindo Whisper (OpenAI), Deepgram e AssemblyAI, e 10 provedores de TTS, incluindo ElevenLabs, OpenAI TTS e Google Cloud TTS. As outras cinco entradas (Whisper.cpp, NVIDIA NeMo, Coqui XTTS, Bark e StyleTTS2) estão marcadas como indisponíveis, e o resolvedor de provedores as ignora. Os provedores Twilio, Telnyx e Plivo fazem e encerram chamadas telefônicas.

AgentOS é self-hostable e roda em qualquer lugar onde Node.js 22 ou superior roda. Faça deploy em sua própria infraestrutura com Docker, em provedores de cloud como AWS, GCP ou Azure, ou use plataformas como Vercel, Railway ou Fly.io. O SQLite não exige configuração, e o MigrationEngine move os dados armazenados para Postgres, Qdrant ou Pinecone quando você precisar de mais escala.

Sim. AgentOS funciona totalmente offline quando combinado com Ollama para inferência de LLM local. Ollama fornece acesso a modelos de pesos abertos como Llama, Mistral e Phi localmente. O backend de armazenamento SQLite e o vector store em memória não requerem serviços externos. O comando ollama-setup da CLI do Wunderland detecta ou instala o Ollama e configura o agente para usá-lo.

Sim. AgentOS oferece pacotes de guardrails opcionais que redigem dados pessoais, moderam conteúdo e verificam as respostas contra as fontes, além de aprovações para chamadas de ferramentas sensíveis, orçamentos de gasto que recusam uma chamada acima do limite e disjuntores que tiram de rotação um provedor com falhas.

AgentOS inclui um guardrail de redação de PII que remove dados pessoais antes que cheguem aos provedores de LLM, e implantação self-hosted para que os dados permaneçam em sua infraestrutura. A memória pode ser exportada em JSON, Markdown, Obsidian ou SQLite para uma solicitação de acesso. Esquecer uma memória a tira da recuperação, mas mantém a linha dela no banco de dados, então um pedido de exclusão exige apagá-la no seu próprio armazenamento. Conformidade com GDPR e SOC 2 é responsabilidade organizacional da equipe que implanta, não uma propriedade da biblioteca em si.

Sim. Para deployments de produção, licenciamento empresarial, suporte dedicado e integrações personalizadas, entre em contato com a equipe em [email protected]. O suporte empresarial inclui resolução prioritária de issues, consultoria de arquitetura e assistência de deployment.

[email protected]

Absolutamente. AgentOS é projetado para ser self-hosted desde o início. Para deployments self-hosted, seus dados permanecem em sua infraestrutura com SQLite, Postgres, pgvector, Qdrant ou Neo4j. Se preferir um banco vetorial gerenciado por vendor, Pinecone também é suportado. Um helper de configuração pode iniciar um contêiner Qdrant local com Docker.