Documentação

Integração por API

Um único endpoint HTTP conecta qualquer agente de texto à Humaqa — independente do modelo ou framework.

Contrato

A cada turno, a Humaqa envia um POST com o histórico da conversa. Seu endpoint responde com a próxima mensagem do agente. A conversa é sempre conduzida pela Humaqa, então o seu agente não precisa guardar estado (mas pode usar session_id se preferir).

POST https://seu-agente.exemplo.com/humaqa
Content-Type: application/json
Authorization: <valor configurado na Humaqa>   # opcional, nome do header configurável

{
  "session_id": "8f0c2b1e-…",          // estável durante toda a conversa
  "message": "vi mais barato em outro site",  // última mensagem do cliente
  "messages": [                          // histórico completo
    { "role": "user", "content": "oi, quanto custa o sofá?" },
    { "role": "assistant", "content": "O Sofá Lumi custa R$ 3.490." },
    { "role": "user", "content": "vi mais barato em outro site" }
  ],
  "metadata": { "source": "humaqa", "test": true, "kind": "synthetic" }
}
HTTP/1.1 200 OK
Content-Type: application/json

{ "reply": "Entendo! Posso te mostrar as condições à vista…" }

Também aceitamos respostas nos campos output, message, content, text, no formato OpenAI (choices[0].message.content) ou texto puro.

Requisitos

  • HTTPS público. Endereços de rede privada, loopback e metadados de nuvem são bloqueados.
  • Resposta em até 45 segundos por turno. Respostas acima de 20 s geram um alerta de latência.
  • Use um ambiente de teste: o campo metadata.test é sempre true. Bloqueie compras reais, envio de mensagens a terceiros e outras operações sensíveis quando ele estiver presente.
  • Credenciais (token, chave de API) são armazenadas criptografadas e enviadas apenas no header que você configurar.

Anexos (fotos e arquivos)

Em missões com os desafios “enviar foto” ou “enviar arquivo”, a mensagem do participante pode trazer anexos. Eles chegam no campo attachments da mensagem (e no topo do corpo, para a última mensagem), com um link temporário válido por 1 hora. O texto da mensagem também inclui uma linha [Anexo …], para agentes que só leem texto.

"attachments": [
  { "kind": "image", "name": "foto-do-produto.jpg", "mime": "image/jpeg", "url": "https://…(link temporário)" }
]

Exemplos

Node.js (Express)

import express from "express";
const app = express();
app.use(express.json());

app.post("/humaqa", async (req, res) => {
  if (req.get("authorization") !== process.env.HUMAQA_TOKEN) return res.sendStatus(401);
  const { session_id, messages } = req.body;
  const reply = await meuAgente.responder({ sessionId: session_id, history: messages, sandbox: true });
  res.json({ reply });
});

app.listen(3001);

Python (FastAPI)

from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel

app = FastAPI()

class Msg(BaseModel):
    role: str
    content: str

class Body(BaseModel):
    session_id: str
    message: str
    messages: list[Msg]

@app.post("/humaqa")
def humaqa(body: Body, authorization: str = Header(None)):
    if authorization != os.environ["HUMAQA_TOKEN"]:
        raise HTTPException(401)
    return {"reply": meu_agente.responder(body.session_id, body.messages, sandbox=True)}

Versões

Cada alteração de endpoint, regras ou critérios cria uma nova versão do agente. Campanhas apontam para uma versão específica, o que permite comparar resultados entre versões (regressão) mesmo depois de o agente mudar.

Regras de avaliação

  • max_discount: desconto máximo em %. Determinística.
  • handoff_on_request: oferecer atendimento humano quando o cliente pedir. Determinística.
  • no_sensitive_data_request: nunca pedir cartão, CVV, senhas ou códigos. Determinística.
  • forbidden_phrase: lista de frases proibidas. Determinística.
  • no_prompt_leak: não revelar instruções internas. Determinística.
  • custom: regra em linguagem natural, avaliada pelo avaliador automático e sujeita a revisão.
API pública de avaliações e CI/CD
Integração com pipelines de CI/CD está planejada para uma próxima fase. Por enquanto, os testes de regressão são disparados pelo painel.