Mensajes

Próxima versión — Zylon 1.58Esta documentación se publica antes del lanzamiento para que puedas preparar tus integraciones de API. La imagen de la versión todavía no está disponible. Para instalaciones con 1.57, consulta la documentación de 1.57.

Messages es el núcleo de ZylonGPT: envías un historial de conversación y Zylon devuelve el siguiente mensaje del asistente como lista de bloques de contenido.

Requisitos previos

Un token de API. Consulta Backoffice Developer Console.
El nombre de host de Zylon (sustituye {BASE_URL} en los ejemplos).

PrivateGPT.Read.All permite POST /messages síncrono, POST /messages/validate y los demás endpoints de la allowlist de solo lectura de ZylonGPT. Read.All permite las mismas llamadas solo cuando el token de cuenta incluye gateway_id; sin contexto de gateway, no puede llamar a ZylonGPT. El acceso efectivo también depende de los permisos de rol del propietario del token.

Solicitud y respuesta básica

Envía un mensaje y recibe una respuesta.

Mensaje único
Bloques de contenido

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 32,
    "temperature": 0,
    "messages": [
      { "role": "user", "content": "Write a one-sentence status update about deploying a billing dashboard and fixing three bugs." }
    ]
  }'

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 32,
    "temperature": 0,
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Write a one-sentence status update about deploying a billing dashboard and fixing three bugs." }
        ]
      }
    ]
  }'

Ejemplo de respuesta

{
  "id": "msg_abf981cf3f1c449eacb7a85c064ca505",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "start_timestamp": "2026-02-06T13:23:16.876744Z",
      "stop_timestamp": "2026-02-06T13:23:16.975362Z",
      "text": "Deployed the new billing dashboard and resolved three bugs successfully."
    }
  ],
  "model": "private-gpt",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 95,
    "output_tokens": 16
  }
}

Formato de mensajes

El mismo cuerpo de mensaje se usa en ZylonGPT y en el campo pgpt de las peticiones de chat/interacción de Workspace. Envía el contenido de la conversación; el modelo o gateway seleccionado determina qué opciones admite. model y max_tokens son opciones que admiten null, no campos obligatorios para todos los modelos. Indicarlos explícitamente hace predecibles la selección de modelo y el límite de salida; valida las peticiones con tu gateway.

Cuerpo de la petición

Campo	Tipo / valor por defecto	Descripción
`messages`	message[]; `[]`	Historial de conversación. Cada mensaje tiene `role` (`user` o `assistant`) y `content` (cadena o array de bloques). Crear una interacción de Workspace requiere exactamente un mensaje de usuario.
`model`	string o null	Nombre del modelo, normalmente `default`; Valida su omisión con el gateway seleccionado.
`max_tokens`	integer o null	Límite de tokens de salida, sujeto a la validación del modelo.
`stream`	boolean; `false`	Messages de ZylonGPT devuelve JSON por defecto y SSE con `true`. Las rutas actuales `/app/chat` y de interacción de Workspace transmiten por streaming independientemente del indicador.
`system`	string, object, object[] o null	Texto y configuración del sistema; campos anidados abajo.
`tools`	object[] o null	Definiciones de herramientas. Consulta Herramientas.
`tool_choice`	object o null	Selección y validación de herramientas, descritas abajo.
`tool_context`	object[] o null	Contexto tipado, como `ingested_artifact` o `sql_database`; consulta la guía de la herramienta correspondiente.
`mcp_servers`	object[] o null	Configuración de servidores MCP. Cada uno requiere `url`; `name` y `tool_configuration` son opcionales.
`thinking`	object o null	`enabled` es `false` por defecto; `type` (string) y `budget_tokens` (integer) son opcionales.
`output_config`	object o null	`effort`: `low`, `medium`, `high` o `max`; `format` opcional, descrito abajo.
`cache_control`	object o null	Si se incluye, requiere `type` de tipo string. Su soporte depende del modelo.
`temperature`, `min_p`, `top_p`	number o null	Opciones de muestreo; los rangos admitidos dependen del modelo.
`top_k`	integer o null	Opción de muestreo.
`repetition_penalty`, `presence_penalty`, `frequency_penalty`	number o null	Opciones de penalización de tokens.
`seed`	integer o null	Semilla de muestreo opcional.
`priority`	integer o null	Prioridad de petición opcional.
`stop_sequences`	string[]; `[]`	Límites personalizados de generación.
`metadata`	object; `{}`	`ws_member_id` es una cadena opcional que admite null. Usa un ID de miembro, no de cuenta. `user_id` sigue siendo un alias de entrada; envía solo un nombre.
`service_tier`	string; `auto`	`auto` o `standard_only`.
`inference_geo`	string o null	Preferencia opcional de ubicación de inferencia.
`container`	string o null	ID opcional de un contenedor existente.
`message_id`, `correlation_id`	string o null	Identificadores opcionales de mensaje y correlación.

Los campos que admiten null pueden omitirse. Una opción que no admite null pero tiene valor por defecto puede omitirse; no envíes null.

