Principal Primeiros passos

Primeiros passos

primeiros passos na claudia agentica
Fabrício Rissetto
Por Fabrício Rissetto
• 9 artigos

Como criar Sub-agentes na ClaudIA Agêntica

Quando usar - Você vai criar um novo Sub-agente para a ClaudIA Agêntica (rastrear pedido, consultar crédito, validar agendamento, qualificar lead, etc.). - Você está revisando um Sub-agente existente e quer alinhar com o padrão atual. - Você está migrando lógica de um Eddie (fluxo Typebot) para um Sub-agente. Sobre este artigo Sub-agentes são os especialistas da ClaudIA Agêntica. O Supervisor decide qual chamar a partir da descrição de cada Sub-agente e passa o request. O Sub-agente executa e devolve dado/resultado ao Supervisor, que formata a resposta para o cliente. :::warning O Sub-agente nunca fala diretamente com o cliente. Ele devolve dados ao Supervisor, que cuida da comunicação. Frases prontas para o cliente dentro do system_prompt são bug. ::: Cada Sub-agente tem dois artefatos: - description (agent card) — texto curto que define se e quando este agente deve ser chamado. - system_prompt — instruções de como ele se comporta quando é chamado. Como criar um Sub-agente Opção recomendada — AI Companion A forma mais rápida é usar o AI Companion dentro da plataforma. Você descreve em linguagem natural o que o agente precisa fazer e o Companion gera description e system_prompt no padrão atual. O Companion consegue: - Criar um Sub-agente do zero a partir de um pedido em linguagem natural. - Migrar um Eddie (Typebot) existente para um Sub-agente — ele lê o fluxo, identifica tools necessárias, mapeia as regras de negócio e gera os artefatos. - Revisar um Sub-agente já criado e sugerir ajustes (description mais específica, system_prompt mais enxuto). - Iterar com você até o resultado ficar bom. Veja o passo a passo em Como criar agentes com linguagem natural (AI Companion). Mesmo usando o Companion, vale entender os dois artefatos abaixo para revisar o que ele gera. Description (agent card) A description é o texto que o Supervisor usa para decidir se e quando chamar este agente. Precisa ser objetiva, curta e em pt-BR. Formato: O QUE FAZ: <1-3 frases sobre a ação. Descreva a AÇÃO, não a interface ("busca o endereço pelo CEP" ✓; "solicita o CEP ao cliente" ✗).> PRÉ-REQUISITOS DE INVOCAÇÃO (request DEVE conter): - <campo 1> — <formato esperado> QUANDO ACIONAR: <1-2 frases: que tipo de pedido do cliente dispara este agente, COM o pré-requisito em mãos. Use a linguagem do cliente.> QUANDO NÃO ACIONAR: <1-2 frases: pedidos similares que NÃO são deste agente. Inclua "cliente expressou intenção mas ainda não forneceu [pré-requisito]" quando aplicável.> Exemplo — Sub-agente de rastreamento: O QUE FAZ: Consulta o status atual de um pedido e devolve a posição da entrega. PRÉ-REQUISITOS DE INVOCAÇÃO: - número do pedido — formato alfanumérico, 8-12 caracteres QUANDO ACIONAR: Cliente quer saber onde está o pedido, status da entrega, ou se o produto já foi enviado — E já forneceu o número do pedido. QUANDO NÃO ACIONAR: - Cliente quer cancelar, trocar ou devolver — outro especialista. - Cliente relata defeito no produto recebido — escopo de garantia. - Cliente expressou intenção mas ainda não enviou o número — Supervisor coleta antes. :::info Por que os pré-requisitos importam: se a description só diz "agente rastreia pedido", o Supervisor invoca na intenção ("quero saber do meu pedido") sem o número. O Sub-agente devolve "incompleto", o Supervisor pergunta ao cliente, reinvoca — 2 round-trips em vez de 1. Declarando o pré-requisito, o Supervisor coleta o dado antes de rotear. ::: System Prompt O system_prompt é a inteligência do agente. Princípios: - Explique o raciocínio, não só a regra. Em vez de "se status = IN_TRANSIT, responda em trânsito", escreva "traduza o status técnico para linguagem do cliente. IN_TRANSIT significa que o pedido saiu do CD e está a caminho". - Descreva critérios como sinais, não como if/else. "O sinal mais forte para qualificar é o tamanho da equipe (>50). Como segundo critério, o budget. Como último, o segmento." - Descreva a AÇÃO, não a tool. "Busque o endereço pelo CEP" funciona melhor do que citar o nome literal da tool — assim o prompt sobrevive a renomeações e mudanças no MCP. - Confie na IA com contexto parcial. Declare o princípio em vez de mapear todas as combinações: "trabalhe com o que tem, peça só o que precisa". - Deixe claro o papel: a resposta vai pro Supervisor, não pro cliente — formato direto: dados, status ou erro. Erros comuns a evitar - Description sem pré-requisitos para agente data-dependent. Se precisa de CEP, CPF, número de pedido — declare. Sem isso, o Supervisor invoca sem o dado e queima round-trip. - "QUANDO NÃO ACIONAR" fraco. Sem distinguir "iniciar nova ação" vs "consultar existente", ou sem excluir defeito/reclamação/orientação, o roteamento erra sempre que a palavra-chave do domínio aparecer. - Capacidade na description sem cobertura no prompt nem tool. Se a description promete "lida com cancelamento", precisa existir cenário no system_prompt e tool que suporte a ação. Sem isso vira alucinação. - Mensagens prontas para o cliente no system_prompt. O Sub-agente devolve dados. O Supervisor monta a fala. - Lógica de conversa dentro do Sub-agente. Retenção, reformulação para cliente insistente, tom — tudo isso é do Supervisor. O Sub-agente faz a mesma coisa na primeira e na quinta chamada. - Formato de retorno engessado (DIAGNÓSTICO + MOTIVO + RECOMENDAÇÃO + …). Quanto mais campos estruturados o Sub-agente devolve, mais matéria-prima o Supervisor tem pra cherry-pickar trechos errados. Deixe a resposta emergir em prosa natural. - Prompts paranoicos com blocos longos de "BLOQUEANTE / fraude potencial" + frases prontas de recusa: o agente passa a recusar usar as tools. Anti-fabricação cabe em uma linha: "use somente dados retornados pelas tools".

