HTTP Request Tool

A HTTP Request Tool permite que seu Agente interaja com APIs e serviços externos, estendendo suas capacidades além do ecossistema nativo do Zaia Endless.

Com ela, seu Agente pode buscar dados, criar ou atualizar registros, disparar ações de terceiros ou sincronizar informações com sistemas externos em tempo real.

---

🔹 Como a HTTP Request Tool funciona

1. Você define a Tool com uma descrição clara em linguagem natural explicando quando ela deve ser usada.
2. O Agente lê essa descrição para decidir se e quando a Tool se aplica durante uma conversa.
3. Você define Properties (variáveis) que o Agente precisa coletar (por exemplo, ID, e-mail, data).
4. Se as properties obrigatórias estiverem faltando, o Agente vai pedi-las ao usuário primeiro.
5. Assim que todos os dados necessários estiverem disponíveis, o Agente executa a requisição HTTP usando sua configuração.

Isso garante que cada requisição seja completa, contextual e precisa antes da execução.

---

🔹 Métodos HTTP suportados

A HTTP Request Tool suporta todos os métodos REST padrão:

• GET → Buscar informações
• POST → Criar novos recursos
• PUT → Atualizar recursos existentes
• PATCH → Realizar atualizações parciais
• DELETE → Remover recursos

---

⚙️ Campos de configuração

Ao criar uma HTTP Request Tool, você configura:

• Name
• Description (o que a Tool faz e quando usá-la)
• URL
• Method
• Headers
• Query parameters
• Body
• Properties (variáveis)

Cada property inclui:

• Tipo (string, number, etc.)
• Descrição (usada pelo Agente para perguntar ao usuário corretamente)
• Sinalização de obrigatória / opcional

---

🧩 Property Picker (inserção de variáveis)

Ao editar Headers, Query ou Body, o Zaia Endless oferece um Property Picker.

Em vez de digitar variáveis manualmente ({{variableName}}), você pode:

1. Clicar dentro de qualquer campo (Headers, Query ou Body).
2. Uma lista flutuante aparece mostrando todas as properties definidas.
3. Clicar em uma property para inseri-la automaticamente no formato correto.

💡 Exemplo
Se uma property se chama userId, selecioná-la insere automaticamente:

{{userId}}

Isso elimina erros de sintaxe e agiliza significativamente a configuração.

---

🤖 cURL Import Assistant

O Zaia Endless inclui um Creation Assistant que permite importar uma configuração HTTP completa diretamente de um comando cURL.

Como funciona:

1. Clique no ícone de varinha mágica / assistente ao criar uma HTTP Request Tool.
2. Cole um comando curl completo (ou descreva a requisição).
3. O Assistant automaticamente:
   • Detecta o método HTTP
   • Extrai a URL
   • Analisa os headers
   • Converte os campos do corpo da requisição em Properties
   • Preenche previamente a configuração da Tool

Isso é especialmente útil quando:

• Você já tem exemplos de API vindos de documentação
• Você está migrando integrações existentes
• Você quer evitar erros de configuração manual

💡 Exemplo de cURL

curl -X POST "https://api.example.com/users" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@email.com"}'

O Assistant vai gerar automaticamente:

• URL
• Method: POST
• Headers
• Body
• Properties (name, email)

Você pode então refinar as descrições e os campos obrigatórios antes de salvar.

---

🔹 Exemplo de configuração

Name: Customer API Lookup
Description:
“Permite que o Agente recupere informações de clientes do CRM externo usando um ID de cliente.”

Property:

• id (number) → “ID do cliente fornecido pelo usuário. Deve ser numérico.”

Configuração:

• URL: https://api.crm.com/customers/{{id}}
• Method: GET
• Headers:

{
  "Authorization": "Bearer {{api_key}}"
}

Exemplo de POST Body:

{
  "name": "{{name}}",
  "email": "{{email}}",
  "project_type": "{{project_type}}"
}

Se project_type estiver faltando, o Agente vai pedi-lo ao usuário antes de executar a requisição.

---

🧠 Boas práticas

• Seja explícito nas descrições das properties
  Exemplo: “Data de nascimento no formato YYYY-MM-DD.”
• Mantenha as Tools focadas — uma Tool por ação clara de API.
• Sempre teste as requisições usando o Internal Chat antes de publicar.
• Evite fixar segredos diretamente nas requisições.
• Para APIs complexas, divida as ações em múltiplas Tools.
• Use o Property Picker e o cURL Assistant para reduzir erros.

---

✅ Resumo

A HTTP Request Tool é a ponte entre seu Agente e o mundo externo.

Combinando:

• Descrições claras
• Properties bem definidas
• O Property Picker
• O cURL Import Assistant

Você permite que seus Agentes interajam com qualquer API externa de forma segura, dinâmica e inteligente — pedindo dados que faltam quando necessário e executando apenas quando tudo estiver pronto.