Como usar o Agent Component em cenários reais

Saiba mais sobre como usar o Agent Component em cenários reais, com exemplos que mostram quando aplicar cada configuração e quais resultados esperar.

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.

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.

Vantagens:

• Fácil de configurar com apenas uma entrada.

• Bom para testar diferentes prompts rapidamente.

• Funciona bem para requisições simples.

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:

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."

Exemplo de saída:

{
  "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
  }
}

Configuração com User + System Prompts

Essa configuração utiliza os parâmetros User Prompt e System Prompt para guiar a resposta da IA.

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.

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:

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.

User Prompt:

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."

Exemplo de saída:

{
  "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
  }
}

Configuração com Prompts + JSON Schema

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.

Essa configuração utiliza User Prompt, System Prompt e JSON Schema para gerar uma resposta estruturada.

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.

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:

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

User Prompt:

Avalie o seguinte comentário:
"Tive uma ótima experiência com essa empresa. A equipe é profissional e muito prestativa."

JSON Schema:

{
  "$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
}

Saída:

{
  "body": {
    "status": "200",
    "body": {
      "score": "0",
      "label": "inofensivo",
      "should_approve": true
    }
  },
  "tokenUsage": {
    "inputTokenCount": 207,
    "outputTokenCount": 24,
    "totalTokenCount": 231
  }
}

Configuração com Prompts + JSON simples

Essa configuração utiliza User Prompt, System Prompt e JSON simples (sem schema) para retornar uma resposta estruturada.

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.

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:

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.

User Prompt:

Avalie o seguinte comentário:
"Tive uma ótima experiência com essa empresa. A equipe é profissional e muito prestativa."

JSON Simples:

{
  "score": "",
  "label": "",
  "should_approve": ""
}

Saída:

{
  "body": {
    "score": "0",
    "label": "Inofensivo",
    "should_approve": "sim"
  },
  "tokenUsage": {
    "inputTokenCount": 91,
    "outputTokenCount": 26,
    "totalTokenCount": 117
  }
}

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.

Vantagens:

• Permite prompts contextuais com base em dados do pipeline.

• Conecta a resposta da IA a informações de tempo de execução.

Exemplo prático

• Caso de uso: Um pipeline recebe dados de endereço de um conector REST 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:

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.

User Prompt com Double Braces:

Use o seguinte endereço para fazer sua avaliação: {{message.body}}

Output Format Body:

{
  "tipo": "",
  "razão": ""
}

Possível saída:

{
  "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
  }
}

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.

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.

Exemplo prático

• Caso de uso: Um pipeline se conecta ao servidor MCP Deepwiki 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: https://mcp.deepwiki.com/mcp

System prompt:

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.

User prompt:

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.

JSON Schema:

{
  "$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
}

Saída:

{
  "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
  }
}