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é sempretrue. 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.