Documentação

Guia completo
do Agenti.

Tudo que você precisa saber para construir pipelines de IA poderosos, colaborar em equipe e entender como o sistema funciona por dentro.

🌊
O que é o Agenti
Conceito central
O Agenti é um orquestrador visual de pipelines de IA. Em vez de mandar um único prompt enorme para um modelo de linguagem e torcer pelo melhor, você divide o trabalho em especialistas — cada um com um papel específico, conectados em sequência ou em paralelo.

Imagine uma linha de produção: o primeiro nó transcreve seu áudio, o segundo extrai as informações importantes, o terceiro analisa riscos, o quarto escreve o e-mail executivo. Cada etapa pega o resultado da anterior e adiciona uma nova camada de inteligência. O resultado final é muito mais preciso, rastreável e controlável do que um único "me responde tudo" no ChatGPT.
💡
Por que isso é melhor? Modelos de linguagem alucinam menos quando têm um escopo bem definido. Um especialista que só extrai tarefas vai extrair muito melhor do que um generalista que tenta fazer tudo.
Início rápido

Primeiros passos.

1️⃣
Configure sua API Key
Clique no ícone de chave 🔑 no canto superior direito. Você precisará de uma chave de pelo menos um provedor: Anthropic (Claude), OpenAI (GPT) ou Google (Gemini). → Guia completo de API Keys
2️⃣
Importe um flow pronto
Clique em Fluxos na barra lateral do canvas e selecione um dos templates. Experimente o "Transcrições → Tasks" — cole uma transcrição de reunião e veja o pipeline gerar tarefas, riscos e e-mail executivo em segundos.
3️⃣
Rode e explore os resultados
Clique no botão ▶ Rodar (ou Ctrl+Enter). Acompanhe cada nó processando no painel de logs à direita. Ao terminar, os resultados aparecem em cada nó de saída — clique neles para expandir.
Canvas

Tipos de nós.

Cada elemento no canvas é um nó com um papel específico. Conecte-os com fios para definir o fluxo de dados.

📥
Entrada
Nó de Input
Ponto de entrada do pipeline. Aceita texto livre, áudio (transcrição automática), PDF, CSV ou Markdown. É sempre o primeiro nó do fluxo.
Obrigatório · 1 por flow
🧠
Especialista
Agente de IA
O coração do pipeline. Cada especialista tem um papel definido em Markdown — recebe o contexto do nó anterior e produz uma transformação específica.
Ilimitados · configurável
📤
Saída
Nó de Output
Exibe o resultado final de uma cadeia de especialistas. Você pode ter múltiplos nós de saída — um para tarefas, outro para o e-mail, outro para o resumo.
Múltiplos permitidos
🤝
Controle
Human-in-the-Loop
Pausa o pipeline e aguarda sua aprovação antes de continuar. Você pode editar os dados intermediários antes de liberar para o próximo especialista.
Opcional · qualquer posição
🎩
Sistema
Alfred (Mordomo)
Roteador inteligente que decide se responde diretamente (perguntas simples) ou aciona o swarm completo. Pode buscar na web antes de disparar os agentes.
Opcional · entrada do sistema
🛠️
Worker
Ferramenta
Executa ações determinísticas: chamadas HTTP, busca na web com Serper, geolocalização com Google Places, webhooks externos. Sem IA, só lógica.
HTTP · Serper · Places · Webhook
Especialistas

Como os especialistas funcionam.

Cada especialista é definido por um arquivo Markdown com frontmatter YAML. Esse arquivo é o "cérebro" do agente — define quem ele é, o que faz e como entrega.

📄
Anatomia de um especialista
Cada arquivo .md tem dois blocos:

Frontmatter (YAML) — metadados: id, role (título), description (resumo curto), briefing (instruções para o agente anterior sobre como entregar os dados), icon e category.

System Prompt (Markdown) — o corpo do arquivo, após o ---. É aqui que você define o comportamento, as regras de formatação de saída, exemplos e restrições do especialista. Quanto mais detalhado, melhor o resultado.
🤖
Criar com IA: No Agenti você pode descrever o que quer em linguagem natural e a IA gera o especialista completo para você — frontmatter + system prompt. Clique em "Novo Especialista" na biblioteca e escreva o que precisa.
Sistema

Alfred — o mordomo.

🎩
O roteador de intenções
butlerService.ts
Alfred é o primeiro ponto de contato do sistema. Antes de acionar o swarm, ele analisa o que você pediu e decide o melhor caminho:

Pergunta simples → Alfred responde diretamente, sem acionar os agentes. Economiza tokens e tempo.

Tarefa complexa → Alfred prepara um briefing estruturado e dispara o pipeline completo com o contexto correto já formatado.

Alfred pode buscar informações na web (via Serper) antes de montar o briefing — útil quando os agentes precisam de contexto externo.
Motor

Como o pipeline funciona.

⚙️
BFS + Algoritmo de Kahn
core-engine · sem deadlocks
Quando você clica em Rodar, o motor lê a topologia do canvas e resolve a ordem de execução usando o algoritmo de Kahn (ordenação topológica). Isso garante que:

— Nenhum agente roda antes de seus predecessores terminarem
— Nós em paralelo (sem dependência entre si) rodam ao mesmo tempo
— Merges (múltiplos pais convergindo num nó) são resolvidos automaticamente
— Loops ou conexões circulares são detectados e bloqueados antes de rodar
🔧
Auto-Reparo de JSON
Engine V2 · resiliência automática
Modelos de linguagem às vezes produzem JSON inválido (vírgula a mais, aspas faltando, estrutura truncada). O motor detecta isso automaticamente e dispara uma subtarefa de reparo antes de passar o resultado para o próximo agente. O pipeline nunca trava por erro de sintaxe.
📨
Protocolos de Handoff
tags <handoff>
Agentes podem enviar notas "invisíveis" para o próximo usando tags <handoff>. Essas notas aparecem no log técnico mas não poluem o output final para o usuário. Permite que especialistas passem contexto rico entre si sem comprometer a qualidade do resultado exibido.
Colaboração

Multiplayer em tempo real.

O Agenti permite que múltiplas pessoas trabalhem no mesmo canvas simultaneamente — sem instalar nada, sem criar conta. Só compartilhar o link.

🔗
Como entrar numa sala
Clique em "Compartilhar" no canvas (ícone de link) e copie a URL da sala. Qualquer pessoa com o link pode entrar diretamente — sem cadastro, sem senha. O acesso é controlado por você ao compartilhar ou revogar o link.
👁️
Cursores e edição simultânea
Você vê o cursor de cada participante em tempo real com o nome de quem é. Quando alguém edita um nó, ele fica destacado com a cor desse usuário. Todas as mudanças — adicionar nó, conectar, editar prompt, deletar — são sincronizadas instantaneamente para todos na sala.
🌐
Líder de sala: O primeiro a entrar vira o líder. Ele pode sincronizar o viewport de todos (botão "Liderar") e tem prioridade em caso de conflito de edição simultânea.
Segurança

Criptografia de ponta a ponta.

Toda comunicação em salas multiplayer é criptografada com AES-GCM 256-bit. Nem nós, nem o servidor, conseguimos ler o conteúdo dos seus fluxos.

Seu navegador
→ cifra AES-GCM →
Dado criptografado
→ servidor →
Dado criptografado
→ decifra →
Navegador do colega
Servidor
vê apenas →
bytes cifrados ilegíveis
✓ sem acesso ao conteúdo
1
Geração da chave de sala
Quando você cria uma sala, o Agenti gera uma chave simétrica aleatória com crypto.getRandomValues() — a API nativa de criptografia do navegador. Essa chave é única para cada sala e nunca sai do seu dispositivo.
2
A chave vai na URL (fragment)
A chave de decifração é incluída como fragment hash na URL da sala: agenti.app/sala/abc123#CHAVE. O que vem depois do # nunca é enviado ao servidor pelo protocolo HTTP — fica só no browser. O servidor distribui os dados cifrados sem jamais ter acesso à chave.
3
Ciframento AES-GCM 256-bit
Toda mensagem enviada — edição de nó, movimento de cursor, novo especialista — é cifrada com AES-GCM usando a chave da sala antes de sair do navegador. AES-GCM 256-bit é o mesmo padrão usado em comunicações militares e bancárias.
4
Deciframento no destino
Apenas quem tem o link completo (com o fragment) pode decifrar as mensagens. O servidor atua só como roteador de bytes opacos — distribui os pacotes cifrados entre os participantes sem conseguir lê-los.
⚠️
Atenção ao compartilhar: O link completo da sala é a chave de acesso. Qualquer pessoa com ele pode entrar e decifrar o conteúdo. Compartilhe apenas com quem deve ter acesso.
💾
API Keys — armazenamento local
Suas chaves de API (OpenAI, Anthropic, Gemini) são armazenadas exclusivamente no localStorage do seu navegador. Elas nunca são enviadas para nossos servidores em nenhuma circunstância. Quando você usa o Agenti, as chamadas para os modelos de IA são feitas diretamente do seu navegador para os servidores do provedor escolhido — o Agenti é só o intermediário visual.
Entrada