Última atualização em May 20, 2026

Como configurar o Supervisor da ClaudIA Agêntica

Quando usar - Você está configurando pela primeira vez o Supervisor da Agêntica - Você quer entender o que ele faz e o que ele não faz - Você precisa configurar o tom de voz do Supervisor Pré-requisitos - Acesso ao Hub com a feature Agêntica habilitada - Projeto (workspace) selecionado no seletor do canto superior direito da tela de Agentes — o campo Project é obrigatório nos formulários do Supervisor e dos Sub-agentes - (Recomendado) Sub-agentes já criados — ver Como criar Sub-agentes Sobre este artigo O Supervisor é o orquestrador da ClaudIA Agêntica — responsável por entender a intenção do cliente, decidir como responder e garantir que a resposta chegue com tom de voz correto. O que o Supervisor faz O Supervisor entra em cena para pegar o pedido do cliente e resolver junto aos Sub-agentes: 1. Entende o que o cliente precisa 2. Seleciona o Sub-agente correto, com base na description de cada especialista 3. Passa o contexto necessário para o Sub-agente agir 4. Itera com o Sub-agente para resolver a dor do cliente 5. Formata a resposta final usando o tom de voz configurado :::error O Supervisor NUNCA inventa, complementa ou contradiz informações que o Sub-agente não forneceu. A resposta do especialista é a fonte da verdade. ::: O que o Supervisor não faz - Não tem acesso ao mundo real diretamente — não liga, não envia e-mail, não abre tickets - Não pede dados "por via das dúvidas" — só solicita o absolutamente necessário (se um Sub-agente pedir, o Supervisor pede ao cliente) - Não oferece sugestões proativas após responder — sem "Posso ajudar em mais alguma coisa?" - Não promete ações que não pode executar — na dúvida, assume que não pode Como o Supervisor decide qual Sub-agente chamar O Supervisor seleciona com base na description de cada Sub-agente — texto curto que descreve quando aquele especialista deve ser acionado. :::warning Não é necessário (nem recomendado) listar os Sub-agentes no prompt do Supervisor. As descriptions já fazem esse trabalho. Duplicar regras de roteamento no prompt do Supervisor + na description cria duas fontes de verdade que podem conflitar. Mantenha as regras apenas na description. ::: Configurando o Tom de Voz O tom de voz define como o Supervisor se comunica com o cliente — não o que ele faz. Configurado no campo prompt. O que deve estar no tom de voz - Tom geral — formal/informal, direto/explicativo, caloroso/neutro - Vocabulário — palavras preferidas/proibidas, tratamento (você/tu/senhor), uso de emoji - Situações difíceis — como responder à frustração, dar notícias ruins, dizer "não consigo" - Formato — comprimento da resposta, listas, quebras de parágrafo - Exemplos — pares de "prefira X / evite Y" — são os mais úteis para a IA :::info Exemplo de instrução eficaz: Prefira "seu pedido tá a caminho" a "o pedido encontra-se em trânsito". Use linguagem direta e evite formalismo burocrático. ::: O que não deve estar - Lógica de negócio ou cenários → vai no system prompt do Sub-agente - Regras de roteamento → vão na description do Sub-agente - Instruções de quando acionar tools → vão no system prompt do Sub-agente Checklist de avaliação do tom de voz :::success - Sem contradições — "ser informal" + "sempre usar senhor/senhora" é conflito; resolva antes de publicar - Cobertura emocional — cobre ao menos pergunta neutra, cliente frustrado e notícia ruim - Escrito como instrução — não é copy-paste de brand doc; é instrução para IA ::: Observações - Para criar Sub-agentes: Como criar Sub-agentes - Para entender o handoff humano: Como funciona o handoff para humano na ClaudIA Agêntica - Para boas práticas gerais: Boas práticas para criação de agentes na plataforma ClaudIA Agêntica

Última atualização em May 21, 2026

Como funciona o handoff para humano na ClaudIA Agêntica