Sistema, selección de herramientas y salida estructurada

Objeto	Campo	Tipo / valor por defecto
`system`	`text`	Cadena opcional.
`system`	`citations`	Objeto; `enabled` es `false` por defecto y `known_citations` es un array opcional de citas.
`system`	`blob_visibility`	`binary`, `internal` o `public`, opcional.
`system`	`extensions`	string[] opcional; actualmente admite `zylon`.
`system`	`prompt`	Objeto con booleanos `tools`, `citations`, `thinking`, `code_execution` y `skills`; todos son `false` por defecto.
`tool_choice`	`type`	String; `auto`.
`tool_choice`	`name`	Cadena opcional que identifica una herramienta.
`tool_choice`	`disable_parallel_tool_use`	Boolean; `false`.
`tool_choice`	`validation_mode`	`eager` o `lazy`; `lazy`.
`output_config.format`	`type`	`json_schema` obligatorio.
`output_config.format`	`schema`	Objeto JSON Schema obligatorio.

response_format está obsoleto; usa output_config.format. Mueve thinking.effort a output_config.effort. Sustituye system.use_default_prompt por los indicadores individuales de system.prompt; el indicador antiguo con true activa todas las categorías de prompt.

Campos de respuesta del mensaje

Campo	Tipo	Significado
`id`, `type`, `role`, `model`	string	ID de mensaje, tipo `message`, rol `assistant` y modelo seleccionado.
`created`	integer	Milisegundos desde epoch.
`content`	object[]	Bloques de contenido. Consulta los bloques de herramientas de servidor de 1.58.
`stop_reason`	string o null	`end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` o `refusal`.
`interaction_stop_reason`	string o null	Resultado global de la interacción: `stop`, `error`, `cancelled` o `refusal`.
`stop_details`	object o null	`type` obligatorio; `category` y `explanation` opcionales.
`container`	object o null	`id` obligatorio; `expires_at` opcional de tipo string.
`usage`	object	`input_tokens` y `output_tokens` (por defecto `0`); uso de caché y herramientas opcional, descrito abajo.
`errors`	object[]	Detalles de errores cuando estén disponibles.

usage puede incluir cache_creation_input_tokens, cache_read_input_tokens, inference_geo, service_tier, cache_creation (ephemeral_1m_input_tokens, ephemeral_1h_input_tokens, ephemeral_5m_input_tokens) y server_tool_use (web_fetch_requests, web_search_requests). Los contadores de esos objetos anidados son 0 por defecto. Los campos que admiten null pueden omitirse en la respuesta. No hay un campo stop_sequence en el nivel superior; usa stop_reason: "stop_sequence". Consulta Motivos de parada.

Validar una solicitud

Usa /messages/validate para comprobar la forma del cuerpo de la petición antes de enviar una solicitud real. Devuelve valid: true o una lista de errores de validación.

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 32,
    "messages": [
      { "role": "user", "content": "Validate this payload." }
    ]
  }'

Ejemplo de respuesta:

{ "valid": true, "errors": null }

Conversaciones con varios turnos

Incluye turnos anteriores en messages:

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 16,
    "temperature": 0,
    "messages": [
      { "role": "user", "content": "My name is Ada." },
      { "role": "assistant", "content": "Nice to meet you." },
      { "role": "user", "content": "What is my name? Reply with only the name, no punctuation." }
    ]
  }'

Ejemplo de respuesta

{
  "id": "msg_9b14c8fd514741d29a0dff8996ca9213",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "start_timestamp": "2026-02-06T10:34:12.924887Z",
      "stop_timestamp": "2026-02-06T10:34:12.974785Z",
      "text": "Ada"
    }
  ],
  "model": "private-gpt",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 135, "output_tokens": 2 }
}

Prompts del sistema

Usa el campo system a nivel superior para controlar el comportamiento:

Prefiere el campo system de nivel superior para que las instrucciones se apliquen de forma consistente.

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 8,
    "temperature": 0,
    "system": { "text": "You are a support agent. Reply with only a short ticket title." },
    "messages": [
      { "role": "user", "content": "The login button on mobile does not work." }
    ]
  }'

Ejemplo de respuesta

{
  "id": "msg_4e328dc4baeb42b8a18dc0c4abd89468",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "start_timestamp": "2026-02-06T13:37:36.368426Z",
      "stop_timestamp": "2026-02-06T13:37:36.446733Z",
      "text": "Mobile login button not working"
    }
  ],
  "model": "private-gpt",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 100, "output_tokens": 6 }
}

JSON estructurado (json_schema)

Si necesitas salida legible por máquina, usa output_config.format.type = json_schema e incluye el esquema en output_config.format.schema.

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 128,
    "system": {
      "text": "Return ONLY valid JSON."
    },
    "messages": [
      {
        "role": "user",
        "content": "We deployed the billing dashboard. Return a status and the next step."
      }
    ],
    "output_config": {
      "format": {
        "type": "json_schema",
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "status": {
              "type": "string"
            },
            "next_step": {
              "type": "string"
            }
          },
          "required": [
            "status",
            "next_step"
          ]
        }
      }
    }
  }'

