# GLM-5.2 mediante Z.ai API — alcance de la primera integración

## Disponible en código

- Proveedor **Z.ai · GLM-5.2** en Conectores. API estándar, modelo exacto `glm-5.2`; no Coding Plan y sin sustitución automática de modelo.
- Credencial cifrada por empresa; el Gateway sólo usa la clave del conector del tenant autenticado. No hay clave de respaldo global. La variable privada de provisionamiento no se consume en peticiones de usuarios.
- Endpoint estándar configurado por servidor, no editable para este proveedor. El código bloquea el envío de la credencial a otros endpoints aunque se altere el destino almacenado.
- Texto, herramientas de tipo función e historial entre turnos. El conector **no ejecuta** las herramientas ni concede acceso a terminal, correo o bases de datos.
- Retención completa antes de entregar JSON/SSE. Se mantienen los límites del Gateway de **2 MB de salida retenida y 120 s de lectura del cuerpo**.
- Entrada y salida limitadas por políticas. Para Z.ai el máximo de salida admitido por esta integración es **8192 tokens**, por defecto 1024; no equivale al máximo nativo anunciado por el proveedor.
- `thinking` permite `enabled`/`disabled`, con `clear_thinking:false` para conservar historial. `reasoning_effort` high/max, por defecto high. Se reenvían los bloques recibidos sin reordenarlos ni modificarlos.
- `tool_choice:auto`, herramientas secuenciales; `json_object` y texto. Formatos no soportados se rechazan localmente, sin llamar al proveedor.

## Privacidad y limitaciones de historial

La tokenización habitual procesa contenido de mensajes. El historial `reasoning_content`, argumentos, IDs y definiciones de herramientas **no se reescriben** para no alterar el protocolo: si los patrones detectan PII en esos campos, se rechaza la petición con `ZAI_PROTOCOL_PII_REJECTED`. Esto puede impedir continuar un historial que contenga datos personales; minimícelo antes de enviar. Los detectores no reconocen toda PII ni todos los ataques.

Un Gateway alojado recibe el texto antes de tokenizarlo. El origen del modelo no acredita residencia de datos. La jurisdicción del procesador queda **sin declarar** hasta que el administrador la verifique conforme a su contrato. Revisar tratamiento, retención y restricciones del proveedor antes de enviar datos sensibles.

## Uso

1. Abrir **Conectores** y elegir **Z.ai · GLM-5.2**. Registrar la clave de la API estándar correspondiente a su empresa. No pegarla en prompts, capturas ni reportes.
2. Pulsar **Probar** y confirmar el consumo. La prueba hace una inferencia sintética con thinking desactivado y máximo 128 tokens. No depende de un endpoint de catálogo `/models`.
3. Una prueba exitosa acredita conexión e inferencia básica, no ejecución de tareas ni todas las capacidades del modelo. Se registra fecha, código de resultado y uso reportado.
4. Usar el Gateway existente con una API key de IA Gobernanza (`gateway:invoke`) y el nombre del conector como `model`. Nunca usar la clave del proveedor en el navegador.
5. Para herramientas, enviar el mensaje assistant completo de la respuesta anterior, seguido por el resultado de cada herramienta con su `tool_call_id`. El ejecutor externo debe validar permisos/HITL antes de actuar.

El conector inicialmente provisionado queda deshabilitado hasta una prueba real exitosa. Si falla por autenticación, saldo o acceso a GLM-5.2, corregir la cuenta/clave y volver a probar. **No se sustituye el proveedor por un MOCK para simular éxito**.

## Errores seguros

- `ZAI_AUTH_FAILED`: credencial rechazada; sin reintentos automáticos.
- `ZAI_BALANCE_REQUIRED`: saldo/paquete requerido por Z.ai; sin reintentos automáticos.
- `ZAI_RATE_LIMITED`: límite de solicitudes; esperar antes de un nuevo intento explícito.
- `ZAI_MODEL_UNAVAILABLE`: cuenta o endpoint sin disponibilidad del modelo exacto.
- Errores locales de parámetros/PII no se envían al proveedor. No se devuelve el cuerpo crudo de sus errores.

## Estado de verificación

**Integración real verificada con Z.ai**, dentro del alcance siguiente. Última prueba de interfaz con API real: **2026-09-16T19:43:52.017Z**. El conector de la empresa propietaria permanece activo; su credencial sigue cifrada y no se publica.

| Prueba | Resultado y procedencia |
|---|---|
| Credencial y modelo exacto | Inferencia básica real `glm-5.2`, sin sustitución de modelo |
| Chat JSON y SSE diferido | Respuestas reales a través del Gateway, sin desactivar la auditoría previa |
| Herramientas e historial | El modelo propuso una función; recibió un resultado **SIMULADO de prueba** y continuó. La inferencia fue real; no se ejecutó una herramienta externa |
| Parámetros, límites y errores | 16 comprobaciones backend aprobadas en el conjunto ejecutado; los errores 401/429/saldo se probaron con respuestas locales **SIMULADAS**, sin enviar claves incorrectas al proveedor |
| Hero | 6 comprobaciones de interfaz aprobadas, incluidos mensajes de alcance y enlaces |
| Edición y prueba desde interfaz | 17 comprobaciones aprobadas: endpoint/modelo fijos, clave no recuperable en el formulario, cambio de proveedor sin nueva clave rechazado con 422 y sin mutar el conector; cancelar sin llamada y confirmar una prueba real con HTTP 200 |

**Consumo de esta revisión:** 6 llamadas reales, 319 tokens de entrada y 122 de salida reportados. Estimación conservadora sin descuento de caché: **US$0.0009834 (aproximadamente US$0.001)**, frente a US$1 autorizado. Es una estimación basada en uso reportado y tarifa consultada, no una factura del proveedor. Las credenciales y conectores QA temporales se retiran al cierre; no afecta al conector propietario.

No se ha validado residencia de datos, carga/concurrencia productiva ni todas las combinaciones de herramientas, historial sensible o parámetros del modelo. Las pruebas de agente no son aceptación del usuario, pentest ni certificación. Un panel “Conectado” acredita su última prueba básica, no autonomía ni ejecución segura de cualquier tarea.

## Próximas fases, no implementadas en esta entrega

- Consumo de autorizaciones de ejecución de uso único y catálogo de herramientas permitidas.
- Motor interno de agentes acotados (incidentes, borradores, propuestas con aprobación), colas y ejecución aislada.
- Instancia self-hosted y validación de rendimiento/recorrido privado de datos. El usuario decidió continuar sólo con API; no se supone presupuesto ni residencia privada.