Ferramentas: o agente chama os seus endpoints HTTP

Tudo o que o agente faz para além de falar passa por ferramentas: ler uma agenda, marcar, verificar uma encomenda, abrir um ticket. Uma ferramenta é um endpoint GET ou POST do seu lado, descrito para o modelo com um esquema JSON. O modelo decide quando o chamar e com que argumentos; a plataforma executa o pedido.

Definir uma ferramenta

Uma ferramenta tem um nome, uma descrição escrita para o modelo, um esquema JSON dos seus argumentos e a parte de execução: URL, método, cabeçalhos e um modelo de corpo opcional. Escreva marcadores {{nome}} no URL, nos valores dos cabeçalhos ou no corpo; cada marcador tem de ser declarado no esquema com uma descrição. O modelo preenche-o a partir da conversa e a execução substitui-o, codificado no URL e com escape num corpo JSON.

{
  "name": "book_appointment",
  "description": "Marca uma consulta. Chamar só depois de quem liga confirmar dia, hora e nome.",
  "method": "POST",
  "url": "https://api.example.ch/clinics/{{clinic}}/appointments",
  "headers": { "Authorization": "Bearer sk_…" },
  "body": "{ \"start\": \"{{start}}\", \"name\": \"{{name}}\", \"phone\": \"{{phone}}\" }",
  "schema": { "type": "object", "properties": {
    "clinic": { "type": "string", "description": "Código da clínica: sempre 'zurich'" },
    "start":  { "type": "string", "description": "Início, yyyy-MM-dd HH:mm" },
    "name":   { "type": "string", "description": "Nome e apelido de quem liga" },
    "phone":  { "type": "string", "description": "Telefone de quem liga, só dígitos" }
  }, "required": ["clinic", "start", "name", "phone"] }
}

O que o seu endpoint recebe e deve responder

Cada pedido leva um cabeçalho token com o token de ferramentas do agente: verifique-o primeiro. Responda 200 com um corpo JSON. Em caso de sucesso, { "success": true, "message": "…" } mais quaisquer dados: a mensagem destina-se a ser transmitida a quem liga. Num erro de negócio, { "success": false, "error": "…" } com o erro escrito como uma frase para o modelo, por exemplo o que propor em alternativa. Em 401 ou 500 o agente pede desculpa e propõe um retorno de chamada. Mantenha as respostas abaixo de alguns segundos: quem liga está à espera em linha.

app.post('/clinics/:clinic/appointments', express.json(), async (req, res) => {
  if (req.get('token') !== process.env.SWISSAI_TOOL_TOKEN) return res.status(401).end();
  const { start, name, phone } = req.body;
  if (!(await isFree(req.params.clinic, start)))
    return res.json({ success: false, error: 'Essa hora está ocupada. Propõe as 11:00 ou as 14:30 do mesmo dia.' });
  await book(req.params.clinic, start, name, phone);
  res.json({ success: true, message: 'Consulta marcada para ' + start + '.' });
});

Uma só lista de ferramentas, partilhada pelos agentes

As ferramentas vivem na secção Ferramentas do painel e os agentes usam-nas por referência: edita uma ferramenta uma vez e todos os agentes que a usam ficam atualizados. Uma ferramenta atribuída a um cliente só pode ser usada pelos agentes desse cliente. Antes de guardar, o painel verifica a definição com o Claude e constrói o esquema a partir dos marcadores.

Experimentar sem alojar nada

A sandbox é um conjunto de endpoints de exemplo a funcionar, com dados de teste separados para cada conta: agenda, mesas de restaurante, stock, retornos de chamada, contactos, encomendas. As suas 22 ferramentas já estão na secção Ferramentas; cada uma tem um guia com os parâmetros, um exemplo completo de pedido e resposta e o código do endpoint, que pode descarregar e usar como base.

Páginas relacionadas

• Marcações por telefone, tratadas por um agente IA
• Um URI SIP para cada agente de voz
• Um botão de chamada no seu site, atendido pelo agente