#Glossário de agentes de IA

Este glossário explica os termos que aparecem quando você constrói um agente de IA que atende clientes, de tool calling e RAG a transferência para uma pessoa, evals, preview e live. Cada entrada traz primeiro o significado geral e depois, quando se aplica, o que o termo significa na Vatio, onde você descreve um agente em um arquivo vatio.yml e ele responde no WhatsApp, no Instagram, na web e em apps iOS.

Os termos estão agrupados por tema e em ordem alfabética dentro de cada grupo.

#Agentes e como são construídos

#Agente de IA

Software que usa um modelo de linguagem para manter uma conversa e decidir, turno a turno, se responde, busca algo ou age por meio de uma tool. Na Vatio, um workspace roda exatamente um agente, definido em agent: no vatio.yml, e o mesmo agente responde em todos os canais. Construir um agente de IA monta um a partir de uma pasta vazia.

#Coding agent

Um assistente de IA que trabalha no seu repositório e no seu terminal: lê código, edita arquivos e roda comandos, como o Claude Code, o Codex ou o Cursor. Na Vatio o agente é feito de arquivos e de uma CLI, então um coding agent consegue escrevê-lo, testá-lo e corrigi-lo: vatio init adiciona uma seção da Vatio ao AGENTS.md, e a documentação é um único arquivo Markdown em https://vatio.ai/docs/docs.md.

#Framework de agentes

Uma biblioteca que você importa no seu próprio backend para construir um agente em código, com abstrações para chamar o modelo, definir tools, cuidar da memória e encadear etapas. Quem roda é você, junto com tudo o que um agente que atende clientes precisa em volta: webhooks dos canais, estado da conversa, um inbox, deploys e testes. Vatio vs. frameworks e plataformas no-code compara as três abordagens.

#Fulfillment conversacional

O nome que a Vatio dá a tudo o que acontece entre a mensagem de um cliente e a resposta que ele recebe, por analogia com o fulfillment do ecommerce. Você decide o que o agente pode fazer; a Vatio recebe as mensagens, agrupa, espera as mídias, dá ritmo à resposta e chama uma pessoa quando é preciso. Veja Conversas fluidas.

#Instruções (system prompt)

O texto que diz a um modelo qual trabalho ele faz e quais regras segue, também chamado de system prompt. Na Vatio é o agent.instructions, o único campo obrigatório do agente, e a Vatio acrescenta em volta o contexto do negócio, o estado do contato, a descrição das tools e as próprias instruções da plataforma. Escreva o que o agente nunca deve fazer como regras explícitas; Boas práticas mostra como.

#Manifesto (vatio.yml)

O arquivo que define um workspace da Vatio, guardado no seu repositório ao lado de um arquivo YAML por tool em tools/. As únicas chaves de primeiro nível são workspace, agent e auth, e uma chave desconhecida faz a validação falhar. A referência do manifesto descreve cada uma.

#Personalidade

A voz e o tom de um agente, separados do que ele faz. Na Vatio é o campo opcional agent.personality, que por padrão é caloroso, breve e claro.

#Plataforma no-code de chatbots

Um produto hospedado em que você desenha as conversas como fluxos em um editor visual e conecta canais em uma tela de configurações. Serve para equipes sem desenvolvedor e conversas quase sempre fixas, como menus ou formulários; o agente fica no editor da plataforma, e não em um repositório.

#Runtime de agentes

Um serviço hospedado que roda um agente a partir de uma definição que você escreve e opera a maquinaria em volta. A Vatio é um runtime: você escreve o vatio.yml e um arquivo YAML por tool, e a Vatio opera os canais, o agrupamento de mensagens, a verificação de identidade, as salvaguardas, o inbox e os deploys.

#Workspace

Na Vatio, o contêiner de um agente e das suas conversas, contatos, conhecimento, secrets e conexões de canais. O slug dele é a chave workspace do vatio.yml, e cada comando da CLI o lê do vatio.yml mais próximo.

#Tools, identidade e dados

#Contato

A pessoa por trás de uma conversa, com nome, email e telefone quando são conhecidos. Na Vatio, um contato é preenchido pelo identify_contact, pelo número de onde vem uma mensagem de WhatsApp ou pelos claims de um token assinado, e as tools o leem como $contact.name, $contact.email e $contact.phone_number.

#JWT (identidade do visitante)

