# Agentes

<figure><img src="/files/u8SCzIL8ktNURnmtfSAE" alt=""><figcaption></figcaption></figure>

A funcionalidade **Agents** é a área central para criação e gerenciamento das capacidades de inteligência artificial dentro do sistema.\
Ela permite construir **chat agents**, estruturas de **RAG (Retrieval-Augmented Generation)** e **tools** que expandem o que os agentes podem saber e fazer.

O principal objetivo desta seção é permitir que você projete o comportamento, o conhecimento e as ações dos agentes de forma estruturada, reutilizável e escalável.

Ao acessar **Agents**, você verá:

* Uma barra lateral esquerda listando todos os agentes criados
* Um campo de busca para localizar agentes rapidamente
* Abas superiores para alternar entre:
  * Agents
  * Tools
  * RAG
* Um botão **( + )** para criar novos recursos

<figure><img src="/files/AKYr8Gv35VZ0qVqnIuNc" alt=""><figcaption></figcaption></figure>

## Como Configurar seu Agent

### Acessando a Área Agents

1. No menu lateral esquerdo, clique no ícone **Agents**
2. Você será direcionado para a tela de criação e gerenciamento de agentes

Essa tela funciona como um painel central onde você pode:

* Criar novos agentes
* Editar agentes existentes
* Gerenciar tools e bases de conhecimento
* Definir como cada agente se comporta dentro do sistema

***

### Criando um Novo Recurso

Clique no botão **( + )** no topo da tela.

Selecione uma das opções disponíveis:

* **New chat agent:** Criar um agente conversacional com personalidade, objetivos e regras definidas
* **New RAG:** Criar uma base de conhecimento contextual para recuperação de informação
* **New tool:** Criar uma ferramenta que execute ações ou integrações

***

## Como Criar um Novo RAG (Retrieval-Augmented Generation)

Antes de tudo, um RAG é uma camada de conhecimento que permite aos agentes recuperar informações de documentos e arquivos e utilizar esse conteúdo para gerar respostas mais precisas, contextuais e confiáveis.

Em vez de depender apenas do conhecimento geral do modelo, o RAG permite que o agente baseie suas respostas nos seus próprios dados.

O RAG foi projetado para:

* Fornecer respostas baseadas em fatos usando documentos internos
* Reduzir alucinações ao fundamentar respostas em conteúdo real
* Permitir que agentes trabalhem com:
  * Arquivos CSV
  * Documentos de texto (PDF, .doc, .txt, .md, .pptx, etc.)
  * Dados estruturados e semi-estruturados (.json, .png, .jpg, .mp3, .mp4, etc.)

{% hint style="danger" %}
Um RAG não atua sozinho. Ele deve ser anexado a um Chat Agent para ser utilizado em conversas.
{% endhint %}

***

### Estrutura da Tela de Configuração do RAG

A tela é dividida em duas áreas principais:

* **Painel esquerdo →** Definição e comportamento do RAG
* **Painel direito →** Seleção e gerenciamento de arquivos

<figure><img src="/files/ToIYh4AiQtWO1ZmdDJfz" alt=""><figcaption></figcaption></figure>

Após abrir o painel:

* Insira um nome claro e descritivo para o RAG
* Descreva o tipo de informação fornecida

Você pode:

* Utilizar o campo de busca para filtrar arquivos pelo nome
* Selecionar um ou mais arquivos da lista

Após a seleção, o conteúdo desses arquivos se torna pesquisável pelo agente.