Quando usar - Você precisa entender por que o handoff falhou num caso específico - Você está configurando os cenários de escalação no system prompt do Sub-agente - Você quer evitar o erro de descrever sem executar o handoff Pré-requisitos - Sub-agente já criado com system prompt configurado - Acesso ao Playground para testar cenários de handoff Sobre este artigo Handoff é a transferência do atendimento da ClaudIA para um agente humano (N2). Na ClaudIA Agêntica, esse mecanismo funciona de forma diferente do que pode parecer intuitivo. Como funciona tecnicamente :::error O handoff não acontece automaticamente quando um Sub-agente detecta uma situação crítica. O único mecanismo de transferência é a tool handoff_to_human. ::: O Supervisor tem acesso a uma tool universal chamada handoff_to_human. Ele pode acioná-la quando achar que a conversa precisa ser escalada (por iniciativa própria ou por sinalização do Sub-agente). Fluxo completo 1. O Sub-agente retorna sinalização para o Supervisor: "pedido em atraso — encaminhar para humano" 2. O Supervisor lê esse retorno 3. O Supervisor chama a tool handoff_to_human 4. A transferência é executada no sistema 5. O Supervisor informa o cliente sobre a transferência :::warning Regra crítica: descrever ≠ executar Se o Sub-agente retornar "encaminhar para humano" em texto mas o Supervisor não reconhecer isso como gatilho, o handoff não acontece. O ticket continua com a IA — mesmo que a resposta mencione transferência. ::: Quando sinalizar handoff Os Sub-agentes devem sinalizar handoff nas situações que você julgar necessárias. O Supervisor também pode acionar a tool por conta própria de acordo com diretrizes globais (ex: frustração ou se não conseguir entender a dúvida). :::error Cada situação deve estar explicitamente mapeada no system prompt do Sub-agente — o "senso comum" da IA não é suficiente (apesar de ser um bom fallback). ::: Como configurar corretamente No system prompt do Sub-agente Mapeie cada cenário de escalação de forma explícita: "Cenário: pedido com data de previsão vencida. Sempre que a data de previsão for anterior à data atual, sinalizar para o Supervisor encaminhar para humano — independente de o rastreio estar disponível ou não." :::error Não confie que a IA vai inferir que uma situação requer handoff. Se não está escrito, não acontece de forma 100% confiável. A instrução deve ser inequívoca: a tool é chamada primeiro, a explicação vem depois. ::: Caso real — quando o handoff falha Situação: cliente consultou um pedido em atraso. A ClaudIA identificou o atraso, mas respondeu apenas com link de rastreio em vez de escalar. Causa: o system prompt do Sub-agente não tinha cenário específico para pedido em atraso — cobria pedido em atraso da mesma forma que os outros (busca info e responde o que o cliente quer, sem ajuste para o caso de atraso). Como foi corrigido: - Sub-agente: adicionado cenário explícito — "pedido em atraso = sinalizar handoff, independente de rastreio disponível" Aprendizado: prompts com contradições internas são especialmente perigosos em situações de handoff. Teste os cenários de escalação ativamente — não apenas os de resolução. Checklist de configuração - Cada cenário de escalação está explicitamente mapeado no system prompt do Sub-agente? - O handoff foi testado ativamente no Playground para os cenários críticos? Observações - Para criar Sub-agentes: Como criar Sub-agentes na ClaudIA Agêntica - Para o Supervisor: Como configurar o Supervisor da ClaudIA Agêntica - Para boas práticas gerais: Boas práticas para criação de agentes na plataforma ClaudIA Agêntica

Última atualização em May 21, 2026

Quando usar Fluxo controlado ou ClaudIA Agêntica (comparativo)

Quando usar - Você está avaliando se um caso de uso deve virar fluxo Eddie ou ClaudIA Agêntica - Você quer entender as forças e limitações de cada abordagem - Você está modernizando um fluxo Eddie existente e considerando migrar para Agêntica Pré-requisitos - Conhecimento básico do Eddie e da ClaudIA Agêntica Sobre este artigo ClaudIA Agêntica e Eddie são os dois mecanismos que permitem à ClaudIA acessar sistemas externos e executar ações via API. Eles se complementam — a escolha depende do tipo de processo. Eddie — fluxos estruturados O Eddie é um agente interativo que segue um fluxo pré-definido e bastante rígido. Cada possível caminho da conversa é mapeado antecipadamente — a ClaudIA segue esse roteiro etapa por etapa. Quando o Eddie é a escolha certa - Processos regulatórios ou com compliance — qualquer variação é inaceitável - Fluxos com etapas obrigatórias e sequenciais que não podem ser puladas - Situações onde você precisa de controle total sobre cada passo - Processos simples e bem delimitados onde o cliente não sai do roteiro O que o Eddie faz bem :::success - Previsibilidade total — a resposta segue exatamente o fluxo - Controle granular sobre o que a IA pode ou não perguntar ::: Limitação :::warning - Se o cliente responder algo fora do caminho previsto, o fluxo trava (ou reinicia) e cai em fallback - Qualquer novo cenário exige atualização manual do fluxo - Esforço de correção cresce exponencialmente com a complexidade do fluxo ::: ClaudIA Agêntica — reasoning contextual Com a Agêntica, não há fluxo fixo. A ClaudIA usa reasoning para decidir em tempo real qual tool acionar, em qual momento e com quais parâmetros — combinando o pedido do cliente, o prompt de diretrizes e as tools disponíveis. Quando a Agêntica é a escolha certa - Conversas que podem seguir caminhos diferentes dependendo do contexto - Situações onde o cliente pode trazer múltiplas demandas numa mesma mensagem - Processos onde a IA precisa raciocinar antes de agir — ex: verificar se um pedido está em atraso antes de decidir o que fazer - Casos de uso com variações naturais — rastreio, consulta de crédito, agendamentos - Quando existe espaço para a IA modificar a forma de agir para melhor atender o cliente - Quando um Eddie cresceu demais e ficou difícil de manter — a Agêntica absorve a flexibilidade que o fluxo rígido perdeu O que a Agêntica faz bem :::success - Lida com conversas que fogem do roteiro sem travar - Combina múltiplas tools numa mesma interação - Valida o input do cliente antes de acionar a chamada - Melhora conforme os cenários ocorrem em produção - Respostas muito fluidas e zero robóticas ::: Limitação :::warning Requer prompt de diretrizes e descriptions bem escritos para a IA agir dentro do escopo correto. ::: Comparativo rápido | | Eddie | ClaudIA Agêntica | | --- | --- | --- | | Tipo de fluxo | Pré-definido e fixo | Dinâmico, baseado em reasoning | | Ideal para | Processos rígidos, etapas obrigatórias | Conversas com múltiplos caminhos e flexibilidade | | Cliente sai do roteiro | Trava, reinicia ou vai para fallback | Raciocina e continua | | Configuração | Fluxo visual no Eddie | Prompt + tools no workspace | | Previsibilidade | Total | Alta, mas depende do prompt | | Manutenção | Atualizar fluxo para cada novo cenário | Refinar o prompt com base em casos reais | Migrando de Eddie para Agêntica Se você tem um Eddie em produção que cresceu demais ou está caindo em fallback com frequência, dá pra migrar pra Agêntica direto pelo AI Companion. Ao abrir o Companion, você escolhe "Migrar fluxo existente", seleciona o Eddie da lista do workspace e o Companion analisa a estrutura: - Webhooks viram tools - Condicionais viram cenários - Mensagens viram tom de voz O resultado é uma stack agêntica equivalente que você pode revisar e ajustar antes de publicar. :::info Detalhes do fluxo completo em Como criar agentes com linguagem natural (AI Companion). ::: Regra prática :::success Use o Eddie quando o processo precisa de controle total e zero variação. Use a Agêntica quando quiser acessar sistemas externos com muita flexibilidade e fluidez. Os dois podem coexistir no mesmo projeto — Eddie para processos críticos e fixos, Agêntica para o restante. ::: Observações - Para entender a Agêntica: O que é a ClaudIA Agêntica e como ela funciona - Para criar fluxos Eddie: Como lançar um novo Eddie passo a passo - Para migrar Eddie para Agêntica via Companion: **Como criar agentes com linguagem natural (AI Companion) ** Workshop de apresentação | 29/04/2026 https://www.loom.com/share/df78ef9d1bc94f829def2b0bbc8299c5

