# Como usar o Agent Component em cenários reais O **Agent Component** permite integrar modelos de IA aos seus pipelines para executar tarefas como classificação, moderação, geração de conteúdo e estruturação de dados. Neste artigo, você encontra uma coleção de **casos de uso práticos**, mostrando diferentes formas de configurar o componente, desde prompts simples até combinações com JSON Schema, dados dinâmicos e MCP Server. Cada exemplo demonstra quando usar cada abordagem e quais resultados esperar. Se quiser explorar todas as opções de configuração em detalhes, consulte a documentação do [**Agent Component**](/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm.md). ### **Configuração apenas com User Prompt** Essa configuração utiliza apenas o parâmetro **User Prompt** para enviar uma requisição ao modelo de IA. {% hint style="success" %} #### **Vantagens:** * Fácil de configurar com apenas uma entrada. * Bom para testar diferentes prompts rapidamente. * Funciona bem para requisições simples. {% endhint %} #### **Exemplo prático** * **Caso de uso:** Um pipeline integrado ao Zendesk recebe um novo ticket de cliente. O Agent Component é utilizado para analisar a solicitação e classificar seu tópico. * **Objetivo:** Classificar o tópico de um ticket de suporte. **User Prompt:** {% code overflow="wrap" %} ``` Classifique o tópico da seguinte solicitação de cliente: "Meu pagamento foi recusado, mas o valor foi debitado da minha conta. Preciso de ajuda para resolver isso." ``` {% endcode %} **Exemplo de saída:** {% code overflow="wrap" expandable="true" %} ```json { "body": { "text": "Tópico: **Problemas com pagamento / Cobrança indevida**\n\nExplicação: \nA solicitação do cliente refere-se a um problema relacionado ao pagamento, especificamente uma cobrança indevida (pagamento recusado, mas valor debitado). Portanto, o tópico correto é \"Problemas com pagamento\" ou \"Cobrança indevida\"." }, "tokenUsage": { "inputTokenCount": 43, "outputTokenCount": 71, "totalTokenCount": 114 } } ``` {% endcode %} ### **Configuração com User + System Prompts** Essa configuração utiliza os parâmetros **User Prompt** e **System Prompt** para guiar a resposta da IA. {% hint style="success" %} #### **Vantagens:** * Ajuda a guiar o tom e o comportamento da IA. * Torna as respostas mais consistentes. * Adiciona contexto que ajuda a IA a entender melhor o prompt. {% endhint %} #### **Exemplo prático** * **Caso de uso:** Após classificar o ticket de suporte, o pipeline consulta uma base de conhecimento. O Agent Component é então usado novamente para gerar uma resposta personalizada ao cliente. * **Objetivo:** Gerar uma resposta personalizada utilizando tom e estilo predefinidos. **System Prompt:** {% code overflow="wrap" %} ``` Você é um agente de suporte amigável e prestativo. Use sempre um tom empático e forneça instruções claras. Retorne a mensagem em texto simples, sem quebras de linha. ``` {% endcode %} **User Prompt:** {% code overflow="wrap" %} ``` Escreva uma resposta para o cliente abaixo, explicando que iremos investigar o pagamento e responder dentro de 24 horas: "Meu pagamento foi recusado, mas o valor foi debitado da minha conta. Preciso de ajuda para resolver isso." ``` {% endcode %} **Exemplo de saída:** {% code overflow="wrap" expandable="true" %} ```json { "body": { "text": "Olá! Entendemos a sua preocupação e sentimos muito pelo transtorno. Vamos investigar o seu pagamento e daremos um retorno com uma solução em até 24 horas. Se precisar de mais alguma informação, estamos à disposição para ajudar." }, "tokenUsage": { "inputTokenCount": 100, "outputTokenCount": 47, "totalTokenCount": 147 } } ``` {% endcode %} ### **Configuração com Prompts + JSON Schema** {% hint style="info" %} O suporte a **JSON Schema** pode variar entre provedores e modelos de LLM. Recomendamos consultar a documentação oficial do provedor e do modelo antes de configurar para confirmar a compatibilidade. {% endhint %} Essa configuração utiliza **User Prompt**, **System Prompt** e **JSON Schema** para gerar uma resposta estruturada. {% hint style="success" %} #### **Vantagens:** * Mantém a saída consistente com um formato definido. * Valida automaticamente tipos de campos, campos obrigatórios e valores permitidos. * Funciona como um contrato entre sistemas, tornando a integração mais confiável. * Evita que dados inválidos sejam processados. {% endhint %} #### **Exemplo prático** * **Caso de uso:** Um pipeline recebe um comentário gerado por um usuário em uma plataforma de ISV (independent software vendor). O Agent Component envia o comentário para a IA avaliar se ele é nocivo ou ofensivo. A pontuação retornada é então usada para decidir se o comentário deve ser publicado ou se o usuário deve ser sinalizado. * **Objetivo:** Avaliar e atribuir uma pontuação ao nível de nocividade de um comentário e determinar se ele deve ser aprovado. **System Prompt:** {% code overflow="wrap" %} ``` Você é um moderador de conteúdo. Avalie se o comentário é nocivo, atribua uma pontuação de 0 a 1 para gravidade e indique se ele deve ser aprovado ``` {% endcode %} **User Prompt:** {% code overflow="wrap" %} ``` Avalie o seguinte comentário: "Tive uma ótima experiência com essa empresa. A equipe é profissional e muito prestativa." ``` {% endcode %} **JSON Schema:** {% code overflow="wrap" expandable="true" %} ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ModerationResult", "type": "object", "properties": { "status": { "type": "integer", "enum": [200], "description": "Código de status HTTP" }, "body": { "type": "object", "properties": { "score": { "type": "string", "pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$", "description": "Pontuação de gravidade de 0 a 1" }, "label": { "type": "string", "description": "Rótulo descrevendo o conteúdo, ex.: inofensivo, potencialmente nocivo" }, "should_approve": { "type": "boolean", "description": "Indica se o comentário deve ser aprovado" } }, "required": ["score", "label", "should_approve"], "additionalProperties": false } }, "required": ["status", "body"], "additionalProperties": false } ``` {% endcode %} **Saída:** {% code expandable="true" %} ```json { "body": { "status": "200", "body": { "score": "0", "label": "inofensivo", "should_approve": true } }, "tokenUsage": { "inputTokenCount": 207, "outputTokenCount": 24, "totalTokenCount": 231 } } ``` {% endcode %} ### **Configuração com Prompts + JSON simples** Essa configuração utiliza **User Prompt**, **System Prompt** e **JSON simples** (sem schema) para retornar uma resposta estruturada. {% hint style="success" %} #### **Vantagens:** * Produz saída em um formato simples e legível. * Flexível e fácil de trabalhar. * Bom quando não é necessária validação rigorosa. {% endhint %} #### **Exemplo prático** Usando o mesmo caso de uso acima, os prompts orientam a IA a retornar diretamente um objeto JSON, sem validação de schema. **System Prompt:** {% code overflow="wrap" %} ``` Você é um moderador de conteúdo. Avalie se o comentário é nocivo, atribua uma pontuação de 0 a 1 para gravidade e indique se ele deve ser aprovado. ``` {% endcode %} **User Prompt:** {% code overflow="wrap" %} ``` Avalie o seguinte comentário: "Tive uma ótima experiência com essa empresa. A equipe é profissional e muito prestativa." ``` {% endcode %} **JSON Simples:** ```json { "score": "", "label": "", "should_approve": "" } ``` **Saída:** {% code expandable="true" %} ```json { "body": { "score": "0", "label": "Inofensivo", "should_approve": "sim" }, "tokenUsage": { "inputTokenCount": 91, "outputTokenCount": 26, "totalTokenCount": 117 } } ``` {% endcode %} ### **Configuração com Prompts + Double Braces** Essa configuração utiliza o campo **User Prompt** para injetar dinamicamente dados de um conector anterior usando expressões Double Braces. Além disso, os campos **System Prompt** e **Output Format** são usados para orientar a IA e gerar uma resposta estruturada. {% hint style="success" %} #### **Vantagens:** * Permite prompts contextuais com base em dados do pipeline. * Conecta a resposta da IA a informações de tempo de execução. {% endhint %} #### **Exemplo prático** * **Caso de uso:** Um pipeline recebe dados de endereço de um [conector REST](/documentation/connectors-and-triggers/pt-br/connectors/web-protocols/rest-v2.md) que consulta a API pública brasileira de CEP (OpenCEP). O Agent Component é então utilizado para classificar o tipo de endereço como residencial, comercial ou rural, com base no nome da rua e no bairro retornados pela API. * **Objetivo:** Categorizar o tipo de endereço utilizando dados dinâmicos do conector anterior. **System Prompt:** {% code overflow="wrap" %} ``` Você é um assistente de classificação de endereços. Com base no nome da rua e no bairro, classifique o endereço como residencial, comercial ou rural. Explique seu raciocínio. ``` {% endcode %} **User Prompt com Double Braces:** {% code overflow="wrap" %} ``` Use o seguinte endereço para fazer sua avaliação: {{message.body}} ``` {% endcode %} **Output Format Body:** ```json { "tipo": "", "razão": "" } ``` **Possível saída:** {% code overflow="wrap" expandable="true" %} ```json { "status": 200, "body": { "tipo": "Residencial", "razão": "Os endereços residenciais geralmente são caracterizados por nomes de rua sem identificadores comerciais ou industriais. A 'Rua Abilio Carvalho Bastos' não sugere que seja uma área comercial ou industrial. Além disso, as ruas normalmente representam áreas residenciais em uma cidade ou cidade. O bairro 'Fósforo', por não possuir uma identificação típica de zonas comerciais ou rurais, também sugere ser uma área residencial." } }, "tokenUsage": { "inputTokenCount": 170, "outputTokenCount": 62, "totalTokenCount": 232 } } ``` {% endcode %} ### **Configuração com MCP Server** Essa configuração utiliza um **MCP Server**, combinado com **User Prompt**, **System Prompt** e **JSON Schema**, para solicitar e estruturar documentação gerada a partir de fontes de dados externas. {% hint style="success" %} #### **Vantagens:** * Permite comunicação segura entre modelos de IA e sistemas de origem. * Mantém a saída gerada consistente com um formato predefinido. * Valida automaticamente campos obrigatórios e tipos de dados. * Garante geração de documentação confiável e precisa. {% endhint %} #### **Exemplo prático** * **Caso de uso:** Um pipeline se conecta ao servidor MCP Deepwik**i** para recuperar conhecimento técnico sobre um tópico. A IA transforma essas informações brutas em documentação estruturada. * **Objetivo:** Gerar uma seção de documentação sobre Arquitetura Orientada a Eventos (Event-Driven Architecture\*)\* com título claro, descrição breve, casos de uso práticos e boas práticas. **MCP Server:** * **Name:** DeepWiki * **URL:** **System prompt:** {% code overflow="wrap" %} ``` Você é um gerador de documentação técnica. Sempre escreva em inglês claro e conciso, usando um tom profissional, mas simples. Sua tarefa é transformar informações brutas recuperadas de ferramentas externas (como o Deepwiki) em documentação bem estruturada. Garanta que sua saída seja consistente, precisa e alinhada com o formato solicitado. ``` {% endcode %} **User prompt:** {% code overflow="wrap" %} ``` Use as informações recuperadas do servidor MCP Deepwiki sobre o tópico "Event-Driven Architecture" para criar uma seção de documentação. A documentação deve incluir: - Um título claro. - Uma descrição concisa (2–3 frases). - Pelo menos três casos de uso práticos. - Pelo menos três boas práticas. Formate a resposta seguindo estritamente o JSON Schema fornecido. ``` {% endcode %} **JSON Schema:** {% code overflow="wrap" expandable="true" %} ```json { "$schema": "http://json-schema.org/draft-07/schema#", "title": "DocumentationSection", "type": "object", "required": ["title", "description", "use_cases", "best_practices"], "properties": { "title": { "type": "string", "description": "O título da seção de documentação" }, "description": { "type": "string", "description": "Uma descrição concisa do tópico (2-3 frases)" }, "use_cases": { "type": "array", "description": "Casos de uso práticos para o tópico", "items": { "type": "string" }, "minItems": 3 }, "best_practices": { "type": "array", "description": "Boas práticas recomendadas para o tópico", "items": { "type": "string" }, "minItems": 3 } }, "additionalProperties": false } ``` {% endcode %} **Saída:** {% code overflow="wrap" expandable="true" %} ```json { "body": { "title": "Event-Driven Architecture", "description": "Arquitetura Orientada a Eventos (Event-Driven Architecture - EDA) é um padrão de design de software em que os componentes do sistema se comunicam produzindo e consumindo eventos. Essa abordagem possibilita sistemas fracamente acoplados que podem reagir a mudanças em tempo real, aumentando a escalabilidade e a flexibilidade. A EDA é comumente usada em sistemas distribuídos e aplicações que exigem processamento assíncrono.", "use_cases": [ "Construção de microsserviços que precisam se comunicar de forma assíncrona.", "Implementação de plataformas de análise em tempo real que processam dados em fluxo.", "Automatização de fluxos de trabalho em resposta a eventos de negócios, como processamento de pedidos ou ações de usuários." ], "best_practices": [ "Projetar eventos autônomos e descritivos para garantir comunicação clara entre os componentes.", "Usar sistemas de mensageria confiáveis para garantir a entrega de eventos e evitar perda de dados.", "Monitorar e registrar o fluxo de eventos para detectar e resolver rapidamente problemas no sistema." ] }, "tokenUsage": { "inputTokenCount": 396, "outputTokenCount": 162, "totalTokenCount": 558 } } ``` {% endcode %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digibee.com/documentation/resources/pt-br/ai-practical-examples/how-to-agent-component.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.