Um JSON Web Token: um conjunto compacto e assinado de claims, muito usado para dizer quem é um usuário. Na Vatio, o seu backend assina um JWT RS256 com sub (o id do seu usuário), aud (o slug do workspace) e exp, e a Vatio o verifica com a sua chave pública; ela nunca guarda a chave privada, então consegue verificar uma identidade, mas nunca criar uma. O widget e os SDKs o repassam como visitor token: veja Conectar seu backend.

#Memória (remember e recall)

O que um agente sabe sobre uma pessoa a partir de conversas anteriores. Na Vatio, uma conversa com um contato conhecido é resumida depois de 30 minutos em silêncio, e os fatos duradouros viram notas; com as tools nativas remember e recall ativadas, o agente vê até 20 notas em cada conversa, salva notas novas com remember e busca em resumos e notas com recall. Os contatos do preview e do live nunca veem a memória uns dos outros.

#Token de desenvolvedor

Na Vatio, o token vat_… que a CLI usa, criado quando você autoriza uma máquina com vatio login. Com ele é possível fazer deploy, ler secrets e criar tokens publicáveis, então ele fica na sua máquina ou em um secret de CI como VATIO_TOKEN, nunca em uma página web, em um app ou em um repositório.

#Token publicável

Na Vatio, o token vatpub_… que uma página web ou um app leva para falar com um workspace e um ambiente. Ele só funciona a partir das origens permitidas, valores exatos scheme://host[:port] ou ios-app://BUNDLE_ID, que o mantêm no seu site ou app, mas não dizem nada sobre quem é o visitante. Veja Um chat com IA para o seu site e Um agente de IA no seu app iOS.

#Tool (function calling)

Uma ação que um modelo pode pedir para executar, descrita por um nome, uma descrição e parâmetros: o modelo preenche os parâmetros, o runtime faz a chamada e o modelo responde a partir do resultado. Também é chamada de function calling ou tool use. Na Vatio uma tool é uma requisição HTTP para a sua API, descrita em tools/<key>.yml e ativada em agent.tools, e qualquer lógica com desvios fica atrás de um endpoint no seu backend.

#Tool privada

Na Vatio, uma tool marcada access: private: ela só roda para um visitante cujo JWT foi verificado, e chega aos dados dele por $auth.subject ou $auth.token. Ela não pode receber user_id, customer_id, account_id, member_id, patient_id nem subject como parâmetro, porque quem preenche os parâmetros é o modelo; se receber, o deploy falha. As tools privadas rodam na web, em apps e no WhatsApp e no Instagram depois que o contato entra na conta.

#Tool pública

Na Vatio, uma tool com access: public, ou sem access, que roda para qualquer pessoa, inclusive os contatos do WhatsApp e do Instagram que não entraram na conta. Tudo o que ela revelar sobre uma pessoa precisa de uma checagem no seu backend, como um número de referência mais um segundo dado que precisam bater.

#Tools nativas

As tools que já vêm com a Vatio, para as quais você não escreve YAML: knowledge_lookup, identify_contact (salva um nome que o visitante informa), request_contact_info (pede a um visitante do WhatsApp que compartilhe o número dele), remember e recall. Elas são ativadas em agent.tools; já o handoff é adicionado ao declarar agent.handoff.

#Conhecimento e precisão

#Alucinação

Quando um modelo de linguagem afirma algo plausível que não é verdade: um preço, uma política, um estoque, um link. Na Vatio, as salvaguardas removem qualquer URL que não foi dada ao agente; o resto se previne com o que você constrói: regras como “nunca invente um preço”, tools para os dados que mudam, uma base de conhecimento para as políticas e evals a partir de respostas marcadas. Cada chamada de tool fica visível no inbox, então uma resposta errada pode ser rastreada até a origem.

#Base de conhecimento

Um conjunto de documentos que um agente lê em vez de decorar. Na Vatio, uma base de conhecimento guarda entradas em Markdown que você escreve pela CLI ou pelo inbox, é criada com vatio kb create e declarada em agent.knowledge; a Vatio não lê sites. Veja Base de conhecimento.

#Entrada de conhecimento

Um documento Markdown dentro de uma base de conhecimento, escrito com vatio kb write BASE ENTRADA arquivo.md. Os títulos dividem a entrada em seções buscadas separadamente, então cada seção deve responder a uma pergunta sozinha. Cada mudança fica guardada como uma versão numerada, e os supervisores podem editar entradas no inbox.

#knowledge_lookup