Última atualização em May 25, 2026

Boas práticas para criação de agentes na plataforma ClaudIA Agêntica

Quando usar - Você está construindo seu primeiro Sub-agente e quer evitar erros comuns - Você está revisando agentes existentes e quer um checklist de validação - Você quer entender as boas práticas para criação de tools Pré-requisitos - Acesso à plataforma ClaudIA Agêntica - Conhecimento básico de arquitetura agêntica (Supervisor, Sub-agente, Tools) Sobre este artigo Este artigo apresenta conceitos essenciais e os erros mais comuns na criação de Sub-agentes (especialistas) na plataforma. Seguir essas boas práticas garante: - Roteamento funcionando corretamente - Decisões consistentes do agente - Experiência fluida do usuário final Como funciona a arquitetura de agentes Cada Sub-agente possui dois campos principais: 1. Description (agent card) — texto usado como descrição das capacidades do Sub-agente. Com base nele, o sistema decide para qual agente encaminhar a conversa. Quando acionar e quando não acionar. 2. System prompt — instruções completas que o Sub-agente segue quando é acionado. Define quem ele é, o que faz, como decidir e o que retornar. :::warning O Sub-agente nunca fala diretamente com o cliente. Ele recebe uma requisição em linguagem natural do Supervisor, executa sua lógica e retorna dados estruturados. Quem formata a resposta final para o cliente é sempre o Supervisor. ::: Erros conhecidos Description com linguagem interna Se o cliente diz "quero cancelar" mas a description diz "workflow de churn prevention", o roteamento vai falhar. Use linguagem do cliente, não termos internos. Ausência de status de retorno na description A description deve listar todos os resultados possíveis: sucesso, dados faltantes, erro e necessidade de escalonamento. Sem isso, o Supervisor não sabe como reagir. Regras sem explicação de contexto no system prompt ❌ "Se o valor for acima de 1.000, o lead é qualificado" (rígido, falha em borda) ✅ "Acima de 1.000 porque abaixo disso o custo não se paga" (lógica de negócio) Árvores de decisão no system prompt Cadeias de "Se X, faça Y. Se não, verifique Z, faça W" são frágeis e difíceis de manter. ✅ Em vez disso: descreva critérios como sinais com pesos — "o sinal mais forte é X, seguido de Y, e como último recurso Z". Mensagens prontas para o cliente no system prompt Sub-agente retorna dados estruturados — quem monta a resposta é o Supervisor, com tom de voz configurado. Textos como "Prezado cliente, informamos que..." no Sub-agente conflitam com o tom do Supervisor. Regras de roteamento repetidas no Supervisor A description já é usada para roteamento. Repetir "quando chamar" / "quando não chamar" no Supervisor cria duas fontes de verdade. Sub-agente tentando interpretar a intenção do cliente O Sub-agente recebe requisição já processada pelo Supervisor — não a mensagem original. Entender a intenção é responsabilidade do Supervisor. Passos numerados obrigatórios "Passo 1, Passo 2, Passo 3" (linha de montagem) limita a capacidade da IA de resolver múltiplas questões simultaneamente. Mapeamento exaustivo de cenários Não tente mapear todas as combinações. Use o princípio: "vá o mais longe possível com o que você tem, peça apenas o necessário, não pule para a opção complexa se houver caminhos simples". Criação de tools Tools são as ferramentas que os Sub-agentes usam para consultar sistemas externos. Configuradas via MCP e vinculadas ao agente — não definidas dentro do prompt. Erros conhecidos em tools Tool sem descrição clara de parâmetros Cada tool precisa ter parâmetros bem descritos: nome, tipo, obrigatório/opcional, formato esperado (numérico, prefixo, UUID). Tool genérica demais Prefira tools com escopo bem definido. Uma para buscar pedido, outra para consultar pagamento, outra para verificar endereço. Tool duplicada com nomes diferentes Antes de criar uma nova tool, verifique se já não existe uma que faz a mesma coisa. Falta de orientação de uso no system prompt A tool existe, mas o system prompt não menciona quando usar. Inclua: "use a tool X quando o cliente perguntar sobre status do pedido" ou "só use a tool Y depois de já ter o número do pedido". Tool que retorna dados demais Configure para retornar apenas o necessário ou oriente no system prompt quais campos são relevantes. Ausência de tratamento de erro Toda tool pode falhar. O system prompt deve orientar: tentar novamente, pedir outro dado, ou escalar para humano. Checklist de validação de tools - A tool tem descrição clara do que faz? - Os parâmetros estão documentados (tipo, formato, obrigatoriedade)? - Não existe outra tool que faz a mesma coisa? - O system prompt orienta quando e por que usar? - O retorno contém só os dados necessários (ou o prompt orienta quais usar)? - O system prompt cobre erros? Checklist de validação geral Description - O sistema conseguiria identificar quando chamar apenas pela description? - Está claro o que NÃO faz? - A linguagem reflete as palavras do cliente? - Os retornos cobrem sucesso, dados faltantes, erro e escalonamento? System prompt - As regras incluem raciocínio de negócio, não apenas valores numéricos? - Lógica de decisão usa sinais com peso em vez de cadeias rígidas? - Há um princípio para informações incompletas? - O prompt não tem mensagens prontas para o cliente? - As ferramentas estão mencionadas com orientação de uso? - O que retornar está claro para cada resultado? - Existe seção de limites (o que nunca fazer)? Conclusão :::success Garantir que os agentes sejam criados seguindo essas boas práticas é essencial para roteamento preciso, decisões consistentes e experiência fluida. Agentes bem construídos são mais fáceis de manter, evoluir e investigar quando algo dá errado. ::: Observações - Para criar Sub-agentes: Como criar Sub-agentes na ClaudIA Agêntica - Para o Supervisor: Como configurar o Supervisor - Para conectar tools externas: Como conectar ferramentas externas via MCP Servers - Para handoff humano: Como funciona o handoff para humano

