Saltar al contenido principal

Ejecutar una evaluación mediante la API

Inicia una evaluación para uno de tus miembros desde tu propio backend y conduce la conversación en tu propia interfaz.

Usa esta API para conducir la conversación en tu propia interfaz (una app móvil nativa, una herramienta de escritorio, un proceso de backend o cualquier superficie en la que tú muestres la conversación y seas dueño de cada turno). Claire, el agente de IA, sigue haciendo las preguntas y puntuando las evidencias; tú transportas los mensajes.

¿Prefieres que Wiselook muestre la conversación en tu propio sitio web? Entonces integra el widget: Wiselook se encarga del streaming y de la sesión, y tu backend solo emite sesiones de visitante.

Obtener el consentimiento te corresponde a ti. Eres el responsable del tratamiento de los datos de tus miembros. Iniciar una evaluación no avisa a nadie, así que asegúrate de que la persona ha dado su conformidad antes de empezar.

Requisitos previos​

  • Un cliente API con el permiso evaluations:write, más evaluations:read para consultar el resultado.
  • Un bearer token emitido desde ese cliente, como se describe en Autenticación. Los ejemplos siguientes suponen que está en $TOKEN.
  • Un miembro al que evaluar. Este flujo evalúa a personas que ya están en tu lista de Miembros, y nunca las crea. Para añadir a alguien primero, consulta Invitar miembros en bloque.
  • Una de las metodologías adoptadas por tu organización (tenant).

1. Encuentra al miembro​

Cada evaluación nombra a la persona a la que corresponde. Usa el id del miembro, tal como lo devuelve la API de Miembros:

curl "https://$WISELOOK_HOST/v1/tenant-users?email=maria@example.com" \
  -H "Authorization: Bearer $TOKEN"

Leer miembros requiere el permiso tenant_users:read. Consulta Gestionar miembros mediante la API.

2. Inicia la evaluación​

curl -X POST "https://$WISELOOK_HOST/v1/members/$TENANT_USER_ID/evaluations" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"methodology_id": "<ADOPTED_METHODOLOGY_UUID>"}'
{
  "id": "7c1e9a04-…",
  "tenant_user_id": "3f8b2d61-…",
  "methodology_id": "009f91ce-…",
  "status": "in_progress",
  "locale": "en-US",
  "channel": "text",
  "created_at": "2026-09-18T09:14:22Z"
}

Guarda el id. Es el evaluation_id que usan todas las llamadas posteriores. La fila devuelve el miembro como tenant_user_id: el mismo id que pasaste en la ruta, con el nombre del campo que ocupa en la evaluación.

CampoObligatorioNotas
methodology_idsíDebe ser una que tu organización haya adoptado
localenoPor defecto, el idioma preferido del miembro y, si no, el predeterminado de la metodología
channelnotext (por defecto) o voice. Queda fijado en cuanto empieza la evaluación

El idioma y el canal no se pueden cambiar después.

Rechazos habituales:

EstadoSignificado
400La persona no es un miembro evaluable de tu organización. Los miembros eliminados y los ids desconocidos responden igual
403Al token le falta evaluations:write
409Se ha agotado tu saldo de evaluaciones
422Tu organización no ha adoptado la metodología, o un campo no es válido

3. Conduce la conversación​

Envía cada turno de la persona al endpoint de chat. La respuesta llega en streaming como server-sent events:

curl -N -X POST \
  "https://$WISELOOK_HOST/v1/members/$TENANT_USER_ID/evaluations/$EVALUATION_ID/chat/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content": "Hello"}'

Qué se recibe​

La respuesta es text/event-stream. Cada evento es una línea SSE event: y una línea data: con JSON. El JSON repite el nombre del evento en un campo type, así que puedes ramificar según cualquiera de los dos:

event: message_start
data: {"type": "message_start", "message_id": "m_resp_7c1e9a04_1", "role": "assistant"}

event: message_delta
data: {"type": "message_delta", "message_id": "m_resp_7c1e9a04_1", "content_delta": "Got "}

event: message_delta
data: {"type": "message_delta", "message_id": "m_resp_7c1e9a04_1", "content_delta": "it. "}

event: message_delta
data: {"type": "message_delta", "message_id": "m_resp_7c1e9a04_1", "content_delta": "Tell me about a deadline you missed. "}

event: message_complete
data: {"type": "message_complete", "message_id": "m_resp_7c1e9a04_1", "content": "Got it. Tell me about a deadline you missed. "}

