# 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**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/ai-tools/llm).

### **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](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/web-protocols/rest-v2) 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:** <https://mcp.deepwiki.com/mcp>

**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 %}