Ações

Obter dados em tempo real durante a chamada

Deixe o agente perguntar ao seu sistema por uma encomenda, um nível de stock ou uma conta enquanto quem liga espera.

Com a Ferramenta de API RAG, o agente pede ao seu sistema dados em tempo real a meio da conversa — o estado de uma encomenda, o stock de um produto, os dados de uma conta — e responde com eles. O agente decide quando a usar com base na sua descrição.

Configurar

1. Adicione a ferramenta

   Abra o agente → Ações → Adicionar ferramenta → CRM e serviços → Ferramenta de API RAG.

2. Descreva-a e aponte-a para o seu endpoint

   Campo	O que introduzir
   Nome	p. ex. Consulta de encomendas
   Condição geral	Quando a usar, p. ex. o cliente pergunta pelo estado de uma encomenda
   URL do endpoint da API	p. ex. https://api.yourshop.com/orders/{order_id} — os {placeholders} são preenchidos com os valores que o agente recolhe
   Método HTTP	GET, POST, PUT, DELETE ou PATCH
   Mensagem de execução	O que o agente diz enquanto espera, p. ex. Um momento, estou a verificar a sua encomenda
   Timeout da requisição (ms)	Quanto tempo esperar pela resposta; 5000 por defeito
   Cabeçalhos, Parâmetros de consulta	Valores fixos opcionais, p. ex. a sua chave API

3. Indique o que o agente tem de recolher

   O Esquema de parâmetros (JSON) lista os valores que o agente recolhe junto de quem liga e envia — consulte mais abaixo. Se faltar um valor obrigatório, o agente pergunta-o primeiro.

dica

Preencha sempre a Mensagem de execução — o silêncio enquanto o pedido decorre parece uma chamada caída.

O esquema de parâmetros

Não é o corpo do pedido em si, mas um JSON Schema dos valores a recolher. Onde vão parar:

Caso	Para onde vai o valor
O URL contém {name}	Para o URL
GET, DELETE	O resto como ?key=value
POST, PUT, PATCH	O resto como corpo JSON

Consulta de uma encomenda pelo número:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "O número da encomenda pela qual o cliente pergunta, normalmente de 6 a 10 dígitos. Pergunta se não for indicado."
    }
  },
  "required": ["order_id"]
}

Uma reserva com vários valores:

{
  "type": "object",
  "properties": {
    "product_id": { "type": "string", "description": "ID do produto de uma pesquisa anterior." },
    "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Quantos. Por defeito 1." },
    "delivery_method": { "type": "string", "enum": ["pickup", "home_delivery", "locker"], "description": "Como o cliente quer receber." },
    "customer_email": { "type": "string", "format": "email", "description": "Email para a confirmação. Pergunta se não for indicado." }
  },
  "required": ["product_id", "delivery_method", "customer_email"]
}

Um endpoint estático, p. ex. o horário: { "type": "object", "properties": {} }.

Bons esquemas para voz:

• Mantenha-o simples e plano: 3 a 5 valores.
• Escreva uma description para cada valor, com exemplos — é o que melhor orienta o agente.
• Use enum para escolhas fixas: o agente converte «o azul» em blue.
• Marque um valor como required apenas quando o pedido não funcionar sem ele.
• Use nomes em snake_case que correspondam aos {placeholders} do URL.

Casos de uso

• Estado da encomenda — «Onde está a minha encomenda 482913?»
• Disponibilidade — verificar o stock ou uma mesa livre no seu próprio sistema.
• Perguntas sobre a conta — saldo, fim do contrato, tickets em aberto.

Problemas comuns

Problema	O que verificar
O agente nunca a usa	Faça com que a Condição geral indique o pedido
O seu endpoint recebe valores vazios	Os nomes no esquema têm de corresponder exatamente aos {placeholders}
O agente diz que não conseguiu verificar	O seu endpoint demorou mais do que o timeout ou respondeu com um erro

Relacionado

• Conhecer quem liga antes de a chamada começar — dados antes da saudação
• Servidores MCP — muitas ferramentas a partir de um só servidor