Entrada multimodal.

🎙️
Áudio
Transcrição com Whisper
Suba um arquivo de áudio (MP3, WAV, M4A, OGG) ou grave direto pelo microfone. O Agenti usa Groq Whisper para transcrever antes de injetar no pipeline.
Groq Whisper API
📄
Documento
PDF, TXT, Markdown
Arraste ou selecione arquivos de texto. O parser extrai o conteúdo e injeta como contexto no primeiro especialista do pipeline.
Parsing nativo
📊
Planilha
CSV / Excel
Suba planilhas de estoque, relatórios, listas. O sistema converte para formato estruturado e injeta no pipeline para análise.
CSV · XLSX
✍️
Texto
Input livre
Digite ou cole qualquer texto diretamente no nó de entrada. Cole transcrições, e-mails, briefs, relatórios — qualquer conteúdo textual.
Sem limite de tamanho
Controle

Human-in-the-Loop.

🤝
O que é e para que serve
Um nó de aprovação insere um ponto de pausa no pipeline. Quando o fluxo chega nele, o pipeline para e espera. Você vê os dados intermediários que chegaram até ali — pode aprovar, editar ou rejeitar antes de liberar para o próximo especialista.

Útil quando você quer revisar o diagnóstico de um especialista antes de mandar o resultado para o cliente. Ou quando precisa validar uma extração de dados antes de ela virar a base de um relatório.
⏸️
Promise Suspension: Tecnicamente, o nó de aprovação usa um mecanismo de Promise suspensa — o motor aguarda uma resolução externa (sua aprovação) antes de continuar o grafo. O estado do pipeline é preservado integralmente durante a pausa.
Referência

Atalhos de teclado.

Ação Atalho
Rodar pipeline Ctrl + Enter
Parar execução Esc
Salvar fluxo Ctrl + S
Novo especialista Ctrl + Shift + N
Deletar nó selecionado Delete ou Backspace
Selecionar tudo Ctrl + A
Desfazer Ctrl + Z
Refazer Ctrl + Shift + Z
Zoom in Ctrl + +
Zoom out Ctrl + -
Ajustar ao canvas Ctrl + Shift + F
Buscar especialista Ctrl + K
Perguntas

Perguntas frequentes.

Minha API Key fica salva em algum servidor? ▼
Não. Sua chave é armazenada apenas no localStorage do seu próprio navegador. Ela nunca trafega pelos nossos servidores. As chamadas para os modelos de IA são feitas diretamente do seu browser para o provedor (OpenAI, Anthropic, Google).
Qual provedor devo usar? ▼
Para começar sem gastar nada: Gemini (plano gratuito generoso). Para melhor custo-benefício no dia a dia: Claude Haiku (Anthropic) ou GPT-4o mini (OpenAI). Para tarefas complexas que exigem raciocínio profundo: Claude Sonnet ou GPT-4o.
Quantas pessoas podem entrar numa sala? ▼
Não há limite técnico imposto pelo Agenti. O desempenho depende da conexão de cada participante e da capacidade do servidor de relay. Na prática, salas de até 20 pessoas funcionam sem problemas.
Meus fluxos ficam salvos na nuvem? ▼
Por padrão, seus fluxos ficam salvos localmente no navegador (localStorage). Você pode exportar como arquivo .json para backup ou para compartilhar. Salas multiplayer são temporárias — o estado da sala existe enquanto há participantes conectados.
O que acontece se um agente falhar? ▼
O motor tem três camadas de resiliência: (1) Auto-reparo de JSON para erros de formato, (2) retry automático em caso de timeout de API, (3) o pipeline marca o nó como falho e continua os caminhos independentes — outros branches não são bloqueados por um único erro.
Posso usar o Agenti offline? ▼
O canvas funciona offline para montar e editar fluxos. A execução dos pipelines requer conexão com a internet para acessar as APIs dos modelos de IA (OpenAI, Anthropic, Google). O multiplayer também requer conexão.
Como criar um especialista do zero? ▼
Clique em "Especialistas" na sidebar → "Novo Especialista". Você pode (1) descrever o que quer e deixar a IA gerar o arquivo .md completo, ou (2) escrever manualmente o frontmatter YAML + system prompt. Salve e o especialista aparece na biblioteca para arrastar para o canvas.