Para importar arquivos, consulte a seção [**Files Ingest**](https://docs.gaiodataos.com/gaio-dataos-portuguese/~/revisions/2tckaTVQDo0Oojn6ZRqK/tools/tarefas/etl/file-ingest) neste documento.

## Como configurar novas ferramentas

As **Ferramentas** definem quais ações um agente pode executar além da conversa.

Elas expandem as capacidades do agente, permitindo:

* Integrações externas
* Acesso seguro a dados
* Execução controlada de queries
* Manipulação de mídia

Um agente só pode utilizar tools que foram explicitamente criadas e atribuídas a ele.\
Isso garante segurança, previsibilidade e governança.

<figure><img src="/files/ll5Ff2Of1R4IMxiIffrH" alt=""><figcaption></figcaption></figure>

Na tela de **Ferramentas**, você pode criar e gerenciar os seguintes tipos de ferramentas:

| Ferramenta       | Finalidade                                         |
| ---------------- | -------------------------------------------------- |
| HTTP Request     | Chamar APIs e serviços externos                    |
| MCP              | Conectar-se a APIs e serviços baseados em MCP      |
| Verified Queries | Executar consultas SQL pré-aprovadas com segurança |
| Media File       | Selecionar e recuperar arquivos de mídia           |

Cada tipo de ferramenta é projetado para uma classe específica de ação e possui seu próprio modelo de configuração.

***

### Criando uma Nova Ferramenta

1. Acesse a seção **Tools**
2. Clique no card do tipo de ferramenta desejado
3. Configure os parâmetros da ferramenta
4. Clique em **Save** para salvar a configuração

### HTTP Request

Permite que o agente interaja com APIs externas utilizando métodos HTTP padrão.

<figure><img src="/files/MlQtkxD4EXxTJbitLlT8" alt=""><figcaption></figcaption></figure>

#### Casos de uso:

* Buscar dados de serviços terceiros
* Enviar dados para sistemas externos
* Disparar webhooks ou workflows

#### Características:

* Suporte a APIs REST
* Parâmetros definidos explicitamente
* O agente só pode chamar endpoints previamente configurados

***

### MCP

Permite integração com APIs compatíveis com MCP.

<figure><img src="/files/lHFWGujuT0xieVv3jDlc" alt=""><figcaption></figcaption></figure>

#### Casos de uso:

* Acessar serviços internos ou de parceiros expostos via MCP
* Interações padronizadas com APIs
* Acesso controlado a sistemas corporativos

#### Características:

* Acesso estruturado e controlado
* Projetado para integrações empresariais
* Reutilizável entre múltiplos agentes

***

### Verified Queries

Permite que agentes executem consultas SQL previamente aprovadas.

<figure><img src="/files/PumWGTJErfGxeQ4lsODi" alt=""><figcaption></figcaption></figure>

#### Objetivo:

* Evitar execução arbitrária de queries
* Garantir governança de dados
* Assegurar performance e segurança

#### Funcionamento:

* Queries são definidas e validadas previamente
* Apenas essas queries podem ser executadas
* Agentes podem passar parâmetros, mas não alterar a lógica

{% hint style="warning" %}
Agentes não podem escrever ou modificar SQL. Apenas executar queries verificadas.
{% endhint %}

### Media Files

Permite que o agente acesse, referencie e entregue arquivos durante uma conversa.

<figure><img src="/files/seNYIK9S1DOpPaEAelRk" alt=""><figcaption></figcaption></figure>

#### Uso ideal:

* Compartilhar documentos
* Referenciar materiais oficiais
* Fornecer downloads controlados
* Enriquecer respostas com conteúdo visual ou técnico

## Como Criar seu Agent

Após criar as **Tools** e os **RAGs**, o desenvolvedor pode montar um **Chat Agent**.

Essa etapa define:

* Quem é o agente
* Como ele se comporta
* O que ele pode acessar

Um Chat Agent funciona como camada de orquestração, combinando:

* Identidade e propósito
* Regras comportamentais
* Fontes de conhecimento (RAG ou tabelas)
* Diagramas (relacionamentos entre tabelas)
* Capacidades de ação (Tools)

<figure><img src="/files/cP7RCSCALj8gte4WN3Cl" alt=""><figcaption></figcaption></figure>

Na aba **General**, você pode:

* Definir um nome claro e significativo
* Escrever uma descrição resumida do agente
* Definir identidade, tom, capacidades e limites
* Descrever o objetivo principal e critérios de sucesso
* Fornecer contexto, restrições e background do domínio
* Inserir perguntas exemplo para orientar o usuário final

Após definir a identidade do agente, **configure o que ele poderá acessar.**

{% embed url="<https://app.arcade.software/share/XhtOrGQqcMDdUgoQouNO>" %}

{% hint style="info" %}
Para configurações de **Discovery**, consulte a [seção correspondente](https://docs.gaiodataos.com/gaio-dataos-portuguese/~/revisions/pLWMD05SeIC0EJUGtvX2/tools/descoberta).
{% endhint %}

{% hint style="info" %}
Para criação de **Schema**, consulte a [seção específica deste documento.](https://docs.gaiodataos.com/gaio-dataos-portuguese/~/revisions/pLWMD05SeIC0EJUGtvX2/tools/diagramas-schema)
{% endhint %}


---

# 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.gaiodataos.com/gaio-dataos-portuguese/tools/agentes.md?ask=<question>
```

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.