A tool nativa da Vatio que busca nas bases de conhecimento que o agente declara em knowledge. Você a ativa em agent.tools e diz ao agente, nas instruções, quando buscar; cada busca aparece junto com as outras chamadas de tool do turno.

#Lista de links permitidos

A lista de URLs que um agente pode enviar, também chamada de allowlist. Na Vatio é o agent.links, em que cada link é uma URL ou { url, when, values }, com placeholders expandidos no deploy. Uma resposta só pode levar uma URL que foi dada ao agente, em links, em outra parte do prompt ou no resultado de uma tool, e as salvaguardas removem qualquer outra.

#RAG (geração aumentada por recuperação)

Uma técnica em que os trechos relevantes para uma pergunta são recuperados de um repositório de documentos e adicionados ao contexto do modelo, para ele responder a partir do seu texto e não de memória. Na Vatio, o mais próximo disso é o knowledge_lookup: o agente o chama quando precisa do seu conteúdo, e ele busca nas seções das entradas que você escreveu, que a Vatio indexa em segundo plano depois de cada escrita. Ele busca só nessas entradas; a Vatio não percorre sites nem se conecta a outros repositórios de documentos.

#Salvaguardas

Verificações que cada resposta passa antes de ser enviada. Na Vatio elas pegam respostas vazias, mídias geradas e links que não foram dados ao agente; uma verificação que falha dispara uma tentativa de correção, e elas não podem ser desligadas. O que o agente nunca deve dizer é você quem escreve nas instruções: veja Salvaguardas.

#Conversas e canais

#Agrupamento de mensagens (buffering)

Tratar várias mensagens que alguém manda seguidas como uma só pergunta. No WhatsApp e no Instagram, a Vatio agrupa os fragmentos que chegam juntos e espera um momento de silêncio, e também as mídias que ainda estão sendo baixadas ou processadas, antes de o agente responder, e mantém as mensagens na ordem em que foram enviadas. Uma espera que se adapta a cada pessoa está em desenvolvimento e ainda não está disponível; veja Conversas fluidas.

#Assumir a conversa (takeover)

Quando uma pessoa responde em uma conversa no lugar do agente. Na Vatio, uma resposta pelo inbox, ou pelo app do WhatsApp Business no seu próprio número, pausa o agente naquele chat até alguém devolvê-lo, ou até 8 horas depois da última mensagem do cliente.

#Canal

Um lugar onde os clientes falam com o agente. Os canais da Vatio são o widget web e o SDK de navegador, o WhatsApp, as DMs do Instagram, o SDK de iOS e a CLI para testes; é o mesmo agente em todos, e só muda a forma de entrega.

#Horário de atendimento

Na Vatio, quando há uma pessoa de plantão: um fuso horário e um ou mais turnos por dia, que quem toca o negócio define na página Negócio do inbox, não no vatio.yml. O agente recebe a semana e sabe dizer aos clientes quando o negócio atende. O horário não decide quando o agente responde, só o que acontece depois de uma transferência: dentro dele o agente fica em silêncio, fora dele continua ajudando, e uma transferência que ninguém assume em uma hora volta para o agente.

#Janela de conversa

Quanto tempo uma conversa fica aberta antes de a próxima mensagem começar uma nova. No WhatsApp e no Instagram, a Vatio continua uma conversa até a última mensagem do visitante ter mais de oito horas. Nos SDKs web e de iOS, uma conversa guardada pode ser retomada enquanto duram as credenciais do chat, que são 12 horas.

#Número de preview do WhatsApp

O número de WhatsApp compartilhado da Vatio para testes, com o qual você conversa com o seu agente no WhatsApp de verdade, sem conta da Meta. Você adiciona o seu telefone como telefone de teste escaneando um QR code e enviando a mensagem que ele deixa escrita, e depois manda mensagem para o número; os clientes chegam ao seu próprio número comercial quando você o conecta e ativa Em produção. Veja Um agente de IA no WhatsApp.

#Ritmo de resposta (pacing)

Como uma resposta é entregue em cada canal. No WhatsApp e no Instagram, a Vatio envia a resposta em mensagens curtas, com pausas e indicadores de digitação; na web, como uma única resposta exibida de forma progressiva. Os SDKs escolhem com replyStyle: stream, paced ou instant.

#Telefone e conta de teste