Última atualização em May 21, 2026

O que é a ClaudIA Agêntica e como ela funciona

Quando usar - Você quer entender o que é a ClaudIA Agêntica e como ela difere da ClaudIA tradicional - Você quer ver exemplos reais de uso (hospedagem, fintech, varejo) - Você quer aprender a estrutura interna (Judge → Supervisor → Sub-agente) Pré-requisitos - Acesso ao Hub com a feature Agêntica habilitada - Conhecimento básico do que é a ClaudIA tradicional Sobre este artigo A ClaudIA Agêntica permite à ClaudIA executar ações reais via chamadas de API, MCPs (ferramentas) etc. — em vez de responder apenas com base nos conteúdos da base de conhecimento. Na prática, a ClaudIA passa a agir de forma autônoma e contextual, decidindo quando agir, combinando a solicitação do cliente com diretrizes de prompt e executando a ação mais adequada. 🎥 Webinar com o CEO — visão geral e contexto estratégico Como funciona Quando um cliente envia uma mensagem, a IA analisa a solicitação (e o contexto) e decide: - Responder diretamente com base nos conteúdos registrados, ou - Ativar a ClaudIA Agêntica, que age para ajudar o cliente :::success Em resumo: a ClaudIA deixa de ser apenas uma IA que responde perguntas e passa a ser uma IA que também age e busca informações para agir. ::: Os três componentes internos Judge — decide se a Agêntica age Lê a mensagem do cliente e compara com as descriptions das ferramentas disponíveis. Se existir um sub-agente apropriado, a conversa é roteada para a Agêntica. Caso contrário, a ClaudIA responde com base na base de conhecimento. Supervisor — decide quem age e entrega a resposta Quando o Judge ativa a Agêntica, o Supervisor: - Seleciona qual Sub-agente é o mais adequado - Formata a resposta final com o tom de voz do cliente Sub-agente — executa a ferramenta O especialista. Tem prompt próprio para a situação e conta com as ferramentas (chamadas de API). Devolve dados estruturados ao Supervisor — nunca fala diretamente com o cliente. Fluxo: Judge → decide se ativa → Supervisor → seleciona o Sub-agente → Sub-agente → executa a ferramenta → Supervisor → entrega a resposta Exemplos em produção 🎥 Vídeo de demonstrações Antecipação de check-in — hospedagem Cliente informa que o voo chegará mais cedo. A Agêntica: - Explica regras gerais (check-in antes das 13h tem cobrança) - Solicita código de reserva para consultar a API - Verifica disponibilidade — entrada antes das 11h indisponível - Oferece check-in gratuito entre 13h-15h (cortesia) - Cliente aceita → Agêntica chama a tool para registrar no sistema - Confirma → ticket encerrado sem intervenção humana :::info Por que solicitar o código de reserva? A disponibilidade é específica de cada reserva — a ferramenta precisa do parâmetro para consultar a API. ::: Consulta de limite de crédito — fintech Cliente pergunta sobre fatura, depois sobre aumento de limite. A Agêntica: - Responde sobre fatura via base de conhecimento - Ativa a ferramenta de consulta de crédito quando muda o tópico - Usa o helpdeskId automaticamente — sem pedir dados de novo - Retorna limite atual, valor disponível e regras - Orienta sobre antecipar parcela para liberar limite Rastreamento com código inválido — varejo Cliente informa código de pedido com mais dígitos do que o esperado. A Agêntica: - Identifica que o código está fora do formato esperado - Em vez de erro genérico, orienta com exemplo prático - Cliente fornece o código correto → ticket resolvido :::info Como a IA soube? A descrição da ferramenta especifica o formato esperado. Quando a entrada não corresponde, a ClaudIA decide não ativar a chamada. ::: Como criar uma ferramenta As ferramentas são configuradas no espaço de trabalho da ClaudIA, dentro da configuração do agente. Cada ferramenta representa uma chamada de API. A configuração tem três blocos: Bloco 1 — Declaração de variáveis Define quais dados a ClaudIA extrairá da conversa para a chamada: - Nome: cpf, codigo_pedido, email - Descrição: "CPF do cliente, 11 dígitos, apenas números" A descrição instrui a IA sobre o que coletar e em qual formato. Se o dado já estiver no histórico, a ClaudIA o extrai automaticamente. Bloco 2 — Chamada de API - Endpoint — URL - Método — GET, POST, PATCH - Headers — ex: Authorization - Corpo / Parâmetros — usando as variáveis do Bloco 1 Bloco 3 — Configuração da resposta - Resposta completa — toda a resposta da API - Resposta filtrada (JSON específico) — útil quando a API retorna dados sensíveis (tokens, IDs internos, dados bancários) A descrição da ferramenta É um dos campos mais importantes: - Explica as capacidades - Define o formato esperado dos parâmetros (ex: "código de pedido com 6 dígitos, formato #XXXXXX") - Funciona como manual de uso da tool para a IA Boas práticas :::success - Escreva descriptions precisas — controlam quando cada ferramenta é ativada - Especifique o formato dos parâmetros — quantidade de dígitos, prefixo, tipo - Use resposta filtrada para dados sensíveis - Refine com base em casos reais — a Agêntica melhora com o uso :::

