Principal Primeiros passos

Primeiros passos

primeiros passos na claudia agentica
Tech
Por Bernardo Penteado and 1 outro
• 7 artigos

Como criar Sub-agentes

Sub-agentes são os especialistas da ClaudIA Agêntica. Cada um é treinado para uma área específica — rastrear pedidos, consultar crédito, verificar agendamentos, qualificar leads. O Supervisor decide qual Sub-agente chamar e passa o contexto necessário. O Sub-agente executa, retorna os dados, e o Supervisor formata a resposta para o cliente. O Sub-agente nunca fala diretamente com o cliente. Ele retorna dados para o Supervisor, que cuida da comunicação. 📋 O que compõe um Sub-agente Cada Sub-agente tem dois artefatos principais: | Artefato | O que é | Quem lê | | --- | --- | --- | | Description do sub-agente | Texto curto que define quando este agente deve ser chamado | O Supervisor | | System prompt | Instruções/diretrizes completas de como o agente deve se comportar | O Sub-agente em si | 📝 Como escrever a Description do Sub-agente A description do sub-agente é o texto que o Supervisor usa para decidir se e quando chamar aquele Sub-agente. É o mecanismo de roteamento. Formato: When to call: [1-5 frases descrevendo que tipo de pedido do cliente aciona este agente. Usar linguagem do cliente, não termos internos.] Do NOT call if: [1-3 frases delimitando pedidos similares que NÃO são trabalho deste agente] Exemplo para um Sub-agente de rastreamento: When to call: O cliente quer saber onde está o pedido, qual o status da entrega, ou se o produto já foi enviado. Do NOT call if: O cliente quer cancelar o pedido, solicitar troca ou relatar que o produto chegou errado — esses casos são de outro especialista. Regras importantes: - Use a linguagem do cliente — se o cliente diz "quero cancelar", use "quero cancelar", não "workflow de prevenção de churn" - Mantenha ~60 palavras no total — a description compete com outras descriptions pela atenção do modelo - Não liste campos obrigatórios nem status de retorno — o Supervisor interpreta naturalmente 🧩 Como escrever o System Prompt O system prompt instrui o Sub-agente sobre como executar sua tarefa. A estrutura sugerida: 1. Quem você é e como é acionado — contexto básico de papel 2. O que precisa descobrir/resolver — objetivo de negócio em linguagem clara 3. Sinais e critérios de decisão — descreva como sinais com peso, não como if/else rígido 4. Como lidar com informação parcial — declare um princípio, não mapeie cada combinação 5. Ferramentas disponíveis — quais tools pode usar e quando 6. O que retornar — para cada tipo de outcome: resolvido, dados faltantes, erro, escalação 7. Limites — lista curta do que nunca fazer Princípio fundamental Explique o raciocínio, não só a regra. ❌ "Se o campo status for IN_TRANSIT, responda que o pedido está em trânsito." ✅ "Traduz o status técnico da API para linguagem do cliente. IN_TRANSIT significa que o pedido saiu do centro de distribuição e está a caminho — use essa explicação, não o código interno." Descreva critérios como sinais Em vez de if/else, descreva o que pesa mais na decisão: "O sinal mais forte para qualificar é o tamanho da equipe (>50). Como segundo critério, considere o budget declarado. Como último recurso, use o segmento de mercado." ⚠️ Erros comuns a evitar Na description do sub-agente: - Usar jargão interno que o cliente nunca usaria → roteamento falha - Esquecer o "Do NOT call if" → o Supervisor pode chamar o agente errado em casos limítrofes No system prompt: - Divergência entre a description e o prompt → uma description muito ampla e um prompt engessado vai gerar muitos acionamentos mas que o sub-agent nao tenha autonomia para agir e resolver boa parte deles, e vice-versa - Escrever fluxogramas de if/else → a IA não precisa de fluxograma, precisa de lógica - Colocar mensagens prontas para o cliente → quem cuida da comunicação é o Supervisor - Tentar lidar com a retenção do cliente ou reformular respostas → responsabilidade do Supervisor - Over-especificar cada cenário → declare o princípio e confie na IA ✅ Checklist de validação Description do sub-agente: - O sistema identificaria quando chamar baseado só na description? - Está claro o que o agente não faz? - A linguagem reflete as palavras do cliente? - Tem menos de ~60 palavras? System prompt: - Explica o porquê das regras, não só o quê? - Usa sinais com peso, não árvores if/else? - Tem um princípio para lidar com informações incompletas? - Não tem mensagens prontas para o cliente? - Menciona as tools disponíveis e quando usá-las? - Descreve o que retornar para cada tipo de resultado? - Tem seção de limites (o que nunca fazer)?