Um telefone ou uma conta do Instagram que você conecta pela página Testar do inbox, enviando ao preview compartilhado o código que ele mostra, para conversar com o seu agente antes de ele estar no live. Cada workspace pode ter até cinco telefones de teste no número de preview compartilhado do WhatsApp e até cinco contas de teste na conta de preview compartilhada do Instagram. Veja Um agente de IA no Instagram.

#Transferência para uma pessoa (handoff)

Quando um agente passa uma conversa para uma pessoa. Na Vatio, declarar agent.handoff dá essa tool ao agente, com as suas próprias condições em when e um piso em after_turns, e um visitante que pede para falar com uma pessoa sempre dispara uma transferência. O chat fica aguardando no inbox; a Vatio ainda não avisa ninguém. Veja Transferir para uma pessoa.

#Supervisionar e melhorar

#Digest

Na Vatio, o documento Markdown que o vatio flags imprime para um coding agent: cada flag aberta com a conversa até a resposta, as chamadas de tool daquele turno com o que o seu backend respondeu, e a nota do supervisor. Quando há flags novas, o dono e os developers também recebem um email diário às 08:00 de America/Santiago, com o prompt /vatio:vatio-improve para colar no Claude Code; ele não cita nenhuma conversa.

#Eval e caso de eval

Um eval é um teste automático de um agente: conversas repetidas contra ele, com cada resultado avaliado. Na Vatio, cada flag com nota, feita no live ou no preview, vira um caso de eval, com os turnos do visitante como entrada e a nota como resultado esperado, e o vatio eval repete todos os casos contra o preview e sai com código 1 se algum falhar. Os evals chamam as suas tools de verdade, então aponte-as para um sandbox com um valor de testes antes; veja Melhorar seu agente.

#Flag

Na Vatio, a marcação que um supervisor faz em uma resposta errada, com Reportar esta resposta no inbox, junto com uma nota do que deveria ter acontecido: outra resposta, uma ação ou uma tool que o agente deveria ter usado. Uma flag com nota vira um caso de eval, e o estado dela aparece na própria resposta, na conversa: aberta, corrigida no preview quando o vatio eval passa nela, e resolvida quando o live passa, com a versão que a corrigiu. Editar a nota a reabre.

#Inbox

Onde uma equipe lê as conversas de um agente. O inbox da Vatio mostra cada conversa com cada chamada de tool, encontra qualquer uma por um nome, um número ou algo que foi dito, e é onde os supervisores assumem uma conversa, marcam respostas com uma flag e editam o conhecimento.

#Juiz (judge)

Um modelo que avalia a resposta de um agente em relação a um resultado esperado, uma abordagem conhecida como LLM-as-a-judge. No vatio eval, o juiz é de uma família de modelos diferente da do seu agente e responde aprovado ou reprovado com uma frase de justificativa, que o vatio eval --show RUN_ID imprime.

#Regressão

Uma mudança que quebra algo que funcionava. No vatio eval, um caso que passa no live e falha no preview é uma regressão, aparece primeiro na lista e impede o vatio publish.

#Supervisor

Uma pessoa do negócio que acompanha as conversas do agente. Na Vatio, os supervisores são convidados pela página Equipe do inbox e entram com um código enviado para o email deles; eles veem o inbox e o conhecimento, e não podem fazer deploy nem mudar tools.

#Deploy e ambientes

#Ambiente

Um lugar com nome para onde um agente é publicado. Na Vatio, um ambiente aponta para um deployment, um snapshot salvo da configuração: preview para testar mudanças e live para os clientes. Não há outros.

#Live

O ambiente com o qual os clientes falam. Na Vatio, o live muda com vatio publish, e os clientes chegam a ele pelo widget do seu site, WhatsApp, Instagram ou pelos SDKs.

#Preview

O ambiente padrão para testar um agente antes de os clientes o verem. Na Vatio, vatio push faz o deploy no preview, sem rodar testes, e os telefones e contas de teste chegam a ele. Antes da primeira publicação, o preview é o agente.

#Publicar

Levar uma versão para o live. Na Vatio, vatio publish promove o preview para o live junto com as mudanças de conhecimento dele. Depois da primeira publicação, ele é recusado se a versão do preview não foi testada com vatio eval ou se quebra uma flag que o live passa; veja Melhorar seu agente.

#Rollback

Voltar para a versão anterior do live. Na Vatio, vatio rollback restaura o snapshot anterior do live, configuração e conhecimento juntos; ele não restaura valores de secrets nem desfaz o que uma tool já fez.

Atualizado: 11 de outubro de 2026