Última atualização em May 14, 2026

Como criar agentes com linguagem natural (AI Companion)

Quando usar - Você quer criar agentes do zero sem configurar tudo manualmente - Você quer migrar um fluxo Eddie/Typebot existente para Agêntica - Você prefere descrever em linguagem natural o que precisa em vez de configurar campos Pré-requisitos - Acesso à plataforma ClaudIA Agêntica - (Para migração) Um fluxo Eddie/Typebot já existente no seu workspace (o Companion lista automaticamente) - (Recomendado) Dados das APIs prontos: URL, método, headers, parâmetros Sobre este artigo O AI Companion é um sistema de "agentes que criam agentes". Em vez de configurar manualmente cada Sub-agente, cada tool e cada Supervisor, você descreve em linguagem natural o que precisa — e o Companion cria toda a estrutura agêntica para você. Você acessa pela tela de agentes: - Cloud Chat: - OAP: O que o Companion cria | Componente | O que é | Exemplo | | --- | --- | --- | | Tools | Ferramentas que chamam APIs externas | Tool que consulta status de pedido via GET | | Sub-agentes | Especialistas com prompt, tools e lógica | Agente de rastreamento de pedidos | | Supervisor | Orquestrador que roteia e formata respostas | Supervisor com tom amigável e informal | Ao final, você tem um fluxo agêntico completo e funcional — pronto para testar. Como funciona o processo Fase 1 — Levantamento de requisitos O Companion conduz uma conversa para entender: - APIs — endpoints, métodos, headers, parâmetros - Cenários — sucesso, erro, exceções - Tom de voz do atendimento - Quando escalar para humano :::error Nessa etapa não passe API tokens reais. Use placeholders genéricos (ex: TOKEN_API_KEY) e edite o valor verdadeiro depois, direto na tela de Ferramentas. ::: Fase 2 — Criação das tools Com base na spec, o Companion cria automaticamente as tools — URL, método, headers e parâmetros. Fase 3 — Criação dos agentes e Supervisor O Companion cria os Sub-agentes com prompts, vincula as tools e monta o Supervisor. Acompanhando a análise Análises do Companion — principalmente as do migrador de fluxos — podem levar alguns minutos. Pra você não ficar no escuro durante esse tempo: - Durante o processamento, um indicador inline mostra a etapa atual e o tempo decorrido (ex: "Etapa 3 · 2:14") - A sessão fica salva no navegador por até 24h — pode recarregar a página, fechar a aba ou voltar mais tarde que continua do mesmo ponto - Se você abrir o AI Companion em outra aba, a conversa sincroniza automaticamente - Se o stream for interrompido (queda de rede, reload), a mensagem incompleta aparece marcada visualmente — você sabe que aquela linha ficou pela metade - Botão "Start over" disponível pra descartar a sessão atual e recomeçar do zero quando quiser Dois modos de uso Ao abrir o AI Companion, aparece um modal de início com duas opções: Criar do zero Você descreve o que precisa e o Companion levanta os requisitos. Use quando não tem fluxo existente. Migrar um fluxo Eddie/Typebot Você seleciona um Eddie/Typebot da lista do seu workspace (o Companion lista automaticamente). O JSON do fluxo é carregado e o Companion analisa a estrutura: - Webhooks viram tools - Condicionais viram cenários - Mensagens viram tom de voz Use quando quer modernizar um fluxo que já existe. :::info A escolha do modo (criar do zero ou migrar) também aparece quando você clica em Start over no meio de uma conversa — você não cai mais num confirm dialog, mas no mesmo modal de início. ::: O que você precisa fornecer Para criar do zero - Dados das APIs — URL, método HTTP, headers, parâmetros, campos relevantes - Cenários de atendimento — pedido encontrado, em atraso, dados inválidos etc. - Regras de escalação — quando transferir para humano - Tom de voz — como o Supervisor deve se comunicar :::info O Companion vai perguntar o que estiver faltando — mas quanto mais contexto, mais rápido e preciso o resultado. ::: Para migrar um fluxo existente - Eddie selecionado — escolhido na lista do workspace dentro do modal de início - Contexto adicional — regras de negócio que não estão explícitas no fluxo O que o Companion não faz :::warning - Não modifica agentes existentes — ele cria novos. Para editar, use o OAP - Não cria APIs — ele cria tools que chamam APIs (a API precisa existir) - Não configura base de conhecimento — Companion monta a stack agêntica; conteúdos da base são configurados separadamente - Não garante que a API funciona — se o endpoint estiver errado/offline, a tool falha ::: Se algo der errado O Companion executa em ordem: spec → tools → agentes. Se uma fase falhar: - Não retenta automaticamente (evita duplicação) - Informa o erro e pede para iniciar nova conversa - Componentes criados com sucesso antes da falha permanecem — você pode visualizá-los/removê-los manualmente no OAP Boas práticas :::success - Seja específico com APIs — endpoints completos, headers, formato de parâmetros - Descreva cenários reais — em vez de "trate erros", diga "quando o pedido não for encontrado, peça novamente e explique o formato (#XXXXXX)" - Um fluxo por conversa — não misture múltiplos fluxos na mesma conversa - Revise antes de publicar — abra cada agente no OAP e revise prompts, descriptions e tools - Teste no Playground — antes de produção, teste com cenários reais ::: Observações - Para o Supervisor: Como configurar o Supervisor - Para Sub-agentes: Como criar Sub-agentes na ClaudIA Agêntica - Para boas práticas: Boas práticas para criação de agentes - Para conectar tools externas: Como conectar ferramentas externas via MCP Servers - Para navegar pela interface: Como navegar pela interface de agentes da ClaudIA Agêntica - Para decidir entre Eddie e Agêntica: Quando usar Fluxo controlado ou ClaudIA Agêntica (comparativo)