event: progress_update
data: {"type": "progress_update", "current_eco_id": "3f2a7b18-…", "progress_percent": 25}

event: stream_end
data: {"type": "stream_end", "reason": "complete"}

Son eventos semánticos, nunca tokens en bruto del modelo.

EventoCamposQué hacer con él
message_startmessage_id, roleEmpieza una respuesta
message_deltamessage_id, content_deltaAñade el fragmento a lo que estás mostrando
message_completemessage_id, contentLa respuesta completa, ya ensamblada. Úsala para verificar lo que has mostrado
progress_updateprogress_percent, current_eco_idActualiza cualquier indicador de progreso
assessment_completeevaluation_id, statusLa conversación ha terminado. Deja de enviar turnos
stream_endreasonEl stream de este turno se ha cerrado

Cada turno termina con stream_end. En el último turno, y solo entonces, assessment_complete llega justo antes.

Gestionar el bucle​

Una petición por turno. Lee el stream hasta el final, muestra la respuesta, recoge la respuesta de la persona y envía el siguiente turno. Sigue hasta que veas assessment_complete.

import json, requests

BASE = f"https://{WISELOOK_HOST}/v1/members/{tenant_user_id}/evaluations/{evaluation_id}"
HEADERS = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}


def send_turn(text: str) -> tuple[str, bool]:
    """Send one turn. Returns the assistant's reply and whether we are done."""
    reply, done = "", False
    with requests.post(
        f"{BASE}/chat/messages", headers=HEADERS, json={"content": text}, stream=True
    ) as r:
        r.raise_for_status()
        for line in r.iter_lines(decode_unicode=True):
            if not line or not line.startswith("data: "):
                continue  # the `event:` line repeats what `type` already tells us
            event = json.loads(line[len("data: "):])

            if event["type"] == "message_delta":
                reply += event["content_delta"]
                print(event["content_delta"], end="", flush=True)
            elif event["type"] == "assessment_complete":
                done = True
            elif event["type"] == "error":
                raise RuntimeError(event["message"])
    return reply, done


done = False
answer = "Hello"
while not done:
    _, done = send_turn(answer)
    if not done:
        answer = input("\n> ")

Tres cosas con las que este ejemplo tiene cuidado, porque es fácil equivocarse:

  • Lee hasta el final del stream antes de enviar el siguiente turno. Un turno termina cuando su stream se cierra, no cuando deja de llegar texto.
  • Un error llega dentro de un stream sano. El estado HTTP ya es 200 cuando empiezan a fluir los eventos, así que un fallo a mitad de turno llega como un evento error seguido de stream_end con reason igual a error. Gestiona el evento; no te fíes solo del código de estado. La carga de error lleva code, message y retryable, para que puedas distinguir un fallo transitorio de uno que merece la pena mostrar.
  • Acumula tú los deltas. message_complete lleva el texto completo, así que puedes usarlo para comprobar lo que has ensamblado, o simplemente mostrarlo si no quieres hacer streaming.

El endpoint de conversación está anidado bajo la evaluación a propósito. La evaluación a la que pertenece forma parte de la dirección, así que nunca se puede enviar un turno a la conversación de otra persona por error.

4. Lee el resultado​

Tras assessment_complete, la puntuación se calcula en segundo plano. La evaluación pasa a completed cuando el informe está listo. Consúltala periódicamente:

curl "https://$WISELOOK_HOST/v1/members/$TENANT_USER_ID/evaluations/$EVALUATION_ID" \
  -H "Authorization: Bearer $TOKEN"

Leer requiere el permiso evaluations:read, distinto del evaluations:write que inicia una evaluación. Un cliente que solo consulta resultados no debería poder iniciarlos también. Concede ambos a un mismo cliente si hace las dos cosas.

Las puntuaciones y los campos del informe siguen en null hasta que el estado es completed.

Qué puedes y qué no puedes hacer​

  • No puedes evaluar a un miembro eliminado. Los miembros invitados, que todavía no han iniciado sesión, sí se pueden evaluar.
  • Una evaluación pertenece a la organización que la creó. Un token de otra organización no puede leerla ni enviarle turnos.
  • Aquí miembros, en el widget visitantes. Un miembro está en tu lista de Miembros con un rol, un estado y etiquetas. Un visitante del widget se identifica por la cadena que tu backend pasa al emitir la sesión, y es un registro aparte incluso cuando esa cadena nombra a alguien que también es miembro. Elige la vía que corresponde a quién estás evaluando.

Consulta también​