Ejemplo de respuesta

{
  "id": "msg_eaf35004b4654234be5e767ea09e72e6",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "start_timestamp": "2026-02-06T13:39:44.864978Z",
      "stop_timestamp": "2026-02-06T13:39:45.412991Z",
      "text": "{\"status\":\"success\",\"next_step\":\"Monitor adoption and collect feedback.\"}"
    }
  ],
  "model": "private-gpt",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 98, "output_tokens": 16 }
}

Streaming (SSE)

Configura stream: true para recibir eventos text/event-stream.

curl -N -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "default",
    "stream": true,
    "max_tokens": 32,
    "messages": [
      { "role": "user", "content": "Give a three-word tagline for a productivity app." }
    ]
  }'

Ejemplo de eventos

event: message_start
data: {"type":"message_start","message":{"id":"msg_b55d29718361410bad4f80f8f67c6b72","type":"message","role":"assistant","content":[],"model":"private-gpt","usage":{}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","content_block":{"type":"text","start_timestamp":"2026-02-06T13:18:37.331257Z","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","delta":{"type":"text_delta","text":"Focus"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","delta":{"type":"text_delta","text":" fast daily"}}

event: content_block_stop
data: {"type":"content_block_stop","stop_timestamp":"2026-02-06T13:18:37.417617Z","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044"}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"input_tokens":90,"output_tokens":3}}

event: message_stop
data: {"type":"message_stop"}

Mensajes asíncronos

Las rutas de inicio, streaming, estado, cancelación y eliminación de mensajes asíncronos requieren PrivateGPT.ReadWrite.All o ReadWrite.All. Los tokens de solo lectura reciben 403 en todo el ciclo de vida asíncrono.

Los mensajes asíncronos usan el mismo cuerpo que los mensajes síncronos: solo cambia el endpoint. La diferencia principal está en la respuesta: los mensajes síncronos devuelven el mensaje completo, y los asíncronos devuelven un message_id para hacer streaming o consultar el estado.

Forma de la respuesta: síncrona vs asíncrona

Respuesta síncrona
Respuesta asíncrona

{
  "id": "msg_abf981cf3f1c449eacb7a85c064ca505",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "start_timestamp": "2026-02-06T13:23:16.876744Z",
      "stop_timestamp": "2026-02-06T13:23:16.975362Z",
      "text": "Deployed the new billing dashboard and resolved three bugs successfully."
    }
  ],
  "model": "private-gpt",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 95,
    "output_tokens": 16
  }
}

{
  "message_id": "1cc8ed5e-fc7a-45e1-baf4-0b916ed32290",
  "status": "pending",
  "message": "Request initiated successfully"
}

Iniciar un mensaje asíncrono

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 32,
    "messages": [
      { "role": "user", "content": "Say only: async ok" }
    ]
  }'

Streaming o consulta de estado

Streaming:

curl -N "https://{BASE_URL}/api/gpt/v1/messages/async/{message_id}/stream" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Accept: text/event-stream"

Consulta de estado:

curl "https://{BASE_URL}/api/gpt/v1/messages/async/{message_id}/status" \
  -H "Authorization: Bearer {API_TOKEN}"

Cancelar o eliminar

Cancelar: POST /messages/async/{message_id}/cancel
Eliminar: DELETE /messages/async/{message_id}/delete

Errores comunes

Método incorrecto: /messages es POST, no GET.
Falta de autenticación: incluye Authorization: Bearer ....
Base URL incorrecta: usa https://{BASE_URL}/api/gpt/v1/.
Cuerpo inválido: usa POST /messages/validate para validar.
Paradas o errores inesperados: revisa Motivos de parada para causas y soluciones.

Primeros pasos

Construye con Zylon

Coding Agents

Requisitos previos

Solicitud y respuesta básica

Formato de mensajes

Validar una solicitud

Conversaciones con varios turnos

Prompts del sistema

JSON estructurado (json_schema)

Streaming (SSE)

Mensajes asíncronos

Iniciar un mensaje asíncrono

Streaming o consulta de estado

Cancelar o eliminar

Errores comunes

Próximos pasos

Herramientas

Artefactos

​Requisitos previos

​Solicitud y respuesta básica

​Formato de mensajes

​Validar una solicitud

​Conversaciones con varios turnos

​Prompts del sistema

​JSON estructurado (json_schema)

​Streaming (SSE)

​Mensajes asíncronos

​Iniciar un mensaje asíncrono

​Streaming o consulta de estado

​Cancelar o eliminar

​Errores comunes

​Próximos pasos

Herramientas

Artefactos

Requisitos previos

Solicitud y respuesta básica

Formato de mensajes

Validar una solicitud

Conversaciones con varios turnos

Prompts del sistema

JSON estructurado (json_schema)

Streaming (SSE)

Mensajes asíncronos

Iniciar un mensaje asíncrono

Streaming o consulta de estado

Cancelar o eliminar

Errores comunes

Próximos pasos