Última atualização em May 21, 2026

Como auditar chats em que a Agêntica foi acionada

Quando usar - Você quer auditar o comportamento dos agentes em produção - Você quer ver quais conversas dispararam chamadas agênticas - Você quer priorizar tickets com muitas chamadas ou que terminaram em N2 Pré-requisitos - Acesso ao Hub com a feature Agêntica habilitada - Período de tempo com chats em que a Agêntica foi acionada Sobre este artigo A aba Uso Agêntica dentro do Dashboard lista todos os chats em que a ClaudIA Agêntica foi acionada no período selecionado. Serve para auditar o comportamento dos agentes em produção — ver quais conversas dispararam chamadas, quantas foram, e em que nível foram encerradas. Como acessar Etapa 1 — Acessar o Hub Acesse hub.cloudhumans.com/pt-BR/projects. Etapa 2 — Abrir o Dashboard No menu lateral, clique em Dashboard. Etapa 3 — Aba Uso Agêntica Na barra de abas no topo, vá até a última aba à direita: Uso Agêntica. Etapa 4 — Filtrar por período Ajuste com Data Inicial e Data Final. Aba Uso Agêntica O que cada coluna significa | Coluna | Significado | | --- | --- | | cloud_chat_url | Link direto para o chat no Hub. Clicar abre a conversa completa | | projectname | Projeto ao qual o chat pertence | | first_agentic_date | Data da primeira chamada da Agêntica naquele chat | | agentic_calls | Quantas vezes a Agêntica foi chamada na conversa | | level | Nível em que a conversa finalizou | Como usar para auditoria :::success - Priorize chats com muitas agentic_calls e nível N2 — múltiplas chamadas em uma mesma conversa podem indicar loops, falhas de tool, ou que o agente não conseguiu resolver de primeira - Use o first_agentic_date para focar em casos recentes ou cruzar com mudanças de configuração que você fez no agente - Abra o chat pelo cloud_chat_url para ver a conversa completa do agente ::: Observações - Para boas práticas de auditoria: Quais as melhores práticas para auditar a ClaudIA - Para entender as razões de transferência: Como funciona a ClaudIA e o processo de auditorias - Para entender a Agêntica: O que é a ClaudIA Agêntica e como ela funciona

Última atualização em May 21, 2026

Como navegar pela interface de agentes da ClaudIA Agêntica