Última atualização em Apr 06, 2026

Como configurar o Supervisor

O Supervisor é o orquestrador da ClaudIA Agêntica — o componente responsável por entender a intenção do cliente, decidir como responder e garantir que a resposta chegue com o tom de voz correto. Entender o que o Supervisor faz (e o que ele não faz) é essencial para configurar bem a plataforma. 🧠 O que o Supervisor faz O Supervisor só entra em cena para pegar o cliente do pedido e resolver junto aos sub-agents, ele: 1. Entende o que o cliente presica 2. Seleciona o Sub-agente correto para aquele pedido, com base na description de cada especialista 3. Passa o contexto necessário para o Sub-agente agir 4. Faz iterações com o sub-agent para resolver a dor do cliente 5. Formata a resposta final usando o tom de voz configurado para aquele cliente 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 que é absolutamente necessário para avançar (se um sub-agent pedir mais dados, 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 o Sub-agente com base na description de cada um — um texto curto que descreve quando aquele especialista deve ser acionado. Não é necessário (nem recomendado) listar os Sub-agentes no prompt do Supervisor. As descriptions já fazem esse trabalho. ⚠️ Atenção: duplicar regras de roteamento no prompt do Supervisor e na description do sub-agent cria duas fontes de verdade que podem conflitar. Mantenha as regras de roteamento 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 do prompt e controla identidade, vocabulário, formato e regras de comunicação. O que deve estar no tom de voz - Tom geral: formal ou informal, direto ou explicativo, caloroso ou neutro - Vocabulário: palavras preferidas e proibidas, como tratar o cliente (você/tu/senhor), uso de emoji - Situações difíceis: como responder à frustração, dar notícias ruins, dizer "não consigo fazer isso" - Formato: comprimento da resposta, uso de listas, quebras de parágrafo - Exemplos: pares de "prefira X / evite Y" — são os mais úteis para a IA 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 no tom de voz - Lógica de negócio ou cenários de atendimento → vai no system prompt do Sub-agente - Regras de roteamento → vão na description do sub-agent - Instruções sobre quando acionar tools → vão no system prompt do Sub-agente Checklist de avaliação do tom de voz - Sem contradições: "ser informal" + "sempre usar senhor/senhora" é conflito — resolver 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

Última atualização em Apr 06, 2026

Handoff para Humano: como funciona

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 O handoff não acontece automaticamente quando um Sub-agente detecta uma situação crítica. O único mecanismo de transferência. Supervisor tem acesso a uma tool universal chamada handoff_to_human. O Supervisor pode acionar essa tool a qualquer momento que achar que a conversa precisa ser escalada para um humano ou um especialista. Isso pode vir dele ou pode vir do sub-agent. O fluxo completo: 1. O Sub-agente retorna uma 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 ⚠️ Regra crítica: descrever ≠ executar Se o Sub-agente retornar "encaminhar para humano" em texto mas o Supervisor não reconhecer isso como gatilho para chamar a tool, o handoff não acontece. O ticket continua com a IA — mesmo que a resposta mencione uma transferência. 📋 Quando sinalizar handoff Os Sub-agentes devem sinalizar handoff nas situações que você julgar necessarias. O Supervisor pode também acionar essa tool por conta própria de acordo com as diretrizes globais da Cloud Humans (por exemplo frustração ou se não conseguir entender a dúvida do cliente). Cada uma das situações deve estar explicitamente mapeada no system prompt do Sub-agente responsável — o "senso comum" da IA não é suficiente (apesar de ser um ótimo fallback). ✍️ Como configurar corretamente No system prompt do Sub-agente Mapeie cada cenário de escalação de forma explícita. Exemplo: "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." Não confie somente 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: o que acontece quando o handoff falha Situação: Um cliente consultou um pedido que estava em atraso. A ClaudIA identificou o atraso, respondeu com link de rastreio. Causa: 1. O system prompt do Sub-agente não tinha cenário específico para pedido em atraso — cobria um pedido em atraso da mesma forma que os outros, busca a informação e responde o cliente quer, se ajuste para 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 do handoff - 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?

Última atualização em Apr 06, 2026

Agêntica vs Eddie: quando usar cada um

A ClaudIA Agêntica e o Eddie são os dois mecanismos que permitem à ClaudIA acessar sistemas externos e executar ações via API ou buscar informações. Eles se complementam — a escolha entre um e outro depende do tipo de processo que você quer automatizar. 🔀 Eddie — fluxos estruturados O Eddie é um agente interativo que acessa sistemas externos para recuperar ou modificar dados dinâmicos, seguindo 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 — onde 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 da interação - Processos simples e bem delimitados onde o cliente não sai do roteiro O que o Eddie faz bem: - Previsibilidade total — a resposta segue exatamente o fluxo configurado - Controle granular sobre o que a IA pode ou não perguntar Limitação: - Se o cliente responder algo fora do caminho previsto, o fluxo trava (e reinicia) ou cai em fallback - Qualquer novo cenário exige atualização manual do fluxo - Problemas exigem grande esforço para serem corrigido e quanto maior e mais complexo o fluxo, esse esforço aumenta de forma exponencial. 🤖 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 do cliente - Situações onde o cliente pode trazer múltiplas demandas em uma 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 — rastreamento de pedidos, consulta de crédito, agendamentos, etc. - Quando existe espaço para a IA modificar a forma de agir para melhor atender o cliente em cada caso. O que a Agêntica faz bem: - Lida com conversas que fogem do roteiro sem travar - Combina múltiplas tools numa mesma interação quando necessário - Valida o input do cliente antes de acionar a chamada de API - Melhora conforme os cenários vão acontecendo em produção - Respostas muito fluidas e zero robôticas Limitação: - Requer um prompt de diretrizes e description 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 possíveis e flexibilidade | | Quando o 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 o fluxo para cada novo cenário | Refinar o prompt com base em casos reais | 💡 Regra prática 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 — o Eddie para os processos críticos e fixos, a Agêntica para o restante.

Última atualização em Apr 06, 2026

Boas práticas para criação de agentes na plataforma Claudia Agentic

Este artigo apresenta os conceitos essenciais e os erros mais comuns na criação de sub-agentes (especialistas) na plataforma Claudia. Seguir essas boas práticas garante que o roteamento funcione corretamente, que o agente tome decisões consistentes e que a experiência do usuário final seja fluida. Como funciona a arquitetura de agentes Cada sub-agente possui dois campos principais: 1. Description (agent card) — texto que usado como descrição das capacidades que esse sub-agente possui. É com base nesse texto que o nosso sistema decide para qual agente encaminhar a conversa e se vai usar um sub-agente ou vai para a Claudia tradicional. Pontos principais são quando acionar e quando não acionar o sub-agente. 2. System prompt — conjunto completo de instruções que o sub-agente segue quando é acionado. Define quem ele é, o que deve fazer, como decidir e o que retornar. O sub-agente nunca fala diretamente com o cliente. Ele recebe uma requisição em linguagem natural do supervisor de sub-agentes, executa sua lógica e retorna dados estruturados. Quem formata a resposta final para o cliente é sempre esse supervisor. Erros conhecidos Description com linguagem interna A description é usada para decidir o roteamento da conversa. Se o cliente diz "quero cancelar" mas a description diz "workflow de churn prevention", o roteamento vai falhar. A description deve sempre usar a linguagem do cliente, não termos internos da operação. Ausência de status de retorno na description A description deve listar todos os resultados possíveis que o agente pode retornar: sucesso, dados faltantes, erro e necessidade de escalonamento humano. Sem essa informação, o supervisor não sabe como reagir ao resultado do agente e pode dar respostas genéricas ou incorretas ao cliente. Regras sem explicação de contexto no system prompt Escrever "se o valor for acima de 1.000, o lead é qualificado" sem explicar o porquê faz com que o agente aplique o critério de forma rígida e falhe em situações de borda. O correto é incluir o raciocínio por trás: "acima de 1.000 porque abaixo disso o custo não se paga para o cliente". Quando o agente entende a lógica de negócio, ele toma decisões melhores em cenários ambíguos. Árvores de decisão no system prompt Prompts com 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 de montar um fluxograma, descreva os critérios como sinais com pesos: "o sinal mais forte é X, seguido de Y, e como último recurso Z". O agente decide melhor quando entende prioridades do que quando segue um roteiro fixo. Mensagens prontas para o cliente no system prompt O sub-agente retorna dados estruturados — quem monta a resposta final é o supervisor, usando o tom de voz configurado. Incluir textos prontos como "Prezado cliente, informamos que..." no prompt do sub-agente cria conflito com o tom do supervisor e gera respostas inconsistentes. Regras de roteamento repetidas no supervisor A description do agente já é usada pelo sistema para decidir o roteamento. Repetir regras de "quando chamar" e "quando não chamar" no prompt do supervisor cria duas fontes de verdade que inevitavelmente divergem. O prompt do supervisor deve definir apenas como lidar com os resultados dos sub-agentes, não qual sub-agente chamar. Sub-agente tentando interpretar a intenção do cliente O sub-agente recebe uma requisição já processada pelo supervisor, não a mensagem original do cliente. Ele deve executar o que foi pedido, não tentar descobrir qual é a pergunta do cliente. Entender a intenção é responsabilidade do supervisor. Passos numerados obrigatórios Evite instruções como "Passo 1, Passo 2, Passo 3" como se fosse uma linha de montagem. O agente consegue resolver múltiplas questões ao mesmo tempo se tiver contexto suficiente. Passos rígidos limitam essa capacidade e tornam o prompt frágil a variações. Mapeamento exaustivo de cenários Tentar mapear todas as combinações possíveis de dados presentes ou ausentes gera prompts enormes e ainda assim incompletos. O princípio correto é: "vá o mais longe possível com o que você tem, peça apenas o que realmente precisa, e não pule para a opção mais complexa se caminhos mais simples ainda existirem". Criação de tools Tools são as ferramentas que os sub-agentes usam para consultar sistemas externos — buscar dados de um pedido, verificar status de pagamento, consultar estoque, etc. Elas são configuradas separadamente via MCP e vinculadas ao agente, não definidas dentro do prompt. Como o sub-agente interage com tools O sub-agente sabe quais tools estão disponíveis pela configuração do MCP. No system prompt, você descreve quando e por que usar cada tool, mas não define a tool em si. A definição técnica (URL, parâmetros, autenticação) fica na configuração do MCP. Erros conhecidos Tool sem descrição clara de parâmetros Cada tool precisa ter seus parâmetros bem descritos — nome, tipo, se é obrigatório ou opcional, e o que representa. Se a tool aceita um order_id mas a descrição não deixa claro o formato esperado (ex: numérico, com prefixo, UUID), o agente pode enviar dados no formato errado e receber erros silenciosos. Tool genérica demais Uma tool que faz coisas demais (ex: "consulta qualquer informação do cliente") dificulta o uso correto pelo agente. Prefira tools com escopo bem definido: uma para buscar pedido, outra para consultar pagamento, outra para verificar endereço. Quando o agente tem clareza sobre o que cada tool faz, ele escolhe melhor. Tool duplicada com nomes diferentes Às vezes, durante a construção, são criadas duas tools que na prática chamam o mesmo endpoint com os mesmos parâmetros, mas com nomes diferentes. Isso confunde o agente, que pode chamar uma ou outra de forma inconsistente. 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 e está configurada, mas o system prompt não menciona quando usá-la. O agente até pode descobrir sozinho em alguns casos, mas o resultado é imprevisível. No system prompt, inclua orientações como: "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 Se a tool retorna 30 campos mas o agente só precisa de 3 para responder ao cliente, o excesso de informação pode confundir a tomada de decisão. Quando possível, configure a tool para retornar apenas o que é necessário. Quando não for possível, oriente no system prompt quais campos são relevantes para cada situação. Ausência de tratamento de erro Toda tool pode falhar — timeout, dado não encontrado, erro de autenticação. O system prompt deve orientar o que fazer quando a tool retorna erro: tentar novamente, pedir outro dado ao cliente, ou escalar para atendimento humano. Sem essa orientação, o agente pode travar ou dar respostas vazias. Checklist de validação de tools - A tool tem uma descrição clara do que faz? - Os parâmetros estão documentados com tipo, formato e obrigatoriedade? - Não existe outra tool que faz a mesma coisa com nome diferente? - O system prompt orienta quando e por que usar essa tool? - O retorno da tool contém apenas os dados necessários (ou o prompt orienta quais campos usar)? - O system prompt cobre o que fazer quando a tool falha? Checklist de validação Antes de publicar um agente, valide: Na description: - O sistema conseguiria identificar corretamente quando chamar este agente apenas pela description? - Está claro o que este agente NÃO faz? - A linguagem usada reflete as palavras do cliente? - Os resultados de retorno cobrem sucesso, dados faltantes, erro e escalonamento? No system prompt: - As regras incluem o raciocínio de negócio, não apenas valores numéricos soltos? - A lógica de decisão usa sinais com peso em vez de cadeias rígidas de se/então? - Existe um princípio para lidar com informações incompletas? - O prompt não contém mensagens prontas para o cliente? - As ferramentas disponíveis estão mencionadas com orientação de quando usar? - O que o agente retorna está claro para cada resultado possível? - Existe uma seção curta e direta de limites (o que nunca fazer)? Conclusão Garantir que os agentes sejam criados seguindo essas boas práticas é essencial para um roteamento preciso, decisões consistentes e uma experiência de atendimento fluida para o cliente. Agentes bem construídos são mais fáceis de manter, evoluir e investigar quando algo dá errado. A partir das validações e orientações descritas aqui, sua equipe pode criar agentes mais robustos, previsíveis e alinhados com a lógica real do negócio.

Última atualização em Apr 06, 2026

O que é a ClaudIA Agêntica

📹 Webinar com o CEO — visão geral e contexto estratégico https://www.loom.com/share/5a783e1f97c2446799fd9c8756c9170a A ClaudIA Agêntica é uma funcionalidade que permite à ClaudIA executar ações reais via chamadas de API, MCPs (ferramentas), etc. — em vez de responder apenas com base nos conteúdos registrados na base de conhecimento. Na prática: a ClaudIA passa a agir de forma autônoma e contextual. Ela decide quando agir, combina a solicitação do cliente com as diretrizes de um prompt e executa a ação mais adequada para resolver o atendimento ou simplesmente responder à dúvida da melhor forma possível — tudo isso sem precisar transferir para um humano. Como funciona? Quando um cliente envia uma mensagem, nossa IA analisa a solicitação (e o contexto da conversa) e decide: - Responder diretamente com base nos conteúdos registrados, ou - Ativar a ClaudIA Agêntica, que age para ajudar o cliente 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 da ClaudIA Agêntica: Judge — decide se a Agêntica age O Judge lê a mensagem do cliente e a compara com as descrições das ferramentas disponíveis. Se existir um sub-agente para agir naquele assunto, a conversa será roteada para a Agêntica. Se não, a ClaudIA responde com base nos conteúdos da base de conhecimento e fluxos habituais. Supervisor — decide quem age e entrega a resposta Quando o Judge ativa a Agêntica, entra em cena o Supervisor: ele seleciona qual Sub-agente é o mais adequado para aquela solicitação e, após receber a resposta, formata a resposta final com o tom de voz do cliente. Sub-agente — executa a ferramenta O Sub-agente é o especialista. Ele tem prompt próprio para lidar com aquela situação e conta com as ferramentas (chamadas de API). Age seguindo as diretrizes do prompt e das ferramentas, devolve os dados estruturados ao Supervisor e 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 ao cliente. Exemplos em produção https://www.loom.com/share/015769c60741423e8457649333333d33 Antecipação de check-in — hospedagem Uma cliente entrou em contato informando que seu voo chegaria mais cedo e queria antecipar o check-in. O que a ClaudIA Agêntica fez: - Explicou as regras gerais (check-in antes das 13h tem cobrança adicional por dia) - Solicitou o código de reserva para consultar as informações específicas dessa cliente via API - Verificou a disponibilidade e identificou que a entrada antes das 11h não estava disponível - Ofereceu o check-in gratuito entre 13h e 15h (cortesia após as 13h) - Quando a cliente aceitou, chamou a ferramenta para registrar a solicitação no sistema - Confirmou à cliente — ticket encerrado sem intervenção humana 💡 Por que a ClaudIA solicitou o código de reserva? Porque a disponibilidade de informações é específica de cada reserva. A ferramenta precisa desse parâmetro para consultar a API correta. Consulta de limite de crédito — fintech Um cliente perguntou sobre sua fatura e depois solicitou informações sobre aumento de limite. O que a ClaudIA Agêntica fez: - Respondeu sobre as condições gerais da fatura com base nos conteúdos registrados - Quando o cliente perguntou sobre o limite, ativou a ferramenta de consulta de crédito - Usou o helpdeskid (que chega automaticamente com o ticket) para identificar o cliente — sem precisar solicitar os dados novamente - Retornou o limite atual, valor disponível e regras de recorrência — dados reais e personalizados - Orientou sobre como antecipar uma parcela para liberar o limite 💡 Diferença em relação à ClaudIA sem Agêntica: Sem Agêntica: resposta genérica sobre como o limite de crédito funciona. Com Agêntica: dados reais do cliente em tempo real. Rastreamento com código inválido — varejo Um cliente forneceu um código de pedido com formato incorreto (mais dígitos do que o esperado). O que a ClaudIA Agêntica fez: - Ao tentar ativar a ferramenta, identificou que o código estava fora do formato esperado - Em vez de retornar um erro genérico, orientou o cliente sobre o formato correto com um exemplo prático - O cliente forneceu o código correto, a ClaudIA localizou o pedido e resolveu o ticket 💡 Como a ClaudIA soube que o código estava errado? A descrição da ferramenta especifica o formato esperado. Quando a entrada não corresponde, a ClaudIA decide não ativar a chamada e guia o cliente para corrigir a informação — sem uma mensagem de erro robótica. 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 que a ClaudIA pode executar durante o atendimento. A configuração tem três blocos principais: Bloco 1 — Declaração de variáveis Define quais dados a ClaudIA extrairá da conversa para usar na chamada de API. - Nome da variável: ex.: CPF, codigo_pedido, email - Descrição: ex.: "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 do ticket, a ClaudIA o extrai automaticamente — sem perguntar novamente. Bloco 2 — Chamada de API Configura a requisição enviada ao sistema externo: - Endpoint: a URL da API - Método: GET, POST, PATCH, etc. - Headers: ex.: Authorization com token de autenticação - Corpo / Parâmetros: os dados enviados na requisição, usando as variáveis do bloco anterior Bloco 3 — Configuração da resposta Define o que a ClaudIA receberá da API para formular a resposta: - Resposta completa: retorna toda a resposta da API para a ClaudIA - Resposta filtrada (JSON específico): útil quando a API retorna dados sensíveis que não devem ser expostos ao cliente — ex.: tokens, IDs internos, dados bancários A descrição da ferramenta A descrição é o campo que instrui a ClaudIA sobre quando e como ativar aquela ferramenta. É um dos campos mais importantes: - Explica as capacidades daquela ferramenta - Define o formato esperado dos parâmetros (ex.: "código de pedido com 6 dígitos, formato #XXXXXX") - Funciona como o "manual de uso" da ferramenta para que a IA saiba quando usá-la e quais informações precisa para isso ✅ Boas práticas - Escreva descrições precisas — são o principal mecanismo de controle de quando cada ferramenta é ativada - Especifique o formato dos parâmetros — quantidade de dígitos, prefixo, tipo de dado — isso evita chamadas com entrada inválida - Use resposta filtrada para dados sensíveis — exponha ao modelo apenas o necessário para formular a resposta - Refine com base em casos reais — a Agêntica melhora à medida que os cenários ocorrem em produção

Última atualização em Apr 08, 2026

Get Agentic Done (GAD) — criando agentes com linguagem natural

O que é o GAD O GAD (Get Agentic Done) é 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 GAD cria toda a estrutura agêntica para você. Na prática: você conversa com o GAD explicando o que o seu atendimento precisa fazer, e ele constrói os componentes automaticamente na plataforma. Você acessa pela tela de agentes. O que o GAD cria O GAD produz três tipos de componentes: | 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 do processo, você tem um fluxo agêntico completo e funcional — pronto para testar. Como funciona o processo O GAD opera em fases sequenciais e automáticas: Fase 1 — Levantamento de requisitos O GAD conduz uma conversa com você para entender: - Quais APIs o fluxo precisa acessar (endpoints, métodos, headers, parâmetros) - Quais cenários o agente precisa tratar (sucesso, erro, exceções) - Qual o tom de voz do atendimento - Quando escalar para humano OBS: nessa etapa você não deve passas API tokens etc, passe nomes genéricos como TOKEN_API_KEY e depois vá nas tools e coloque os valores corretos. Ao final, o GAD gera uma especificação (spec) — um documento estruturado com tudo que será criado (normalmente ela nem expõe isso a você). Fase 2 — Criação das tools Com base na spec, o GAD cria automaticamente as tools (nosso sistema de ferramentas). Cada tool é configurada com a URL, método, headers e parâmetros que você informou. Fase 3 — Criação dos agentes e supervisor O GAD cria os sub-agentes com seus prompts, vincula as tools criadas, e monta o supervisor que vai orquestrar o fluxo. Dois modos de uso Criar do zero — Você descreve o que precisa e o GAD levanta os requisitos conversando com você. Use quando não tem um fluxo existente. Migrar um fluxo Eddie/Typebot — Você cola o JSON de um fluxo Eddie existente, e o GAD analisa a estrutura (webhooks viram tools, condicionais viram cenários, mensagens viram tom de voz) e converte para a arquitetura agêntica (se precisar de mais informação, vai te pedir no chat). Use quando quer modernizar um fluxo que já existe. O que você precisa fornecer Para criar um fluxo do zero, tenha em mãos: - Dados das APIs — URL do endpoint, método HTTP (GET/POST), headers de autenticação, parâmetros de entrada e quais campos da resposta importam - Cenários de atendimento — o que o agente faz em cada situação (pedido encontrado, pedido em atraso, dados inválidos, etc.) - Regras de escalação — quando o atendimento deve ser transferido para um humano - Tom de voz — como o supervisor deve se comunicar com o cliente O GAD vai perguntar o que estiver faltando — mas quanto mais contexto você trouxer, mais rápido e preciso é o resultado. Para migrar um fluxo existente: - O JSON do fluxo — exporte o fluxo do Eddie/Typebot e cole na conversa - Contexto adicional — regras de negócio que não estão explícitas no fluxo O que o GAD não faz - Não modifica agentes existentes — ele cria novos. Para editar, use o OAP diretamente - Não cria APIs — ele cria tools que chamam APIs, mas a API precisa já existir - Não configura base de conhecimento — o GAD monta a stack agêntica, mas conteúdos da base de conhecimento são configurados separadamente - Não garante que a API funciona — ele configura a tool com os dados que você forneceu. Se o endpoint estiver errado ou offline, a tool vai falhar Se algo der errado durante a criação O GAD executa as fases em ordem: spec → tools → agentes. Se uma fase falhar: - O GAD não retenta automaticamente para evitar criar componentes duplicados - Ele informa o erro e pede para você iniciar uma nova conversa para tentar novamente - Os componentes que foram criados com sucesso antes da falha permanecem — você pode visualizá-los e removê-los manualmente no OAP se necessário Boas práticas - Seja específico com as APIs — informe endpoints completos, headers de autenticação, e formato dos parâmetros. O GAD não inventa dados de API - Descreva cenários reais — em vez de "trate erros", diga "quando o pedido não for encontrado, peça o número novamente e explique o formato correto (#XXXXXX)" - Um fluxo por conversa — cada conversa com o GAD deve criar um fluxo completo. Não misture múltiplos fluxos na mesma conversa - Revise antes de publicar — após o GAD criar os componentes, abra cada agente no OAP e revise os prompts, descriptions e tools vinculadas - Teste no Playground — antes de colocar em produção, teste o fluxo completo com cenários reais

Última atualização em Apr 10, 2026