# Agent Component — Guia completo de configuração

Crie seu próprio Agente de IA com o **Agent Component**. Esse componente abstrai as APIs dos principais provedores de LLM para que você possa executar facilmente tarefas como classificação de texto, extração de informações, sumarização, avaliação de conteúdo e muito mais, tudo dentro dos seus pipelines Digibee.

Este guia apresenta:

* Explicação de cada opção de configuração
* Recursos avançados como tools, recuperação de conteúdo, guardrails e respostas mock

{% hint style="success" %}
**Dica:** Você pode encontrar mais **exemplos reais** do Agent Component na [**seção Use Cases**](https://app.gitbook.com/s/XfrDexGOLMin51pAiWkq/ai-practical-examples).
{% endhint %}

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FAaBXdlTtTYzoSLiBdhoM%2F%5Bpt%5D%20agent-component-overview.gif?alt=media&#x26;token=cf44ccf6-4141-4d14-a227-350c993d7936" alt=""><figcaption></figcaption></figure>

## **Configuração básica**

Com os dois passos abaixo, seu Agent já está pronto para tarefas simples e diretas.

{% stepper %}
{% step %}

### Selecione o modelo

Escolha o provedor e o modelo que o Agent deve usar. Provedores suportados:

* **Anthropic Claude**
* **DeepSeek**
* **Google Gemini**
* **OpenAI**
* **Azure OpenAI**
* **Custom Model**
* **Azure OpenAI (Private)**
* **Amazon Bedrock (Private)**

Ou selecione **Custom Model** para personalizar o modelo.

Após selecionar o provedor, clique no **ícone de engrenagem** (⚙) para abrir a página **Configuração do Modelo**. Preencha os campos a seguir.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2F7daYsMn0v5SCVTlPgEZi%2F%5Bpt%5D%20model-configuration.gif?alt=media&#x26;token=d5a95383-de80-459c-9d97-0efc6b53787d" alt=""><figcaption></figcaption></figure>

#### **Configuração da Conta**

Essas configurações definem como a Digibee autentica com o provedor de LLM. Se nenhuma conta for selecionada, o conector não funcionará. Alguns provedores também exigem um **Endpoint** personalizado, dependendo de como expõem seus modelos.

Provedores privados — como **Azure OpenAI (Private)** e **Amazon Bedrock (Private)** — sempre exigem um endpoint personalizado. Ao selecionar um desses provedores, garanta que você informe o endpoint correto para seu ambiente.

Para **Amazon Bedrock**, é necessário:

* Selecionar o tipo de conta **AWS‑V4**, método suportado pelo Bedrock.
* Como a Digibee não fornece modelos predefinidos para Bedrock, você deve habilitar **Custom Model** e informar o ARN (Amazon Resource Name) do modelo presente na sua conta AWS.

| Parâmetro                       | Descrição                                                                                                                                                                                                                                                           | Tipo    | Suporta DB | Padrão  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------- | ------- |
| **Conta**                       | Conta usada para autenticar no provedor LLM. Deve ser cadastrada em [**Contas**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts). Suporta **Secret Key** ou **AWS-V4** (para Bedrock).                                    | Conta   | ❌          | N/A     |
| **Certificado**                 | Conta usada para permitir comunicação HTTPS segura com endpoints externos. Ela deve estar previamente registrada em [**Contas**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts). Tipo compatível: **Certificate Chain**. | Conta   | ❌          | N/A     |
| **Endpoint**                    | Endpoint personalizado para o provedor selecionado. Necessário para provedores privados.                                                                                                                                                                            | String  | ✅          | N/A     |
| **Permitir conexões inseguras** | Permite conexões SSL inseguras. Recomendado apenas para testes ou ambientes internos.                                                                                                                                                                               | Boolean | ❌          | `false` |

Se você selecionar um modelo privado, também deve configurar o **Nome do Modelo Personalizado**. Para personalizar totalmente o modelo, configure o **Nome do Modelo Personalizado** e selecione um provedor compatível.

#### **Parâmetros do Modelo**

Esses valores determinam a personalidade e o comportamento do modelo.

| Parâmetro                     | Descrição                                                                                                                      | Tipo de dado | Suporta DB | Padrão |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------ | ---------- | ------ |
| **Temperatura**               | Controla a criatividade. Valores baixos = mais foco; valores altos = mais diversidade.                                         | Float        | ✅          | `0.7`  |
| **Máximo de Tokens de Saída** | Limita o número de tokens na saída.                                                                                            | Integer      | ✅          | `1024` |
| **Top K**                     | Limita quantas opções de palavras o modelo considera a cada etapa. Valores baixos = mais seguro; valores altos = mais diverso. | Integer      | ✅          | `64`   |
| **Top P**                     | Controla a variabilidade usando limites de probabilidade. Valores baixos = respostas mais focadas.                             | Integer      | ✅          | `1`    |
| **Penalidade de Frequência**  | Reduz a repetição de palavras idênticas.                                                                                       | Integer      | ✅          | N/A    |
| **Penalidade de Presença**    | Incentiva o modelo a trazer novas ideias em vez de permanecer no mesmo tópico.                                                 | Float        | ✅          | N/A    |

#### **Configurações Avançadas**

Use essas opções para ajustar o desempenho e a resiliência do modelo. Você pode modificá-las conforme necessário ou manter a configuração padrão.

| Parâmetro                     | Descrição                                                         | Tipo de dado      | Suporta DB | Padrão  |
| ----------------------------- | ----------------------------------------------------------------- | ----------------- | ---------- | ------- |
| **Timeout**                   | Tempo máximo permitido (em ms) para a operação ser concluída.     | Integer           | ✅          | `30000` |
| **Máximo de Tentativas**      | Número de tentativas de repetição após uma falha.                 | Integer           | ✅          | `1`     |
| **Parâmetros Personalizados** | Parâmetros personalizados adicionais para enviar à API do modelo. | Pares chave-valor | ❌          | N/A     |

#### **Formato da Resposta**

Define como o modelo deve estruturar a saída. Quando o provedor oferece suporte, configurar um Esquema JSON é recomendado para garantir respostas mais precisas e consistentes.

| Parâmetro                     | Descrição                                                               | Tipo de dado | Suporta DB | Padrão  |
| ----------------------------- | ----------------------------------------------------------------------- | ------------ | ---------- | ------- |
| **Usar Esquema JSON**         | Permite fornecer um Esquema JSON para reforçar a estrutura da resposta. | Boolean      | ❌          | `false` |
| **Definição do Esquema JSON** | O Esquema que define a estrutura esperada.                              | JSON         | ❌          | N/A     |
| **Usar Modo JSON**            | Permite enviar um exemplo em JSON para orientar a resposta.             | Boolean      | ❌          | `false` |
| **Definição JSON**            | O exemplo JSON que o modelo deve seguir.                                | JSON         | ❌          | N/A     |
| {% endstep %}                 |                                                                         |              |            |         |

{% step %}

### Configure as mensagens

* **Mensagem do Sistema**: Descreve regras, tom e comportamento geral.
  * Exemplo: “Você é um analista de dados sênior…”
* **Mensagem do Usuário**: O prompt em si. Você pode injetar dados do pipeline usando Double Braces.
  * Exemplo: “Resuma o conteúdo abaixo…”

Depois de adicionar suas mensagens, você já pode testar o Agent.

{% hint style="danger" %}
Cada execução consome tokens do seu provedor. Para reduzir o uso ao testar o pipeline completo, considere adicionar uma [**resposta mock**](#configure-uma-resposta-mock).
{% endhint %}

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FrgvV1R7YQBNbEEzACYNW%2F%5Bpt%5D%20message-configuration.gif?alt=media&#x26;token=85322976-5c57-461f-b430-e8446c7c6bf6" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## **Configuração avançada**

As configurações avançadas permitem estender e personalizar o comportamento do Agent. Elas não são obrigatórias, mas são úteis quando você precisa de integrações, recuperação de contexto externo, validação ou testes controlados.

{% stepper %}
{% step %}

### **Adicione tools**&#x20;

As tools expandem o que o Agent pode fazer. Use-as quando o Agent precisar:

* Chamar APIs
* Acessar sistemas internos
* Acionar outros pipelines
* Buscar conteúdo externo na web

Se você estiver apenas gerando texto ou fazendo classificação, pode ignorar ferramentas.

Veja como configurar os tipos de ferramentas suportadas.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FEL1vUnafIUzhQY5lYWs1%2F%5Bpt%5D%20tools-configuration.gif?alt=media&#x26;token=1604814b-ca48-4b5f-88f5-c9e21417bd24" alt=""><figcaption></figcaption></figure>

#### **Servidor MCP**

Um servidor **Model Context Protocol (MCP)** gerencia a comunicação entre o modelo de IA e sistemas externos, permitindo que o LLM acesse ferramentas e dados externos com segurança.

**Adicionar ferramentas MCP a partir do Registro**

Se você tiver pipelines implantados com o [**MCP Server Trigger**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/mcp-server) em **Test** ou **Prod**, eles estarão disponíveis na aba **MCP Do Registro**.

Nesta aba, você pode visualizar:

* O nome do pipeline
* O tipo de autenticação
* As tools configuradas e seus respectivos parâmetros
* A versão do pipeline implantado
* Pipelines MCP que estão sendo usados atualmente como tools no componente (identificados com a tag **Em uso**)

Para adicionar um pipeline MCP como ferramenta no seu **Agent Component**, selecione o pipeline desejado e clique em **Adicionar Ferramenta**. Você será redirecionado para a aba **Adicionar Ferramentas MCP** para concluir a configuração.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FnW7T3nrqCeDCmYWwJRbz%2Fpt-mcp-tools-from-registry.gif?alt=media&#x26;token=51867d56-ffd0-4d15-a8c7-3bb0eb03451a" alt=""><figcaption></figcaption></figure>

**Adicionar Ferramentas MCP**

Use esta aba para configurar a sua ferramenta MCP.

Se o pipeline MCP tiver sido selecionado pela aba **MCP Do Registro**, alguns parâmetros são preenchidos automaticamente:

* **Nome:** Preenchido automaticamente com o nome do pipeline.
* **URL do Servidor:** Preenchido automaticamente com o endpoint do pipeline.
* **Cabeçalhos:** Se um método de autenticação estiver configurado, o campo **Chave** é preenchido automaticamente de acordo com o tipo de autenticação:
  * Se **API Key** estiver habilitado, o header será `apiKey`.
  * Se **Token JWT** estiver habilitado, o header será `Authorization`.
  * Se **External JWT** estiver habilitado, o header será `externalJWT`.

Você deve informar manualmente o **Valor** correspondente.

Consulte a descrição dos parâmetros abaixo para mais detalhes sobre cada opção de configuração.

| Parâmetro                   | Descrição                                                                                                                                                                                                                                                                             | Tipo de dado      | Suporta DB | Padrão |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------- | ------ |
| **Nome**                    | Identificador deste MCP server.                                                                                                                                                                                                                                                       | String            | ✅          | N/A    |
| **URL do Servidor**         | Endpoint que recebe a requisição.                                                                                                                                                                                                                                                     | String            | ✅          | N/A    |
| **Conta**                   | Conta usada para autenticação. Deve ser configurada em [**Contas**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts). Tipo suportado: **Secret Key**.                                                                                        | Account           | ❌          | N/A    |
| **Conta Personalizada**     | Conta secundária referenciada por Double Braces, por exemplo `{{ account.custom.value }}`.                                                                                                                                                                                            | String            | ❌          | N/A    |
| **Conta de Certificado**    | Conta usada para permitir comunicação HTTPS segura com endpoints externos. Ela deve estar previamente registrada em **Contas**. Tipo compatível: [**Certificate Chain**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts#certificate-chain). | Conta             | ❌          | N/A    |
| **Cabeçalhos**              | Cabeçalhos HTTP incluídos na requisição.                                                                                                                                                                                                                                              | Pares chave-valor | ❌          | N/A    |
| **Parâmetros de Consulta**  | Parâmetros de consulta incluídos na requisição.                                                                                                                                                                                                                                       | Pares chave-valor | ❌          | N/A    |
| **Ferramentas Disponíveis** | <p>Este campo está disponível apenas quando um pipeline MCP é selecionado na aba <strong>MCP Do Registro</strong>.</p><p></p><p>Ele exibe as ferramentas configuradas no pipeline MCP selecionado. Habilite as ferramentas que você deseja disponibilizar para o Agent Component.</p> | Booleano          | ❌          | N/A    |

#### **Recuperação de Conteúdo**

Habilite **Retrieval-Augmented Generation (RAG)** para permitir que o modelo use contexto externo armazenado em um banco vetorial.

**Modelo de Embedding**

Um modelo de embedding converte texto em vetores que representam seu significado. Escolha um provedor e modelo que correspondam à sua arquitetura. Opções suportadas:

<details>

<summary><strong>Local (all-MiniLM-L6-v2)</strong></summary>

| Parâmetro                | Descrição                                                                                                        | Tipo de dado | Suporta DB | Padrão |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------ | ---------- | ------ |
| **Máximo de Resultados** | Número máximo de vetores retornados da busca por similaridade.                                                   | Integer      | ❌          | `N/A`  |
| **Pontuação Mínima**     | Similaridade mínima (0.0 a 1.0) para que um resultado seja considerado relevante. Quanto maior, mais restritivo. | String       | ✅          | `0.7`  |

</details>

<details>

<summary><strong>OpenAI</strong></summary>

| Parâmetro                       | Descrição                                                                          | Tipo de dado | Suporta DB | Padrão |
| ------------------------------- | ---------------------------------------------------------------------------------- | ------------ | ---------- | ------ |
| **Conta de Embedding**          | Conta OpenAI usada para embeddings. Suporta: **Basic**, **Secret Key**.            | Select       | ❌          | N/A    |
| **Nome do Modelo de Embedding** | Nome do modelo, por exemplo `text-embedding-3-large`.                              | String       | ✅          | N/A    |
| **Dimensão do Vetor**           | Número de dimensões do embedding. Deve corresponder ao banco vetorial.             | Integer      | ❌          | N/A    |
| **Máximo de Resultados**        | Número máximo de vetores similares retornados.                                     | Integer      | ❌          | N/A    |
| **Pontuação Mínima**            | Similaridade mínima para considerar um resultado. Valores altos = mais restritivo. | String       | ✅          | `0.7`  |

</details>

<details>

<summary><strong>Hugging Face</strong></summary>

| Parâmetro                       | Descrição                                                                                                | Tipo de dado | Suporta DB | Padrão |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------ | ---------- | ------ |
| **Conta de Embedding**          | Credenciais Hugging Face. Suporta: **Basic**, **Google Key**.                                            | Select       | ❌          | N/A    |
| **Nome do Modelo de Embedding** | Nome do modelo, ex.: `sentence-transformers/all-mpnet-base-v2`.                                          | String       | ✅          | N/A    |
| **Dimensão do Vetor**           | Dimensão do vetor gerado. Deve corresponder ao seu store.                                                | Integer      | ❌          | N/A    |
| **Aguardar Modelo**             | Se o sistema deve aguardar o carregamento do modelo (`true`) ou retornar erro se indisponível (`false`). | Boolean      | ❌          | `true` |
| **Máximo de Resultados**        | Máximo de vetores retornados.                                                                            | Integer      | ❌          | N/A    |
| **Pontuação Mínima**            | Similaridade mínima para considerar relevância.                                                          | String       | ✅          | `0.7`  |

</details>

**Armazenamento Vetorial**

Um armazenamento vetorial é um banco otimizado para armazenar e recuperar embeddings. Você pode conectar:

<details>

<summary><strong>PostgreSQL (PGVector)</strong></summary>

| Parâmetro                           | Descrição                                       | Tipo de dado | Suporta DB | Padrão       |
| ----------------------------------- | ----------------------------------------------- | ------------ | ---------- | ------------ |
| **Host**                            | Hostname ou IP do servidor PostgreSQL.          | String       | ✅          | `localhost`  |
| **Porta**                           | Porta de conexão.                               | Number       | ❌          | `5432`       |
| **Nome do Banco de Dados**          | Nome do banco com a tabela vetorial.            | String       | ✅          | N/A          |
| **Conta do Armazenamento Vetorial** | Conta com credenciais de acesso.                | Select       | ❌          | N/A          |
| **Nome da Tabela**                  | Nome da tabela onde embeddings são armazenados. | String       | ✅          | `embeddings` |

</details>

<details>

<summary><strong>Neo4j</strong></summary>

| Parâmetro                           | Descrição                                      | Tipo de dado | Suporta DB | Padrão      |
| ----------------------------------- | ---------------------------------------------- | ------------ | ---------- | ----------- |
| **Nome do Banco de Dados**          | Nome do banco Neo4j usado.                     | String       | ✅          | N/A         |
| **Conta do Armazenamento Vetorial** | Credenciais de conexão.                        | Select       | ❌          | N/A         |
| **Nome do Índice**                  | Índice que contém os vetores.                  | String       | ✅          | N/A         |
| **URI**                             | URI para conexão.                              | String       | ✅          | N/A         |
| **Rótulo do Nó**                    | Label dos nodes que armazenam embeddings.      | String       | ✅          | `Document`  |
| **Propriedade de Embedding**        | Propriedade com o vetor.                       | String       | ✅          | `embedding` |
| **Propriedade de Texto**            | Propriedade com o texto ou documento original. | String       | ✅          | `text`      |

</details>
{% endstep %}

{% step %}

### Adicione arquivos

Para incluir documentos externos (PDFs, imagens, etc.) como contexto:

1. Faça upload usando um storage connector (ex.: **S3**, **Azure Blob**, **Digibee Storage**).
2. Clique no **botão (+).**
3. Insira o nome do arquivo (ex.: `bankslip_1.pdf`) ou use Double Braces.

O conteúdo será injetado no prompt como contexto adicional.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FnllxMFAa92pzDb0IHVRD%2F%5Bpt%5D%20add-files.gif?alt=media&#x26;token=ef7011b7-dc6f-4cd1-add0-53e58b0e8800" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Configure guardrails

Use guardrails quando suas entradas podem conter dados sensíveis (como PII) ou quando você deve controlar estritamente o que é enviado ao LLM.

1. Clique no **ícone de engrenagem (⚙)** ao lado de **Guardrails**.
2. Marque as validações desejadas ou use **Selecionar Tudo**.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2F8wdulZKTC1oupmhtXkAK%2F%5Bpt%5D%20setup-guardrails.gif?alt=media&#x26;token=7713ce43-601d-448a-89e8-375f344f29b7" alt=""><figcaption></figcaption></figure>

| Parâmetro                           | Descrição                                                                                                                                                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mask on detection**               | Mascara as PIIs detectadas antes de enviar a entrada para o LLM. Se desativado, a execução é interrompida e um erro é retornado.                                                                                    |
| **CNPJ detection**                  | Detecta padrões de CNPJ (Cadastro Nacional da Pessoa Jurídica) na **Mensagem de Usuário**, como `00.000.000/0000-00`. Não valida a lógica numérica.                                                                 |
| **Credit Card detection**           | Detecta padrões de números de cartão de crédito na **Mensagem de Usuário**, variando de 13 a 19 dígitos. Não realiza validação de checksum (Luhn).                                                                  |
| **IP detection**                    | Detecta padrões de endereços IPv4 e IPv6 na **Mensagem de Usuário**. Não valida rede nem faixa de IP.                                                                                                               |
| **Datetime detection**              | Detecta padrões de data/hora na **Mensagem de Usuário**, como `2025-11-05`, `05/11/2025` ou `Nov 5, 2025`. Não valida a lógica da data/hora.                                                                        |
| **IBAN code detection**             | Detecta padrões de IBAN (International Bank Account Number) na **Mensagem de Usuário**, como `GB82WEST12345698765432`. Não realiza validação de checksum.                                                           |
| **CPF detection**                   | Detecta padrões de CPF (Cadastro de Pessoa Física) na **Mensagem de Usuário**, como `000.000.000-00`. Não valida a lógica numérica.                                                                                 |
| **Email detection**                 | Detecta endereços de e-mail na **Mensagem de Usuário**, como `user@example.com`. Não valida o domínio nem a existência do endereço.                                                                                 |
| **Crypto Wallet Address detection** | Detecta padrões de endereços de carteiras de criptomoedas na **Mensagem de Usuário**, como endereços Bitcoin que começam com `1` e contêm de 26 a 35 caracteres base58. Não valida checksum nem tipo de blockchain. |
| **Phone number detection**          | Detecta padrões de números de telefone na **Mensagem de Usuário**, como `(11) 99999-9999` ou `+55 11 99999-9999`. Não valida operadora nem região.                                                                  |
| **URL detection**                   | Detecta padrões de URL na **Mensagem de Usuário**, como `http://example.com` ou `https://www.example.org/path`. Não verifica a validade do link.                                                                    |

Na mesma página, você também pode:

* Ativar a **validação por Esquema JSON** para as respostas. A saída é validada com base no esquema fornecido. Se for inválida, o Agent envia uma nova solicitação pedindo o formato correto. Se o modelo ainda retornar uma resposta inválida, a execução é encerrada com um erro.
* Definir **padrões regex personalizados** para validar a entrada. Forneça o **Nome do Padrão** e o **Padrão Regex**.
  {% endstep %}
  {% endstepper %}

## **Testando seu Agent**

Use o Painel de Testes no lado direito da página para validar sua configuração antes de executar o pipeline completo.

Para obter orientações detalhadas sobre como realizar testes no Agent Component e explorar todos os detalhes técnicos disponíveis, consulte a documentação [**Construindo testes no Agent: Datasets, Casos de Teste e Avaliações**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm/testing-your-agent).

{% hint style="warning" %}
Cada **teste bem-sucedido** consumirá tokens, e a quantidade utilizada é exibida na saída. Se você quiser testar o pipeline inteiro com uma resposta específica do Agent Component, poderá [**simular essa resposta (mock)**](#configure-uma-resposta-mock) durante a execução do pipeline para evitar custos de uso de IA.
{% endhint %}

## **Versionando o componente**

O Agent Component oferece suporte **opcional a versionamento**. Você pode aplicar o Agent diretamente ao pipeline ou salvar versões para acompanhar e reutilizar diferentes configurações ao longo do tempo.

{% hint style="info" %}
Você pode começar a versionar o componente apenas após salvar o pipeline.
{% endhint %}

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FODipnlLcJpuPEIqVRYI4%2FAgent%20Component%20-%20Versionamento.gif?alt=media&#x26;token=6b3806ba-998c-4a08-90b9-ffd40af481e4" alt=""><figcaption></figcaption></figure>

### **Sem versionamento**

Por padrão, o componente é aberto no modo **Rascunho**. Se você optar por não usar versionamento, configure o componente e clique em **Confirmar**, no canto superior direito, para aplicar a configuração diretamente ao pipeline.

Apenas a configuração atual é armazenada, e nenhum histórico de versões é criado.

### **Com versionamento**

O versionamento permite salvar, organizar e reutilizar diferentes configurações do Agent Component.

Para criar ou gerenciar versões:

1. Após fazer alterações no componente, clique em **Salvar** ao lado do indicador **Rascunho**, no canto superior esquerdo, e selecione **Criar nova versão**.
2. No modal, selecione **Criar nova versão** ou **Atualizar versão existente**, dependendo de já existirem versões.
3. Opcionalmente, adicione tags para ajudar a identificar a versão, como o nome do modelo (por exemplo, *OpenAI – gpt-4o*).
4. Clique em **Salvar**.

Cada versão salva recebe um número de versão, como v1, além das tags definidas. Depois de criadas, as versões não podem ser excluídas.

Para aplicar uma versão salva ao pipeline, clique em **Confirmar**. A versão atualmente aplicada é marcada com a tag **No pipe**.

#### **Salvando e aplicando alterações em uma versão**

Após atualizar a configuração do componente, você pode escolher como prosseguir:

* **Salvar (canto superior esquerdo):** Salva as alterações em uma versão e mantém o componente aberto para edições adicionais.
* **Salvar e Confirmar (canto superior direito):** Salva as alterações em uma versão e a aplica imediatamente ao pipeline.

Você pode acessar qualquer versão criada a qualquer momento pelo canto superior esquerdo para carregar, revisar ou comparar versões anteriores.

#### **Fazendo o deploy de uma versão**

Ao fazer o deploy de um pipeline que inclui um Agent Component com versões, o deploy usa automaticamente a versão atualmente aplicada ao pipeline.

{% hint style="success" %}
**Dica:** Para confirmar qual versão está aplicada, abra o componente e verifique qual versão está marcada com a tag **No pipe**.
{% endhint %}

Depois que uma versão é implantada, ela não pode mais ser alterada e recebe a tag **Bloqueado**. As outras versões que não foram implantadas permanecem editáveis e podem ser atualizadas normalmente.

## **Configurando ajustes gerais**

Esses parâmetros influenciam como o componente se comporta dentro do seu pipeline, e não como o LLM opera.

Eles podem ser acessados na aba **Configurações**.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2Fix4LOowezz5FnHOX0JaK%2F%5Bpt%5D%20general-settings.gif?alt=media&#x26;token=e40b3749-6e72-4cc7-9f24-d07e8d1422cc" alt=""><figcaption></figcaption></figure>

### **Configure o passo**

* **Nome do Passo:** O nome exibido no seu pipeline.
* **Alias:** Um alias que você pode usar para referenciar a saída deste conector mais tarde usando Double Braces. [Saiba mais](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/how-to-reference-data-using-double-braces/previous-steps-access).

### **Configure uma resposta mock**

Crie uma mock response para testar seu pipeline sem enviar solicitações reais para um LLM.

Isso é útil quando você deseja:

* Testes determinísticos
* Evitar custos de uso

Mocks substituem chamadas reais ao modelo durante a execução do pipeline.

**Etapas para criar um mock:**

1. Clique em **Criar resposta mock**.
2. Defina um **Nome**.
3. Insira o JSON da resposta mock no campo **Resposta JSON**.
4. Ative **Definir como ativo** para usar esse mock nos testes.
5. Clique em **Criar Resposta Mock** para salvar.

### **Configure o tratamento de erros**

Ative **Falhar em Erro** se quiser que o pipeline pare em caso de falha. Caso contrário, o conector continua e retorna `{ "success": false }` dentro da saída.

## **Documentando o uso do Agent Component**

Use a aba **Documentação** para registrar:

* Casos de uso
* Regras de negócio
* Entradas necessárias
* Exemplos de saída

Tudo pode ser formatado em Markdown.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2FT9nifBja7zhOkjRjK4CU%2F%5Bpt%5D%20documentation.gif?alt=media&#x26;token=e25708cc-5d9b-4c83-842c-1511ec73f886" alt=""><figcaption></figcaption></figure>

## **Perguntas frequentes**

<details>

<summary><strong>Como posso testar e experimentar meus prompts?</strong></summary>

Use o **painel de testes** localizado no lado direito do formulário de configuração do conector. Para orientações detalhadas, consulte o tópico [**Testando seu Agent**](#testando-seu-agent).

</details>

<details>

<summary><strong>Posso usar dados de conectores anteriores?</strong></summary>

Sim. Você pode usar [expressões Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview) para referenciar dados de conectores anteriores e incluí-los no seu prompt.

</details>

<details>

<summary><strong>Como os dados sensíveis são tratados?</strong></summary>

O conector não redige nem filtra os dados do payload. Recomendamos seguir as mesmas práticas de tratamento de dados usadas com outros conectores.

</details>

<details>

<summary><strong>Posso encadear várias chamadas LLM em um único pipeline?</strong></summary>

Sim. Você pode usar a saída de uma chamada LLM como entrada para outra. Por exemplo, primeiro classificar um ticket de suporte, depois gerar uma resposta com base na classificação.

</details>

<details>

<summary><strong>E se o conector gerar resultados imprecisos ou inventados?</strong></summary>

Para tarefas críticas, reduza o risco de **alucinações** seguindo estas melhores práticas:

* Configure parâmetros como **Temperature**, **Top K**, **Top P**, **Frequency Penalty** e **Presence Penalty**.
* Divida os processos em etapas menores, por exemplo, gere primeiro e verifique depois. Essa abordagem oferece melhor controle e permite validar os resultados antes de utilizá-los.
* Crie prompts mais eficazes aplicando [técnicas de prompt engineering](https://www.promptingguide.ai/).

</details>

<details>

<summary><strong>O que acontece se o provedor demorar muito para responder?</strong></summary>

Se o provedor demorar muito para responder, a solicitação será encerrada por tempo excedido e uma mensagem de erro será exibida no Painel de Execução.

</details>