Quando usar - Você é novo na tela de Agentes da Agêntica e quer entender o que cada parte faz - Você precisa criar, testar, publicar ou manter agentes - Você quer entender as três abas (Agentes, Ferramentas, Servidores MCP) Pré-requisitos - Acesso à plataforma ClaudIA Agêntica - (Recomendado) Conhecimento dos conceitos — ver O que é a ClaudIA Agêntica Sobre este artigo Este guia explica, tela por tela, como usar a área de Agentes da ClaudIA Agêntica — onde você cria, testa, publica e mantém os agentes que vão atender seus clientes. O foco aqui é navegação e uso da interface (para conceitos, use os outros artigos). https://www.loom.com/share/8fa6d0df23b94549ac1ef6fd28b574d5 As três abas da plataforma A área da ClaudIA Agêntica é dividida em três abas no menu lateral: 1. Agentes — onde você cria e gerencia o Supervisor e os Sub-agentes 2. Ferramentas (Tools) — onde você cria e configura as chamadas de API que os Sub-agentes podem usar 3. Servidores MCP — onde você gerencia conexões via Model Context Protocol que disponibilizam tools para a plataforma As três abas Aba Agentes Lista todos os agentes do projeto, dividida em duas seções: - Supervisores — o orquestrador (normalmente um só). Mostra quantos Sub-agentes estão vinculados - Sub-agentes — os especialistas. Cada linha mostra nome, trecho da descrição e quantas tools estão ativas Filtro por projeto (workspace) No canto superior direito, antes do botão de criar, existe um seletor de projeto. Cada conta pode ter mais de um workspace. :::info Se você só vê um projeto ou o seletor aparece desabilitado, é porque sua conta tem apenas um workspace disponível — comportamento normal. ::: Os dois caminhos para criar um agente 1. Montar com AI Companion (botão laranja, à esquerda) — abre um modal de início com duas opções: começar do zero ou migrar um Eddie existente do workspace. Em ambos os casos, o Companion conduz a criação em linguagem natural. 2. + Criar (botão laranja, à direita) — abre o formulário manual para criar um Sub-agente ou Supervisor. Recomendado para quem já entende a estrutura. :::success Os dois caminhos coexistem — você pode criar a base com o Companion e refinar manualmente. ::: Ações em cada linha À direita de cada agente: 1. Testar (Playground) — abre o Playground encaixado para conversar com o agente em modo teste 2. Duplicar — cria uma cópia para editar sem mexer no original (útil para testar variações de prompt) 3. Editar — abre o formulário do agente 4. Deletar — remove o agente :::warning Se for um Sub-agente vinculado ao Supervisor, é preciso desvinculá-lo antes de deletar. ::: Criando um Sub-agente manualmente Ao clicar em + Criar → Sub-agente, abre o modal com quatro campos: Modal Criar sub-agente 1. Nome do sub-agente — identifica na lista. Use algo descritivo como "Especialista em Status de Pedidos". Não aparece para o cliente. 2. Descrição — texto que o Supervisor lê para decidir quando chamar. A regra de roteamento mora aqui. Use linguagem do cliente. 3. Instruções de comportamento (system prompt) — o que o Sub-agente deve fazer quando acionado. 4. Tools — lista de ferramentas disponíveis. Ative apenas as que o especialista precisa. Selecionar todas liga todas de um servidor de uma vez. Após salvar, o Sub-agente vai para a seção "Sub-agentes" e fica pronto para ser vinculado ao Supervisor. Para o Supervisor, o fluxo é parecido com campos próprios (tom de voz, sub-agentes vinculados). Criando com AI Companion Ao clicar em Montar com AI Companion, a tela troca para um chat. Você descreve em linguagem natural e o Companion conduz a conversa. Tela do Companion :::error Não cole tokens reais ou API keys aqui — use placeholders genéricos (ex: TOKEN_API_KEY) e edite o valor verdadeiro depois, direto na tela de Ferramentas. ::: Testando no Playground Para abrir, clique no ícone do balãozinho na linha do agente. Playground No topo do painel direito: 1. Seletor de agente — troca o agente sem fechar o painel 2. Reiniciar conversa — limpa o histórico (use sempre que terminar um caso de teste) No corpo da conversa, sempre que o agente chama uma tool, aparece um bloco Saída da tool expansível mostrando o nome, o JSON cru e o call_id. O toggle Ocultar chamadas de tool mostra só a conversa do ponto de vista do cliente. Aba Ferramentas Lista todas as tools criadas no projeto, com nome, descrição curta, número de parâmetros, criação e atualização. Aba Ferramentas Criando uma ferramenta Clique em + Criar ferramenta: Modal criar tool 1. Nome — usado pelo agente internamente. Sem espaços, prefira snake_case (ex: consultar_endereco_por_cep) 2. Descrição da ferramenta — campo mais importante. É com base nela que o agente decide se usa essa tool durante o reasoning. :::warning Descrições genéricas geram chamadas erradas e silenciosas. Especifique o que a tool faz, qual API consome, quais parâmetros precisa receber e em qual formato. ::: Após criar, a ferramenta abre no editor visual de Fluxos controlados (Eddie) onde você monta a chamada de API. Observações - Para conceitos: O que é a ClaudIA Agêntica e como ela funciona - Para criar com IA: Como criar agentes com linguagem natural (AI Companion) - Para o Supervisor: Como configurar o Supervisor - Para Sub-agentes: Como criar Sub-agentes - Para servidores MCP: Como conectar ferramentas externas via MCP Servers

Última atualização em May 21, 2026