Configuração de Funções de API para Agentes IA

Documentação para criar/editar funções utilizadas pelos agentes de IA para integração com APIs externas. Inclui validação automática e controle de ativação.

1. Estrutura Base da Função

Campos Principais

{
  "name": "nomeDaFuncao",
  "description": "Descrição detalhada",
  "isActive": true,
  "method": "POST",
  "endpoint": "https://api.exemplo.com/recurso",
  "headers": {},
  "body": {},
  "parameters": []
}

Detalhamento dos Campos

name

• Identificador único e descritivo
• Sem espaços ou caracteres especiais
• Ex: “createProduct”, “updateUserStatus”

description

• Propósito e funcionamento da função
• Inclua casos de uso e resultados esperados
• Ex: “Cria produto no catálogo com nome, preço e categoria”

isActive

• Controla disponibilidade da função
• Desativa automaticamente se houver erros
• Default: false

method

• GET: buscar dados
• POST: criar recurso
• PUT: atualizar completo
• PATCH: atualização parcial
• DELETE: remover recurso

endpoint

• URL completa da API
• Aceita placeholders:
• Exemplos:

  https://api.exemplo.com/produtos
  https://api.exemplo.com/usuarios/{{userId}}
  https://api.exemplo.com/busca?q={{query}}&limit={{limit}}
  

headers

{
  "Authorization": "Bearer {{apiKey}}",
  "Content-Type": "application/json",
  "Accept": "application/json"
}

body (POST/PUT/PATCH)

{
  "name": "{{productName}}",
  "price": "{{price}}",
  "metadata": {
    "tags": "{{tags}}"
  }
}

2. Configuração de Parâmetros

Estrutura do Parâmetro

{
  "name": "nomeParametro",
  "type": "string",
  "description": "Descrição do uso",
  "required": true,
  "enum": "valor1,valor2,valor3",
  "minimum": 0,
  "maximum": 100
}

Tipos de Parâmetros

String

{
  "name": "status",
  "type": "string",
  "description": "Status do pedido",
  "required": true,
  "enum": "pending,processing,completed"
}

Número

{
  "name": "price",
  "type": "number",
  "description": "Preço em reais",
  "required": true,
  "minimum": 0.01,
  "maximum": 99999.99
}

Inteiro

{
  "name": "quantity",
  "type": "integer",
  "description": "Quantidade",
  "minimum": 0,
  "maximum": 1000
}

Boolean

{
  "name": "active",
  "type": "boolean",
  "description": "Status de ativação"
}

3. Sistema de Validação

Validações Automáticas

1. JSON

• Headers e body devem ser válidos
• Erros desativam a função

2. Placeholders ()

• Case-sensitive
• Devem ter parâmetro correspondente

3. Parâmetros

• Nomes únicos
• Tipos corretos
• Limites numéricos válidos
• Enums sem valores vazios

Erros e Avisos

• Função desativa se houver:
  • JSON inválido
  • Parâmetros não documentados
  • Violações de tipo
• Erros aparecem em undocumentedParameters

4. Exemplo Completo

{
  "name": "createProduct",
  "description": "Criar novo produto no catálogo",
  "isActive": true,
  "method": "POST",
  "endpoint": "https://api.store.com/v1/products",
  "headers": {
    "Authorization": "Bearer {{apiKey}}",
    "Content-Type": "application/json"
  },
  "body": {
    "name": "{{productName}}",
    "price": "{{price}}",
    "category": "{{category}}"
  },
  "parameters": [
    {
      "name": "apiKey",
      "type": "string",
      "description": "Chave de API",
      "required": true
    },
    {
      "name": "productName",
      "type": "string",
      "description": "Nome do produto",
      "required": true
    },
    {
      "name": "price",
      "type": "number",
      "description": "Preço em reais",
      "required": true,
      "minimum": 0.01
    },
    {
      "name": "category",
      "type": "string",
      "description": "Categoria do produto",
      "required": true,
      "enum": "electronics,clothing,books"
    }
  ]
}