# Visión general de Backoffice API
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/backoffice-api/overview

API de Backoffice para operaciones y tareas a nivel de plataforma.

La Backoffice API ofrece endpoints a nivel de plataforma para operadores autorizados y procesos de automatización. Úsala para tareas operativas que quedan fuera de la Workspace API, como recuperar registros de Zylon para investigar incidencias o exportarlos.

## URL base

Los endpoints de Backoffice se sirven desde la raíz de la plataforma:

```http theme={null}
https://{BASE_URL}
```

A diferencia de la Workspace API, estos endpoints no usan el prefijo de workspace `/api/v1/app`.

## Autenticación y permisos

Las solicitudes requieren un token de cuenta o una sesión de cuenta con, al menos, el rol `operator`. El token de cuenta puede usar `Read.All` si el rol de su propietario también concede el permiso de Backoffice solicitado; `Read.All` nunca amplía los permisos del propietario. `ReadWrite.All` también incluye acceso de lectura.

```bash theme={null}
-H "Authorization: Bearer {API_TOKEN}"
```

> [!NOTE]
>
> Los tokens exclusivos de Workspace no son suficientes para los endpoints de Backoffice.

Consulta [Gestión de tokens](/es/v1.58/developer-manual/get-started/token-management) para elegir el flujo de autenticación adecuado.

## Secciones disponibles

> **[Registros (guía en inglés)](/en/v1.58/developer-manual/build-with-zylon/backoffice-api/logging)**
>
> Recupera registros almacenados de plataforma, gateway, seguridad, workspace y uso de IA. Esta referencia de endpoints está disponible en inglés.

Para consultar la entrega al SIEM, la conservación y las evidencias de auditoría en español, ve a [Registro y entrega de logs](/es/v1.58/operator-manual/backoffice/log-delivery-storage).


# Herramienta de ejecución de código
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/built-in/code-execution-tool

Ejecuta comandos bash y edita archivos en un contenedor aislado para analizar datos, generar archivos e iterar sobre soluciones.

La herramienta de ejecución de código permite al asistente ejecutar comandos bash y crear, ver y editar archivos dentro de un contenedor aislado (sandbox), directamente dentro de una solicitud a `/messages`. Úsala para analizar datos subidos, hacer cálculos, transformar documentos o generar archivos como gráficos, hojas de cálculo e informes.

Sigue el mismo modelo que la [herramienta de ejecución de código de Anthropic](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool): el servidor ejecuta todos los comandos, así que nunca tienes que ejecutar código ni enviar bloques `tool_result` por tu cuenta.

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).
* Un proveedor de ejecución de código configurado, incluido por defecto en los despliegues estándar de Zylon 1.58. Para las solicitudes de la API del Workspace, también debe estar habilitada la funcionalidad del Workspace. Consulta [Ejecución de código](/es/v1.58/operator-manual/configuration/features/feat-code-execution) para la configuración y el comportamiento al desactivarla.

## Requisitos

* Especificación de la herramienta: `{ "name": "code_execution", "type": "code_execution_v1" }`
* También se acepta la especificación compatible con Anthropic: `{ "name": "code_execution", "type": "code_execution_20250825" }`
* No requiere `tool_context`
* Opcional: un ID de `container` para reutilizar un sandbox entre solicitudes

## Inicio rápido

```bash theme={null}
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": 4096,
    "messages": [
      { "role": "user", "content": "Calcula la media y la desviación estándar de [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" }
    ],
    "tools": [
      { "name": "code_execution", "type": "code_execution_v1" }
    ]
  }'
```

Para comprobar la solicitud sin ejecutarla, envía el mismo cuerpo a `POST /api/gpt/v1/messages/validate`.

## Cómo funciona la ejecución de código

Cuando añades la herramienta de ejecución de código a una solicitud:

1. El asistente decide si ejecutar código ayudaría a responder la pregunta.
2. La herramienta se expande en dos subherramientas que el asistente puede combinar libremente:
   * `bash_code_execution`: ejecuta comandos de shell.
   * `text_editor_code_execution`: ve, crea y edita archivos.
3. Cada operación se ejecuta en el servidor dentro de un contenedor aislado, y los resultados se devuelven al asistente dentro de la misma solicitud.
4. La respuesta contiene cada llamada a herramienta (`server_tool_use`) y su resultado, seguidos de la respuesta final del asistente.
5. La respuesta también contiene un objeto `container` de nivel superior. Pasa su `id` en solicitudes posteriores para seguir trabajando en el mismo sandbox.

> [!TIP]
>
> En solicitudes dudosas, pídelo explícitamente (por ejemplo, "ejecuta código para verificarlo") para que el asistente use el sandbox en lugar de responder de memoria.

### Subherramientas

**`bash_code_execution`**

| Parámetro | Tipo | Descripción |
| - | - | - |
| `command` | string | Obligatorio. El comando de shell que se ejecuta. |
| `timeout` | integer | Opcional. Tiempo de espera en segundos (por defecto `60`). |
| `restart` | boolean | Opcional. Reinicia el espacio de trabajo. |

Cada llamada se ejecuta en una shell nueva. Los archivos persisten entre llamadas; las variables de entorno y `cd`, no.

**`text_editor_code_execution`**

| `command` | Parámetros | Descripción |
| - | - | - |
| `view` | `path`, `view_range` (opcional, `[start, end]`, empezando en 1, `-1` = final del archivo) | Ver un archivo o listar un directorio |
| `create` | `path`, `file_text` | Crear o sobrescribir un archivo |
| `str_replace` | `path`, `old_str`, `new_str` | Reemplazar una cadena exacta y única |
| `insert` | `path`, `insert_line`, `insert_text` | Insertar texto después de una línea (`0` = inicio del archivo) |

Las rutas relativas se resuelven respecto al espacio de trabajo (`/home/agent/workspace/`).

## Contenedores

Un contenedor es un sandbox aislado con su propio sistema de archivos. El contenedor se identifica con un ID de tipo cadena que eliges tú o que asigna el servidor.

### Seleccionar un contenedor

Establece el campo `container` de nivel superior con el ID que quieras usar. Si el contenedor todavía no existe, se crea; si existe, la solicitud lo reutiliza junto con todos sus archivos.

```json theme={null}
{
  "model": "default",
  "max_tokens": 4096,
  "container": "sales-analysis-2026-q3",
  "messages": [{ "role": "user", "content": "..." }],
  "tools": [{ "name": "code_execution", "type": "code_execution_v1" }]
}
```

> [!WARNING]
>
> Si omites `container`, el sandbox se asocia al usuario autenticado, de modo que todas las solicitudes de ese usuario sin `container` comparten el mismo sandbox. Usa un ID de `container` explícito y único por conversación o tarea para mantener el trabajo aislado.

### Leer el contenedor desde la respuesta

Cuando se ejecuta código, la respuesta incluye el contenedor que se ha usado:

```json theme={null}
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "content": [ ... ],
  "stop_reason": "end_turn",
  "container": {
    "id": "sales-analysis-2026-q3",
    "expires_at": "2026-10-08T12:30:00Z"
  }
}
```

En streaming, el objeto `container` llega en el evento final `message_delta` como `delta.container`.

### Reutilizar un contenedor

Pasa el mismo ID de `container` en las solicitudes de seguimiento para conservar los archivos creados anteriormente:

```bash theme={null}
# Primera solicitud: crear un archivo
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": 4096,
    "container": "my-container",
    "messages": [
      { "role": "user", "content": "Escribe un número aleatorio en /home/agent/workspace/number.txt" }
    ],
    "tools": [{ "name": "code_execution", "type": "code_execution_v1" }]
  }'

# Segunda solicitud: mismo contenedor, el archivo sigue ahí
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": 4096,
    "container": "my-container",
    "messages": [
      { "role": "user", "content": "Lee /home/agent/workspace/number.txt y eleva el número al cuadrado" }
    ],
    "tools": [{ "name": "code_execution", "type": "code_execution_v1" }]
  }'
```

`expires_at` es un valor móvil que se renueva con cada solicitud. Cuando un contenedor está inactivo, su sandbox se apaga para liberar recursos, pero sus archivos se conservan. La siguiente solicitud con el mismo ID arranca un sandbox nuevo con los mismos archivos. Los paquetes instalados, los procesos en ejecución y el estado de la shell no se conservan.

Para empezar desde cero, usa un ID de `container` nuevo o [elimina los archivos](#eliminar-archivos).

### Estructura del sistema de archivos

| Ruta | Acceso | Propósito |
| - | - | - |
| `/home/agent/workspace/` | lectura y escritura | Directorio de trabajo. Archivos temporales y resultados intermedios. |
| `/mnt/user-data/uploads/` | solo lectura | Archivos que subes a través de la [Files API](#trabajar-con-archivos). |
| `/mnt/user-data/outputs/` | lectura y escritura | Entregables. Los archivos de esta carpeta se pueden listar y descargar a través de la Files API. |
| `/mnt/skills/` | solo lectura | Skills cargadas para la solicitud, una carpeta por skill. |

> [!TIP]
>
> Si tu aplicación espera un archivo generado, pide al asistente que lo guarde en `/mnt/user-data/outputs/` (por ejemplo, "guarda el gráfico como `/mnt/user-data/outputs/chart.png`").

### Entorno de ejecución

El sandbox incluye Python 3 con las librerías de datos más habituales: pandas, numpy, scipy, scikit-learn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab, img2pdf, sympy, mpmath, tqdm, python-dateutil, pytz y joblib. Entre las herramientas de línea de comandos se incluyen `unzip`, `unrar`, `7zip`, `bc`, `rg`, `fd` y `sqlite3`.

### Red y seguridad

* **Sin acceso a internet.** El sandbox no puede acceder a internet, por lo que no se pueden instalar paquetes en tiempo de ejecución. Solo están disponibles las librerías preinstaladas.
* **Acceso a la API de Zylon.** El sandbox puede acceder a la API de Zylon, con estas variables de entorno ya definidas: `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` y `ANTHROPIC_MODEL`. El código que se ejecuta en el sandbox, como un script que use el SDK de Anthropic, puede llamar al modelo **con los permisos del usuario que envió la solicitud**.
* **Aislamiento.** Cada contenedor se ejecuta en su propio sandbox, aislado del host y del resto de contenedores.

Tu operador puede permitir el acceso a servicios internos adicionales. Ver [Ejecución de código](/es/v1.58/operator-manual/configuration/features/feat-code-execution).

## Trabajar con archivos

Usa la Files API para colocar archivos en un contenedor antes de una solicitud, y para listar, descargar y eliminar los archivos que haya generado. Todas las llamadas a la Files API reciben un parámetro de consulta `scope_id`: **es el ID del contenedor**.

| Método | Endpoint | Descripción |
| - | - | - |
| `POST` | `/api/gpt/v1/files?scope_id={container}` | Subir un archivo (multipart) |
| `PUT` | `/api/gpt/v1/files/{key}?scope_id={container}` | Colocar un archivo en una clave concreta (cuerpo en bruto) |
| `GET` | `/api/gpt/v1/files?scope_id={container}` | Listar archivos |
| `GET` | `/api/gpt/v1/files/{file_id}?scope_id={container}` | Obtener los metadatos de un archivo |
| `HEAD` | `/api/gpt/v1/files/{file_id}?scope_id={container}` | Comprobar que un archivo existe (metadatos en las cabeceras `X-File-*`) |
| `GET` | `/api/gpt/v1/files/{file_id}/content?scope_id={container}` | Descargar el contenido de un archivo |
| `DELETE` | `/api/gpt/v1/files/{file_id}?scope_id={container}` | Eliminar un archivo |
| `DELETE` | `/api/gpt/v1/files?scope_id={container}&prefix={prefix}` | Eliminar todos los archivos subidos bajo un prefijo |

### Subir archivos

Sube un archivo a la carpeta de subidas del contenedor. Estará disponible para el asistente en `/mnt/user-data/uploads/{filename}`:

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/files?scope_id=my-container" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -F "file=@sales.csv"
```

Respuesta:

```json theme={null}
{
  "id": "L21udC91c2VyLWRhdGEvdXBsb2Fkcy9zYWxlcy5jc3Y",
  "created_at": "2026-10-08T10:30:00Z",
  "filename": "sales.csv",
  "mime_type": "text/csv",
  "size_bytes": 4096,
  "type": "file",
  "downloadable": false,
  "etag": "d41d8cd98f00b204e9800998ecf8427e",
  "namespace": "session",
  "scope": { "id": "my-container", "type": "session" }
}
```

El `id` es el ID de archivo que usan el resto de endpoints. Es la ruta del sandbox codificada en base64url (en este caso, `/mnt/user-data/uploads/sales.csv`), sin relleno.

Usa el parámetro de consulta `path` para elegir la clave, por ejemplo para organizar los archivos en carpetas. Las carpetas padre se crean automáticamente, y subir a una clave existente la sobrescribe:

```bash theme={null}
# Disponible en /mnt/user-data/uploads/data/2026/q3.xlsx
curl -X POST "https://{BASE_URL}/api/gpt/v1/files?scope_id=my-container&path=data/2026/q3.xlsx" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -F "file=@q3.xlsx"
```

Una clave que empieza por `outputs/` coloca el archivo en `/mnt/user-data/outputs/`. Las claves deben ser relativas y no pueden contener `..` ni terminar en `/`.

También puedes colocar bytes en bruto en una clave, al estilo de S3:

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/gpt/v1/files/config/settings.json?scope_id=my-container" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @settings.json
```

### Analizar archivos subidos

Después de subirlo, envía un mensaje con el **mismo ID de contenedor** y haz referencia al archivo por su ruta:

```bash theme={null}
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": 4096,
    "container": "my-container",
    "messages": [
      {
        "role": "user",
        "content": "Analiza /mnt/user-data/uploads/sales.csv. Representa los ingresos mensuales y guarda el gráfico en /mnt/user-data/outputs/revenue.png"
      }
    ],
    "tools": [{ "name": "code_execution", "type": "code_execution_v1" }]
  }'
```

### Listar archivos

Lista todos los archivos de un contenedor, tanto los subidos como los generados, ordenados por fecha de creación:

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/files?scope_id=my-container" \
  -H "Authorization: Bearer {API_TOKEN}"
```

```json theme={null}
{
  "data": [
    {
      "id": "L21udC91c2VyLWRhdGEvdXBsb2Fkcy9zYWxlcy5jc3Y",
      "filename": "sales.csv",
      "mime_type": "text/csv",
      "size_bytes": 4096,
      "type": "file",
      "downloadable": false,
      "scope": { "id": "my-container", "type": "session" }
    },
    {
      "id": "L21udC91c2VyLWRhdGEvb3V0cHV0cy9yZXZlbnVlLnBuZw",
      "filename": "revenue.png",
      "mime_type": "image/png",
      "size_bytes": 38211,
      "type": "file",
      "downloadable": true,
      "scope": { "id": "my-container", "type": "session" }
    }
  ],
  "first_id": "L21udC91c2VyLWRhdGEvdXBsb2Fkcy9zYWxlcy5jc3Y",
  "last_id": "L21udC91c2VyLWRhdGEvb3V0cHV0cy9yZXZlbnVlLnBuZw",
  "has_more": false
}
```

`downloadable` es `true` para los archivos de `/mnt/user-data/outputs/` y `false` para los subidos.

Parámetros de consulta opcionales:

| Parámetro | Por defecto | Descripción |
| - | - | - |
| `limit` | `20` | Tamaño de página (de 1 a 1000) |
| `after_id` | | Devuelve los archivos posteriores a este ID de archivo (página siguiente) |
| `before_id` | | Devuelve los archivos anteriores a este ID de archivo (página anterior) |
| `prefix` | | Solo los archivos cuya clave de subida empieza por este prefijo, por ejemplo `data/2026/` |

### Descargar archivos

Descarga un archivo con su ID:

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/files/L21udC91c2VyLWRhdGEvb3V0cHV0cy9yZXZlbnVlLnBuZw/content?scope_id=my-container" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -o revenue.png
```

Añade `disposition=inline` para abrir el archivo en el navegador en lugar de descargarlo.

El ID de archivo es la ruta del sandbox codificada en base64url, así que también puedes construirlo tú mismo:

```bash theme={null}
FILE_ID=$(printf '/mnt/user-data/outputs/revenue.png' | base64 | tr '+/' '-_' | tr -d '=')
```

```python theme={null}
import base64

file_id = base64.urlsafe_b64encode(b"/mnt/user-data/outputs/revenue.png").decode().rstrip("=")
```

### Eliminar archivos

Elimina un archivo, ya sea uno subido, una salida generada o un archivo del espacio de trabajo:

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/gpt/v1/files/L21udC91c2VyLWRhdGEvdXBsb2Fkcy9zYWxlcy5jc3Y?scope_id=my-container" \
  -H "Authorization: Bearer {API_TOKEN}"
```

```json theme={null}
{ "id": "L21udC91c2VyLWRhdGEvdXBsb2Fkcy9zYWxlcy5jc3Y", "type": "file_deleted" }
```

Elimina todos los archivos subidos bajo un prefijo. Termina el prefijo en `/` para no eliminar claves hermanas que comparten el mismo texto:

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/gpt/v1/files?scope_id=my-container&prefix=data/2026/" \
  -H "Authorization: Bearer {API_TOKEN}"
```

```json theme={null}
{ "prefix": "data/2026/", "deleted_count": 3, "type": "prefix_deleted" }
```

### Ejemplo completo

```python theme={null}
import base64
import requests

BASE = "https://{BASE_URL}/api/gpt/v1"
HEADERS = {"Authorization": "Bearer {API_TOKEN}"}
CONTAINER = "sales-analysis-2026-q3"

# 1. Subir el archivo de entrada
with open("sales.csv", "rb") as f:
    requests.post(f"{BASE}/files", params={"scope_id": CONTAINER},
                  headers=HEADERS, files={"file": f}).raise_for_status()

# 2. Pedir al asistente que lo analice en el mismo contenedor
response = requests.post(f"{BASE}/messages", headers=HEADERS, json={
    "model": "default",
    "max_tokens": 4096,
    "container": CONTAINER,
    "messages": [{
        "role": "user",
        "content": "Analiza /mnt/user-data/uploads/sales.csv y guarda un gráfico de ingresos "
                   "en /mnt/user-data/outputs/revenue.png",
    }],
    "tools": [{"name": "code_execution", "type": "code_execution_v1"}],
}).json()
print(response["content"][-1]["text"])

# 3. Descargar todas las salidas generadas
files = requests.get(f"{BASE}/files", params={"scope_id": CONTAINER}, headers=HEADERS).json()
for item in files["data"]:
    if item["downloadable"]:
        content = requests.get(f"{BASE}/files/{item['id']}/content",
                               params={"scope_id": CONTAINER}, headers=HEADERS)
        with open(item["filename"], "wb") as out:
            out.write(content.content)

# 4. Limpiar
for item in files["data"]:
    requests.delete(f"{BASE}/files/{item['id']}", params={"scope_id": CONTAINER}, headers=HEADERS)
```

## Ejecución de código en la Workspace API

Cuando usas la [Workspace API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/overview) en lugar de llamar directamente a la API de ZylonGPT, Zylon gestiona el contenedor por ti:

* **El contenedor es el hilo del chat.** Cada hilo tiene su propio sandbox, y el campo `container` toma el ID del hilo. Los archivos persisten durante toda la vida del hilo, y los hilos no pueden ver los archivos de otros hilos.
* **La ejecución de código se añade automáticamente** cuando la solicitud usa Skills y la funcionalidad del Workspace está habilitada. También puedes solicitarla explícitamente mediante `pgpt.tools`. Si `features.codeExecution.enabled` es `false`, el Workspace elimina estas herramientas, incluidas las solicitadas explícitamente. Este flag no desactiva globalmente el proveedor de la API de ZylonGPT; consulta [Cuando está desactivada](/es/v1.58/operator-manual/configuration/features/feat-code-execution#cuando-está-desactivada).
* **Los archivos generados se convierten en artefactos.** Cuando el asistente presenta un archivo, Zylon lo guarda como artefacto en el proyecto y lo devuelve en el stream como un bloque `zylon-resource`, para que los usuarios puedan previsualizarlo y descargarlo.

Usa los endpoints del hilo para gestionar los archivos del sandbox de un hilo:

| Método | Endpoint | Descripción |
| - | - | - |
| `POST` | `/api/v1/app/thread/{threadId}/upload-file` | Subir un archivo (campo multipart `file`, `path` opcional) a `/mnt/user-data/uploads/` |
| `PUT` | `/api/v1/app/thread/{threadId}/put-file/{path}` | Colocar bytes en bruto en una clave |
| `GET` | `/api/v1/app/thread/{threadId}/download-file?path={path}` | Descargar un archivo por su ruta en el sandbox, por ejemplo `/mnt/user-data/outputs/chart.png` |

```bash theme={null}
# Subir un archivo al sandbox del hilo
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadId}/upload-file" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -F "file=@sales.csv"

# Descargar un archivo generado
curl "https://{BASE_URL}/api/v1/app/thread/{threadId}/download-file?path=/mnt/user-data/outputs/revenue.png" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -o revenue.png
```

> [!NOTE]
>
> Las descargas dependen de la configuración de tu organización: los archivos generados (`outputs/`) requieren que estén habilitadas las descargas de recursos generados, y los archivos subidos (`uploads/`) requieren que estén habilitadas las descargas de recursos subidos.

## Formato de respuesta

Cada llamada a una subherramienta aparece como un bloque `server_tool_use` seguido de su bloque de resultado.

### Comando bash

```json theme={null}
{
  "type": "server_tool_use",
  "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "name": "bash_code_execution",
  "input": { "command": "ls -la /mnt/user-data/uploads" }
},
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "content": {
    "type": "bash_code_execution_result",
    "stdout": "total 8\n-rw-r--r-- 1 agent agent 4096 Oct  8 10:30 sales.csv",
    "stderr": "",
    "return_code": 0
  }
}
```

Un `return_code` distinto de cero no es un error: significa que el comando se ejecutó y falló, y el asistente puede leer `stderr` y volver a intentarlo.

### Operaciones con archivos

**Ver:**

```json theme={null}
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": {
    "type": "text_editor_code_execution_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 4
  }
}
```

**Crear:**

```json theme={null}
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": {
    "type": "text_editor_code_execution_create_result",
    "is_file_update": false
  }
}
```

**Editar (`str_replace` e `insert`):**

```json theme={null}
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "content": {
    "type": "text_editor_code_execution_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}
```

### Errores

Cuando una herramienta no puede ejecutarse, su resultado contiene un bloque de error:

```json theme={null}
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable",
    "detail": {
      "code": "unavailable",
      "explanation": "File not found: /home/agent/workspace/missing.txt"
    }
  }
}
```

`detail.explanation` contiene el motivo subyacente. Es una extensión de Zylon y se omite en las respuestas compatibles con Anthropic.

| Situación | Comportamiento |
| - | - |
| El comando supera su tiempo de espera | `return_code: 124`, `stderr: "Command timed out after 60s."` |
| Salida mayor que el límite (1 MiB por defecto) | La salida se trunca y termina en `...[truncated]` |
| El archivo no existe, o `old_str` no aparece o no es único | Bloque de error con el motivo en `detail.explanation` |
| Escritura en una carpeta de solo lectura (`uploads`, `skills`) | Bloque de error: `Path '...' is in a read-only mount` |
| Ruta fuera de las carpetas del sandbox | Bloque de error: `Path '...' does not match any session mount` |
| No hay un proveedor de ejecución de código configurado en GPT | Bloque de error: `code_execution provider is not configured.` |

## Consejos

* Usa un ID de `container` por conversación o tarea, y reutilízalo en todas las solicitudes de seguimiento y llamadas a la Files API.
* Pide que los entregables se guarden en `/mnt/user-data/outputs/` para poder listarlos y descargarlos.
* Combina la ejecución de código con otras herramientas, como [Web Fetch](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/web-fetch-tool) o [Búsqueda semántica](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/semantic-search-tool), para incorporar datos al análisis.
* Elimina los archivos subidos y las salidas que ya no necesites: los archivos permanecen en el contenedor hasta que los borras.

## Próximos pasos

* Descubre cómo los mensajes devuelven bloques de herramientas: [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)
* Gestiona turnos de larga duración: [Motivos de parada](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/handling-stop-reasons)


# Herramienta de consulta a base de datos
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/built-in/database-query-tool

Consulta una base SQL desde lenguaje natural.

Usa Database Query para traducir lenguaje natural a SQL sobre una conexión configurada.

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).
* Una cadena de conexión a la base de datos.

## Requisitos

* Especificación de la herramienta: `{ "name": "database_query", "type": "database_query_v1" }`
* `tool_context`: un contexto `sql_database` con `connection_string`

## Solicitud y respuesta básicas

Este ejemplo valida el cuerpo de la petición y usa `tool_choice: none` para no conectar durante la validación.

```bash theme={null}
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": 128,
    "messages": [
      { "role": "user", "content": "What were total Q1 subscriptions by plan?" }
    ],
    "tools": [
      { "name": "database_query", "type": "database_query_v1" }
    ],
    "tool_choice": { "type": "none" },
    "tool_context": [
      {
        "type": "sql_database",
        "connection_string": "postgresql://{username}:{password}@db.example.com:5432/analytics",
        "schemas": ["public"],
        "ssl": true
      }
    ]
  }'
```

Ejemplo de respuesta:

```json theme={null}
{ "valid": true, "errors": null }
```

Para ejecutar, envía el mismo cuerpo a `POST /messages` y cambia `tool_choice` a `{ \"type\": \"auto\" }`.

## Bloques de respuesta

Zylon ejecuta esta herramienta en el servidor. La respuesta contiene un bloque `server_tool_use` con la llamada, seguido de un bloque `server_tool_result` con el resultado. El ID de la llamada empieza por `srvtoolu_`. No envíes un `tool_result` de vuelta para ella.

```json theme={null}
[
  { "type": "server_tool_use", "id": "srvtoolu_5c6d", "name": "database_query", "input": { "query": "Total Q1 subscriptions by plan" } },
  {
    "type": "server_tool_result",
    "tool_use_id": "srvtoolu_5c6d",
    "content": [{ "type": "text", "text": "Query result: \nplan,subscriptions\nPro,320\nTeam,145" }],
    "is_error": false
  }
]
```

Error:

```json theme={null}
{ "type": "server_tool_result", "tool_use_id": "srvtoolu_5c6d", "content": "At least one SQL database artifact is required.", "is_error": true }
```

`is_error` es `true` cuando la herramienta falla, y `content` contiene el mensaje de error.

Consulta [Migración de 1.57 a 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) para ver la lista completa de bloques de herramientas de servidor.

## Consejos

* Usa un usuario de solo lectura.
* Limita los esquemas (`schemas`) para acelerar la inspección.

## Próximos pasos

* Formato de mensajes: [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)


# Herramienta de búsqueda semántica
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/built-in/semantic-search-tool

Busca en artefactos ingeridos durante un mensaje.

Usa Semantic Search cuando quieras recuperar información de artefactos ingeridos (documentos, notas, PDFs, HTML, etc.).

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).
* Artefactos ingeridos para buscar.

## Requisitos

* Especificación de la herramienta: `{ "name": "semantic_search", "type": "semantic_search_v1" }`
* `tool_context`: al menos un `ingested_artifact` con `context_filter`.

## Solicitud y respuesta básicas

Este ejemplo valida una petición que habilita Semantic Search:

```bash theme={null}
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": 128,
    "messages": [
      { "role": "user", "content": "What shipped in the latest billing dashboard release?" }
    ],
    "tools": [
      { "name": "semantic_search", "type": "semantic_search_v1" }
    ],
    "tool_choice": { "type": "auto" },
    "tool_context": [
      {
        "type": "ingested_artifact",
        "context_filter": {
          "collection": "{collectionID}"
        }
      }
    ]
  }'
```

Ejemplo de respuesta:

```json theme={null}
{ "valid": true, "errors": null }
```

Para ejecutar, envía el mismo cuerpo a `POST /messages`.

## Bloques de respuesta

Zylon ejecuta esta herramienta en el servidor. La respuesta contiene un bloque `server_tool_use` con la llamada, seguido de un bloque `server_tool_result` con el resultado. El ID de la llamada empieza por `srvtoolu_`. No envíes un `tool_result` de vuelta para ella.

```json theme={null}
[
  { "type": "server_tool_use", "id": "srvtoolu_9c0d", "name": "semantic_search", "input": { "query": "billing dashboard release" } },
  {
    "type": "server_tool_result",
    "tool_use_id": "srvtoolu_9c0d",
    "content": [
      { "type": "source", "sources": [{ "object": "context.chunk", "id": "chunk_1", "text": "The billing dashboard release added invoice exports..." }] },
      { "type": "text", "text": "The billing dashboard release added invoice exports and fixed three bugs." }
    ],
    "is_error": false
  }
]
```

Los bloques `source` son específicos de Zylon. Solo se devuelven cuando la extensión Zylon está activada.

Error:

```json theme={null}
{ "type": "server_tool_result", "tool_use_id": "srvtoolu_9c0d", "content": "context_filter is required", "is_error": true }
```

`is_error` es `true` cuando la herramienta falla, y `content` contiene el mensaje de error.

Consulta [Migración de 1.57 a 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) para ver la lista completa de bloques de herramientas de servidor.

## Consejos

* Mantén `tool_context` acotado.
* Si los resultados no son relevantes, ingesta texto más depurado.

## Próximos pasos

* Ingesta de artefactos: [Artefactos](/es/v1.58/developer-manual/build-with-zylon/working-with-artifacts)
* Formato de mensajes: [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)


# Herramienta de análisis tabular
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/built-in/tabular-analysis-tool

Analiza artefactos tabulares durante un mensaje.

Usa Tabular Analysis para cálculos sobre datos tabulares (CSV/TSV o tablas extraídas).

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).
* Artefactos tabulares ingeridos.

## Requisitos

* Especificación de la herramienta: `{ "name": "tabular_analysis", "type": "tabular_analysis_v1" }`
* `tool_context`: al menos un `ingested_artifact` con `context_filter`.

## Solicitud y respuesta básicas

```bash theme={null}
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": 128,
    "messages": [
      { "role": "user", "content": "What is the average of the Q1 revenue column?" }
    ],
    "tools": [
      { "name": "tabular_analysis", "type": "tabular_analysis_v1" }
    ],
    "tool_choice": { "type": "auto" },
    "tool_context": [
      {
        "type": "ingested_artifact",
        "context_filter": {
          "collection": "{collectionID}"
        }
      }
    ]
  }'
```

Ejemplo de respuesta:

```json theme={null}
{ "valid": true, "errors": null }
```

Para ejecutar, envía el mismo cuerpo a `POST /messages`.

## Bloques de respuesta

Zylon ejecuta esta herramienta en el servidor. La respuesta contiene un bloque `server_tool_use` con la llamada, seguido de un bloque `server_tool_result` con el resultado. El ID de la llamada empieza por `srvtoolu_`. No envíes un `tool_result` de vuelta para ella.

```json theme={null}
[
  { "type": "server_tool_use", "id": "srvtoolu_3a4b", "name": "tabular_analysis", "input": { "query": "Average of the Q1 revenue column" } },
  {
    "type": "server_tool_result",
    "tool_use_id": "srvtoolu_3a4b",
    "content": [{ "type": "text", "text": "avg_q1_revenue\n18250.4" }],
    "is_error": false
  }
]
```

Error:

```json theme={null}
{ "type": "server_tool_result", "tool_use_id": "srvtoolu_3a4b", "content": "context_filter is required", "is_error": true }
```

`is_error` es `true` cuando la herramienta falla, y `content` contiene el mensaje de error.

Consulta [Migración de 1.57 a 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) para ver la lista completa de bloques de herramientas de servidor.

## Consejos

* Asegura que el contenido sea una tabla limpia.
* Mantén tablas pequeñas para análisis rápido.

## Próximos pasos

* Ingesta de artefactos: [Artefactos](/es/v1.58/developer-manual/build-with-zylon/working-with-artifacts)
* Formato de mensajes: [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)


# Herramienta Web Fetch
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/built-in/web-fetch-tool

Extrae contenido de una URL en el mensaje.

Usa Web Fetch cuando necesitas que el asistente recupere contenido de una URL.

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).

## Requisitos

* Especificación de la herramienta: `{ "name": "web_extract", "type": "web_extract_v1" }`
* No requiere `tool_context`

## Solicitud y respuesta básicas

```bash theme={null}
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": 64,
    "messages": [
      { "role": "user", "content": "Summarize https://example.com/" }
    ],
    "tools": [
      { "name": "web_extract", "type": "web_extract_v1" }
    ],
    "tool_choice": { "type": "auto" }
  }'
```

Ejemplo de respuesta:

```json theme={null}
{ "valid": true, "errors": null }
```

Para ejecutar, envía el mismo cuerpo a `POST /messages`.

## Bloques de respuesta

Zylon ejecuta esta herramienta en el servidor. La respuesta contiene un bloque `server_tool_use` con la llamada, seguido de un bloque `web_fetch_tool_result` con el resultado. El ID de la llamada empieza por `srvtoolu_`. No envíes un `tool_result` de vuelta para ella.

```json theme={null}
[
  { "type": "server_tool_use", "id": "srvtoolu_3c4d", "name": "web_extract", "input": { "url": "https://example.com/" } },
  {
    "type": "web_fetch_tool_result",
    "tool_use_id": "srvtoolu_3c4d",
    "content": {
      "type": "web_fetch_result",
      "url": "https://example.com/",
      "retrieved_at": "2026-10-08T10:00:00Z",
      "content": {
        "type": "document",
        "title": "Example Domain",
        "source": { "type": "text", "media_type": "text/plain", "data": "# Example Domain\n\nThis domain is for use in examples." }
      }
    }
  }
]
```

Error:

```json theme={null}
{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_3c4d",
  "content": { "type": "web_fetch_tool_result_error", "error_code": "url_not_accessible" }
}
```

Estos bloques no tienen campo `is_error`. Para detectar un fallo, comprueba si `content.type` termina en `_error` y lee `content.error_code`.

Con la extensión Zylon activada (`system.extensions` incluye `zylon`), el resultado se devuelve como un bloque `tool_result` simple con contenido `text`.

Consulta [Migración de 1.57 a 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) para ver la lista completa de bloques de herramientas de servidor.

## Consejos

* La URL debe aparecer en el mensaje.
* Mantén el prompt conciso.

## Próximos pasos

* Formato de mensajes: [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)


# Herramienta Web Search
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/built-in/web-search-tool

Busca en la web desde una consulta natural.

Usa Web Search para ejecutar búsquedas rápidas.

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).

## Requisitos

* Especificación de la herramienta: `{ "name": "web_search", "type": "web_search_v1" }`
* No requiere `tool_context`

## Solicitud y respuesta básicas

```bash theme={null}
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": 64,
    "messages": [
      { "role": "user", "content": "Find recent updates about the EU AI Act." }
    ],
    "tools": [
      { "name": "web_search", "type": "web_search_v1" }
    ],
    "tool_choice": { "type": "auto" }
  }'
```

Ejemplo de respuesta:

```json theme={null}
{ "valid": true, "errors": null }
```

Para ejecutar, envía el mismo cuerpo a `POST /messages`.

## Bloques de respuesta

Zylon ejecuta esta herramienta en el servidor. La respuesta contiene un bloque `server_tool_use` con la llamada, seguido de un bloque `web_search_tool_result` con el resultado. El ID de la llamada empieza por `srvtoolu_`. No envíes un `tool_result` de vuelta para ella.

```json theme={null}
[
  { "type": "server_tool_use", "id": "srvtoolu_1a2b", "name": "web_search", "input": { "query": "EU AI Act recent updates" } },
  {
    "type": "web_search_tool_result",
    "tool_use_id": "srvtoolu_1a2b",
    "content": [
      {
        "type": "web_search_result",
        "url": "https://example.com/eu-ai-act",
        "title": "EU AI Act: what changed this month",
        "encrypted_content": "The European Commission published new guidance...",
        "page_age": "2 days ago"
      }
    ]
  }
]
```

Zylon ejecuta la búsqueda, así que `encrypted_content` contiene el texto del resultado en texto plano, no datos cifrados.

Error:

```json theme={null}
{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_1a2b",
  "content": { "type": "web_search_tool_result_error", "error_code": "unavailable" }
}
```

Estos bloques no tienen campo `is_error`. Para detectar un fallo, comprueba si `content.type` termina en `_error` y lee `content.error_code`.

Con la extensión Zylon activada (`system.extensions` incluye `zylon`), el resultado se devuelve como un bloque `tool_result` simple con contenido `text`.

Consulta [Migración de 1.57 a 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) para ver la lista completa de bloques de herramientas de servidor.

## Consejos

* Usa consultas precisas para reducir ruido.

## Próximos pasos

* Formato de mensajes: [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)


# Herramientas personalizadas
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/custom/custom-tools

Define tus propias herramientas usando JSON Schema.

Las herramientas personalizadas permiten definir una interfaz (nombre + JSON Schema) y dejar que el asistente decida cuándo usarla. Cuando se usa, devuelve un bloque `tool_use` con `input` estructurado.

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).

## Requisitos

En la lista `tools`, incluye:

* `name`: nombre único
* `description`: qué hace la herramienta
* `inputSchema`: JSON Schema de la entrada

## Solicitud y respuesta básicas

Este ejemplo valida una herramienta de calculadora y fuerza su uso.

```bash theme={null}
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": 64,
    "messages": [
      { "role": "user", "content": "Add 5 and 7." }
    ],
    "tools": [
      {
        "name": "simple_calculator",
        "description": "Add two numbers.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "a": { "type": "number" },
            "b": { "type": "number" }
          },
          "required": ["a", "b"]
        }
      }
    ],
    "tool_choice": { "type": "tool", "name": "simple_calculator" }
  }'
```

Ejemplo de respuesta:

```json theme={null}
{ "valid": true, "errors": null }
```

Para ejecutar, envía el mismo cuerpo a `POST /messages`. Cuando el asistente devuelva un `tool_use`, ejecuta la herramienta y responde con un bloque `tool_result`.

> [!NOTE]
>
> Solo las herramientas personalizadas usan `tool_use` y `tool_result`. Las herramientas integradas se ejecutan en el servidor y devuelven bloques `server_tool_use` seguidos de su resultado; no envíes resultados de vuelta para ellas. Consulta [Cómo se devuelven los resultados de las herramientas integradas](/es/v1.58/developer-manual/build-with-zylon/tools/introduction-to-tools#cómo-se-devuelven-los-resultados-de-las-herramientas-integradas).


# Visión general
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/tools/introduction-to-tools

Habilita herramientas integradas y personalizadas en la API de mensajes.

Las herramientas permiten que el asistente ejecute operaciones específicas (como buscar artefactos, analizar datos tabulares o extraer una página web) como parte de una respuesta.

Puedes habilitar herramientas añadiendo tres campos a una petición `POST /messages`:

| Campo | Propósito |
| - | - |
| `tools` | Qué herramientas están permitidas. |
| `tool_choice` | Cómo debe elegir herramientas el asistente (`auto`, forzar una herramienta o `none`). |
| `tool_context` | Contexto opcional (documentos o conexiones de BD). |

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).
* El nombre de host de Zylon (sustituye `{BASE_URL}` en los ejemplos).

## Solicitud y respuesta básicas

Empieza con `POST /messages/validate` para validar el cuerpo de la petición sin ejecutar el modelo.

Este ejemplo habilita **Web Fetch**:

```bash theme={null}
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": 64,
    "messages": [
      { "role": "user", "content": "Summarize: https://example.com/" }
    ],
    "tools": [
      { "name": "web_extract", "type": "web_extract_v1" }
    ],
    "tool_choice": { "type": "auto" }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> { "valid": true, "errors": null }
> ```

Para ejecutar la petición, envía el mismo cuerpo a `POST /messages`.

## Herramientas integradas

Zylon incluye herramientas integradas:

| Tipo de herramienta | Qué hace | Requiere `tool_context` |
| - | - | - |
| `semantic_search_v1` | Buscar artefactos ingeridos | Sí (`ingested_artifact`) |
| `tabular_analysis_v1` | Analizar artefactos tabulares | Sí (`ingested_artifact`) |
| `web_extract_v1` | Extraer una URL del mensaje | No |
| `web_search_v1` | Buscar en la web | No |
| `database_query_v1` | Consultar una BD SQL | Sí (`sql_database`) |
| `code_execution_v1` | Ejecutar comandos bash y editar archivos en un contenedor aislado | No |

Guías:

* [Herramienta de búsqueda semántica](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/semantic-search-tool)
* [Herramienta de análisis tabular](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/tabular-analysis-tool)
* [Herramienta Web Fetch](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/web-fetch-tool)
* [Herramienta Web Search](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/web-search-tool)
* [Herramienta de consulta a base de datos](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/database-query-tool)
* [Herramienta de ejecución de código](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/code-execution-tool)

### Cómo se devuelven los resultados de las herramientas integradas

Zylon ejecuta las herramientas integradas en el servidor, dentro de la misma solicitud. Cada llamada aparece en la respuesta como un bloque `server_tool_use` (prefijo de ID `srvtoolu_`), seguido de su bloque de resultado:

| Herramienta | Bloque de resultado |
| - | - |
| `semantic_search`, `tabular_analysis`, `database_query`, `summarize`, `present_files`, skills, herramientas MCP | `server_tool_result` (`content`, `is_error`) |
| `web_search` | `web_search_tool_result` |
| `web_fetch` | `web_fetch_tool_result` |
| Ejecución de código: `bash_code_execution` | `bash_code_execution_tool_result` |
| Ejecución de código: `text_editor_code_execution` | `text_editor_code_execution_tool_result` |

```json theme={null}
[
  { "type": "server_tool_use", "id": "srvtoolu_9c0d", "name": "semantic_search", "input": { "query": "billing issues" } },
  {
    "type": "server_tool_result",
    "tool_use_id": "srvtoolu_9c0d",
    "content": [{ "type": "text", "text": "Customers reported duplicate charges after the plan change." }],
    "is_error": false
  }
]
```

No envíes resultados de vuelta para las herramientas integradas: Zylon ya las ha ejecutado. `stop_reason: "tool_use"` y los bloques `tool_result` solo se aplican a las [herramientas personalizadas](#herramientas-personalizadas). Cada guía de herramienta muestra su formato de resultado.

## Herramientas personalizadas

Las herramientas personalizadas te permiten definir una interfaz mediante JSON Schema.

Ver: [Herramientas personalizadas](/es/v1.58/developer-manual/build-with-zylon/tools/custom/custom-tools)

## Errores comunes

* **Nombre de campo**: usa `inputSchema` (no `input_schema`).
* **Falta de contexto**: algunas herramientas requieren `tool_context`.
* **Autenticación**: incluye `Authorization: Bearer ...` en cada petición.

## Próximos pasos

* Formato de mensajes: [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)
* Ingesta de contenido: [Artefactos](/es/v1.58/developer-manual/build-with-zylon/working-with-artifacts)


# Artefactos
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/working-with-artifacts

Crea e ingesta artefactos de ZylonGPT para recuperación y contexto.

Un **artefacto** es una pieza de información (o un recurso listo para herramientas) que incorporas a Zylon para poder usarla como contexto en consultas y operaciones. Los artefactos viven dentro de una **colección** y cada uno tiene un ID `artifact` estable.

Se pueden crear a partir de:

| Tipo | Entrada | Notas |
| - | - | - |
| **Text** | Cadena | Contenido directo. |
| **File** | Bytes en base64 | Para archivos como `.txt` o `.pdf`. |
| **URI** | URL | Zylon obtiene e ingesta el contenido. |

## Requisitos previos

* Un token de API con el scope de escritura necesario. Consulta [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console) o [Gestión de tokens](/es/v1.58/developer-manual/get-started/token-management).
* El nombre de host de Zylon (sustituye `{BASE_URL}` en los ejemplos).

> [!WARNING]
>
> Todas las operaciones de artefactos de ZylonGPT, incluidas ingesta, listado, recuperación de contenido, estado de tareas y eliminación, requieren un scope de lectura y escritura. `PrivateGPT.Read.All` y `Read.All` con `gateway_id` devuelven `403` para todas las rutas de artefactos. Un token `Read.All` sin contexto de gateway no puede llamar a ZylonGPT.

## Solicitud y respuesta básica

Usa `POST /artifacts/ingest` cuando quieras que la ingesta termine en la misma petición.

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "{collectionID}",
    "artifact": "{artifactID}",
    "input": {
      "type": "text",
      "value": "Release notes: Shipped billing dashboard and fixed three bugs."
    },
    "metadata": {
      "file_name": "release_notes.txt",
      "source": "docs"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "object": "list",
>   "model": "private-gpt",
>   "data": [
>     {
>       "object": "ingest.document",
>       "artifact": "docs_text_artifact_sync",
>       "doc_metadata": {
>         "file_name": "release_notes.txt"
>       }
>     }
>   ]
> }
> ```

> **Campos de respuesta de ingesta síncrona**
>
> | Campo | Tipo | Significado |
> | - | - | - |
> | `object`, `model` | string | Tipo de respuesta y modelo. |
> | `data` | object\[] | Referencias de documentos ingeridos. |
> | `data[].object`, `data[].artifact` | string | Tipo de documento e ID del artefacto. |
> | `data[].doc_metadata` | object | Campos opcionales de tipo string que admiten null: `window`, `original_text`, `page_label`, `file_name`, `doc_id`. |
> | `callback.properties` | JSON o null | Metadatos devueltos opcionales; es una clave literal del nivel superior, no un objeto anidado. |
>
> Los campos que admiten null pueden omitirse. La respuesta de ingesta síncrona no incluye metadatos arbitrarios del documento devueltos por el proveedor.

## Ingesta asíncrona

Usa `POST /artifacts/ingest/async` para cuerpos de petición más grandes o cuando la ingesta pueda tardar. Envuelve el cuerpo de ingesta síncrona en `ingest_body` e incluye el objeto obligatorio `callback`. Usa `callback: {}` si consultas el estado sin configurar callbacks. La respuesta devuelve un `task_id` que puedes consultar.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `ingest_body` | Si | Cuerpo de ingesta síncrona con `collection`, `artifact` e `input` obligatorios; `metadata` opcional. |
> | Body | `callback` | Si | Objeto de callback; se acepta `{}`. El campo opcional `properties` contiene datos de correlación. |

**Text**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}",
      "input": {
        "type": "text",
        "value": "Release notes: We shipped a new billing dashboard and fixed three bugs."
      },
      "metadata": {
        "file_name": "release_notes.txt",
        "source": "docs"
      }
    },
    "callback": {}
  }'
```

**File**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}",
      "input": {
        "type": "file",
        "value": "SGVsbG8gZnJvbSBmaWxlIGFydGlmYWN0Lgo="
      },
      "metadata": {
        "file_name": "onboarding_checklist.txt",
        "source": "docs"
      }
    },
    "callback": {}
  }'
```

**URI**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}",
      "input": {
        "type": "uri",
        "value": "https://example.com/"
      },
      "metadata": {
        "file_name": "example.html",
        "source": "docs"
      }
    },
    "callback": {}
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> { "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7" }
> ```

Consultar estado:

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async/{task_id}" \
  -H "Authorization: Bearer {API_TOKEN}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7",
>   "task_status": "PENDING",
>   "task_result": null
> }
> ```

## Listar artefactos

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/list?collection={collectionID}" \
  -H "Authorization: Bearer {API_TOKEN}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "object": "list",
>   "model": "private-gpt",
>   "data": [
>     {
>       "object": "ingest.document",
>       "artifact": "docs_file_artifact",
>       "doc_metadata": {
>         "file_name": "docs_file_artifact.txt",
>         "artifact_id": "docs_file_artifact",
>         "collection": "019c7569-f1f3-74da-8017-35d4a11f93ca"
>       }
>     }
>   ]
> }
> ```

## Recuperar contenido

### Contenido completo

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/content" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "context_filter": {
      "collection": "{collectionID}"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "artifact_id": "docs_file_artifact",
>       "content": "Hello from file artifact.\n\n"
>     }
>   ]
> }
> ```

### Contenido en fragmentos

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/chunked-content" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "context_filter": {
      "collection": "{collectionID}"
    },
    "max_tokens": 50
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "artifact_id": "docs_file_artifact",
>       "content": [
>         { "type": "source", "sources": [{ "object": "context.chunk", "id": "c5f20f0f-56e6-44e0-99e8-0d4ff4bb87eb" }] },
>         { "type": "text", "text": "**Context Information**:\nBelow is important information..." }
>       ]
>     }
>   ]
> }
> ```

## Eliminar artefactos

Eliminar (síncrono):

```bash theme={null}
curl -i -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "{collectionID}",
    "artifact": "{artifactID}"
  }'
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/2 200
>
> null
> ```

Eliminar (asíncrono):

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "delete_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> { "task_id": "2d48e74f-3eff-474e-b338-a931390ac218" }
> ```

Consultar estado:

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async/{task_id}" \
  -H "Authorization: Bearer {API_TOKEN}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "task_id": "2d48e74f-3eff-474e-b338-a931390ac218",
>   "task_status": "PENDING",
>   "task_result": null
> }
> ```

> [!TIP]
>
> Sigue consultando hasta que `task_status` sea `"SUCCESS"` o `"FAILURE"`.
> Si falla mientras el índice se completa, reintenta luego.

## Errores y casos límite

* **401/403**: token ausente o permisos insuficientes.
* **404**: colección o artefacto no encontrado.
* **409**: tarea de ingesta/eliminación ya en progreso.
* **413**: entrada demasiado grande para una ingesta.
* **422**: cuerpo de la petición inválido.
* **Fallos asíncronos**: cuando `task_status` es `FAILURE`, revisa `task_result` (por ejemplo `routing_key_error: "ingest.failed"` o `delete.failed`) y reintenta tras corregir la entrada.


# Mensajes
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/working-with-messages

Peticiones de Messages con patrones síncronos, streaming y asíncronos.

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](/es/v1.58/developer-manual/get-started/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](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview). `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**

```bash theme={null}
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." }
    ]
  }'
```

**Bloques de contenido**

```bash theme={null}
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**
>
> ```json theme={null}
> {
>   "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](/es/v1.58/developer-manual/build-with-zylon/tools/introduction-to-tools). |
> | `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](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#bloques-de-herramientas-de-servidor). |
> | `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](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/handling-stop-reasons).

## 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.

```bash theme={null}
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:

```json theme={null}
{ "valid": true, "errors": null }
```

## Conversaciones con varios turnos

Incluye turnos anteriores en `messages`:

```bash theme={null}
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**
>
> ```json theme={null}
> {
>   "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.

```bash theme={null}
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**
>
> ```json theme={null}
> {
>   "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`.

```bash theme={null}
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**
>
> ```json theme={null}
> {
>   "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`.

```bash theme={null}
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**
>
> ```text theme={null}
> 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

> [!WARNING]
>
> 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**
>
> ```json theme={null}
> {
>   "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
>   }
> }
> ```
>
> **Respuesta asíncrona**
>
> ```json theme={null}
> {
>   "message_id": "1cc8ed5e-fc7a-45e1-baf4-0b916ed32290",
>   "status": "pending",
>   "message": "Request initiated successfully"
> }
> ```

### Iniciar un mensaje asíncrono

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/handling-stop-reasons) para causas y soluciones.

## Próximos pasos

> **[Herramientas](/es/v1.58/developer-manual/build-with-zylon/tools/introduction-to-tools)**
>
> Deja que Zylon use herramientas integradas y personalizadas durante un mensaje.

> **[Artefactos](/es/v1.58/developer-manual/build-with-zylon/working-with-artifacts)**
>
> Ingiere texto, archivos o URI en colecciones reutilizables.


# Migración de API 1.57 -> 1.58
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58

Adapta tus integraciones de la API de Workspace a las rutas, cuerpos y respuestas de la versión 1.58.

Zylon 1.58 unifica las rutas de artefactos y separa las membresías del espacio de trabajo de las cuentas. Usa esta guía para actualizar integraciones creadas para 1.57. Abarca cambios en APIs existentes de Workspace y los nuevos [bloques de herramientas de servidor](#bloques-de-herramientas-de-servidor) que devuelven los mensajes de chat, tanto en la API de Workspace como en la de ZylonGPT.

> [!WARNING]
>
> **Cambios incompatibles: migra las integraciones antes de actualizar.**
>
> Las rutas antiguas de artefactos, integraciones y miembros quedan obsoletas en 1.58 y su retirada está prevista para 1.59. Otros alias aceptados tienen sus propias notas de compatibilidad más abajo. Usa las rutas actuales de 1.58 para integraciones nuevas o mantenidas.
>
> **Si tu integración depende de la identidad del usuario, IDs de creador o filtros de creador, migra las llamadas afectadas a la API actual y actualiza tus mapeos de identidad.** Que una URL antigua funcione no restaura el modelo de identidad de 1.57. Los campos de creador ahora identifican cuentas; las rutas de membresía siguen usando IDs de miembro. Sigue la [migración de IDs de usuario guardados](#migrar-ids-de-usuario-guardados) antes de confiar en búsquedas, comparaciones o filtros existentes.

## Requisitos previos

* Un token de API y el nombre de host de Zylon. Consulta [Gestión de tokens de Workspace](/es/v1.58/developer-manual/get-started/token-management).
* Envía `Authorization: Bearer {API_TOKEN}` y `x-org: {org_slug}` en las peticiones de Workspace.
* Envía `Content-Type: application/json` para cuerpos JSON. Deja que tu cliente HTTP establezca el delimitador de las peticiones multipart.

Las rutas de las tablas son relativas a `https://{BASE_URL}/api/v1`.

## Rutas de artefactos

Sustituye el prefijo de artefactos del proyecto o de la organización por `/app/artifact`. Indica explícitamente el proyecto para asignar la propiedad o filtrar cuando corresponda.

| Método | Ruta obsoleta | Ruta actual |
| - | - | - |
| `GET`, `POST` | `/app/project/{projectID}/artifact` o `/app/organization/artifact` | `/app/artifact` |
| `GET`, `PUT`, `DELETE` | Cualquiera de los prefijos antiguos + `/{artifactID}` | `/app/artifact/{artifactID}` |
| `POST` | Cualquiera de los prefijos antiguos + `/validate` | `/app/artifact/validate` |
| `POST` | Cualquiera de los prefijos antiguos + `/{artifactID}/validate` | `/app/artifact/{artifactID}/validate` |
| `GET` | Cualquiera de los prefijos antiguos + `/{artifactID}/download` | `/app/artifact/{artifactID}/download` |
| `GET` | `/app/project/{projectID}/artifact/{artifactID}/parsed-content` | `/app/artifact/{artifactID}/parsed-content` |
| `POST` | `/app/project/{projectID}/artifact/{artifactID}/retry` | `/app/artifact/{artifactID}/retry` |
| `POST` | `/app/project/{projectID}/artifact/{artifactID}/sync` | `/app/artifact/{artifactID}/sync` |
| `POST` | `/app/project/{projectID}/artifact/{artifactID}/ingest` | `/app/artifact/{artifactID}/ingest` |
| `PUT`, `DELETE` | `/app/project/{projectID}/artifact/bulk` | `/app/artifact/bulk` |

> **Parametros del endpoint**
>
> | Operación | Qué cambiar |
> | - | - |
> | Listar | Mueve el `projectID` de la ruta al parámetro de consulta `project_id`. Mantén `x-org` para seleccionar el espacio de trabajo. |
> | Crear, validar creación, reintentar | Mueve el `projectID` de la ruta al campo `project_id` del cuerpo. Omítelo o envía `null` para artefactos de organización. |
> | Ingerir | Envía `project_id` en el cuerpo JSON específico del proveedor. Conserva los parámetros existentes del proveedor. |
> | Otras operaciones por ID | El ID del artefacto identifica su propietario. Conserva los parámetros específicos de cada operación. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact?project_id={projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

Si usas `x-org`, no envíes también `organization_id`. Sin `x-org`, especificar `organization_id` requiere Operator o SuperAdmin. Crear artefactos de organización requiere AppAdmin o superior; los artefactos `Link` requieren un proyecto.

### Cuerpos de creación

El campo JSON actual `content` contiene **bytes de archivo o texto codificados en Base64**. Sustituye al antiguo campo de texto `raw_content`. Por ejemplo, el texto UTF-8 `Hello` se convierte en `SGVsbG8=`.

**Petición 1.57**

`POST /app/project/{projectID}/artifact`

```json theme={null}
{
  "type": "SmartDoc",
  "name": "Draft",
  "raw_content": "Hello",
  "props": {}
}
```

**Petición 1.58**

`POST /app/artifact`

```json theme={null}
{
  "project_id": "{projectID}",
  "type": "SmartDoc",
  "name": "Draft",
  "content": "SGVsbG8=",
  "props": {}
}
```

> **Cambios en el cuerpo**
>
> | Campo | Migración |
> | - | - |
> | `raw_content` | Sustitúyelo por `content` codificado en Base64 en las peticiones JSON actuales de creación, validación de creación y reintento. |
> | `file_data` | Conserva este campo de archivo multipart, también para subir skills. Añade `project_id` como campo del formulario para crear en un proyecto. |
> | `project_id` | Nueva ubicación del selector de la ruta antigua. Cadena opcional o `null`; necesario para asignar el artefacto a un proyecto. |
> | `organization_id` | Omítelo si envías `x-org`. Sin esa cabecera, está disponible para Operator/SuperAdmin autorizados. |
> | `props`, `private_props`, `integration_id` | Usa estos nombres canónicos. Siguen aceptándose los alias `config`, `private_config` (solo creación) e `integration_artifact_id`. |
> | `source` | Por defecto `User`. Los clientes no pueden establecer `Assistant` ni `System`. |

Los demás campos específicos de cada tipo mantienen sus reglas actuales. Consulta los [campos y tipos de artefactos](/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts#campos-de-petición-de-artefacto).

### Cuerpos de actualización

El antiguo `content` de actualización contenía **estado binario del editor codificado en Base64**. El `content` JSON actual contiene **texto UTF-8**, como Markdown. Exporta el documento del editor a Markdown; decodificar sus bytes Base64 no produce texto del documento.

**Petición 1.57**

`PUT /app/project/{projectID}/artifact/{artifactID}`

```json theme={null}
{
  "content": "{BASE64_EDITOR_STATE}",
  "plain_text_content": "Hello"
}
```

`{BASE64_EDITOR_STATE}` representa tu documento del editor ya codificado.

**Petición 1.58**

`PUT /app/artifact/{artifactID}`

```json theme={null}
{
  "content": "Hello"
}
```

> [!WARNING]
>
> Creación y actualización usan codificaciones distintas: **Base64 al crear con JSON, texto sin codificar al actualizar con JSON**. No envíes el antiguo estado del editor a la ruta actual de actualización: se trataría como texto literal.

El mismo formato se aplica a la validación de actualizaciones y a cada entrada `artifacts[].update` de las actualizaciones en lote. Las entradas siguen usando `artifactId` y `update`. Elimina `plain_text_content`: era un texto de búsqueda separado y ahora se deriva del documento. Para sustituir un archivo, usa `file_data` multipart en la ruta actual de actualización. Consulta [actualizar un artefacto](/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts#actualizar-un-artefacto).

### Qué peticiones antiguas siguen siendo compatibles

* La creación, validación y reintento con JSON aceptan `raw_content`; la creación multipart también acepta bytes de archivo. La creación antigua obtiene el proyecto de la URL y rechaza `project_id`, `organization_id` y el nuevo `content` JSON en el cuerpo.
* Las actualizaciones JSON antiguas convierten el estado del editor de Base64 a Markdown antes de guardar. El servicio de conversión de documentos de la instalación debe estar disponible. Se puede enviar contenido binario con o sin `plain_text_content`; este último campo por sí solo no sustituye el contenido.
* La actualización, validación de actualización y actualización en lote antiguas solo aceptan JSON. Usa el endpoint actual para sustituir archivos con multipart.
* Se rechaza una creación que combine `raw_content` y un archivo: no se pueden conservar ambos en el único campo de contenido actual. Envía una sola representación del contenido.
* Se rechazan campos desconocidos y tipos de datos no válidos. La creación en una organización solo acepta ámbitos de esa organización.

### Respuestas y selección de artefactos

Las respuestas antiguas conservan `has_content`, siempre `false`: este campo describía el contenido binario del editor, no la existencia de un archivo. Los bytes originales del editor no se pueden reconstruir, por lo que `content` es nulo/se omite.

En las consultas de detalle de artefactos por la URL antigua, añade `include_content=true` para recibir el texto UTF-8 disponible como `raw_content`. El valor por defecto es `false`; los listados y las respuestas de escritura no incluyen texto. Se conservan los espacios y el texto vacío. Los archivos no textuales y el UTF-8 inválido no generan `raw_content`. Se aplican los permisos actuales de descarga: si están desactivadas, devuelve `403`; si falta el archivo almacenado, devuelve el error actual de descarga.

> **Campos de contenido antiguos (respuesta parcial)**
>
> ```json theme={null}
> {
>   "has_content": false,
>   "raw_content": "# Documento actual"
> }
> ```
>
> Los campos nulos se omiten. No se genera `content` binario del editor en Base64 a partir del texto.

Las respuestas actuales de artefactos omiten estos campos de contenido antiguos. Usa `/app/artifact/{artifactID}/download` para obtener el contenido almacenado. `/app/artifact/{artifactID}/parsed-content` devuelve texto extraído y requiere un índice vectorial inicializado. La descarga devuelve una URL prefirmada por defecto; con `Content-Disposition: attachment` devuelve los bytes del archivo. Las URLs antiguas de descarga también admiten ambos modos.

`created_by` ahora representa una **cuenta**. Actualiza el código que lee los datos del creador o compara sus IDs; consulta [IDs de cuenta y campos renombrados](#ids-de-cuenta-y-campos-renombrados).

`scopes[].ws_auto_select` y `scopes[].enabled` ya existían en las versiones publicadas de 1.57 y siguen siendo compatibles, incluido `enabled: false`. El campo anterior `ws_auto_select` de nivel superior no se acepta. Las skills siguen usando `file_data`; no hay una migración independiente de su cuerpo. Consulta los [ámbitos de artefactos](/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts#añadir-o-eliminar-un-alcance).

## Miembros del espacio de trabajo

Los datos de usuario se unifican en la **cuenta**: la identidad, el nombre, el correo y la imagen de perfil pertenecen a la cuenta. El antiguo usuario pasa a ser una **membresía del espacio de trabajo**, que mantiene los roles, permisos y estado activo/inactivo de esa cuenta dentro del espacio.

Sustituye `/app/user` por `/app/member`. Los IDs de estas rutas siguen siendo **IDs de miembro del espacio de trabajo**, no IDs de cuenta.

| Método | Ruta obsoleta | Ruta actual |
| - | - | - |
| `GET`, `POST` | `/app/user` | `/app/member` |
| `GET`, `PUT` | `/app/user/{wsMemberId}` | `/app/member/{wsMemberId}` |
| `POST` | `/app/user/{wsMemberId}/activate` o `/deactivate` | `/app/member/{wsMemberId}/activate` o `/deactivate` |
| `GET` | `/app/user/{wsMemberId}/project` | `/app/member/{wsMemberId}/project` |
| `GET` | `/app/user/{wsMemberId}/latest-artifacts` | `/app/member/{wsMemberId}/latest-artifacts` |

Las respuestas antiguas de `/app/user` al listar, consultar, crear, cambiar el rol, activar o desactivar un miembro conservan `name`, `email` y `profile_picture` (si está disponible) en el primer nivel, tomados del perfil actual de la cuenta. Se mantienen `id`, `org_id`, `account_id`, `state`, `roles` y `created_at` de la membresía. Los datos eliminados del puesto de trabajo no se pueden recuperar y son nulos/se omiten. Estos campos de respuesta no restauran las actualizaciones de perfil mediante la ruta antigua del miembro.

`GET /app/me` conserva su URL, pero también devuelve el nuevo modelo de miembro. El nombre, el correo y la imagen de perfil son datos de la cuenta y ya no son campos de primer nivel del miembro. Solicita `include=Account` al listar miembros, consultar un miembro o llamar a `/app/me` para recibir la cuenta anidada.

> **Parametros del endpoint**
>
> | Operación | Petición |
> | - | - |
> | `POST /app/member` | `account_id` y `role` son cadenas obligatorias. No se restaura el antiguo campo `user_info`. |
> | `PUT /app/member/{wsMemberId}` | `role` es una cadena obligatoria. Los campos de perfil ya no se actualizan aquí, tampoco mediante la URL antigua. |
> | Listado de miembros | `state` opcional: `Active`, `Inactive`, separados por comas; ambos por defecto. No se conserva la ordenación antigua con `order_by`/`order`. |
> | Lecturas de miembros | `include=Account` opcional. |
>
> Roles del espacio de trabajo: `AppGuest`, `AppMember`, `AppAdmin`, `AppOwner`.

Actualiza los campos de perfil con `POST /account/{accountId}` (`me` permite actualizar tu propia cuenta), en lugar del endpoint de miembros. Los antiguos campos `job_position_name` y `job_position_description` se eliminan del miembro; no forman parte del modelo de cuenta.

> **Respuesta actual de miembro**
>
> | Campo | Tipo | Significado |
> | - | - | - |
> | `id` | string | ID de miembro del espacio de trabajo. |
> | `org_id` | string | ID de organización. |
> | `account_id` | string | ID de cuenta, distinto del ID de miembro. |
> | `state` | string | `Active` o `Inactive`. |
> | `roles` | string\[] | Roles del espacio de trabajo. |
> | `created_at` | timestamp | Fecha de creación de la membresía, generada por el servidor. |
> | `account` | object o null | Datos de la cuenta cuando se solicitan. Consulta el [ejemplo completo de miembro y cuenta](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user#obtener-el-miembro-actual). |

## IDs de cuenta y campos renombrados

### Migrar IDs de usuario guardados

Si tu cliente guardó `userId` a partir del campo `id` de una respuesta `/app/user` de 1.57, ese valor es un ID de miembro del espacio de trabajo. **No sustituyas todos los `userId` por `accountId`: identifican registros distintos.** Una cuenta puede tener IDs de miembro diferentes en distintas organizaciones.

1. Conserva el ID de miembro guardado y su organización. Usa el endpoint actual de miembros para leer el ID de cuenta asociado:

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Ruta | `wsMemberId` | Si | El ID de miembro que antes devolvía `id` en el usuario antiguo. |
> | Cabecera | `x-org` | Si | La organización que contiene esa membresía. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member/{wsMemberId}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Respuesta de mapeo de IDs (campos seleccionados)**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "org_id": "{orgId}",
>   "account_id": "{accountId}"
> }
> ```
>
> `account_id` se devuelve sin un parámetro `include`. Añade `include=Account` si también necesitas el perfil de cuenta; consulta la [respuesta completa de miembro](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user#obtener-el-miembro-actual).

2. Guarda ambos IDs con nombres distintos. Usa `account_id` para comparar con `created_by.id` de artefactos, hilos, interacciones e incidencias, y para los filtros `created_by` de artefactos o incidencias. Conserva el `id` de miembro para `/app/member/{wsMemberId}`, miembros de proyecto, transferencia de propiedad y `metadata.ws_member_id` del chat.
3. Actualiza las llamadas afectadas a las rutas actuales y nombres canónicos, y comprueba tus relaciones y filtros guardados. Por ejemplo, un filtro de creador de artefactos debe usar `created_by={accountId}`; una petición de miembro de proyecto sigue usando `ws_member_id: "{wsMemberId}"`.

Para tu propia identidad, `GET /api/v1/app/me` devuelve la misma distinción entre `id` y `account_id`. Para migrar un directorio, pagina `/app/member` por separado en cada organización y crea un mapeo de IDs de miembro a IDs de cuenta. Si tu aplicación necesita un ID de miembro para la cuenta de un creador, resuelve su membresía en la organización seleccionada; un ID de cuenta por sí solo no identifica una membresía concreta.

### Qué conservan los alias antiguos

Las lecturas de `/app/user` antiguo pueden restaurar campos de perfil seleccionados, como `name` y `email`, pero `id` sigue siendo un ID de miembro y `account_id` sigue siendo un ID de cuenta. Los objetos de creador de artefactos antiguos ya usan IDs de cuenta. `include=User` en las consultas de creador compatibles selecciona datos de cuenta; no restaura el antiguo objeto de usuario del espacio de trabajo ni convierte IDs de creador.

Usa los alias antiguos solo como puente temporal para los formatos de petición documentados en esta guía. Si tu integración necesita las relaciones antiguas de IDs de usuario, filtros de creador o comportamiento de actualización de perfil, migra a la API actual y al modelo de cuenta/miembro descrito arriba. Cambiar solo la URL o el nombre de campo no basta.

### Usar nombres de campo canónicos

Los alias temporales siguientes aceptan ciertos nombres de entrada antiguos. Las respuestas mantienen el modelo y los nombres de campo actuales; los alias no convierten IDs de miembro en IDs de cuenta.

| Dónde | Anterior | Actual / acción necesaria |
| - | - | - |
| Entradas de creación/actualización de miembros de proyecto | `user_id` | Usa `ws_member_id`; el nombre anterior sigue siendo un alias de entrada. El valor sigue siendo un ID de miembro. |
| Metadatos de chat (Workspace y ZylonGPT) | `metadata.user_id` | Usa `metadata.ws_member_id`; `user_id` sigue siendo un alias de entrada. Envía solo un nombre. El valor sigue siendo un ID de miembro, no de cuenta. |
| Transferencia de propiedad de proyecto | `old_owner_id`, `new_owner_id` | Usa `old_owner_ws_member_id`, `new_owner_ws_member_id`; los nombres anteriores siguen siendo alias de entrada. |
| Consulta `include` de artefactos, hilos, interacciones e incidencias | `User` | Usa `Account`; `User` sigue siendo un alias de entrada. |
| Consulta `include` del listado de cuentas | `Users` | Usa `WorkspaceMembers`; `Users` sigue siendo un alias de entrada. |
| Membresías en la respuesta de cuenta | `users` | Lee `workspace_members`. |
| Respuesta de miembro de proyecto | `user` | Lee `account`; `id` sigue siendo un ID de miembro del espacio de trabajo. |
| Respuesta `created_by` de artefactos, hilos, interacciones e incidencias | Miembro del espacio de trabajo | Lee un objeto de cuenta y su ID de cuenta. |
| Filtro `created_by` de artefactos | ID de miembro | Envía un ID de cuenta. No se convierten los IDs automáticamente. |
| Filtro `created_by` de incidencias | IDs de miembro | Envía IDs de cuenta separados por comas. No se convierten los IDs automáticamente. |

Consulta [miembros de proyecto](/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project-member), [transferencia de propiedad](/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project) y [filtros de incidencias](/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/issues) para ver los cuerpos y respuestas actuales completos.

## Chats e hilos

### Mover el chat de proyecto a la ruta unificada

Sustituye `POST /app/project/{projectID}/chat` por `POST /app/chat` y mueve el selector de proyecto al cuerpo. Usa una petición de mensajes envuelta en `pgpt` (`private_gpt` sigue siendo un alias de entrada). La ruta actual también acepta una petición antigua sin envolver para contexto del espacio de trabajo, pero los selectores de proyecto y artefactos requieren el cuerpo envuelto. `/app/chat/validate` recibe la petición de mensajes sin envolver.

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/chat" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "pgpt": {
      "messages": [{ "role": "user", "content": "Resume el proyecto." }]
    }
  }'
```

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Migración |
> | - | - | - | - |
> | Body | `project_id` | No | Antes se indicaba en la ruta. Inclúyelo para contexto de proyecto; omítelo para contexto del espacio de trabajo. |
> | Body | `pgpt` | Si | Petición de mensajes. Consulta [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages). |
> | Body | `artifacts` | No | Objeto de selección por ámbito descrito abajo. |

> [!WARNING]
>
> La respuesta actual de `/app/chat` es **siempre SSE**, incluso con `pgpt.stream: false`. La URL de chat de proyecto conservada devuelve JSON cuando ese indicador es `false` y SSE cuando es `true`. Adapta los clientes que esperan JSON antes de cambiar la URL. El alias de chat de proyecto no tiene asignada una versión de retirada.

Para seleccionar artefactos, usa `artifacts.document`, `artifacts.connector`, `artifacts.skill` o `artifacts.agent_flow`. Cada campo es un array de selectores con `scope` (`organization` o `project`), `all_artifacts` opcional y `artifacts_ids` opcional (observa el plural). Por ejemplo:

```json theme={null}
{
  "artifacts": {
    "document": [
      { "scope": "project", "artifacts_ids": ["{artifactID}"] }
    ]
  }
}
```

Es un cuerpo parcial que debes combinar con `pgpt` y, para el ámbito de proyecto, `project_id`. No envíes los campos de los ejemplos antiguos de referencia `artifact_ids` o `all_artifacts` en el nivel superior: los campos desconocidos se ignoran y no seleccionan artefactos. Una categoría no puede repetir el mismo ámbito ni combinar `all_artifacts: true` con `artifacts_ids` no vacío. Consulta [peticiones de chat](/es/v1.58/developer-manual/build-with-zylon/workspace-api/chats/threads#chat-puntual).

### Archivos de hilo y estado de lectura

1.58 añade la escritura de archivos sin multipart con `PUT /app/thread/{threadID}/put-file/{path...}`. Envía los bytes en el cuerpo. `POST /app/thread/{threadID}/upload-file` sigue usando el campo multipart `file` y ahora acepta `path` y `namespace` opcionales. Las subidas multipart, escrituras sin multipart y descargas seleccionan `session` (por defecto), `artifacts` o `skills` mediante `namespace`; la descarga también acepta `disposition=attachment` (por defecto) o `inline`. Consulta [archivos de hilo](/es/v1.58/developer-manual/build-with-zylon/workspace-api/chats/threads#archivos-del-hilo) para subida, descarga y conversión de artefactos MDX.

En los listados de hilos del proyecto, solicita `include=ReadState` para recibir `read_state.last_read_at` y `read_state.has_unread_response`. Un hilo nuevo creado por otra cuenta también puede contar como no leído. Listar interacciones con `GET /app/thread/{threadID}/interaction` ahora avanza el punto de lectura del solicitante hasta las respuestas completadas devueltas. Los clientes que consultan este endpoint periódicamente pueden marcar así el contenido como leído; tenlo en cuenta en la lógica de notificaciones y sondeo.

## Peticiones de filesystem

| Método | Ruta obsoleta | Ruta actual |
| - | - | - |
| `GET` | `/app/project/{projectID}/artifact/{integrationArtifactID}/files` | `/app/artifact/{integrationArtifactID}/files` |
| `POST` | `/app/project/{projectID}/artifact/integration/filesystem/validate` | `/app/artifact/integration/filesystem/validate` |

La validación de credenciales requiere el **cuerpo anidado actual en ambas URLs**. Las credenciales antiguas sin anidar no se adaptan.

> **Cuerpo de la petición**
>
> | Campo | Tipo | Obligatorio | Notas |
> | - | - | - | - |
> | `organization_id` | string | Si | Debe coincidir con el espacio de trabajo autenticado. Es obligatorio en esta operación incluso al enviar `x-org`. |
> | `project_id` | string o null | No | Indica el proyecto explícitamente; su validación requiere Project Admin. Sin él, se requiere AppAdmin o superior en el espacio de trabajo. |
> | `credentials` | object | Si | Campos de credenciales anidados que se detallan a continuación. |
> | `credentials.username` | string | Si | Usuario de filesystem. |
> | `credentials.password` | string | Si | Contraseña de filesystem. |

```json theme={null}
{
  "organization_id": "{orgId}",
  "project_id": "{projectID}",
  "credentials": {
    "username": "***",
    "password": "***"
  }
}
```

Esta operación devuelve un booleano. Consulta [validar credenciales de filesystem](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/filesystem#validar-credenciales) para ver un ejemplo completo. La ingestión desde integraciones usa la ruta unificada `/ingest` y `project_id` en el cuerpo, como se describe arriba.

## Bloques de herramientas de servidor

En 1.57, cada llamada a herramienta de un mensaje se devolvía como un bloque `tool_use` seguido de un bloque `tool_result`, tanto si la ejecutaba Zylon como si la ejecutaba tu aplicación. En 1.58, las herramientas que **Zylon ejecuta en el servidor** usan el formato de herramientas de servidor de la API de Mensajes de Anthropic. Las herramientas que **ejecuta tu aplicación** (herramientas personalizadas) no cambian y siguen usando `tool_use` y `tool_result`.

Esto afecta al contenido de los mensajes en los eventos en streaming, en las interacciones guardadas de los hilos y en las respuestas de `/messages`. Actualiza cualquier código que detecte llamadas a herramientas comprobando `type == "tool_use"` o `type == "tool_result"`.

| Nombre en 1.57 | Nombre en 1.58 | Bloque de llamada en 1.58 | Bloque de resultado en 1.58 |
| - | - | - | - |
| `web_search` | `web_search` | `server_tool_use` | `web_search_tool_result` |
| `web_extract` (`web_fetch` en la ZylonGPT API) | Sin cambios | `server_tool_use` | `web_fetch_tool_result` |
| `bash` | `bash_code_execution` | `server_tool_use` | `bash_code_execution_tool_result` |
| `view`, `create`, `str_replace`, `insert` | `text_editor_code_execution`, con la operación en `input.command` | `server_tool_use` | `text_editor_code_execution_tool_result` |
| `semantic_search`, `summarize`, `tabular_analysis`, `database_query`, `present_files`, `present_server`, herramientas de skills, herramientas MCP | Sin cambios | `server_tool_use` | `server_tool_result` |
| Herramientas personalizadas que ejecuta tu aplicación | Sin cambios | `tool_use` (sin cambios) | `tool_result` (sin cambios) |

* `server_tool_use.name` es el `name` de la herramienta en la solicitud. Los chats del Workspace envían la herramienta web fetch como `web_extract`, así que sus llamadas aparecen como `web_extract`; los clientes de la ZylonGPT API ven el nombre que enviaron (`web_extract` o `web_fetch`). Identifica el resultado por el tipo de bloque (`web_fetch_tool_result`) en lugar del nombre.
* Los IDs de las llamadas a herramientas de servidor empiezan por `srvtoolu_`, y los de herramientas de cliente, por `tool_`. El `tool_use_id` del resultado hace referencia al ID de la llamada, como antes.
* Zylon ya ha ejecutado las herramientas de servidor, así que no envíes un resultado para ellas. `stop_reason: "tool_use"` sigue aplicándose solo a las herramientas que ejecuta tu aplicación.
* Los bloques siguen el [formato de herramientas de servidor de Anthropic](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), por lo que los SDKs de Anthropic pueden leerlos directamente. Ignora los campos que no reconozcas, porque Zylon puede añadir campos adicionales.

### Reglas de migración

* **Herramientas de servidor genéricas** (`server_tool_result`): solo cambian los valores de `type` de los bloques y el prefijo del ID. `content` e `is_error` funcionan como antes, así que puedes reutilizar tu parser de 1.57.
* **Herramientas web y de ejecución de código**: `content` es ahora un objeto tipado (o una lista de objetos tipados en la búsqueda web) en lugar de una lista de bloques `text`. Estos bloques **no tienen campo `is_error`**. Para detectar un fallo, comprueba si `content.type` termina en `_error` y lee `content.error_code`.
* **Fallos que 1.57 devolvía como texto**: en 1.57, las herramientas del editor de texto devolvían los fallos como un `tool_result` correcto cuyo texto empezaba por `Error:`. En 1.58 devuelven un objeto de error.
* **Códigos de salida distintos de cero**: un comando bash que termina con un código distinto de cero no es un error en ninguna de las dos versiones. En 1.58, lee `return_code` en lugar de extraer `exit_code:` del texto.

| Qué leías en 1.57 | Dónde leerlo en 1.58 |
| - | - |
| `tool_use.name` | `server_tool_use.name` (consulta la tabla de nombres anterior) |
| `tool_use.input` | `server_tool_use.input` (las llamadas al editor de texto añaden `command`) |
| `tool_result.is_error: true` | `server_tool_result.is_error: true`, o `content.type` terminado en `_error` en los resultados tipados |
| Líneas `exit_code`, `stdout` y `stderr` del texto de bash | `content.return_code`, `content.stdout`, `content.stderr` |
| Texto de salida del editor de texto | `content` tipado según el comando: resultado de `view`, `create` o `str_replace` |
| Lista de texto de la búsqueda web | `content[]` de `web_search_result` (`url`, `title`, `encrypted_content`, `page_age`) |
| Texto Markdown de web fetch | `content.content.source.data` |

### Ejemplos de migración por herramienta

Cada ejemplo muestra el bloque de llamada y el bloque de resultado de una llamada correcta y de una llamada fallida. Los IDs, las entradas y los textos de resultado son solo ejemplos.

> **web\_search**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_1a2b", "name": "web_search", "input": { "query": "support backlog report" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_1a2b",
>     "content": [
>       {
>         "type": "text",
>         "text": "1. Quarterly Report\nDescription: Support metrics for Q3\nURL: https://example.com/report\nAge: 2 days ago\nContent: Support backlog dropped 8%.\n"
>       }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "tool_1a2b",
>   "content": "Web search provider timed out",
>   "is_error": true
> }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_1a2b", "name": "web_search", "input": { "query": "support backlog report" } },
>   {
>     "type": "web_search_tool_result",
>     "tool_use_id": "srvtoolu_1a2b",
>     "content": [
>       {
>         "type": "web_search_result",
>         "url": "https://example.com/report",
>         "title": "Quarterly Report",
>         "encrypted_content": "Support backlog dropped 8%.",
>         "page_age": "2 days ago"
>       }
>     ]
>   }
> ]
> ```
>
> Zylon ejecuta la búsqueda, así que `encrypted_content` contiene el texto del resultado en texto plano, no datos cifrados.
>
> Error (`content` es un objeto, no una lista):
>
> ```json theme={null}
> {
>   "type": "web_search_tool_result",
>   "tool_use_id": "srvtoolu_1a2b",
>   "content": { "type": "web_search_tool_result_error", "error_code": "unavailable" }
> }
> ```
>
> **1.58 con extensión de Zylon**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_1a2b", "name": "web_search", "input": { "query": "support backlog report" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "srvtoolu_1a2b",
>     "content": [
>       {
>         "type": "source",
>         "sources": [
>           {
>             "object": "context.website",
>             "url": "https://example.com/report",
>             "title": "Quarterly Report",
>             "description": "Support metrics for Q3",
>             "content": "Support backlog dropped 8%."
>           }
>         ]
>       },
>       { "type": "text", "text": "Support backlog dropped 8%." }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "srvtoolu_1a2b",
>   "content": [{ "type": "text", "text": "Web search error: Web search provider timed out" }],
>   "is_error": true
> }
> ```

> **web\_extract (web fetch)**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_3c4d", "name": "web_extract", "input": { "url": "https://example.com" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_3c4d",
>     "content": [{ "type": "text", "text": "# Example page\n\nWelcome to the example page." }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "tool_3c4d",
>   "content": "403 Forbidden",
>   "is_error": true
> }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_3c4d", "name": "web_extract", "input": { "url": "https://example.com" } },
>   {
>     "type": "web_fetch_tool_result",
>     "tool_use_id": "srvtoolu_3c4d",
>     "content": {
>       "type": "web_fetch_result",
>       "url": "https://example.com",
>       "retrieved_at": "2026-09-24T10:00:00Z",
>       "content": {
>         "type": "document",
>         "title": "Example",
>         "source": {
>           "type": "text",
>           "media_type": "text/plain",
>           "data": "# Example page\n\nWelcome to the example page."
>         }
>       }
>     }
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> {
>   "type": "web_fetch_tool_result",
>   "tool_use_id": "srvtoolu_3c4d",
>   "content": { "type": "web_fetch_tool_result_error", "error_code": "unavailable" }
> }
> ```
>
> Valores posibles de `error_code`: `invalid_tool_input`, `url_too_long`, `url_not_allowed`, `url_not_in_prior_context`, `url_not_accessible`, `unsupported_content_type`, `too_many_requests`, `max_uses_exceeded`, `unavailable`.
>
> **1.58 con extensión de Zylon**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_3c4d", "name": "web_extract", "input": { "url": "https://example.com" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "srvtoolu_3c4d",
>     "content": [{ "type": "text", "text": "# Example page\n\nWelcome to the example page." }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "srvtoolu_3c4d",
>   "content": [{ "type": "text", "text": "Web fetch error: 403 Forbidden" }],
>   "is_error": true
> }
> ```

> **bash → bash\_code\_execution**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_5e6f", "name": "bash", "input": { "command": "ls /tmp/outputs" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_5e6f",
>     "content": [{ "type": "text", "text": "exit_code: 0\n\nstdout:\nreport.csv\n" }],
>     "is_error": false
>   }
> ]
> ```
>
> Un comando con código de salida distinto de cero:
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "tool_5e6f",
>   "content": [{ "type": "text", "text": "exit_code: 2\n\nstderr:\nls: cannot access 'missing': No such file or directory\n" }],
>   "is_error": false
> }
> ```
>
> Error (la herramienta no se pudo ejecutar):
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "tool_5e6f",
>   "content": "code_execution provider is not configured.",
>   "is_error": true
> }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_5e6f", "name": "bash_code_execution", "input": { "command": "ls /tmp/outputs" } },
>   {
>     "type": "bash_code_execution_tool_result",
>     "tool_use_id": "srvtoolu_5e6f",
>     "content": {
>       "type": "bash_code_execution_result",
>       "stdout": "report.csv\n",
>       "stderr": "",
>       "return_code": 0
>     }
>   }
> ]
> ```
>
> Un comando con código de salida distinto de cero:
>
> ```json theme={null}
> {
>   "type": "bash_code_execution_tool_result",
>   "tool_use_id": "srvtoolu_5e6f",
>   "content": {
>     "type": "bash_code_execution_result",
>     "stdout": "",
>     "stderr": "ls: cannot access 'missing': No such file or directory\n",
>     "return_code": 2
>   }
> }
> ```
>
> Error (la herramienta no se pudo ejecutar):
>
> ```json theme={null}
> {
>   "type": "bash_code_execution_tool_result",
>   "tool_use_id": "srvtoolu_5e6f",
>   "content": { "type": "bash_code_execution_tool_result_error", "error_code": "unavailable" }
> }
> ```
>
> Valores posibles de `error_code`: `unavailable`, `execution_time_exceeded`, `invalid_tool_input`, `too_many_requests`, `output_file_too_large`, `file_not_found`.
>
> **1.58 con extensión de Zylon**
>
> Los resultados correctos son iguales que sin la extensión. Los objetos de error incluyen además `detail`, con el error original:
>
> ```json theme={null}
> {
>   "type": "bash_code_execution_tool_result",
>   "tool_use_id": "srvtoolu_5e6f",
>   "content": {
>     "type": "bash_code_execution_tool_result_error",
>     "error_code": "unavailable",
>     "detail": { "code": "execution_failed", "explanation": "code_execution provider is not configured." }
>   }
> }
> ```

> **view, create, str\_replace, insert → text\_editor\_code\_execution**
>
> En 1.57, cada operación era una herramienta distinta. En 1.58 todas son `text_editor_code_execution` y la operación se indica en `input.command`. El resto de campos de entrada mantienen su nombre. En `insert`, 1.58 acepta tanto `insert_text` como `new_str`.
>
> | Llamada en 1.57 | Llamada en 1.58 |
> | - | - |
> | `view` `{ "path" }` | `text_editor_code_execution` `{ "command": "view", "path" }` |
> | `create` `{ "path", "file_text" }` | `text_editor_code_execution` `{ "command": "create", "path", "file_text" }` |
> | `str_replace` `{ "path", "old_str", "new_str" }` | `text_editor_code_execution` `{ "command": "str_replace", "path", "old_str", "new_str" }` |
> | `insert` `{ "path", "insert_line", "new_str" }` | `text_editor_code_execution` `{ "command": "insert", "path", "insert_line", "insert_text" }` |
>
> | Comando | Texto de resultado en 1.57 | `content.type` en 1.58 |
> | - | - | - |
> | `view` | Líneas del archivo numeradas | `text_editor_code_execution_view_result` |
> | `create` | `Created <path>` | `text_editor_code_execution_create_result` |
> | `str_replace` | `Updated <path>` | `text_editor_code_execution_str_replace_result` |
> | `insert` | `Updated <path>` | `text_editor_code_execution_str_replace_result` |
>
> **1.57**
>
> `view`:
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_7a8b", "name": "view", "input": { "path": "/tmp/outputs/app.py" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_7a8b",
>     "content": [{ "type": "text", "text": "1: total = 0\n2: print(total)" }],
>     "is_error": false
>   }
> ]
> ```
>
> `create`:
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_7a8c", "name": "create", "input": { "path": "/tmp/outputs/app.py", "file_text": "total = 0\n" } },
>   { "type": "tool_result", "tool_use_id": "tool_7a8c", "content": [{ "type": "text", "text": "Created /tmp/outputs/app.py" }], "is_error": false }
> ]
> ```
>
> `str_replace`:
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_7a8d", "name": "str_replace", "input": { "path": "/tmp/outputs/app.py", "old_str": "total = 0", "new_str": "total = 100" } },
>   { "type": "tool_result", "tool_use_id": "tool_7a8d", "content": [{ "type": "text", "text": "Updated /tmp/outputs/app.py" }], "is_error": false }
> ]
> ```
>
> `insert`:
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_7a8e", "name": "insert", "input": { "path": "/tmp/outputs/app.py", "insert_line": 1, "new_str": "print(total)" } },
>   { "type": "tool_result", "tool_use_id": "tool_7a8e", "content": [{ "type": "text", "text": "Updated /tmp/outputs/app.py" }], "is_error": false }
> ]
> ```
>
> Error. Los errores de archivo se devolvían como un resultado correcto cuyo texto empezaba por `Error:`:
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "tool_7a8b",
>   "content": [{ "type": "text", "text": "Error: File not found: /tmp/outputs/missing.py" }],
>   "is_error": false
> }
> ```
>
> **1.58**
>
> `view`:
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_7a8b", "name": "text_editor_code_execution", "input": { "command": "view", "path": "/tmp/outputs/app.py" } },
>   {
>     "type": "text_editor_code_execution_tool_result",
>     "tool_use_id": "srvtoolu_7a8b",
>     "content": {
>       "type": "text_editor_code_execution_view_result",
>       "file_type": "text",
>       "content": "total = 0\nprint(total)",
>       "num_lines": 2,
>       "start_line": 1,
>       "total_lines": 2
>     }
>   }
> ]
> ```
>
> `create`:
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_7a8c", "name": "text_editor_code_execution", "input": { "command": "create", "path": "/tmp/outputs/app.py", "file_text": "total = 0\n" } },
>   {
>     "type": "text_editor_code_execution_tool_result",
>     "tool_use_id": "srvtoolu_7a8c",
>     "content": { "type": "text_editor_code_execution_create_result", "is_file_update": false }
>   }
> ]
> ```
>
> `str_replace`:
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_7a8d", "name": "text_editor_code_execution", "input": { "command": "str_replace", "path": "/tmp/outputs/app.py", "old_str": "total = 0", "new_str": "total = 100" } },
>   {
>     "type": "text_editor_code_execution_tool_result",
>     "tool_use_id": "srvtoolu_7a8d",
>     "content": {
>       "type": "text_editor_code_execution_str_replace_result",
>       "old_start": 1,
>       "old_lines": 1,
>       "new_start": 1,
>       "new_lines": 1,
>       "lines": ["- total = 0", "+ total = 100"]
>     }
>   }
> ]
> ```
>
> `insert` (devuelve un resultado de `str_replace` con `old_lines: 0`):
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_7a8e", "name": "text_editor_code_execution", "input": { "command": "insert", "path": "/tmp/outputs/app.py", "insert_line": 1, "insert_text": "print(total)" } },
>   {
>     "type": "text_editor_code_execution_tool_result",
>     "tool_use_id": "srvtoolu_7a8e",
>     "content": {
>       "type": "text_editor_code_execution_str_replace_result",
>       "old_start": 2,
>       "old_lines": 0,
>       "new_start": 2,
>       "new_lines": 1,
>       "lines": ["+ print(total)"]
>     }
>   }
> ]
> ```
>
> Error. Los errores de archivo devuelven ahora un objeto de error:
>
> ```json theme={null}
> {
>   "type": "text_editor_code_execution_tool_result",
>   "tool_use_id": "srvtoolu_7a8b",
>   "content": { "type": "text_editor_code_execution_tool_result_error", "error_code": "unavailable" }
> }
> ```
>
> Los códigos de error son los mismos que en `bash_code_execution`.
>
> **1.58 con extensión de Zylon**
>
> Los resultados correctos son iguales que sin la extensión. Los objetos de error incluyen además `detail`, con el error original:
>
> ```json theme={null}
> {
>   "type": "text_editor_code_execution_tool_result",
>   "tool_use_id": "srvtoolu_7a8b",
>   "content": {
>     "type": "text_editor_code_execution_tool_result_error",
>     "error_code": "unavailable",
>     "detail": { "code": "execution_failed", "explanation": "File not found: /tmp/outputs/missing.py" }
>   }
> }
> ```

> **semantic\_search**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_9c0d", "name": "semantic_search", "input": { "query": "billing issues" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_9c0d",
>     "content": [
>       { "type": "source", "sources": [{ "object": "context.chunk", "id": "chunk_1", "text": "Customers reported duplicate charges..." }] },
>       { "type": "text", "text": "Customers reported duplicate charges after the plan change." }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_9c0d", "content": "context_filter is required", "is_error": true }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_9c0d", "name": "semantic_search", "input": { "query": "billing issues" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_9c0d",
>     "content": [
>       { "type": "source", "sources": [{ "object": "context.chunk", "id": "chunk_1", "text": "Customers reported duplicate charges..." }] },
>       { "type": "text", "text": "Customers reported duplicate charges after the plan change." }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "server_tool_result", "tool_use_id": "srvtoolu_9c0d", "content": "context_filter is required", "is_error": true }
> ```
>
> Los bloques `source` son específicos de Zylon. Solo se devuelven cuando la extensión de Zylon está activada.

> **summarize**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_1e2f", "name": "summarize", "input": { "instructions": "Summarize in three bullets" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_1e2f",
>     "content": [{ "type": "text", "text": "- Revenue grew 12%\n- Churn fell to 3%\n- Two new regions launched" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_1e2f", "content": "context_filter is required", "is_error": true }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_1e2f", "name": "summarize", "input": { "instructions": "Summarize in three bullets" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_1e2f",
>     "content": [{ "type": "text", "text": "- Revenue grew 12%\n- Churn fell to 3%\n- Two new regions launched" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "server_tool_result", "tool_use_id": "srvtoolu_1e2f", "content": "context_filter is required", "is_error": true }
> ```

> **tabular\_analysis**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_3a4b", "name": "tabular_analysis", "input": { "query": "Total sales by region" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_3a4b",
>     "content": [{ "type": "text", "text": "region,total\nNorth,1200\nSouth,950" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_3a4b", "content": "context_filter is required", "is_error": true }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_3a4b", "name": "tabular_analysis", "input": { "query": "Total sales by region" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_3a4b",
>     "content": [{ "type": "text", "text": "region,total\nNorth,1200\nSouth,950" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "server_tool_result", "tool_use_id": "srvtoolu_3a4b", "content": "context_filter is required", "is_error": true }
> ```

> **database\_query**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_5c6d", "name": "database_query", "input": { "query": "How many open tickets are there?" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_5c6d",
>     "content": [{ "type": "text", "text": "Query result: \nopen_tickets\n42" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_5c6d", "content": "At least one SQL database artifact is required.", "is_error": true }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_5c6d", "name": "database_query", "input": { "query": "How many open tickets are there?" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_5c6d",
>     "content": [{ "type": "text", "text": "Query result: \nopen_tickets\n42" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "server_tool_result", "tool_use_id": "srvtoolu_5c6d", "content": "At least one SQL database artifact is required.", "is_error": true }
> ```

> **present\_files**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_7e8f", "name": "present_files", "input": { "filepaths": ["/tmp/outputs/report.csv"] } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_7e8f",
>     "content": [
>       { "type": "local_resource", "file_path": "/tmp/outputs/report.csv", "file_id": "L3RtcC9vdXRwdXRzL3JlcG9ydC5jc3Y", "name": "report", "mime_type": "text/csv" },
>       { "type": "text", "text": "Presented 1 file(s): report.csv" }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_7e8f", "content": "code_execution provider is not configured.", "is_error": true }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_7e8f", "name": "present_files", "input": { "filepaths": ["/tmp/outputs/report.csv"] } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_7e8f",
>     "content": [
>       { "type": "local_resource", "file_path": "/tmp/outputs/report.csv", "file_id": "L3RtcC9vdXRwdXRzL3JlcG9ydC5jc3Y", "name": "report", "mime_type": "text/csv" },
>       { "type": "text", "text": "Presented 1 file(s): report.csv" }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "server_tool_result", "tool_use_id": "srvtoolu_7e8f", "content": "code_execution provider is not configured.", "is_error": true }
> ```
>
> En ambas versiones, un archivo que no se puede presentar añade un bloque de texto `Error presenting <path>: ...` y el resultado mantiene `is_error: false`.

> **present\_server**
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_9a0b", "name": "present_server", "input": { "port": 8000, "service_name": "Dashboard" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_9a0b",
>     "content": [
>       { "type": "resource_link", "uri": "https://app-8000.example.com/", "name": "Dashboard", "mime_type": "text/html" },
>       { "type": "text", "text": "The service 'Dashboard' is available at https://app-8000.example.com/." }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_9a0b", "content": "code_execution provider is not configured.", "is_error": true }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_9a0b", "name": "present_server", "input": { "port": 8000, "service_name": "Dashboard" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_9a0b",
>     "content": [
>       { "type": "resource_link", "uri": "https://app-8000.example.com/", "name": "Dashboard", "mime_type": "text/html" },
>       { "type": "text", "text": "The service 'Dashboard' is available at https://app-8000.example.com/." }
>     ],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "server_tool_result", "tool_use_id": "srvtoolu_9a0b", "content": "code_execution provider is not configured.", "is_error": true }
> ```
>
> Si el sandbox no puede exponer el puerto, ambas versiones devuelven un resultado correcto que solo contiene el texto `No HTTP endpoint is available for port 8000. ...`.

> **Herramientas de skills (load\_skill, unload\_skill, list\_skills)**
>
> Las herramientas de skills devuelven JSON como texto. Si no se encuentra una skill, la herramienta devuelve una clave `error` en el JSON y mantiene `is_error: false`.
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_1c2d", "name": "load_skill", "input": { "name": "pdf-report" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_1c2d",
>     "content": [{ "type": "text", "text": "{\"name\": \"pdf-report\", \"skill_id\": \"skl_123\", \"version\": 2, \"loaded\": true}" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> {
>   "type": "tool_result",
>   "tool_use_id": "tool_1c2d",
>   "content": [{ "type": "text", "text": "{\"error\": \"Skill 'pdf-report' not found in current skill_filter\"}" }],
>   "is_error": false
> }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_1c2d", "name": "load_skill", "input": { "name": "pdf-report" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_1c2d",
>     "content": [{ "type": "text", "text": "{\"name\": \"pdf-report\", \"skill_id\": \"skl_123\", \"version\": 2, \"loaded\": true}" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> {
>   "type": "server_tool_result",
>   "tool_use_id": "srvtoolu_1c2d",
>   "content": [{ "type": "text", "text": "{\"error\": \"Skill 'pdf-report' not found in current skill_filter\"}" }],
>   "is_error": false
> }
> ```

> **Herramientas MCP**
>
> Las herramientas MCP mantienen el nombre de la herramienta del servidor MCP y devuelven los bloques de contenido que genera el servidor MCP.
>
> **1.57**
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_3e4f", "name": "create_issue", "input": { "title": "Login fails on Safari" } },
>   {
>     "type": "tool_result",
>     "tool_use_id": "tool_3e4f",
>     "content": [{ "type": "text", "text": "Created issue #128" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_3e4f", "content": "MCP server returned 401 Unauthorized", "is_error": true }
> ```
>
> **1.58**
>
> ```json theme={null}
> [
>   { "type": "server_tool_use", "id": "srvtoolu_3e4f", "name": "create_issue", "input": { "title": "Login fails on Safari" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_3e4f",
>     "content": [{ "type": "text", "text": "Created issue #128" }],
>     "is_error": false
>   }
> ]
> ```
>
> Error:
>
> ```json theme={null}
> { "type": "server_tool_result", "tool_use_id": "srvtoolu_3e4f", "content": "MCP server returned 401 Unauthorized", "is_error": true }
> ```

> **Herramientas personalizadas (sin cambios)**
>
> Nada cambia para las herramientas que define y ejecuta tu aplicación. La respuesta se detiene con `stop_reason: "tool_use"`, tu aplicación ejecuta la herramienta y envía de vuelta un bloque `tool_result`, como en 1.57.
>
> ```json theme={null}
> [
>   { "type": "tool_use", "id": "tool_5a6b", "name": "get_weather", "input": { "city": "Madrid" } }
> ]
> ```
>
> ```json theme={null}
> { "type": "tool_result", "tool_use_id": "tool_5a6b", "content": [{ "type": "text", "text": "24°C, sunny" }], "is_error": false }
> ```

### Peticiones con la extensión de Zylon activada

Si una petición activa la extensión de Zylon (`system.extensions` incluye `zylon`):

* Los resultados de `web_search` y `web_fetch` se devuelven como un bloque `tool_result` normal, como muestran los ejemplos anteriores. El bloque de llamada sigue siendo `server_tool_use` y el ID de la llamada sigue empezando por `srvtoolu_`.
* Los objetos de error de `bash_code_execution_tool_result` y `text_editor_code_execution_tool_result` incluyen un campo `detail` con el error original.
* Los bloques específicos de Zylon, como `source`, se conservan en el contenido de `server_tool_result`.

### Envío del historial de conversación

Puedes enviar de vuelta en `messages` los bloques `server_tool_use` y los resultados de herramientas de servidor tal como los recibiste. Zylon los convierte internamente, así que no necesitas cambios si reenvías sin modificar los turnos anteriores del asistente. El historial con los bloques `tool_use` y `tool_result` de 1.57 se sigue aceptando.

## Antes de actualizar tu cliente

1. Sustituye las URLs obsoletas y mueve el selector de proyecto a la consulta o al cuerpo correspondiente.
2. Usa bytes Base64 para crear artefactos con JSON, texto para actualizarlos y `file_data` para archivos multipart.
3. Adapta la lectura de respuestas a la separación entre cuenta y miembro y a la eliminación del contenido inline de artefactos. Revisa los IDs de usuario/cuenta almacenados, relaciones, comparaciones y filtros aunque las llamadas sigan funcionando.
4. Usa IDs de cuenta en los filtros de creador y los nombres canónicos de campos e inclusiones.
5. Adapta el procesado de mensajes a `server_tool_use` y a los bloques de resultado de herramientas de servidor, y devuelve `tool_result` solo para tus herramientas personalizadas.
6. Adapta los cuerpos de chat, selectores de artefactos por ámbito, SSE, archivos de hilo y sondeo del estado de lectura.
7. Prueba con 1.58, incluidos permisos, validación, conversión de contenido y validación de filesystem. Las URLs antiguas usan la autorización, las respuestas y el comportamiento de servicio actuales; no reproducen todos los comportamientos de 1.57.


# Autenticación
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/auth

Inicia y cierra sesiones para acceso a Workspace API.

Usa estos endpoints para autenticar con credenciales y cerrar sesión. Para los redireccionamientos SSO (Google/Microsoft) y OAuth de integraciones, consulta [OpenID y OAuth](/es/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid).

## Creación de cuentas

Usa `POST /api/v1/auth/register` para crear una cuenta con credenciales.

Para usar esa cuenta en Workspace, necesitas al menos un miembro del espacio de trabajo:

* Crea un miembro del espacio de trabajo con el ID de la cuenta en [Miembros del espacio de trabajo - Crear un miembro del espacio de trabajo](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user).
* Añade membresías/roles adicionales con `POST /api/v1/account/organization/{orgId}/join`.

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/register" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sasha Patel",
    "email": "sasha@example.com",
    "password": "{password}",
    "roles": ["Workspace"]
  }'
```

> **Parametros del endpoint**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre visible de la cuenta. |
> | `email` | string | Sí | Email de la cuenta. |
> | `password` | string | Sí | Contraseña de credenciales. |
> | `roles` | string\[] | Sí | Roles a nivel de cuenta. Se requiere al menos un rol válido. |

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "acct_6c8a1f3b2d4e5f7a",
>   "state": "Active",
>   "email": "sasha@example.com",
>   "name": "Sasha Patel",
>   "provider": "Credentials",
>   "roles": ["Workspace"],
>   "created_at": "2026-02-08T14:12:45Z",
>   "updated_at": "2026-02-08T14:12:45Z"
> }
> ```

## Iniciar sesión con credenciales

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "{username}",
    "password": "{password}"
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> "ok"
> ```

Un inicio de sesión correcto crea una sesión de cuenta. Cuando LDAP está habilitado, el servidor intenta primero autenticación LDAP y después usa credenciales locales como fallback.

## Cerrar sesión

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/logout" \
  -H "Authorization: Bearer {API_TOKEN}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> "ok"
> ```

## Gestionar tokens de API

Usa estos endpoints para gestionar tokens de API de la cuenta autenticada. El secreto del token solo se devuelve al crearlo; después, las respuestas de listado incluyen metadatos y el hash del token.

### Listar tokens

> **Parametros del endpoint**
>
> | Parámetro de consulta | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `page_size` | integer | No | Número máximo de tokens a devolver. |
> | `after` / `before` | string | No | Controles de paginación por cursor cuando estén disponibles. |
> | `gateway_id` | string | No | Filtra tokens por gateway ID. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/account/token?page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "tok_7f1a9c2d4b6e",
>       "name": "workspace-sync",
>       "token": null,
>       "scopes": ["Workspace.ReadWrite.All"],
>       "gateway_id": null,
>       "hashed_token": "{token_hash}",
>       "token_email": "workspace-sync@example.com",
>       "last_used_at": "2026-05-10T08:31:12Z",
>       "created_at": "2026-05-01T10:00:00Z",
>       "valid_until": "2026-12-31T23:59:59Z"
>     }
>   ],
>   "next_cursor": null,
>   "previous_cursor": null,
>   "has_next_page": false,
>   "has_previous_page": false,
>   "total_count": 1
> }
> ```

### Crear un token

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/account/token" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workspace-sync",
    "revoke_existing": false,
    "valid_until": "2026-12-31T23:59:59Z",
    "scopes": ["Workspace.ReadWrite.All"]
  }'
```

> **Parametros del endpoint**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre legible del token. |
> | `revoke_existing` | boolean | No | Si es `true`, revoca tokens existentes según la política del servidor. Por defecto es `false`. |
> | `valid_until` | timestamp | No | Fecha de expiración. Usa `null` u omítelo si no hay expiración explícita. |
> | `scopes` | string\[] | No | Valores permitidos: `Read.All`, `ReadWrite.All`, `Workspace.Read.All`, `Workspace.ReadWrite.All`, `PrivateGPT.Read.All` y `PrivateGPT.ReadWrite.All`. Si se omite, usa `Workspace.ReadWrite.All` por defecto; un array vacío explícito devuelve `400`. |
> | `gateway_id` | string | No | Obligatorio si `scopes` incluye `PrivateGPT.Read.All` o `PrivateGPT.ReadWrite.All`. |

Los scopes de un mismo token se combinan y después se intersectan con los permisos de rol de la cuenta propietaria. Un token no puede elevar a su propietario, incluidos los tokens de SuperAdmin. Las restricciones de scope solo se aplican a tokens de API y no cambian las sesiones interactivas. Consulta [Gestión de tokens](/es/v1.58/developer-manual/get-started/token-management) para ver el acceso de cada scope.

`Read.All` puede crearse sin `gateway_id`, pero sus permisos de lectura de ZylonGPT solo se pueden usar cuando el token incluye ese contexto de gateway. En cambio, la creación de tokens de cuenta devuelve `400` si se solicita cualquiera de los scopes `PrivateGPT.*` dedicados sin `gateway_id`.

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "tok_7f1a9c2d4b6e",
>   "name": "workspace-sync",
>   "token": "{API_TOKEN}",
>   "scopes": ["Workspace.ReadWrite.All"],
>   "gateway_id": null,
>   "hashed_token": "{token_hash}",
>   "token_email": "workspace-sync@example.com",
>   "last_used_at": null,
>   "created_at": "2026-05-01T10:00:00Z",
>   "valid_until": "2026-12-31T23:59:59Z"
> }
> ```

> [!WARNING]
>
> Copia el valor de `token` inmediatamente. Solo se devuelve una vez y no se puede recuperar después.

### Eliminar un token

La eliminación usa el hash almacenado del token, no el secreto en claro.

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/account/token/{token_hash}" \
  -H "Authorization: Bearer {API_TOKEN}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> "Token deleted"
> ```

## Errores y casos límite

* **401/403**: token inválido o ausente.
* **400**: `scopes` está vacío de forma explícita, falta `gateway_id` para un scope de PrivateGPT o una solicitud de token de gateway incluye un scope que no es de PrivateGPT.
* **429**: demasiados intentos de inicio de sesión.
* **400**: el registro no incluye roles de cuenta, email o contraseña obligatorios.


# OpenID y OAuth
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid

Inicia sesiones SSO y flujos OAuth para Confluence y SharePoint.

Usa estos endpoints para iniciar flujos OpenID/OAuth. Los endpoints de inicio de sesión están pensados para el navegador y devuelven redirecciones; los callbacks reciben la respuesta del proveedor.

> Las integraciones deben estar habilitadas antes de usar OAuth. Consulta las guías del operador para [Confluence](/es/v1.58/operator-manual/knowledge-base/confluence) y [SharePoint](/es/v1.58/operator-manual/knowledge-base/sharepoint).

## Solicitud básica y respuesta

Inicia un flujo de inicio de sesión llamando al endpoint del proveedor y siguiendo la redirección.

### Redirecciones SSO de usuario

**Inicio de sesión Google**

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/auth/google/login"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...
> ```

**Inicio de sesión Microsoft**

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/auth/microsoft/login"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...
> ```

### Redirecciones OAuth de integraciones

Usa `project_id` para crear una integración de proyecto u omítelo para crear una integración de organización con rol `AppAdmin` o superior. El parámetro opcional `connector_name` establece su nombre visible.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `project_id` | No | Proyecto propietario de la integración. Omítelo para una integración de organización. |
> | Query | `connector_name` | No | Nombre visible del nuevo artefacto de integración. |

**Inicio de sesión Confluence**

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/confluence/login?project_id={projectID}&connector_name=Confluence" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://auth.atlassian.com/authorize?client_id=...&redirect_uri=...
> ```

**Inicio de sesión SharePoint**

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/sharepoint/login?project_id={projectID}&connector_name=SharePoint" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...
> ```

### Inicio de sesión con una instancia específica

Envía `integration_artifact_id` para sustituir las credenciales OAuth de un artefacto de integración existente. Incluye `project_id` cuando la integración pertenece a un proyecto.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `integration_artifact_id` | Si | Artefacto de integración existente cuyas credenciales OAuth se sustituirán. |
> | Query | `project_id` | Condicional | Proyecto propietario de la integración. Inclúyelo para una integración de proyecto. |

**Instancia Confluence**

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/confluence/login?project_id={projectID}&integration_artifact_id={integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://auth.atlassian.com/authorize?client_id=...&state=conf_8a7b6c5d4e3f2a1b
> ```

**Instancia SharePoint**

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/sharepoint/login?project_id={projectID}&integration_artifact_id={integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&state=sp_1c2d3e4f5a6b7c8d
> ```

### Renovación del token de la integración

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | Artefacto de integración cuyo token se renovará. |

**Renovar token Confluence**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/integration/confluence/refresh_token" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> "ok"
> ```

**Renovar token SharePoint**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/integration/sharepoint/refresh_token" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> "ok"
> ```

### Callbacks

**Microsoft callback**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `code` | Si | Código de autorización OAuth. |
> | Query | `state` | Si | Valor OAuth `state` devuelto por el proveedor. |

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/auth/microsoft/callback?code=...&state=..."
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://{BASE_URL}/app/login/success
> ```

**Confluence callback**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `code` | Si | Código de autorización OAuth. |
> | Query | `state` | Si | Valor OAuth `state` devuelto por el proveedor. |

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/confluence/callback?code=...&state=..."
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://{BASE_URL}/app/integrations/confluence
> ```

**SharePoint callback**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `code` | Si | Código de autorización OAuth. |
> | Query | `state` | Si | Valor OAuth `state` devuelto por el proveedor. |

```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/sharepoint/callback?code=...&state=..."
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 302 Found
> Location: https://{BASE_URL}/app/integrations/sharepoint
> ```

## Errores y casos límite

* **302**: esperado en inicio de sesión y callback.
* **401/403**: token ausente para la renovación.
* **404**: no se encontró el artefacto de integración o el proyecto.


# Chats
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/chats/threads

Hilos, interacciones y chat de una sola llamada.

Los chats en la Workspace API se organizan alrededor de **hilos** e **interacciones**:

| Concepto | Significado |
| - | - |
| **Thread** | Contenedor de conversación dentro de un proyecto. |
| **Interaction** | Interacción individual dentro del hilo. |
| **Chat** | Solicitud de una sola llamada que **no** crea un hilo. |

Usa hilos cuando necesitas historial y seguimiento. Usa interacciones para enviar un nuevo turno a un hilo. Usa el endpoint de chat para solicitudes de un solo turno.

> [!WARNING]
>
> En 1.58, `created_by.id` identifica una cuenta, no un miembro del espacio de trabajo. Ambos IDs son UUIDs. Actualiza las comparaciones y busquedas guardadas; consulta la [migracion de IDs de cuenta](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#ids-de-cuenta-y-campos-renombrados).

## Solicitud básica y respuesta

Crea una interaccion con `POST /api/v1/app/thread/{threadID}/interaction`. Envia exactamente un nuevo mensaje de usuario; el servidor incorpora el historial del hilo. La respuesta es `200` SSE con un evento inicial `interaction` y eventos de mensaje que terminan en `done`.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo; se toma de la URL. |
> | Body | `thread_id` | No | Opcional; el ID de hilo de la URL tiene prioridad. |
> | Body | `pgpt` | Si | Exactamente un mensaje en `messages`, con `role: "user"`. Usa los campos de solicitud de Messages. |
> | Body | `artifacts` | No | Selecciones por alcance; consulta Seleccionar artefactos. |
> | Body | `agent` | No | `Default` (predeterminado) o `ProjectDeepResearch`. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "artifacts": {
      "document": [
        {
          "scope": "project",
          "artifacts_ids": [
            "{artifactID}"
          ]
        }
      ]
    },
    "agent": "Default",
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarize the artifact in three bullets."
            }
          ]
        }
      ],
      "max_tokens": 120,
      "temperature": 0.2
    }
  }'
```

El stream siguiente esta abreviado. Lee el evento inicial `interaction` para obtener el ID de la interaccion guardada y procesa los eventos de mensaje hasta `done`.

> **Ejemplo de stream**
>
> ```text theme={null}
> event: interaction
> data: {"type":"interaction","interaction":{"id":"{interactionID}","project_id":"{projectID}","thread_id":"{threadID}","state":"Processing","user_input":{"role":"user","content":[{"type":"text","text":"Summarize the artifact in three bullets."}]},"created_at":"2026-02-08T14:41:10Z"}}
>
> event: message_start
> data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[]}}
>
> event: content_block_delta
> data: {"type":"content_block_delta","index":0,"block_id":"block_example","delta":{"type":"text_delta","text":"Ticket volume decreased this week."}}
>
> event: message_stop
> data: {"type":"message_stop"}
>
> event: done
> data: {"type":"done"}
> ```

### Campos de respuesta de interaccion

Los campos nulos pueden omitirse. Los mensajes anidados siguen [Messages](/es/v1.58/developer-manual/build-with-zylon/working-with-messages) y las cuentas siguen [Miembros del espacio de trabajo](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user).

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | ID de interaccion generado por el servidor. |
| `project_id` | string | Proyecto de la interaccion. |
| `thread_id` | string or null | Hilo al que pertenece, cuando existe. |
| `state` | string | `Processing`, `Completed`, `Error`. |
| `user_input` | object | Mensaje del usuario: `role` y bloques `content`. |
| `assistant_output` | object or null | Mensaje del asistente cuando existe; consulta el modelo de respuesta de Messages. |
| `artifacts` | object or null | Selecciones de artefactos descritas abajo. |
| `created_at` | timestamp | Fecha de creacion generada por el servidor. |
| `created_by` | object or null | Datos de cuenta al pedir `include=Account` en la lista de interacciones. El ID del creador es un ID de cuenta. |
| `pgpt` | object or null | Solicitud de chat guardada; consulta el modelo de solicitud de Messages. |

## Seleccionar artefactos

Usa `artifacts` en las solicitudes de interaccion y de chat con envoltorio. Contiene arrays opcionales `document`, `connector`, `skill` y `agent_flow`. Cada array contiene selecciones por alcance `organization` o `project`.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `artifacts.document` | No | Documentos, texto inline, carpetas y enlaces. |
> | Body | `artifacts.connector` | No | Bases de datos SQL y servidores MCP. |
> | Body | `artifacts.skill` | No | Skills. |
> | Body | `artifacts.agent_flow` | No | Artefactos Analysis, BulkQA, Composition, ReadAndExtract, SmartDoc y Summary. |
> | Body | `artifacts.<category>[].scope` | Si | `organization` o `project`. |
> | Body | `artifacts.<category>[].all_artifacts` | No | Selecciona todos los artefactos habilitados de ese alcance. Por defecto null. |
> | Body | `artifacts.<category>[].artifacts_ids` | No | Array de IDs de artefactos seleccionados. El nombre exacto incluye la `s`: `artifacts_ids`. Por defecto null. |

No combines `all_artifacts: true` con un array `artifacts_ids` no vacio. Cada categoria admite como maximo una entrada por alcance. La seleccion `project` usa el proyecto del hilo o el `project_id` del chat con envoltorio; sin contexto de proyecto, `all_artifacts` para ese alcance no selecciona nada. `artifact_ids` y `all_artifacts` en el nivel superior no son el modelo de seleccion actual.

```json theme={null}
{
  "artifacts": {
    "document": [
      {
        "scope": "project",
        "artifacts_ids": [
          "{artifactID}"
        ]
      },
      {
        "scope": "organization",
        "all_artifacts": false,
        "artifacts_ids": []
      }
    ]
  }
}
```

Los artefactos de organizacion disponibles se incluyen por defecto en cada categoria sin una entrada explicita `organization`. Para excluir ese valor predeterminado de una categoria, envia una entrada de organizacion con `all_artifacts: false` y `artifacts_ids: []`. Los archivos disponibles producidos en turnos anteriores del mismo hilo tambien siguen utilizables.

## Agregar media al chat

Si el modelo seleccionado soporta entrada multimodal, puedes enviar media en `pgpt.messages[].content[]` (la misma forma de request usada por interacciones en hilo y por chat de una sola llamada).

Puedes combinar múltiples bloques de contenido en un mismo mensaje. Tipos principales en el esquema:

| Tipo | Uso típico | Campos requeridos | Notas |
| - | - | - | - |
| `text` | Prompt/entrada en texto plano | ninguno | Usa `text`; soporta metadata opcional de `citations`. |
| `image` | Imagen adjunta | `data` | `data` puede ser base64 o URL; `mime_type` es opcional. |
| `audio` | Audio adjunto | `data` | `data` puede ser base64 o URL; `mime_type` es opcional. |
| `binary` | Payload binario genérico | `data`, `mime_type` | `filename` opcional. |
| `file` | Bloque de archivo/documento | `content` | `content_type` y `doc_metadata` opcionales. |
| `tool_use` | Llamada a una herramienta personalizada | `id`, `name`, `input` | Llamada a una herramienta que ejecuta tu aplicación. Devuelve un bloque `tool_result`. |
| `server_tool_use` | Llamada a una herramienta integrada | `id` (prefijo `srvtoolu_`), `name`, `input` | Zylon ejecutó la herramienta. Va seguido de su bloque de resultado (`server_tool_result`, `web_search_tool_result`, `web_fetch_tool_result`, `bash_code_execution_tool_result` o `text_editor_code_execution_tool_result`). |

`start_timestamp`, `stop_timestamp` y `_meta` son opcionales en todos los bloques.

> **Ejemplo de bloques de contenido**
>
> ```json theme={null}
> [
>   { "type": "text", "text": "Summarize this image." },
>   { "type": "image", "data": "<BASE64_OR_URL>", "mime_type": "image/png" },
>   { "type": "audio", "data": "<BASE64_OR_URL>", "mime_type": "audio/mpeg" },
>   { "type": "binary", "data": "<BASE64_OR_URL>", "mime_type": "application/octet-stream", "filename": "blob.bin" },
>   {
>     "type": "file",
>     "content": "<BASE64_OR_TEXT_FILE_CONTENT>",
>     "content_type": "application/pdf",
>     "doc_metadata": { "file_name": "contract.pdf", "file_type": "pdf" }
>   },
>   {
>     "type": "source",
>     "sources": [
>       {
>         "type": "context.website",
>         "url": "https://example.com/report",
>         "title": "Quarterly Report",
>         "description": "Public report page"
>       },
>       {
>         "type": "context.chunk",
>         "id": "chunk_01",
>         "score": 0.92,
>         "text": "Support backlog dropped 8% week-over-week",
>         "document": {
>           "object": "artifact",
>           "artifact": "artifact_123",
>           "doc_metadata": { "file_name": "support.csv", "file_type": "csv" }
>         }
>       }
>     ]
>   },
>   { "type": "server_tool_use", "id": "srvtoolu_123", "name": "semantic_search", "input": { "query": "billing issues" } },
>   {
>     "type": "server_tool_result",
>     "tool_use_id": "srvtoolu_123",
>     "content": [{ "type": "text", "text": "Found 5 matching passages." }],
>     "is_error": false
>   },
>   { "type": "thinking", "thinking": "I should compare the latest week to the previous one." },
>   {
>     "type": "tldr",
>     "content": [
>       { "type": "text", "text": "User: Analyze support trend" },
>       { "type": "text", "text": "Assistant: Backlog decreased 8%" }
>     ]
>   }
> ]
> ```

Ejemplo de interacción con imagen + texto y flags de ejecución:

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo; se toma de la URL. |
> | Body | `thread_id` | No | Opcional; el ID de hilo de la URL tiene prioridad. |
> | Body | `pgpt` | Si | Exactamente un mensaje en `messages`, con `role: "user"`. Usa los campos de solicitud de Messages. |
> | Body | `artifacts` | No | Selecciones por alcance; consulta Seleccionar artefactos. |
> | Body | `agent` | No | `Default` (predeterminado) o `ProjectDeepResearch`. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "artifacts": {
      "document": [{ "scope": "project", "all_artifacts": true }]
    },
    "agent": "Default",
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "image",
              "data": "<BASE64_IMAGE_DATA>",
              "mime_type": "image/png"
            },
            {
              "type": "text",
              "text": "What do you see here?"
            }
          ]
        }
      ],
      "system": {
        "use_default_prompt": true,
        "citations": {
          "enabled": true
        }
      },
      "thinking": {
        "enabled": true
      }
    }
  }'
```

* `system.citations.enabled`: pide al modelo incluir referencias/citas cuando estén disponibles.
* `thinking.enabled`: activa modo de razonamiento profundo; puede tardar más pero suele mejorar la calidad.

## Crear o listar hilos

Crear un hilo en un proyecto:

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | `name` | Si | Nombre del hilo. |
> | Body | `visibility` | Si | `Public` o `Private`. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Support Brief",
    "visibility": "Private"
  }'
```

Listar hilos:

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Query | `state` | No | Estados de hilo separados por comas: `Active` y `Deleted`. |
> | Query | `include` | No | Datos relacionados que se incluirán, separados por comas: `Account` y `ReadState`. |
> | Query | `page` | No | Número de página absoluto, empezando en 1. |
> | Query | `page_size` | No | Número de elementos por página. |
> | Query | `page_order` | No | `ASC` o `DESC`. |
> | Query | `after` | No | Cursor o valor desde el que paginar hacia delante. |
> | Query | `before` | No | Cursor o valor desde el que paginar hacia atrás. |
> | Query | `first` | No | Limita a los primeros N elementos después de un cursor. |
> | Query | `last` | No | Limita a los últimos N elementos antes de un cursor. |
> | Query | `total_count` | No | Incluye el total de resultados en la respuesta. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/thread?page=1&page_size=20&include=ReadState" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "{threadID}",
>       "project_id": "{projectID}",
>       "name": "Weekly Support Brief",
>       "state": "Active",
>       "visibility": "Private",
>       "read_state": {
>         "last_read_at": "2026-02-08T14:41:10Z",
>         "has_unread_response": false
>       }
>     }
>   ],
>   "has_next_page": false,
>   "has_previous_page": false
> }
> ```

### Campos de respuesta del hilo

Crear, consultar, actualizar y eliminar devuelven este modelo de hilo con `200`. Las listas de proyecto lo incluyen en el envoltorio de paginacion compartido. Los campos nulos pueden omitirse; las respuestas de hilo no contienen `created_at`. Los datos de cuenta siguen el [modelo de cuenta del miembro](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user).

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | ID de hilo generado por el servidor. |
| `project_id` | string | ID del proyecto al que pertenece. |
| `name` | string | Nombre del hilo. |
| `state` | string | `Active` o `Deleted`. |
| `visibility` | string | `Public` o `Private`. |
| `created_by` | object or null | Objeto de cuenta en listas de hilos con `include=Account`. Los IDs de creador son de cuenta, no de miembro del espacio de trabajo. |
| `read_state` | object or null | Presente en listas de hilos con `include=ReadState`. |
| `read_state.last_read_at` | timestamp or null | Punto de lectura de la cuenta actual; null u omitido antes de la primera lectura. |
| `read_state.has_unread_response` | boolean | True para un hilo nuevo creado por otra cuenta o una respuesta completada posterior al punto de lectura. |

Consultar `GET /app/thread/{threadID}/interaction` avanza el punto de lectura de la cuenta actual hasta las respuestas completadas de la pagina devuelta, o al menos hasta la creacion del hilo si no hay respuestas completadas. Consultar solo el detalle del hilo no marca la conversacion como leida. El estado de lectura es por cuenta.

Crea un hilo y la primera interacción en una sola petición:

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | `thread_name` | No | Nombre del nuevo hilo. Por defecto `New Thread`. |
> | Body | `thread_visibility` | No | `Public` o `Private`; por defecto `Private`. |
> | Body | `pgpt` | Si | Exactamente un mensaje de usuario. |
> | Body | `artifacts` | No | Selecciones de artefactos por alcance. |
> | Body | `agent` | No | `Default` (predeterminado) o `ProjectDeepResearch`. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "thread_name": "Weekly Support Brief",
    "thread_visibility": "Private",
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarize the artifact in three bullets."
            }
          ]
        }
      ],
      "max_tokens": 120,
      "temperature": 0.2
    }
  }'
```

Esta operacion devuelve `200` SSE con los IDs de la nueva interaccion y del hilo en el evento inicial `interaction`, seguido de eventos de mensaje y `done`. `name` y `visibility` pertenecen al cuerpo de creacion de hilo separado y no sustituyen aqui a `thread_name`, `thread_visibility` ni `pgpt`.

## Obtener un hilo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

Devuelve el modelo de respuesta de hilo anterior. Las relaciones `include` estan disponibles en la lista del proyecto, no en este endpoint de detalle.

## Actualizar o eliminar un hilo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |
> | Body | `name` | No | Nuevo nombre en PUT. Omite o envia null para mantenerlo. |
> | Body | `visibility` | No | Nueva visibilidad `Public` o `Private` en PUT. Omite o envia null para mantenerla. |

PUT devuelve el hilo actualizado; DELETE lo elimina de forma logica y devuelve el hilo con `state: "Deleted"`. Ambos devuelven `200` JSON.

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/thread/{threadID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Support Brief",
    "visibility": "Private"
  }'
```

Eliminar un hilo:

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/thread/{threadID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

## Listar u obtener interacciones

Listar interacciones de un hilo:

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |
> | Query | `include` | No | Datos relacionados que se incluirán, separados por comas. Valor compatible: `Account`. |
> | Query | `page` | No | Número de página absoluto, empezando en 1. |
> | Query | `page_size` | No | Número de elementos por página. |
> | Query | `page_order` | No | `ASC` o `DESC`. |
> | Query | `after` | No | Cursor o valor desde el que paginar hacia delante. |
> | Query | `before` | No | Cursor o valor desde el que paginar hacia atrás. |
> | Query | `first` | No | Limita a los primeros N elementos después de un cursor. |
> | Query | `last` | No | Limita a los últimos N elementos antes de un cursor. |
> | Query | `total_count` | No | Incluye el total de resultados en la respuesta. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction?page=1&page_size=20&include=Account" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

Obtener una interacción:

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

## Eliminar o hacer streaming de una interacción

Cancelar una interacción en ejecución:

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/interaction/{interactionID}/cancel" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

Eliminar una interacción:

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

Streaming:

```bash theme={null}
curl -N "https://{BASE_URL}/api/v1/app/interaction/{interactionID}/stream" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Accept: text/event-stream"
```

El stream siguiente esta abreviado. Lee el evento inicial `interaction` para obtener el ID de la interaccion guardada y procesa los eventos de mensaje hasta `done`.

> **Ejemplo de stream**
>
> ```text theme={null}
> event: interaction
> data: {"type":"interaction","interaction":{"id":"{interactionID}","project_id":"{projectID}","thread_id":"{threadID}","state":"Processing","user_input":{"role":"user","content":[{"type":"text","text":"Summarize the artifact in three bullets."}]},"created_at":"2026-02-08T14:41:10Z"}}
>
> event: message_start
> data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[]}}
>
> event: content_block_delta
> data: {"type":"content_block_delta","index":0,"block_id":"block_example","delta":{"type":"text_delta","text":"Ticket volume decreased this week."}}
>
> event: message_stop
> data: {"type":"message_stop"}
>
> event: done
> data: {"type":"done"}
> ```

## Archivos del hilo

Los endpoints de archivos usan el hilo como alcance de sesion. La subida y PUT guardan bytes; la conversion exporta o importa contenido MDX de artefactos. Envia `x-org` y un token API en cada solicitud. La subida, PUT y la exportacion desde un artefacto requieren permiso para actualizar el hilo.

### Subir un archivo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |
> | Query | `path` | No | Clave relativa a uploads, como `reports/report.mdx`. Por defecto el nombre del archivo; se normaliza el prefijo `uploads/`. |
> | Query | `namespace` | No | `session` (predeterminado), `artifacts`, `skills`. |
> | Multipart | `file` | Si | Parte de archivo con los bytes. No fijes manualmente el boundary multipart. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/upload-file?path=report.mdx&namespace=session" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -F "file=@report.mdx;type=text/plain"
```

Devuelve `200` con metadatos de archivo. La ausencia de `file` en multipart devuelve `400`.

### Guardar bytes de archivo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |
> | Path | `path` | Si | Clave de almacenamiento, con segmentos anidados como `reports/report.mdx`. |
> | Query | `namespace` | No | `session` (predeterminado), `artifacts`, `skills`. |
> | Header | `Content-Type` | No | Tipo MIME del archivo; por defecto `application/octet-stream`. |
> | Body | `file bytes` | Si | Bytes sin codificacion JSON ni multipart. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/thread/{threadID}/put-file/reports/report.mdx?namespace=session" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: text/plain" \
  --data-binary @report.mdx
```

Devuelve `200` con metadatos de archivo. Crea las carpetas padre y sobrescribe una clave existente.

### Descargar un archivo del hilo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |
> | Query | `path` | Si | Ruta absoluta del sandbox o su ID de archivo codificado en Base64. Codifica el valor de consulta para la URL. |
> | Query | `namespace` | No | `session` (predeterminado), `artifacts`, `skills`. |
> | Query | `disposition` | No | `attachment` (predeterminado) o `inline`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}/download-file?path=%2Fmnt%2Fuser-data%2Foutputs%2Freport.mdx&namespace=session&disposition=attachment" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -o report.mdx
```

Devuelve `200` con bytes, tipo MIME inferido y `Content-Disposition`; no devuelve una URL prefirmada. La configuracion de organizacion puede denegar la descarga con `403`: outputs requiere descargas de recursos generados, uploads requiere descargas de recursos subidos y las rutas no reconocidas requieren ambos ajustes.

### Convertir un archivo del hilo en artefacto

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |
> | Body | `file_id` | No | ID de archivo. Proporciona `file_id` o `path` no vacio. |
> | Body | `path` | No | Ruta absoluta o codificada en Base64. Cuando se envia, el nombre debe terminar en `.mdx`. |
> | Body | `project_id` | No | ID del proyecto de destino. Omite o envia null para crear un artefacto de organizacion; no se toma del hilo. |
> | Body | `name` | No | Nombre del artefacto; en su ausencia se usa el titulo MDX o el nombre de archivo. |
> | Body | `parent_id` | No | Aceptado pero actualmente sin efecto. Mueve el artefacto con el endpoint de actualizacion despues de convertirlo. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/convert-to-artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/mnt/user-data/outputs/report.mdx",
    "project_id": "{projectID}",
    "name": "Support report"
  }'
```

Devuelve `200` con el [modelo del artefacto](/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts) creado o actualizado. El contenido debe ser MDX valido de artefacto; sus metadatos determinan el tipo y las propiedades. Fallan la ausencia de ambos selectores, las rutas no MDX o el MDX invalido. Se aplican los permisos normales de creacion y actualizacion de artefactos.

### Convertir un artefacto en archivo del hilo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `threadID` | Si | Identificador del hilo. |
> | Body | `artifact_id` | Si | Artefacto que se exporta a la sesion del hilo. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/convert-from-artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact_id": "{artifactID}"
  }'
```

Devuelve `200` con metadatos del archivo MDX exportado. Requiere permiso de lectura del artefacto y las mismas comprobaciones de descarga que el artefacto; las descargas deshabilitadas devuelven `403`.

### Respuesta de metadatos de archivo

La subida, PUT y la exportacion desde artefacto comparten esta respuesta. Los campos nulos pueden omitirse.

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | Identificador que codifica en Base64 la ruta absoluta del sandbox. |
| `created_at` | string | Fecha de creacion generada por el servidor. |
| `filename` | string | Nombre de archivo. |
| `mime_type` | string | Tipo de contenido. |
| `size_bytes` | integer | Tamano en bytes. |
| `type` | string | `file`. |
| `downloadable` | boolean | Si los metadatos marcan el archivo como descargable; tambien se aplica la politica de organizacion. |
| `namespace` | string or null | `session`, `artifacts`, `skills`. |
| `scope` | object or null | Alcance del archivo con `id` (string) y `type` (`session`, `artifacts`, `skills`). |
| `etag` | string or null | Identificador de contenido opcional. |

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "L21udC91c2VyLWRhdGEvdXBsb2Fkcy9yZXBvcnQubWR4",
>   "created_at": "2026-02-08T14:41:10Z",
>   "filename": "report.mdx",
>   "mime_type": "text/plain",
>   "size_bytes": 128,
>   "type": "file",
>   "downloadable": true,
>   "namespace": "session",
>   "scope": {
>     "id": "{threadID}",
>     "type": "session"
>   },
>   "etag": "etag_example"
> }
> ```

## Chat puntual

El endpoint actual devuelve `200` con `Content-Type: text/event-stream`, incluso si `pgpt.stream` es false. No crea un hilo ni una interaccion guardada. Usa el cuerpo con envoltorio para seleccionar un proyecto o artefactos. Se sigue aceptando una solicitud de Messages plana para un chat solo de organizacion.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `pgpt` | Si | Solicitud de Messages con exactamente un mensaje de usuario. `private_gpt` es un alias aceptado. |
> | Body | `project_id` | No | Contexto de proyecto opcional. Omite o envia null para un chat solo de organizacion. |
> | Body | `artifacts` | No | Selecciones de artefactos por alcance descritas arriba. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/chat" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "artifacts": {
      "document": [
        {
          "scope": "project",
          "artifacts_ids": [
            "{artifactID}"
          ]
        }
      ]
    },
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Draft a two-sentence update on this week support backlog."
            }
          ]
        }
      ],
      "max_tokens": 64,
      "temperature": 0.3
    }
  }'
```

Consume los eventos de mensaje hasta `done`; esta operacion no emite un evento `interaction` guardado. La desconexion cancela la solicitud activa. Consulta [Messages](/es/v1.58/developer-manual/build-with-zylon/working-with-messages) para los campos anidados de solicitud y respuesta.

> **Ejemplo de stream**
>
> ```text theme={null}
> event: message_start
> data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[]}}
>
> event: content_block_delta
> data: {"type":"content_block_delta","index":0,"block_id":"block_example","delta":{"type":"text_delta","text":"Ticket volume decreased this week."}}
>
> event: message_stop
> data: {"type":"message_stop"}
>
> event: done
> data: {"type":"done"}
> ```

## Validar un chat

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `messages` | Si | Mensajes de solicitud de chat, enviados directamente en el nivel superior. No uses el envoltorio `pgpt` en este endpoint. Los campos opcionales de generacion, system y herramientas siguen el modelo de Messages enlazado. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/chat/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Give me a three-bullet summary of the Q1 support plan."
          }
        ]
      }
    ],
    "max_tokens": 64,
    "temperature": 0.3
  }'
```

Devuelve `200` con `valid: true`, o `400` con `valid: false` y el resultado de validacion. Los cuerpos invalidos o los fallos anteriores al resultado devuelven un error API estandar. Los campos nulos del resultado pueden omitirse. Esta operacion comprueba el cuerpo de Messages; el contexto de proyecto, las selecciones de artefactos y los permisos de Workspace se comprueban al ejecutar el chat.

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "valid": true,
>   "request_summary": {
>     "message_count": 1,
>     "has_tools": false,
>     "stream_enabled": false
>   }
> }
> ```

| Campo | Tipo | Significado |
| - | - | - |
| `valid` | boolean | Si la validacion fue correcta. |
| `errors` | string\[] o null | Errores de validacion. |
| `warnings` | string\[] o null | Avisos no fatales. |
| `request_summary` | object o null | Resumen opcional de la solicitud comprobada. |
| `request_summary.message_count` | integer o null | Numero de mensajes de entrada. |
| `request_summary.has_tools` | boolean o null | Si se enviaron herramientas. |
| `request_summary.stream_enabled` | boolean o null | Valor solicitado de stream. |
| `request_summary.tool_choice` | string o null | Modo solicitado de seleccion de herramientas. |

## Herramientas disponibles

Solo se aceptan herramientas definidas por Zylon en `pgpt.tools`; estas rutas de chat de Workspace no admiten herramientas personalizadas del cliente. Usa las [declaraciones y ejemplos de herramientas](/es/v1.58/developer-manual/build-with-zylon/tools/introduction-to-tools). Las herramientas de conocimiento de Workspace tambien incluyen `get_knowledge_base_files` (`list_files_v1`), `get_artifact_structure` (`get_file_structure_v1`), `get_artifact_content` (`get_content_v1`), `analyze_artifact` (`analyze_artifact_v1`), `summarize_artifact` (`summarize_artifact_v1`) y `create_document` (`process_content_v1`).

## Errores y casos límite

* **400**: esquema invalido, selectores de artefactos invalidos o solicitud sin exactamente un mensaje de usuario (usa `/chat/validate`).
* **403**: acceso al proyecto insuficiente o descargas deshabilitadas por la organizacion.
* Procesa los eventos SSE `error` y el evento final `done` despues de iniciar el stream HTTP.
* **404**: hilo o interacción no encontrada.
* **409**: interacción ya completada al cancelar.


# Artefactos
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts

Artefactos de Workspace para documentos, flujos y conectores.

> [!WARNING]
>
> Las URLs de artefactos, las codificaciones de contenido y los campos de respuesta cambian en 1.58. Consulta [Migración de API 1.57 → 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#rutas-de-artefactos) antes de actualizar tu integración.

Un artefacto es una pieza de información **o herramienta** que le entregas a Zylon para usarla como contexto en consultas y operaciones. La Workspace API agrupa los artefactos en **documentos**, **documentos IA** y **otros artefactos**.

## Requisitos previos

* Un token de API. Ver [Gestión de tokens de Workspace](/es/v1.58/developer-manual/get-started/token-management).
* El nombre de host de Zylon (sustituye `{BASE_URL}` en los ejemplos).

## Artefactos

| Categoría | Incluye | Cuándo usar |
| - | - | - |
| **Artefactos de documento** | Documentos, carpetas, enlaces | Guardar u organizar contenido en un proyecto. |
| **Documentos IA** | `Summary`, composición, extracción | Ejecutar flujos sobre artefactos para producir resultados. |
| **Otros artefactos** | Servidores MCP, bases de datos SQL, integraciones, skills | Conectar herramientas, fuentes externas o instrucciones reutilizables. |

### Campos de petición de artefacto

Usa `POST /api/v1/app/artifact` para crear cualquier tipo de artefacto. El cuerpo indica la organización o el proyecto propietario e incluye metadatos compartidos y un objeto `props` específico del tipo.

Cuando envías la cabecera `x-org`, omite `organization_id`: la organización se obtiene de la cabecera. Usa `project_id` para crear el artefacto dentro de un proyecto u omítelo para crear un artefacto de organización; esto último requiere el rol `AppAdmin` o superior. Sin `x-org`, los operadores y superadministradores deben enviar `organization_id`; si también envían `project_id`, este debe pertenecer a esa organización. Los artefactos `Link` siempre requieren `project_id`.

> **Campos de petición de artefacto**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `organization_id` | string | Condicional | Organización propietaria. Omítelo al usar `x-org`; sin esa cabecera, solo pueden enviarlo operadores y superadministradores. |
> | `project_id` | string \| null | No | Proyecto propietario. Omítelo o usa `null` para crear un artefacto de organización. Es obligatorio para `Link`. |
> | `type` | string | Sí | Tipo de artefacto. Los tipos expuestos incluyen `Document`, `Folder`, `Link`, `Integration`, `Skill`, `Summary`, `Composition`, `BulkQA`, `ReadAndExtract`, `Analysis`, `SmartDoc`, `SqlDatabase` y `McpServer`. |
> | `name` | string | Sí | Nombre visible del artefacto. |
> | `props` | object | Sí | Configuración específica del tipo. También se acepta el alias legado `config`. |
> | `source` | string | No | Fuente del artefacto. Los valores de producción son `User`, `SharePoint`, `GoogleDrive`, `Confluence`, `ConfluenceLocalLegacy`, `Claromentis`, `FileSystem`, `Assistant` y `System`. Por defecto es `User`. |
> | `description` | string | No | Descripción legible. |
> | `parent_id` | string | No | Artefacto padre para artefactos de árbol, como documentos, carpetas y enlaces. No lo uses para artefactos MCP o de base de datos. |
> | `integration_id` | string | No | ID de integración para artefactos respaldados por integraciones. También se acepta `integration_artifact_id`. |
> | `external_url` | string | No | URL externa para enlaces o artefactos respaldados por conectores. |
> | `content` | string | Condicional | Contenido codificado en Base64 al crear mediante JSON. Para crear correctamente un `Document` o `Skill`, envía este campo o `file_data` multipart. |
> | `keep_file_after_ingestion` | boolean | No | Indica si se conserva el archivo subido tras la ingesta. Por defecto es `true`. |
> | `interaction_id` | string | No | Interacción que produjo el artefacto, si aplica. |
> | `private_props` | object | No | Configuración privada para artefactos `Integration` respaldados por proveedores, MCP y SQL database. También se acepta el alias legado `private_config` al crear. |
> | `scopes` | object\[] | No | Alcances iniciales del artefacto. |
> | `scopes[].scope_type` | string | Sí | `organization` o `project`. |
> | `scopes[].scope_id` | string | Sí | ID de la organización o el proyecto indicado por `scope_type`. |
> | `scopes[].enabled` | boolean | No | Indica si el artefacto está visible en este alcance. Por defecto es `true` al crear un alcance. |
> | `scopes[].ws_auto_select` | boolean | No | Permite que Workspace seleccione automáticamente el artefacto en este alcance. Por defecto es `false` al crear un alcance. |
> | `scopes[].delete` | boolean | No | Elimina el alcance coincidente. Por defecto es `false`; se usa normalmente al actualizar o modificar alcances. |
> | `file_data` | file | Condicional | Binario multipart. Para crear correctamente un `Document` o `Skill`, envía este campo o `content` en JSON. |

Si omites `scopes`, un artefacto de proyecto recibe su alcance de proyecto y un artefacto de organización recibe su alcance de organización. No puedes crear un artefacto de organización con alcances de proyecto; añádelos después con la operación de alcance.

### Artefactos de documento

Los documentos contienen contenido, los enlaces referencian artefactos existentes y las carpetas organizan artefactos dentro de una organización o un proyecto.

**Document**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `file_name` | string | Sí | Nombre original del archivo. |
> | `content_type` | string | Sí | MIME type de `file_data`. |
> | `content_length` | integer \| null | No | Tamaño del archivo en bytes. Debe estar presente y coincidir con los bytes subidos para procesar correctamente el documento; si se omite, el artefacto se crea en estado `Error` con `ingest_status: NotApplicable`. |
> | `metadata` | object | No | Metadatos del proveedor para documentos respaldados por integraciones. |
> | `original_path` | string \| null | No | Ruta montada original cuando el artefacto se promocionó desde un thread. |

```bash theme={null}
printf 'Q1 support summary.\n' > q1-support-summary.txt

curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -F 'project_id={projectID}' \
  -F 'type=Document' \
  -F 'name=Q1 Support Summary' \
  -F 'props={
    "content_type":"text/plain",
    "file_name":"q1-support-summary.txt",
    "content_length":20
  };type=application/json' \
  -F 'file_data=@./q1-support-summary.txt;type=text/plain'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_doc_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "name": "Q1 Support Summary",
>   "type": "Document",
>   "source": "User",
>   "state": "Published",
>   "ingest_status": "NotStarted",
>   "props": {
>     "file_name": "q1-support-summary.txt",
>     "content_type": "text/plain",
>     "content_length": 20
>   },
>   "created_at": "2026-02-08T14:30:12Z",
>   "updated_at": "2026-02-08T14:31:02Z"
> }
> ```

**Folder**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `metadata` | object | No | Metadatos del proveedor para carpetas respaldadas por integraciones. Usa `{}` para carpetas creadas por usuarios sin metadatos. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Folder",
    "source": "User",
    "name": "Q1 Support",
    "description": "Artifacts for Q1 support work.",
    "parent_id": null,
    "props": {}
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_folder_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "name": "Q1 Support",
>   "type": "Folder",
>   "source": "User",
>   "state": "Published",
>   "child_count": 0,
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "created_at": "2026-02-08T14:32:10Z",
>   "updated_at": "2026-02-08T14:32:10Z"
> }
> ```

**Link**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `original_artifact_id` | string | Sí | Artefacto que se enlaza en este proyecto o carpeta. |
> | `source_artifact_id` | string | Solo respuesta | ID canónico del artefacto fuente. Lo asigna el servidor. |
> | `original_artifact_type` | string | Solo respuesta | Tipo del artefacto original. Lo asigna el servidor. |
> | `original_project_id` | string \| null | Solo respuesta | Proyecto propietario del artefacto original, si existe. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Link",
    "source": "User",
    "name": "Q1 Support Summary (link)",
    "description": "Reference to the canonical document.",
    "parent_id": "artifact_folder_q1",
    "props": {
      "original_artifact_id": "{artifactID}"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_link_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "name": "Q1 Support Summary",
>   "parent_id": "artifact_folder_q1",
>   "type": "Link",
>   "source": "User",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "source_artifact_id": "artifact_doc_q1",
>     "original_artifact_id": "artifact_doc_q1",
>     "original_artifact_type": "Document",
>     "original_project_id": "proj_7a5c3e1b9d2f4a6c"
>   },
>   "created_at": "2026-02-08T14:33:22Z",
>   "updated_at": "2026-02-08T14:33:22Z"
> }
> ```

El servidor copia el nombre y el origen del artefacto original en la respuesta del enlace.

### Documentos IA

Los documentos IA ejecutan un flujo de trabajo de Zylon sobre uno o más artefactos para producir un resultado estructurado.

**Summary**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `artifact_ids` | string\[] | Sí | Artefactos de entrada a resumir. |
> | `style` | string | Sí | `Expert`, `Neutral` o `Simple`. Valores obsoletos aún pueden decodificar, pero no deben usarse. |
> | `detail` | string | Sí | `KeyPoints`, `ShortPieces` o `LongPieces`. Valores obsoletos aún pueden decodificar, pero no deben usarse. |
> | `instructions` | string\[] \| null | No | Instrucciones adicionales para la generación del resumen. Omitir el campo equivale a enviar `null`. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Summary",
    "source": "User",
    "name": "Q1 Support Summary (auto)",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Neutral",
      "detail": "KeyPoints",
      "instructions": ["Focus on billing and onboarding trends."]
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_summary_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "Summary",
>   "state": "Processing",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "artifact_ids": ["artifact_doc_q1"],
>     "style": "Neutral",
>     "detail": "KeyPoints",
>     "instructions": ["Focus on billing and onboarding trends."]
>   },
>   "created_at": "2026-02-08T15:10:00Z"
> }
> ```

**Composition**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `artifact_ids` | string\[] | Sí | Artefactos de entrada para el borrador. |
> | `instructions` | string | Sí | Prompt o instrucciones de redacción. |
> | `style` | string | Sí | `Expert`, `Neutral` o `Simple`. |
> | `detail` | string | Sí | `KeyPoints`, `ShortPieces` o `LongPieces`. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Composition",
    "source": "User",
    "name": "Q1 Support Brief",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Expert",
      "detail": "LongPieces",
      "instructions": "Draft a one-page summary for leadership."
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_comp_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "Composition",
>   "state": "Processing",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "artifact_ids": ["artifact_doc_q1"],
>     "style": "Expert",
>     "detail": "LongPieces",
>     "instructions": "Draft a one-page summary for leadership."
>   },
>   "created_at": "2026-02-08T15:12:40Z"
> }
> ```

**BulkQA**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `questions` | string\[] | Sí | Preguntas a responder. |
> | `artifact_ids` | string\[] | Sí | Artefactos de entrada para responder. |
> | `instructions` | string\[] | Sí | Restricciones o guía para las respuestas. |
> | `detail` | string | Sí | `Concise`, `Moderate` o `Comprehensive`. |
> | `style` | string | Sí | `Expert`, `Neutral` o `Simple`. |
> | `results` | object\[] | No | Resultados de respuesta generados por el servidor. Por defecto es `[]`. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "BulkQA",
    "source": "User",
    "name": "Billing FAQ",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Simple",
      "detail": "Concise",
      "instructions": ["Answer using only the artifacts."],
      "questions": [
        "What are the top billing issues?",
        "How quickly were priority bugs resolved?"
      ]
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_bulkqa_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "BulkQA",
>   "state": "Processing",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "artifact_ids": ["artifact_doc_q1"],
>     "style": "Simple",
>     "detail": "Concise",
>     "instructions": ["Answer using only the artifacts."],
>     "questions": [
>       "What are the top billing issues?",
>       "How quickly were priority bugs resolved?"
>     ],
>     "results": []
>   },
>   "created_at": "2026-02-08T15:14:10Z"
> }
> ```

**ReadAndExtract**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `artifact_ids` | string\[] | Sí | Artefactos de entrada a leer. |
> | `sections` | object\[] | Sí | Objetivos de extracción. |
> | `sections[].id` | string | Sí | ID estable de la sección. |
> | `sections[].title` | string | Sí | Título de la sección. |
> | `sections[].description` | string | Sí | Qué extraer para esa sección. |
> | `results` | object\[] | Solo respuesta | Resultados extraídos por sección. |
> | `organization_context` | string \| null | Solo respuesta | Contexto de organización usado por el servidor. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "ReadAndExtract",
    "source": "User",
    "name": "Contract extraction",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "sections": [
        { "title": "Term", "description": "Contract term in months", "id": "term" },
        { "title": "SLA", "description": "Support response time", "id": "sla" }
      ]
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_readextract_v3",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "ReadAndExtract",
>   "state": "Processing",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "artifact_ids": ["artifact_doc_q1"],
>     "sections": [
>       { "title": "Term", "description": "Contract term in months", "id": "term" },
>       { "title": "SLA", "description": "Support response time", "id": "sla" }
>     ],
>     "results": []
>   },
>   "created_at": "2026-02-08T15:15:55Z"
> }
> ```

**Analysis**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `artifact_ids` | string\[] | Sí | Artefactos de entrada a analizar. |
> | `instruction` | object \| null | No | Instrucción de análisis personalizada. Si se omite, el servidor usa su prompt de análisis por defecto. |
> | `instruction.id` | string | Sí si `instruction` está definido | ID estable de la instrucción. |
> | `instruction.prompt` | string | Sí si `instruction` está definido | Prompt usado para el análisis. |
> | `instruction.metadata` | object | No | Claves y valores de tipo string. Por defecto es `{}`. |
> | `result` | object \| null | Solo respuesta | Salida combinada del análisis. |
> | `organization_context` | string \| null | Solo respuesta | Contexto de organización usado por el servidor. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Analysis",
    "source": "User",
    "name": "Support trend analysis",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "instruction": {
        "id": "support_trends",
        "prompt": "Find the top support trends and risks.",
        "metadata": { "audience": "leadership" }
      }
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_analysis_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "Analysis",
>   "state": "Processing",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "artifact_ids": ["artifact_doc_q1"],
>     "instruction": {
>       "id": "support_trends",
>       "prompt": "Find the top support trends and risks.",
>       "metadata": { "audience": "leadership" }
>     }
>   },
>   "created_at": "2026-02-08T15:16:30Z"
> }
> ```

**SmartDoc**

> **props body**
>
> La creación de SmartDoc acepta `props`, pero el servidor inicializa estos artefactos con un objeto vacío. Envía `{}`.

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "SmartDoc",
    "source": "User",
    "name": "Onboarding SmartDoc",
    "props": {}
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_smartdoc_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "SmartDoc",
>   "state": "Draft",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "created_at": "2026-02-08T15:17:20Z"
> }
> ```

### Otros artefactos

Los otros artefactos proporcionan herramientas, conexiones con proveedores y skills reutilizables. `private_props` se usa en artefactos **MCP**, **SqlDatabase** y `Integration` respaldados por proveedores. Consulta las formas de petición de `Integration` en las guías de [Confluence](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/confluence), [SharePoint](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/sharepoint), [Filesystem](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/filesystem) y [Claromentis](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/claromentis).

**SqlDatabase**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `schemas` | string\[] \| null | No | Esquemas de base de datos a exponer. |
> | `tables` | string\[] \| null | No | Tablas de base de datos a exponer. |
> | `ssl` | boolean \| null | No | Indica si la conexión usa SSL. Valor efectivo por defecto: `true`. |
> | `enable_tables` | boolean \| null | No | Habilita descubrimiento/uso de tablas. Valor efectivo por defecto: `true`. |
> | `enable_views` | boolean \| null | No | Habilita descubrimiento/uso de vistas. Valor efectivo por defecto: `true`. |
> | `enable_procedures` | boolean \| null | No | Habilita procedimientos almacenados. Valor efectivo por defecto: `false`. |
> | `enable_functions` | boolean \| null | No | Habilita funciones. Valor efectivo por defecto: `false`. |
> | `private_props.connection_string` | string | Sí | Cadena de conexión. En ejemplos y logs, enmascara secretos. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "SqlDatabase",
    "source": "User",
    "name": "Sales database",
    "description": "Read-only reporting database.",
    "props": {
      "schemas": ["public", "analytics"],
      "tables": ["orders", "customers"],
      "ssl": true,
      "enable_tables": true,
      "enable_views": true,
      "enable_procedures": false,
      "enable_functions": false
    },
    "private_props": {
      "connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_db_sales",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "SqlDatabase",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "schemas": ["public", "analytics"],
>     "tables": ["orders", "customers"],
>     "ssl": true,
>     "enable_tables": true,
>     "enable_views": true,
>     "enable_procedures": false,
>     "enable_functions": false
>   },
>   "created_at": "2026-02-08T15:20:05Z"
> }
> ```

**McpServer**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | Sí | Nombre del servidor MCP visible para herramientas. |
> | `tool_configuration` | object \| null | No | Configuración de allowlist de herramientas. |
> | `tool_configuration.enabled` | boolean | No | Indica si las herramientas están habilitadas. Por defecto es `true`. |
> | `tool_configuration.allowed_tools` | string\[] \| null | No | Nombres de herramientas que los clientes pueden invocar a través de este MCP server. |
> | `private_props.url` | string | Sí | URL del servidor MCP. |
> | `private_props.use_bearer_auth` | boolean | No | Indica si se autentica con bearer auth. Por defecto es `false`. |
> | `private_props.authorization_token` | string \| null | No | Token de autorización cuando el servidor espera un token custom. Enmascara el valor. |
> | `private_props.refresh_token` | string \| null | No | Refresh token de OAuth. Enmascara el valor. |
> | `private_props.client_id` | string \| null | No | Identificador de cliente OAuth. |
> | `private_props.client_secret` | string \| null | No | Secreto de cliente OAuth. Enmascara el valor. |
> | `private_props.bearer_token` | string \| null | No | Bearer token cuando bearer auth está habilitado. Enmascara el valor. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "McpServer",
    "source": "User",
    "name": "Internal tools",
    "props": {
      "name": "internal_mcp",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["crm_lookup", "ticket_search"]
      }
    },
    "private_props": {
      "url": "https://mcp.example.com",
      "authorization_token": "***"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_mcp_internal",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "McpServer",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "name": "internal_mcp",
>     "tool_configuration": {
>       "enabled": true,
>       "allowed_tools": ["crm_lookup", "ticket_search"]
>     }
>   },
>   "created_at": "2026-02-08T15:22:30Z"
> }
> ```

**Skill**

> **props body**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `skill_id` | string \| null | No | ID de skill generado por el servidor. Omítelo al crear una skill. |
> | `versions` | string\[] | Solo respuesta | Versiones disponibles de la skill. |
> | `current_version` | string \| null | Solo respuesta | Versión activa de la skill. |
> | `content_md5` | string \| null | No | Hash generado por el servidor. Omítelo al crear una skill. |
> | `name` | string | Sí | Nombre estable de la skill. |
> | `display_title` | string | Sí | Título que se muestra en Workspace. |
> | `display_description` | string \| null | No | Descripción legible. |
> | `source` | string | No | `custom`, `anthropic` o `zylon`. Por defecto es `custom`. |
> | `loading` | string | No | `lazy` o `eager`. Por defecto es `lazy`. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -F 'project_id={projectID}' \
  -F 'type=Skill' \
  -F 'name=Ticket triage' \
  -F 'props={
    "name":"ticket-triage",
    "display_title":"Ticket triage",
    "display_description":"Classify and route support tickets.",
    "source":"custom",
    "loading":"lazy"
  };type=application/json' \
  -F 'file_data=@./skill.zip;type=application/zip'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_skill_triage",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "type": "Skill",
>   "source": "User",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {
>     "skill_id": "skill_ticket_triage",
>     "versions": ["1"],
>     "current_version": "1",
>     "content_md5": "{CONTENT_MD5}",
>     "name": "ticket-triage",
>     "display_title": "Ticket triage",
>     "display_description": "Classify and route support tickets.",
>     "source": "custom",
>     "loading": "lazy"
>   }
> }
> ```

## Trabajar con artefactos

### Listar artefactos

Con `x-org`, el listado queda limitado a esa organización y no admite `organization_id`. Sin `x-org`, los operadores y superadministradores pueden seleccionar una organización con `organization_id`; si lo omiten, el backend busca en las organizaciones a las que tienen acceso. `project_id` requiere una organización seleccionada.

> **Parametros del endpoint**
>
> | Parámetro de consulta | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `organization_id` | string | Condicional | Organización que se consulta. Omítelo al usar `x-org`; sin esa cabecera, solo pueden enviarlo operadores y superadministradores. |
> | `project_id` | string | No | Limita el listado a un proyecto. Si se envía junto con `organization_id`, debe pertenecer a esa organización. |
> | `state` | string | No | Valores separados por comas de `Initializing`, `Processing`, `Draft`, `Deleted`, `Published`, `Unavailable` y `Error`. Por defecto es `Published,Processing`. |
> | `source` | string | No | Orígenes separados por comas, como `User`, `SharePoint`, `Confluence`, `Claromentis` o `FileSystem`. |
> | `ingest_status` | string | No | Valores separados por comas de `NotApplicable`, `NotStarted`, `Processing`, `Parsing`, `Storing`, `Done` y `Error`. Por defecto incluye todos. |
> | `type` | string | No | Tipos de artefacto separados por comas. |
> | `scopes` | JSON array | No | Filtros de alcance. Cada elemento requiere `scope_type`, `scope_id` y el booleano `enabled`. `ws_auto_select` es opcional y vale `false` por defecto, pero no interviene en el filtrado. |
> | `parent_id` | string | No | Limita los resultados a hijos directos de un artefacto padre. |
> | `include_descendants` | boolean | No | Incluye todo el subárbol bajo `parent_id`; si no hay padre, incluye todos los descendientes del alcance seleccionado. |
> | `filter_by_text` | string | No | Búsqueda de texto sobre nombres de artefactos. |
> | `keep_ancestors` | boolean | No | Incluye los ancestros de los artefactos que coinciden con la consulta completa. |
> | `resolve_links` | boolean | No | Resuelve artefactos Link en listados de proyecto. Sin `parent_id`, solo añade sus descendientes cuando `include_descendants=true`; con un Link como padre, devuelve sus hijos directos o todo su subárbol según `include_descendants`. |
> | `sub_type` | string | No | Tipos separados por comas para filtrar destinos de enlaces mediante `props.original_artifact_type`; también se conservan los artefactos sin esa propiedad. |
> | `include` | string | No | Lista separada por comas de `Account`, `Project`, `Organization`, `Scopes` y `Relationships`. Usa `Account` para incluir detalles del creador. |
> | `created_by` | string | No | ID de la cuenta que creó los artefactos. |
> | `created_by_state` | string | No | Estado de la cuenta creadora: `Active` o `Inactive`. |
> | `order_by` | string | No | `Alphabetical` o `CreatedAt`. |
> | `order` | string | No | `ASC` o `DESC`. Por defecto es `ASC`. |
> | `start_date`, `end_date` | integer | No | Límites inclusivos de fecha de creación en milisegundos desde Unix epoch. |
> | `page` | integer | No | Número de página basado en cero. No puede combinarse con parámetros de cursor. |
> | `page_size` | integer | No | Elementos por página cuando se usa `page`. Por defecto es `50`; la paginación por cursor usa `first` o `last`. |
> | `page_order` | string | No | Orden por ID para paginación absoluta: `ASC` o `DESC`. Por defecto es `ASC`. |
> | `after`, `before` | string | No | Cursores de ID de artefacto para paginación hacia delante o hacia atrás. |
> | `first`, `last` | integer | No | Límite positivo de resultados después o antes de un cursor. |
> | `total_count` | boolean | No | Incluye `total_count` en la respuesta. Por defecto es `false`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact?project_id={projectID}&page=0&page_size=20&total_count=true&parent_id={artifactID}&include_descendants=false&include=Account,Scopes" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "artifact_doc_q1",
>       "project_id": "proj_7a5c3e1b9d2f4a6c",
>       "name": "Q1 Support Summary",
>       "type": "Document",
>       "source": "User",
>       "state": "Published",
>       "ingest_status": "Done",
>       "parent_id": "artifact_folder_q1",
>       "child_count": 0,
>       "keep_file_after_ingestion": true,
>       "scopes": [
>         {
>           "scope_type": "project",
>           "scope_id": "proj_7a5c3e1b9d2f4a6c",
>           "enabled": true,
>           "ws_auto_select": false
>         }
>       ],
>       "created_by": {
>         "id": "acct_6c8a1f3b2d4e5f7a",
>         "state": "Active",
>         "email": "sasha@example.com",
>         "name": "Sasha Patel",
>         "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>         "provider": "Credentials",
>         "roles": ["Workspace"],
>         "created_at": "2026-02-08T14:12:45Z",
>         "updated_at": "2026-02-08T14:12:45Z"
>       },
>       "created_at": "2026-02-08T14:30:12Z",
>       "updated_at": "2026-02-08T14:31:02Z"
>     }
>   ],
>   "has_next_page": false,
>   "has_previous_page": false,
>   "total_count": 1
> }
> ```

La respuesta paginada también devuelve `next_cursor` y `previous_cursor` cuando esos cursores están disponibles. `has_next_page` y `has_previous_page` siempre están presentes; `total_count` solo se devuelve al enviar `total_count=true`.

### Obtener un artefacto

El servidor obtiene la organización y el proyecto del artefacto almacenado. No envíes esos identificadores en la ruta.

> **Parámetros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Descripción |
> | - | - | - | - |
> | Path | `artifactID` | Sí | Identificador del artefacto. |
> | Query | `include_references` | No | Incluye referencias. Por defecto es `true`. |
> | Query | `include_relationships` | No | Incluye relaciones. Si se omite, usa el valor de `include_references`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}?include_references=true&include_relationships=true" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_doc_q1",
>   "project_id": "proj_7a5c3e1b9d2f4a6c",
>   "name": "Q1 Support Summary",
>   "type": "Document",
>   "source": "User",
>   "state": "Published",
>   "ingest_status": "Done",
>   "parent_id": "artifact_folder_q1",
>   "child_count": 0,
>   "props": {
>     "file_name": "q1-support-summary.txt",
>     "content_type": "text/plain",
>     "content_length": 20
>   },
>   "keep_file_after_ingestion": true,
>   "scopes": [
>     {
>       "scope_type": "project",
>       "scope_id": "proj_7a5c3e1b9d2f4a6c",
>       "enabled": true,
>       "ws_auto_select": false
>     }
>   ],
>   "created_by": {
>     "id": "acct_6c8a1f3b2d4e5f7a",
>     "state": "Active",
>     "email": "sasha@example.com",
>     "name": "Sasha Patel",
>     "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-02-08T14:12:45Z",
>     "updated_at": "2026-02-08T14:12:45Z"
>   },
>   "created_at": "2026-02-08T14:30:12Z",
>   "updated_at": "2026-02-08T14:31:02Z"
> }
> ```

| Campo de respuesta | Tipo | Descripción |
| - | - | - |
| `id` | string | ID del artefacto. |
| `parent_id` | string \| null | ID del artefacto padre cuando está anidado. |
| `child_count` | integer | Número de hijos directos. |
| `project_id` | string \| null | ID del proyecto, o `null` para un artefacto de organización. |
| `project` | object \| null | Proyecto expandido cuando se solicita. |
| `organization` | object \| null | Organización expandida cuando se solicita. |
| `name` | string | Nombre del artefacto. |
| `description` | string \| null | Descripción del artefacto. |
| `type` | string | Tipo de artefacto. |
| `source` | string | Origen del artefacto. |
| `state` | string | `Initializing`, `Processing`, `Draft`, `Deleted`, `Published`, `Unavailable` o `Error`. |
| `error` | string \| null | Código de error de ingesta o procesamiento. |
| `ingest_status` | string | `NotApplicable`, `NotStarted`, `Processing`, `Parsing`, `Storing`, `Done` o `Error`. |
| `ingest_warnings` | string\[] \| null | Advertencias no fatales de ingesta. |
| `ingest_progress` | number \| null | Progreso de ingesta cuando está disponible. |
| `integration_id` | string \| null | ID de integración para artefactos respaldados por integraciones. |
| `external_url` | string \| null | URL externa cuando existe. |
| `props` | object | Configuración pública específica del tipo. |
| `file_uri` | string \| null | URL pública temporal del archivo cuando está disponible. |
| `artifact_references` | object\[] \| null | Referencias cuando `include_references=true`. |
| `artifact_relationships` | object\[] \| null | Relaciones publicadas cuando `include_relationships=true`. |
| `artifact_relationships[].node_id` | string | Identificador del nodo de artefacto relacionado. |
| `artifact_relationships[].node_type` | string | Tipo del nodo de artefacto relacionado. |
| `keep_file_after_ingestion` | boolean | Indica si se conserva el archivo subido. |
| `created_by` | object \| null | `AccountDTO` del creador. Se devuelve en el detalle del artefacto y en listados con `include=Account`. |
| `created_at` | timestamp | Fecha de creación. |
| `updated_at` | timestamp | Fecha de última actualización. |
| `etag` | string \| null | Etiqueta de versión cuando está disponible. |
| `scopes` | object\[] \| null | Alcances del artefacto. Cada elemento contiene `scope_type`, `scope_id`, `enabled` y `ws_auto_select`. |

### Actualizar un artefacto

> **Parametros del endpoint**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `artifactID` | path | Sí | Identificador del artefacto. |
> | `name` | string | No | Nuevo nombre del artefacto. |
> | `parent_id` | string | No | Mueve un artefacto de contenido o árbol bajo este artefacto padre. No lo uses en artefactos MCP o de base de datos. |
> | `reset_parent_id` | boolean | No | Ponlo a `true` para mover un artefacto de contenido o árbol a la raíz de su árbol de proyecto u organización. Por defecto es `false`. |
> | `external_url` | string | No | Sustituye la URL externa. |
> | `props` | object | No | Sustituye o actualiza la configuración pública específica del tipo. También se acepta el alias heredado `config`. |
> | `description` | string | No | Sustituye la descripción. |
> | `content` | string | No | Contenido de texto UTF-8 al usar JSON. Para multipart, envía el binario como `file_data`. |
> | `private_props` | object | No | Configuración privada para artefactos `Integration` respaldados por proveedores, MCP y de base de datos SQL. |
> | `scopes` | object\[] | No | Cambios de alcance. Cada elemento usa `scope_type`, `scope_id`, y opcionalmente `enabled`, `ws_auto_select` o `delete`. |
> | `file_data` | file | No | Archivo de reemplazo al usar multipart. Los demás campos se envían como campos del formulario. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Support Summary (final)",
    "description": "Finalized weekly summary notes.",
    "parent_id": "artifact_folder_q1",
    "reset_parent_id": false,
    "content": "Ticket volume rose 12% week-over-week..."
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "artifact_doc_q1",
>   "name": "Q1 Support Summary (final)",
>   "description": "Finalized weekly summary notes.",
>   "parent_id": "artifact_folder_q1",
>   "type": "Document",
>   "source": "User",
>   "ingest_status": "Done",
>   "updated_at": "2026-02-08T14:45:21Z"
> }
> ```

> [!TIP]
>
> Usa `parent_id` para mover un artefacto dentro de una carpeta. Usa `reset_parent_id: true` para quitar el padre actual y moverlo a la raíz de su árbol de proyecto u organización.

### Validar antes de crear o actualizar

La validación está implementada para artefactos `Skill` y `SqlDatabase`. Usa `POST /api/v1/app/artifact/validate` con el mismo cuerpo de creación que enviarías a `POST /api/v1/app/artifact`. Para validar la actualización de uno de esos artefactos, usa `POST /api/v1/app/artifact/{artifactID}/validate` con el mismo cuerpo JSON que enviarías a `PUT /api/v1/app/artifact/{artifactID}`. Ninguna de las dos operaciones guarda cambios.

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "SqlDatabase",
    "name": "Sales database",
    "props": {
      "ssl": true,
      "enable_tables": true
    },
    "private_props": {
      "connection_string": "{DATABASE_CONNECTION_STRING}"
    }
  }'
```

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "props": {
      "ssl": true,
      "enable_tables": true
    },
    "private_props": {
      "connection_string": "{DATABASE_CONNECTION_STRING}"
    }
  }'
```

Ambas rutas devuelven el mismo modelo de validación:

```json theme={null}
{
  "valid": true,
  "errors": [],
  "warnings": []
}
```

La respuesta contiene `valid`, `errors` y `warnings`, además del campo opcional `data`. Cada error o advertencia contiene `type`, `message` y, opcionalmente, `params`. La validación de skills puede devolver `name` y `description` analizados dentro de `data`.

### Añadir o eliminar un alcance

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/scope" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "project",
    "scope_id": "{projectID}",
    "enabled": true,
    "ws_auto_select": false
  }'
```

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `scope_type` | string | Sí | `organization` o `project`. |
| `scope_id` | string | Sí | ID de la organización o el proyecto del alcance. |
| `enabled` | boolean | No | Habilita o deshabilita el artefacto en ese alcance. |
| `ws_auto_select` | boolean | No | Permite que Workspace seleccione automáticamente el artefacto en ese alcance. |
| `delete` | boolean | No | Usa `true` para eliminar el alcance. Por defecto es `false`. |

La respuesta es el artefacto actualizado con su lista `scopes`.

### Reintentar la creación de un artefacto

`POST /api/v1/app/artifact/{artifactID}/retry` elimina el artefacto original y crea uno nuevo con un cuerpo de creación completo. `organization_id` y `project_id` deben coincidir con los del artefacto original.

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/retry" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Folder",
    "name": "Q1 Support (retry)",
    "props": {}
  }'
```

La respuesta es el artefacto de reemplazo.

### Eliminar un artefacto

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "id": "artifact_doc_q1",
>     "state": "Deleted"
>   }
> ]
> ```

La respuesta es una lista porque la eliminación puede afectar a artefactos descendientes.

### Descargar contenido sin procesar

Sin la cabecera `Content-Disposition`, o con `Content-Disposition: inline`, la respuesta es una cadena con una URL prefirmada. Para un artefacto Link disponible, tanto este modo como `Content-Disposition: attachment` resuelven el artefacto original antes de devolver su URL o sus bytes:

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/download" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> https://storage.example.com/artifacts/artifact_doc_q1?signature=...
> ```

Para recibir los bytes directamente, envía `Content-Disposition: attachment`:

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/download" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Disposition: attachment" \
  --output q1-support-summary.txt
```

### Obtener contenido procesado

Este endpoint solo está disponible cuando el artefacto tiene un índice vectorial inicializado.
En la práctica, esto suele implicar documentos de conectores o artefactos con indexación ya completada.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/parsed-content" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> # Q1 Support Summary
>
> Billing issues drove 38% of support cases.
> ```

### Sincronizar un artefacto

Este endpoint se utiliza principalmente con artefactos de integración (SharePoint, Confluence, Claromentis o FileSystem).

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/sync" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Accept: text/event-stream"
```

El cuerpo de la petición está vacío. La respuesta es un stream SSE emitido por el proceso de sincronización de la integración.

> **Campos de eventos de sincronización**
>
> | Campo JSON | Tipo | Presente en | Descripción |
> | - | - | - | - |
> | `type` | string | Todos los eventos | `sync_started`, `sync_progress`, `sync_completed` o `sync_error`. |
> | `current_artifact_count` | integer | `sync_started` | Número de artefactos existentes. Por defecto es `0`. |
> | `integration_item_count` | integer \| null | `sync_started` | Número total de elementos del proveedor cuando se conoce. |
> | `integration_item` | object \| null | `sync_progress` | Elemento del proveedor que se está procesando. |
> | `artifact_id` | string \| null | `sync_progress` | Identificador del artefacto afectado. |
> | `artifact` | object \| null | `sync_progress` | Artefacto público afectado cuando se incluye. |
> | `op` | string | `sync_progress` | `Added`, `Removed`, `Skipped`, `Updated`, `Recreated` o `Error`. |
> | `progress` | number | `sync_progress` | Valor de progreso. Por defecto es `0`. |
> | `message` | string | `sync_error` | Mensaje de error. |

> **Ejemplo de stream**
>
> ```text theme={null}
> event: SyncEvent
> data: {"type":"sync_started","current_artifact_count":12,"integration_item_count":40}
>
> event: SyncEvent
> data: {"type":"sync_progress","artifact_id":"artifact_doc_q1","op":"Updated","progress":0.42}
>
> event: SyncEvent
> data: {"type":"sync_completed"}
> ```

### Ingerir desde un artefacto de integración

`POST /api/v1/app/artifact/{artifactID}/ingest` inicia la ingesta desde el artefacto de integración indicado por `artifactID`. El cuerpo JSON requiere `project_id` y los demás campos dependen del proveedor. El ejemplo selecciona un espacio de Confluence; consulta la guía de cada integración para ver sus campos completos. La respuesta es un stream SSE.

> **Parámetros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Descripción |
> | - | - | - | - |
> | Path | `artifactID` | Sí | Identificador del artefacto de integración. |
> | Body | `project_id` | Sí | Proyecto de destino de la ingesta. |
> | Body | Campos del proveedor | Condicional | Parámetros de selección o ingesta requeridos por la integración. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "space_ids": ["ENG"]
  }'
```

### Actualizar artefactos en bloque

Usa el endpoint de actualización en bloque para aplicar la misma forma de cuerpo de `PUT /api/v1/app/artifact/{artifactID}` a varios artefactos.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `artifacts` | Sí | Lista de actualizaciones de artefactos. |
> | Body | `artifacts[].artifactId` | Sí | Identificador del artefacto a actualizar. |
> | Body | `artifacts[].update` | Sí | Cuerpo de actualización con los mismos campos que `PUT /api/v1/app/artifact/{artifactID}`. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/bulk" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifacts": [
      {
        "artifactId": "artifact_doc_q1",
        "update": {
          "parent_id": "artifact_folder_q1",
          "reset_parent_id": false,
          "description": "Moved into Q1 folder."
        }
      }
    ]
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "id": "artifact_doc_q1",
>     "parent_id": "artifact_folder_q1",
>     "description": "Moved into Q1 folder.",
>     "type": "Document",
>     "state": "Published",
>     "ingest_status": "Done",
>     "updated_at": "2026-02-08T15:20:00Z"
>   }
> ]
> ```

### Eliminar artefactos en bloque

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `artifact_ids` | Sí | Identificadores de artefactos a eliminar. |

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/artifact/bulk" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact_ids": ["artifact_doc_q1", "artifact_link_q1"]
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "id": "artifact_doc_q1",
>     "state": "Deleted"
>   },
>   {
>     "id": "artifact_link_q1",
>     "state": "Deleted"
>   }
> ]
> ```

## Comprobar artefactos enlazados antes de modificar

Usa este endpoint antes de cambiar un artefacto cuando necesites comprobar si otros artefactos enlazados dependen de él.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `created_by` | No | ID de la cuenta que creó los artefactos a comprobar. |
> | Query | `project_id` | No | ID del proyecto donde comprobar artefactos enlazados. |
> | Query | `artifact_id` | No | ID del artefacto donde comprobar artefactos enlazados. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/resource/is-safe-to-modify?project_id={projectID}&artifact_id={artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "has_linked_artifacts": false
> }
> ```

## Errores y casos límite

* **Códigos de error de artefacto**: el campo `error` refleja fallos de ingesta:

| valor `error` | Significado |
| - | - |
| `InvalidExtension` | Extensión de archivo no admitida. |
| `MismatchedType` | El tipo de archivo no coincide con el tipo declarado. |
| `Malformed` | Archivo corrupto o ilegible. |
| `Encrypted` | Archivo protegido con contraseña. |
| `ParsingFailure` | El extractor no pudo analizar el archivo. |
| `MaxNodes` | Documento demasiado grande o complejo para el análisis. |
| `NoValidFile` | No se encontró un archivo válido. |
| `NoValidNodes` | No se pudo extraer contenido analizable. |
| `InternalError` | Fallo inesperado en la ingesta. |
| `Unknown` | Fallo no clasificado. |

Si `ingest_status` es `Error`, corrige el archivo y reintenta o sustituye el artefacto. Para artefactos de integración, corrige el origen y vuelve a sincronizar.

* **Advertencias**: `ingest_warnings` puede incluir valores como `BigSize`, `UnprocessableContent` o `NoContent` para indicar problemas no fatales.
* **400**: en creación falta `organization_id` o `x-org`, se usa `project_id` sin una organización seleccionada o ya hay una sincronización en curso.
* **401**: token ausente o no válido.
* **403**: permisos insuficientes o combinación no permitida de `organization_id` con `x-org`.
* **404**: artefacto o proyecto no encontrado.
* Para archivos de más de 250 MB, el backend conserva únicamente el registro del artefacto con la advertencia `UnprocessableContent`; no almacena los bytes subidos ni inicia la ingesta.


# Analíticas
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/analytics

Mide totales, rankings y series temporales.

Los endpoints de analíticas resumen cómo se usa el espacio de trabajo en proyectos y usuarios.

## Solicitud básica y respuesta

Empieza con los totales desde `GET /api/v1/app/organization/analytics/totals`.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/totals" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "projects_total": 12,
>   "threads_total": 184,
>   "interactions_total": 1420,
>   "agent_flows_total": 36,
>   "uploaded_artifacts_total": 87
> }
> ```

## Ranking de usuarios activos

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `start_date` | No | Inicio del periodo como milisegundos desde Unix epoch. |
> | Query | `end_date` | No | Fin del periodo como milisegundos desde Unix epoch. |
> | Query | `limit` | No | Numero maximo de usuarios a devolver. Por defecto `5`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/ranking/active-users?start_date=1769990400000&end_date=1771804800000&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "account": {
>       "id": "acct_6c8a1f3b2d4e5f7a",
>       "state": "Active",
>       "email": "sasha@example.com",
>       "name": "Sasha Patel",
>       "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>       "provider": "Credentials",
>       "roles": ["Workspace"],
>       "created_at": "2026-02-08T14:12:45Z",
>       "updated_at": "2026-02-08T14:12:45Z"
>     },
>     "interactions_created": 46,
>     "agent_flows_created": 4
>   }
> ]
> ```

## Ranking de proyectos activos

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `start_date` | No | Inicio del periodo como milisegundos desde Unix epoch. |
> | Query | `end_date` | No | Fin del periodo como milisegundos desde Unix epoch. |
> | Query | `limit` | No | Numero maximo de proyectos a devolver. Por defecto `5`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/ranking/active-projects?start_date=1769990400000&end_date=1771804800000&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "project": {
>       "id": "proj_7a5c3e1b9d2f4a6c",
>       "name": "Customer Insights",
>       "goal": "Summarize weekly support trends.",
>       "visibility": "Public",
>       "default_member_role": "Editor",
>       "default_role_enabled": true,
>       "project_context": "Support analytics for Q1.",
>       "use_citations": true,
>       "use_system_prompt": true,
>       "members": [
>         {
>           "id": "{wsMemberId}",
>           "role": "Owner",
>           "account": {
>             "id": "acct_6c8a1f3b2d4e5f7a",
>             "state": "Active",
>             "email": "sasha@example.com",
>             "name": "Sasha Patel",
>             "provider": "Credentials",
>             "roles": [
>               "Workspace"
>             ],
>             "created_at": "2026-02-08T14:12:45Z",
>             "updated_at": "2026-02-08T14:12:45Z"
>           },
>           "is_project_member": true
>         }
>       ],
>       "is_pinned": false
>     },
>     "interactions_created": 112,
>     "agent_flows_created": 12
>   }
> ]
> ```

El proyecto anidado sigue el [modelo de respuesta de Proyecto](/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project#campos-de-respuesta-del-proyecto), incluidas las cuentas de miembros. Los campos nulos del proyecto pueden omitirse.

## Serie de tiempo

Ambos limites de fecha son obligatorios. Los resultados son recuentos semanales en intervalos de siete dias desde la fecha inicial solicitada.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `start_date` | Si | Inicio del periodo como milisegundos desde Unix epoch. |
> | Query | `end_date` | Si | Fin del periodo como milisegundos desde Unix epoch. |
> | Query | `type` | Si | `Thread`, `Interactions`, `artifact_agent_flow` o `artifact_document`; no distingue mayusculas. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/timeseries?start_date=1769990400000&end_date=1771804800000&type=interactions" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   { "date": "2026-02-02", "value": 18 },
>   { "date": "2026-02-09", "value": 25 },
>   { "date": "2026-02-16", "value": 21 },
>   { "date": "2026-02-23", "value": 19 }
> ]
> ```

## Errores y casos límite

* **400**: rango de fechas o tipo inválido.
* **403**: permisos insuficientes.


# Incidencias
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/issues

Crea y gestiona incidencias comunicadas por usuarios.

> [!WARNING]
>
> En 1.58, los filtros de creador usan IDs de cuenta y sus respuestas contienen datos de cuenta. Consulta [Migración de API 1.57 → 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#ids-de-cuenta-y-campos-renombrados) antes de actualizar tu integración.

Las incidencias (`issues`) permiten comunicar problemas con respuestas o contenido. Usa estos endpoints para listar, crear, actualizar y cerrar incidencias.

## Listar incidencias

Lista incidencias con `GET /api/v1/app/issue` antes de crear o actualizar.

> **Parametros del endpoint**
>
> | Parámetro de consulta | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `include` | string | No | Lista separada por comas de `Account` y `Project` para incluir objetos relacionados. |
> | `type` | string | No | Tipos de incidencia separados por comas: `NoAnswer`, `Inaccurate`, `NoContextUsed`, `Format`, `Other`. |
> | `states` | string | No | Estados separados por comas: `NotReviewed`, `InReview`, `Closed`, `Deleted`. |
> | `start_date` / `end_date` | integer | No | Filtro de creación en epoch milliseconds. |
> | `filter_by_text` | string | No | Filtro de texto sobre el contenido de la incidencia. |
> | `created_by` | string | No | IDs de cuenta separados por comas. |
> | `projects` | string | No | IDs de proyecto separados por comas. |
> | `page`, `page_size`, `after`, `before` | mixed | No | Controles de paginación. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/issue?page=1&page_size=20&include=Account,Project&states=NotReviewed,InReview" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "issue_5c4b3a2d1e0f9a8b",
>       "issue_number": 1842,
>       "description": "Response missed the attached policy details.",
>       "resource_type": "Thread",
>       "type": "NoContextUsed",
>       "state": "NotReviewed",
>       "is_read": false,
>       "data": {
>         "thread_id": "thread_3f2a1c4d5b6e7f8a",
>         "reported_interaction_id": "interaction_9b8a7c6d5e4f"
>       },
>       "created_at": "2026-02-08T14:55:10Z",
>       "updated_at": "2026-02-08T14:55:10Z",
>       "created_by": {
>         "id": "acct_6c8a1f3b2d4e5f7a",
>         "state": "Active",
>         "email": "sasha@example.com",
>         "name": "Sasha Patel",
>         "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>         "provider": "Credentials",
>         "roles": ["Workspace"],
>         "created_at": "2026-02-08T14:12:45Z",
>         "updated_at": "2026-02-08T14:12:45Z"
>       },
>       "project": {
>         "id": "proj_7a5c3e1b9d2f4a6c",
>         "name": "Customer Insights"
>       }
>     }
>   ],
>   "next_cursor": null,
>   "previous_cursor": null,
>   "has_next_page": false,
>   "has_previous_page": false,
>   "total_count": 1
> }
> ```

## Crear una incidencia

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `project_id` | Si | Proyecto donde vive el recurso reportado. |
> | Body | `description` | No | Descripción introducida por el usuario. |
> | Body | `resource_type` | Si | Actualmente `Thread`. |
> | Body | `type` | Si | Uno de `NoAnswer`, `Inaccurate`, `NoContextUsed`, `Format`, `Other`. |
> | Body | `config` | Si | Payload específico del recurso. Para incidencias de hilo, usa `thread_id` y `reported_interaction_id`. |
> | Body | `anonymous` | Si | Indica si se oculta el usuario que reporta la incidencia. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/issue" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_7a5c3e1b9d2f4a6c",
    "description": "Response missed the attached policy details.",
    "resource_type": "Thread",
    "type": "NoContextUsed",
    "config": {
      "thread_id": "thread_3f2a1c4d5b6e7f8a",
      "reported_interaction_id": "interaction_9b8a7c6d5e4f"
    },
    "anonymous": false
  }'
```

La petición de creación usa `config`. Las respuestas exponen el payload almacenado como `data`.

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "issue_5c4b3a2d1e0f9a8b",
>   "issue_number": 1842,
>   "description": "Response missed the attached policy details.",
>   "resource_type": "Thread",
>   "type": "NoContextUsed",
>   "state": "NotReviewed",
>   "is_read": false,
>   "data": {
>     "thread_id": "thread_3f2a1c4d5b6e7f8a",
>     "reported_interaction_id": "interaction_9b8a7c6d5e4f"
>   },
>   "created_at": "2026-02-08T14:55:10Z",
>   "updated_at": "2026-02-08T14:55:10Z"
> }
> ```

## Obtener o actualizar una incidencia

**Obtener incidencia**

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/issue/{issueID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "issue_5c4b3a2d1e0f9a8b",
>   "issue_number": 1842,
>   "description": "Response missed the attached policy details.",
>   "resource_type": "Thread",
>   "type": "NoContextUsed",
>   "state": "NotReviewed",
>   "is_read": false,
>   "data": {
>     "thread_id": "thread_3f2a1c4d5b6e7f8a",
>     "reported_interaction_id": "interaction_9b8a7c6d5e4f"
>   },
>   "created_at": "2026-02-08T14:55:10Z",
>   "updated_at": "2026-02-08T14:55:10Z"
> }
> ```

**Actualizar incidencia**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `issueID` | Si | Identificador de la incidencia. |
> | Body | `description` | No | Descripción actualizada. |
> | Body | `type` | No | Tipo de incidencia actualizado. |
> | Body | `state` | No | Estado actualizado. |
> | Body | `is_read` | No | Marca de lectura. Por defecto es `false` si se omite, así que incluye el valor deseado al actualizar otros campos. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/issue/{issueID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Reviewed by support.",
    "type": "NoContextUsed",
    "state": "InReview",
    "is_read": true
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "issue_5c4b3a2d1e0f9a8b",
>   "issue_number": 1842,
>   "description": "Reviewed by support.",
>   "resource_type": "Thread",
>   "type": "NoContextUsed",
>   "state": "InReview",
>   "is_read": true,
>   "data": {
>     "thread_id": "thread_3f2a1c4d5b6e7f8a",
>     "reported_interaction_id": "interaction_9b8a7c6d5e4f"
>   },
>   "created_at": "2026-02-08T14:55:10Z",
>   "updated_at": "2026-02-08T15:05:10Z"
> }
> ```

## Eliminar una incidencia

La eliminación marca la incidencia como eliminada y devuelve el objeto actualizado.

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/issue/{issueID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "issue_5c4b3a2d1e0f9a8b",
>   "issue_number": 1842,
>   "resource_type": "Thread",
>   "type": "NoContextUsed",
>   "state": "Deleted",
>   "is_read": true,
>   "data": {
>     "thread_id": "thread_3f2a1c4d5b6e7f8a",
>     "reported_interaction_id": "interaction_9b8a7c6d5e4f"
>   },
>   "created_at": "2026-02-08T14:55:10Z",
>   "updated_at": "2026-02-08T15:10:00Z"
> }
> ```

## Errores y casos límite

* **404**: incidencia no encontrada.
* **400**: estado, tipo o config de hilo inválidos.


# Visión general
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/overview

Endpoints de monitorización, informes y sistema para la Workspace API.

Usa la sección General para monitorizar el uso, revisar incidencias, buscar contenido y comprobar el estado del sistema.

> **[Analíticas](/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/analytics)**
>
> Totales, rankings y series de tiempo de uso.

> **[Incidencias](/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/issues)**
>
> Gestiona incidencias comunicadas por usuarios.

> **[Búsqueda](/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/search)**
>
> Consulta proyectos, hilos, artefactos e interacciones.

> **[Sistema](/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/system)**
>
> Comprobaciones de salud y estado del sistema.


# Búsqueda
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/search

Busca en proyectos, hilos, artefactos, contenido de artefactos e interacciones.

Usa la API de búsqueda para consultar contenido visible para el miembro autenticado del espacio de trabajo. Puedes combinar filtros de texto, recurso, proyecto, tipo de artefacto y fecha de creación en una sola solicitud.

## Requisitos previos

* Envía un token de API cuyos permisos efectivos incluyan la búsqueda en Workspace.
* Envía el slug de la organización en la cabecera `x-org`.
* La búsqueda semántica de `ArtifactContent` requiere un gateway de PrivateGPT vinculado a la colección de la organización. Las búsquedas solo por palabras clave no usan el motor semántico.

## Buscar contenido de Workspace

Busca con `GET /api/v1/app/search`.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `q` | Si | Texto de búsqueda. Los espacios iniciales y finales se eliminan antes de validar el rango configurado: de 3 a 80 caracteres de forma predeterminada. |
> | Query | `types` | No | Tipos de resultado. Acepta valores separados por comas o repetidos: `Project`, `Artifact`, `Thread`, `Interaction` y `ArtifactContent`. Por defecto incluye todos los tipos. |
> | Query | `type` | No | Alternativa a `types`. Solo se usa cuando `types` está ausente. |
> | Query | `project_ids` | No | Lista de UUID de proyectos que se incluirán. Acepta valores separados por comas o repetidos y busca únicamente en proyectos que también sean visibles para quien realiza la llamada. |
> | Query | `exclude_project_ids` | No | Lista de UUID de proyectos que se excluirán. Acepta valores separados por comas o repetidos. La exclusión prevalece cuando un ID aparece en ambos filtros de proyecto. |
> | Query | `artifact_types` | No | Tipos de artefacto para resultados `Artifact` y `ArtifactContent`. Acepta valores separados por comas o repetidos. |
> | Query | `start_date` | No | Límite inferior inclusivo de la fecha de creación, en milisegundos desde la época Unix. |
> | Query | `end_date` | No | Límite superior inclusivo de la fecha de creación, en milisegundos desde la época Unix. No puede ser anterior a `start_date`. |
> | Query | `limit` | No | Límite positivo aplicado por separado a cada tipo de resultado. El valor predeterminado es `30`. |

Los parámetros de lista distinguen mayúsculas de minúsculas, eliminan espacios y duplicados, y admiten ambos formatos:

```text theme={null}
types=Artifact,ArtifactContent
types=Artifact&types=ArtifactContent
```

`artifact_types` acepta `InlineText`, `Document`, `Folder`, `Summary`, `Composition`, `SmartDoc`, `Link`, `BulkQA`, `ReadAndExtract`, `SqlDatabase`, `McpServer`, `Integration`, `Analysis` y `Skill`. El contenido que se puede buscar actualmente incluye artefactos de la familia de documentos, enlaces visibles a ellos y flujos de agentes. Otros tipos de artefacto válidos pueden no producir resultados de artefactos o contenido.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/search?q=support%20summary&types=Artifact,ArtifactContent&project_ids={projectID}&artifact_types=Document,InlineText&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "id": "0198cc5a-4411-7000-8000-000000000001",
>     "type": "Artifact",
>     "match": "Q1 Support Summary",
>     "rank": 0.0241,
>     "keyword_score": 0.76,
>     "metadata": {
>       "name": "Q1 Support Summary",
>       "type": "Document",
>       "project_id": "0198cc5a-4411-7000-8000-000000000010",
>       "project_name": "Customer Insights"
>     }
>   },
>   {
>     "id": "0198cc5a-4411-7000-8000-000000000002",
>     "type": "ArtifactContent",
>     "match": "Billing issues drove a significant share of support cases.",
>     "rank": 0.0014,
>     "semantic_score": 0.84,
>     "metadata": {
>       "name": "Support Analysis",
>       "type": "Document",
>       "project_id": "0198cc5a-4411-7000-8000-000000000010",
>       "project_name": "Customer Insights"
>     }
>   }
> ]
> ```

## Comportamiento de los filtros

* Si `types` y `type` están presentes, `types` tiene prioridad y `type` se ignora.
* Si omites `project_ids`, la búsqueda incluye todos los proyectos visibles. Los ID válidos de proyectos no accesibles se excluyen sin devolver un error.
* `exclude_project_ids` se aplica después de `project_ids`. Si no queda ningún proyecto, la respuesta es `[]`.
* Los límites de fecha usan la fecha de creación de cada entidad. En resultados de contenido semántico, usan la fecha de creación del artefacto.
* El filtro de tipo de artefacto solo afecta a resultados `Artifact` y `ArtifactContent`.
* La búsqueda solo devuelve proyectos visibles, hilos activos visibles y sus interacciones, y artefactos disponibles y listos para usar.

## Campos de respuesta

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | string | Identificador del resultado. Un resultado creado a partir de un enlace usa el ID del enlace. |
| `type` | string | `Project`, `Artifact`, `Thread`, `Interaction` o `ArtifactContent`. |
| `match` | string | Nombre o fragmento de contenido coincidente. En los fragmentos semánticos se elimina el formato Markdown. |
| `rank` | number | Puntuación combinada y ponderada usada para ordenar la respuesta. Siempre está presente. |
| `keyword_score` | number, opcional | Puntuación original de búsqueda por palabras clave. Se omite en resultados solo semánticos. |
| `semantic_score` | number, opcional | Puntuación original de búsqueda semántica. Se omite en resultados solo por palabras clave. |
| `metadata` | object | Detalles específicos del tipo de resultado. |

### Cómo interpretar las puntuaciones

* **`rank`** combina la puntuación de origen, su posición en la lista de resultados léxicos o semánticos y una ponderación dinámica del origen. No es una probabilidad ni un porcentaje de confianza y no tiene un rango fijo. Usa el orden devuelto en vez de aplicar un umbral fijo.
* **`keyword_score`** es la puntuación original de relevancia de búsqueda de texto completo de PostgreSQL. Los valores más altos se tratan como coincidencias léxicas más fuertes. Un nombre encontrado fuera del ranking de texto completo puede tener una puntuación de `0`.
* **`semantic_score`** es la puntuación original de recuperación semántica para el fragmento de contenido seleccionado. No es una confianza normalizada.
* Compara puntuaciones originales solo entre resultados producidos por el mismo motor y para la misma consulta. No compares `keyword_score` con `semantic_score` ni puntuaciones de solicitudes distintas.
* Los campos opcionales de puntuación se omiten del JSON en lugar de devolverse como `null`.

> [!NOTE]
>
> Los resultados se agrupan en este orden: `Project`, `Artifact`, `Thread`, `Interaction` y `ArtifactContent`. Dentro de cada grupo, los valores de `rank` más altos aparecen primero. Como `limit` se aplica por tipo de resultado, una respuesta con varios tipos puede contener más de `limit` elementos en total. Las entradas devueltas por ambos motores de búsqueda no se deduplican.

## Metadatos por tipo de resultado

| Tipo de resultado | Forma de `metadata` |
| - | - |
| `Project` | `entity`, que contiene `id`, `name`, `goal`, `default_member_role`, `default_role_enabled`, `visibility`, `member_count`, `members`, `project_context`, `use_citations`, `use_system_prompt` e `is_pinned`. Cada miembro contiene `id`, `role`, `account` e `is_project_member`. |
| `Artifact` | `name`, `type`, `project_id` y `project_name`. Los campos del proyecto pueden ser `null`. |
| `ArtifactContent` | `name`, `type`, `project_id` y `project_name`. Un resultado de enlace conserva la identidad del enlace y los metadatos del proyecto de destino, mientras que `type` identifica el tipo del artefacto original. |
| `Thread` | `name`, `project_id` y `project_name`. |
| `Interaction` | `content`, `thread_id`, `project_id`, `project_name` y `thread_name`. |

## Errores y casos límite

* **400**: falta `q` o está vacío; consulta fuera del rango configurado; valores de lista vacíos o no válidos; UUID de proyecto no válido; fecha o límite no válidos; `start_date` posterior a `end_date`; `limit` menor que `1`; o falta el contexto de organización.
* **401**: autenticación ausente o no válida.
* **403**: el token o la cuenta no tienen permiso de búsqueda en Workspace.
* **500**: el despliegue no tiene idiomas de búsqueda configurados.
* Una búsqueda válida sin coincidencias visibles devuelve `[]`.


# Sistema
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/system

Comprobaciones de salud para la disponibilidad del workspace.

Usa estos endpoints para verificar el estado del sistema.

## Solicitud básica y respuesta

Usa la comprobación de salud con `GET /api/health` para verificar la disponibilidad.

```bash theme={null}
curl "https://{BASE_URL}/api/health"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "status": "ok",
>   "uptime": "3d 04:12:33",
>   "commit": "9f1c2a3"
> }
> ```

## Errores y casos límite

* **503**: comprobación de salud no disponible.


# Integración Claromentis
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/claromentis

Sincroniza contenido de Claromentis al espacio de trabajo.

Las integraciones de Claromentis importan contenido de la base de conocimiento. **Habilita Claromentis a nivel de instancia primero**—consulta la guía del operador: [Configuración de Claromentis](/es/v1.58/operator-manual/knowledge-base/claromentis).

## Requisitos previos

* Un token de Workspace API y el slug de la organización.
* Un proyecto de destino.
* Un usuario y una contraseña de Claromentis.

## Crear la integración

Crea la integración como un artefacto de tipo `Integration`. Las credenciales se guardan en `private_props` y no se devuelven en el `ArtifactDTO` público.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `project_id` | No | Proyecto propietario de la integración. Omítelo para una integración de organización; esa operación requiere `AppAdmin` o superior. |
> | Body | `type` | Si | Debe ser `Integration`. |
> | Body | `source` | Si | Debe ser `Claromentis`. |
> | Body | `name` | Si | Nombre visible de la integración. |
> | Body | `props` | Si | Usa `{}`. |
> | Body | `props.metadata` | No | Metadatos opcionales del proveedor. |
> | Body | `private_props.username` | Si | Usuario de Claromentis. |
> | Body | `private_props.password` | Si | Contraseña de Claromentis. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Integration",
    "source": "Claromentis",
    "name": "Base de conocimiento de Claromentis",
    "props": {},
    "private_props": {
      "username": "{claromentis_username}",
      "password": "{claromentis_password}"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{integrationArtifactID}",
>   "child_count": 0,
>   "project_id": "{projectID}",
>   "name": "Base de conocimiento de Claromentis",
>   "type": "Integration",
>   "source": "Claromentis",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "keep_file_after_ingestion": true,
>   "created_at": "2026-02-08T14:05:00Z",
>   "updated_at": "2026-02-08T14:05:00Z"
> }
> ```

## Actualizar las credenciales

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración. |
> | Body | `private_props.username` | Si | Nuevo usuario de Claromentis. |
> | Body | `private_props.password` | Si | Nueva contraseña de Claromentis. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "private_props": {
      "username": "{claromentis_username}",
      "password": "{claromentis_password}"
    }
  }'
```

La respuesta es el `ArtifactDTO` actualizado y no incluye `private_props`.

## Obtener la integración

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{integrationArtifactID}",
>   "child_count": 0,
>   "project_id": "{projectID}",
>   "name": "Base de conocimiento de Claromentis",
>   "type": "Integration",
>   "source": "Claromentis",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "keep_file_after_ingestion": true,
>   "created_by": {
>     "id": "{accountID}",
>     "state": "Active",
>     "email": "sasha@example.com",
>     "name": "Sasha Patel",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-02-08T14:12:45Z",
>     "updated_at": "2026-02-08T14:12:45Z"
>   },
>   "created_at": "2026-02-08T14:05:00Z",
>   "updated_at": "2026-02-08T15:10:00Z",
>   "scopes": [
>     {
>       "scope_type": "project",
>       "scope_id": "{projectID}",
>       "enabled": true,
>       "ws_auto_select": false
>     }
>   ]
> }
> ```

## Iniciar la ingesta

Indica el proyecto de destino, los IDs de carpeta y los IDs de documento que quieres importar. Envía ambos arrays, aunque uno de ellos esté vacío. La respuesta es un stream SSE.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración Claromentis. |
> | Body | `project_id` | Si | Proyecto de destino. |
> | Body | `folder_ids` | Si | IDs de carpetas que se importarán. |
> | Body | `docs_ids` | Si | IDs de documentos que se importarán. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "folder_ids": ["42"],
    "docs_ids": ["314"]
  }'
```

> **Ejemplo de stream**
>
> ```text theme={null}
> event: SyncEvent
> data: {"type":"sync_started","current_artifact_count":0,"integration_item_count":2}
>
> event: SyncEvent
> data: {"type":"sync_progress","artifact_id":"{artifactID}","op":"Added","progress":0.5}
>
> event: SyncEvent
> data: {"type":"sync_completed"}
> ```

## Errores y casos límite

* **400**: faltan campos obligatorios o las credenciales no son válidas.
* **403**: conector no habilitado o permisos insuficientes.
* **404**: proyecto o artefacto de integración no encontrado.


# Integración Confluence
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/confluence

Lee y sincroniza contenido de Confluence en el espacio de trabajo.

Las integraciones de Confluence importan páginas y espacios para usarlos como artefactos. **Debes habilitar Confluence a nivel de instancia primero**—consulta la guía del operador: [Configuración de Confluence](/es/v1.58/operator-manual/knowledge-base/confluence).

Para crear o volver a autenticar una integración de Confluence Cloud, usa el flujo descrito en [OpenID y OAuth](/es/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid). Ese flujo crea o actualiza el artefacto de integración sin exponer los tokens.

## Obtener la integración

Consulta la configuración pública con el endpoint general de artefactos. La respuesta no incluye `private_props` ni tokens OAuth.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración Confluence. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{integrationArtifactID}",
>   "child_count": 0,
>   "project_id": "{projectID}",
>   "name": "Confluence de soporte",
>   "type": "Integration",
>   "source": "Confluence",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "keep_file_after_ingestion": true,
>   "created_by": {
>     "id": "{accountID}",
>     "state": "Active",
>     "email": "sasha@example.com",
>     "name": "Sasha Patel",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-02-08T14:12:45Z",
>     "updated_at": "2026-02-08T14:12:45Z"
>   },
>   "created_at": "2026-03-01T11:00:00Z",
>   "updated_at": "2026-03-01T11:00:00Z",
>   "scopes": [
>     {
>       "scope_type": "project",
>       "scope_id": "{projectID}",
>       "enabled": true,
>       "ws_auto_select": false
>     }
>   ]
> }
> ```

## Iniciar la ingesta

Indica el proyecto de destino y los espacios que quieres importar. Esta operación sirve para integraciones de Confluence Cloud y ConfluenceLocal. La respuesta es un stream de Server-Sent Events (SSE).

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración. |
> | Body | `project_id` | Si | Proyecto de destino. |
> | Body | `space_ids` | Si | IDs de los espacios de Confluence que se importarán. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "space_ids": ["{spaceID}"]
  }'
```

> **Ejemplo de stream**
>
> ```text theme={null}
> event: SyncEvent
> data: {"type":"sync_started","current_artifact_count":0,"integration_item_count":120}
>
> event: SyncEvent
> data: {"type":"sync_progress","artifact_id":"{artifactID}","op":"Added","progress":0.42}
>
> event: SyncEvent
> data: {"type":"sync_completed"}
> ```

## ConfluenceLocal con autenticación básica

Los despliegues que usan el proveedor local guardan un artefacto con `source: ConfluenceLocalLegacy`. Las credenciales viajan en `private_props` y nunca se devuelven en respuestas públicas.

### Crear una integración ConfluenceLocal

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `project_id` | No | Proyecto propietario de la integración. Omítelo para una integración de organización; esa operación requiere `AppAdmin` o superior. |
> | Body | `type` | Si | Debe ser `Integration`. |
> | Body | `source` | Si | Debe ser `ConfluenceLocalLegacy`. |
> | Body | `name` | Si | Nombre visible de la integración. |
> | Body | `props` | Si | Usa `{}`. |
> | Body | `props.metadata` | No | Metadatos opcionales del proveedor. |
> | Body | `private_props.username` | Si | Usuario de ConfluenceLocal. |
> | Body | `private_props.password` | Si | Contraseña de ConfluenceLocal. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Integration",
    "source": "ConfluenceLocalLegacy",
    "name": "ConfluenceLocal de soporte",
    "props": {},
    "private_props": {
      "username": "{confluence_username}",
      "password": "{confluence_password}"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{integrationArtifactID}",
>   "child_count": 0,
>   "project_id": "{projectID}",
>   "name": "ConfluenceLocal de soporte",
>   "type": "Integration",
>   "source": "ConfluenceLocalLegacy",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "keep_file_after_ingestion": true,
>   "created_at": "2026-03-01T11:00:00Z",
>   "updated_at": "2026-03-01T11:00:00Z"
> }
> ```

### Actualizar las credenciales de ConfluenceLocal

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración ConfluenceLocal. |
> | Body | `private_props.username` | Si | Nuevo usuario de ConfluenceLocal. |
> | Body | `private_props.password` | Si | Nueva contraseña de ConfluenceLocal. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "private_props": {
      "username": "{confluence_username}",
      "password": "{confluence_password}"
    }
  }'
```

La respuesta es el `ArtifactDTO` actualizado. Usa el mismo `GET /api/v1/app/artifact/{integrationArtifactID}` para consultar sus campos públicos.

## Errores y casos límite

* **400**: faltan `project_id`, `space_ids` o las credenciales obligatorias.
* **403**: integración no habilitada o permisos insuficientes.
* **404**: proyecto o artefacto de integración no encontrado.


# Integración Filesystem
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/filesystem

Sincroniza archivos desde un sistema de archivos compartido al espacio de trabajo.

> [!WARNING]
>
> En 1.58, la validación de filesystem requiere credenciales anidadas incluso en la URL antigua. Consulta [Migración de API 1.57 → 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#peticiones-de-filesystem) antes de actualizar tu integración.

La integración de Filesystem conecta un directorio compartido con el espacio de trabajo. **Habilita el conector primero** en la guía del operador: [Configuración de Filesystem](/es/v1.58/operator-manual/knowledge-base/file-system).

## Requisitos previos

* Un token de Workspace API y el slug de la organización.
* Un proyecto de destino.
* Las credenciales de Filesystem configuradas para la instancia.

## Crear la integración

Crea la integración como un artefacto de tipo `Integration`. Las credenciales se envían en `private_props` y no se devuelven en las respuestas públicas.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `project_id` | No | Proyecto propietario de la integración. Omítelo para una integración de organización; esa operación requiere `AppAdmin` o superior. |
> | Body | `type` | Si | Debe ser `Integration`. |
> | Body | `source` | Si | Debe ser `FileSystem`. |
> | Body | `name` | Si | Nombre visible de la integración. |
> | Body | `props` | Si | Usa `{}`. |
> | Body | `props.metadata` | No | Metadatos opcionales del proveedor. |
> | Body | `private_props.username` | Si | Usuario de Filesystem. |
> | Body | `private_props.password` | Si | Contraseña de Filesystem. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Integration",
    "source": "FileSystem",
    "name": "Filesystem compartido",
    "props": {},
    "private_props": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{integrationArtifactID}",
>   "child_count": 0,
>   "project_id": "{projectID}",
>   "name": "Filesystem compartido",
>   "type": "Integration",
>   "source": "FileSystem",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "keep_file_after_ingestion": true,
>   "created_at": "2026-02-08T14:10:00Z",
>   "updated_at": "2026-02-08T14:10:00Z"
> }
> ```

## Actualizar las credenciales

Usa la operación general de actualización de artefactos. Envía solo los campos que quieras sustituir.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración. |
> | Body | `private_props.username` | Si | Nuevo usuario de Filesystem. |
> | Body | `private_props.password` | Si | Nueva contraseña de Filesystem. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "private_props": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'
```

La respuesta es el `ArtifactDTO` actualizado y nunca incluye `private_props`.

## Obtener la integración

Usa el endpoint público del artefacto. No hay que recuperar las credenciales para consultar o iniciar una ingesta.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{integrationArtifactID}",
>   "child_count": 0,
>   "project_id": "{projectID}",
>   "name": "Filesystem compartido",
>   "type": "Integration",
>   "source": "FileSystem",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "keep_file_after_ingestion": true,
>   "created_by": {
>     "id": "{accountID}",
>     "state": "Active",
>     "email": "sasha@example.com",
>     "name": "Sasha Patel",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-02-08T14:12:45Z",
>     "updated_at": "2026-02-08T14:12:45Z"
>   },
>   "created_at": "2026-02-08T14:10:00Z",
>   "updated_at": "2026-02-08T15:02:00Z",
>   "scopes": [
>     {
>       "scope_type": "project",
>       "scope_id": "{projectID}",
>       "enabled": true,
>       "ws_auto_select": false
>     }
>   ]
> }
> ```

## Validar credenciales

La validación acepta la organización, un proyecto opcional y las credenciales en el cuerpo. Si omites `project_id`, necesitas el rol `AppAdmin` o superior; si lo envías, necesitas como mínimo el rol `Admin` del proyecto.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `organization_id` | Si | ID de la organización seleccionada mediante `x-org`. |
> | Body | `project_id` | No | Proyecto donde se usarán las credenciales. |
> | Body | `credentials.username` | Si | Usuario de Filesystem. |
> | Body | `credentials.password` | Si | Contraseña de Filesystem. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/integration/filesystem/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "{organizationID}",
    "project_id": "{projectID}",
    "credentials": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> true
> ```

## Listar archivos

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración Filesystem. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/files" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "id": "/support/weekly-brief.pdf",
>     "parentId": "/support",
>     "name": "weekly-brief.pdf",
>     "path": "/support/weekly-brief.pdf",
>     "url": "file:///support/weekly-brief.pdf",
>     "parent": "support",
>     "isFile": true,
>     "isDirectory": false,
>     "isHidden": false,
>     "lastModified": 1770488530000
>   }
> ]
> ```

## Iniciar la ingesta

Indica el proyecto de destino y las rutas que quieres importar. La respuesta es un stream de Server-Sent Events (SSE).

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración Filesystem. |
> | Body | `project_id` | Si | Proyecto de destino. |
> | Body | `item_paths` | Si | Rutas de archivos o directorios que se importarán. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "item_paths": [
      "/support/weekly-brief.pdf",
      "/support/runbooks"
    ]
  }'
```

> **Ejemplo de stream**
>
> ```text theme={null}
> event: SyncEvent
> data: {"type":"sync_started","current_artifact_count":0,"integration_item_count":2}
>
> event: SyncEvent
> data: {"type":"sync_progress","artifact_id":"{artifactID}","op":"Added","progress":0.5}
>
> event: SyncEvent
> data: {"type":"sync_completed"}
> ```

## Errores y casos límite

* **400**: faltan campos obligatorios o `project_id` no es válido.
* **403**: conector no habilitado o permisos insuficientes.
* **404**: organización, proyecto o artefacto de integración no encontrado.


# Integración SharePoint
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/sharepoint

Sincroniza documentos de SharePoint en el espacio de trabajo.

Las integraciones de SharePoint importan bibliotecas y documentos. **Habilita SharePoint a nivel de instancia primero**—consulta la guía del operador: [Configuración de SharePoint](/es/v1.58/operator-manual/knowledge-base/sharepoint).

Usa el flujo de [OpenID y OAuth](/es/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid) para crear o volver a autenticar el artefacto de integración. Los tokens se guardan como propiedades privadas y no se devuelven en la API pública de artefactos.

## Obtener la integración

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración SharePoint. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{integrationArtifactID}",
>   "child_count": 0,
>   "project_id": "{projectID}",
>   "name": "SharePoint de soporte",
>   "type": "Integration",
>   "source": "SharePoint",
>   "state": "Published",
>   "ingest_status": "NotApplicable",
>   "props": {},
>   "keep_file_after_ingestion": true,
>   "created_by": {
>     "id": "{accountID}",
>     "state": "Active",
>     "email": "sasha@example.com",
>     "name": "Sasha Patel",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-02-08T14:12:45Z",
>     "updated_at": "2026-02-08T14:12:45Z"
>   },
>   "created_at": "2026-03-01T11:00:00Z",
>   "updated_at": "2026-03-01T11:00:00Z",
>   "scopes": [
>     {
>       "scope_type": "project",
>       "scope_id": "{projectID}",
>       "enabled": true,
>       "ws_auto_select": false
>     }
>   ]
> }
> ```

## Iniciar la ingesta

Indica el proyecto de destino y los elementos que quieres importar. Cada elemento necesita el ID de la unidad y el ID del archivo o carpeta. La respuesta es un stream de Server-Sent Events (SSE).

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `integrationArtifactID` | Si | ID del artefacto de integración SharePoint. |
> | Body | `project_id` | Si | Proyecto de destino. |
> | Body | `items` | Si | Elementos de SharePoint que se importarán. |
> | Body | `items[].drive_id` | Si | ID de la unidad de SharePoint. |
> | Body | `items[].id` | Si | ID del archivo o carpeta. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "items": [
      {
        "drive_id": "{driveID}",
        "id": "{itemID}"
      }
    ]
  }'
```

> **Ejemplo de stream**
>
> ```text theme={null}
> event: SyncEvent
> data: {"type":"sync_started","current_artifact_count":0,"integration_item_count":1}
>
> event: SyncEvent
> data: {"type":"sync_progress","artifact_id":"{artifactID}","op":"Added","progress":1.0}
>
> event: SyncEvent
> data: {"type":"sync_completed"}
> ```

## Errores y casos límite

* **400**: faltan `project_id`, `items` o alguno de sus IDs.
* **403**: integración no habilitada o permisos insuficientes.
* **404**: proyecto, elemento o artefacto de integración no encontrado.


# Visión general
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/overview

API para automatizar y gestionar Zylon Workspace.

> [!WARNING]
>
> **Cambios incompatibles en la API de 1.58**
>
> Antes de actualizar una integración desde 1.57, sigue la [guía de migración de API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58). La versión 1.58 cambia las rutas y los cuerpos de contenido de artefactos, los IDs de cuenta y de miembro del espacio de trabajo, y los bloques de respuesta de herramientas del servidor en los mensajes de Workspace y ZylonGPT. Las rutas antiguas no conservan todo el contrato de 1.57 y quedan obsoletas, con eliminación prevista para 1.59.

La Workspace API te permite gestionar por API **todo lo que ocurre en Zylon Workspace**: organizaciones, miembros del espacio de trabajo, proyectos, chats, artefactos, integraciones e informes. Úsala para automatizar tareas de administración o integrar Zylon con tus sistemas internos.

## Actualizar a 1.58

Consulta la [guía de migración 1.57 → 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) para las rutas antiguas conservadas, cuerpos de artefactos y cambios de chat/hilos. Si tu integración usa IDs de usuario o cuenta, migra los mapeos y comparaciones afectados: los IDs de creador ahora identifican cuentas, mientras que las APIs de membresía siguen usando IDs de miembro. Que una petición funcione no garantiza que los IDs almacenados sigan coincidiendo. Para integraciones que necesiten identidad de usuario o filtros de creador, usa la API actual y sigue la [búsqueda de ID de cuenta a partir del ID de miembro](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#migrar-ids-de-usuario-guardados); las URLs antiguas conservadas no hacen esa conversión.

## Base URL

Todos los endpoints de Workspace viven bajo:

```
https://{BASE_URL}/api/v1
```

## Cabecera de organización (`x-org`)

Los endpoints de Workspace bajo `/api/v1/app/*` requieren la cabecera `x-org` para que Zylon sepa a qué organización del workspace apuntar.

Puedes enviar `x-org` como:

* el slug de la organización (recomendado), por ejemplo `default`
* el ID de la organización (UUID)

Úsalo así en tus solicitudes:

```bash theme={null}
-H "x-org: {org_slug}"
```

## Scopes de token de solo lectura

`Workspace.Read.All` permite lecturas y búsquedas de Workspace, incluidas organizaciones, miembros del espacio de trabajo, proyectos, artefactos, hilos, interacciones, incidencias, feedback e integraciones. No permite mutaciones de Workspace; las operaciones de creación, actualización, eliminación, unión y otras escrituras devuelven `403`.

`Read.All` incluye los mismos permisos de lectura/búsqueda de Workspace y también inventario de cuentas, tokens y gateways y lecturas de Backoffice/metadatos. Su [allowlist de solo lectura de ZylonGPT](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview) solo se puede usar cuando el token de cuenta incluye `gateway_id`; un token `Read.All` creado sin contexto de gateway no puede llamar a ZylonGPT. El acceso efectivo siempre queda limitado por los permisos de rol del propietario del token. Los scopes múltiples combinan sus permisos. Consulta [Gestión de tokens](/es/v1.58/developer-manual/get-started/token-management) para ver los seis scopes y las reglas de creación.

## Conceptos clave

| Concepto | Significado |
| - | - |
| **Cuenta (`Account`)** | Registro de identidad que se autentica en Zylon. Una cuenta puede pertenecer a varias organizaciones. |
| **Miembro del espacio de trabajo (`WorkspaceMember`)** | Membresía de una cuenta dentro de una organización. Una cuenta puede tener **varios miembros del espacio de trabajo**, uno por organización. |
| **Artefacto (`Artifact`)** | Contenido persistente que puede reutilizarse en chats y herramientas. |

Este modelo permite escenarios multi‑organización en los que una misma persona puede pertenecer a varios espacios de trabajo con roles distintos.

## Paginación

La paginación es un modelo compartido en la Workspace API. Los listados devuelven un sobre con cursores:

> **Ejemplo de sobre de paginación**
>
> ```json theme={null}
> {
>   "data": [],
>   "next_cursor": "cursor_next",
>   "previous_cursor": "cursor_prev",
>   "has_next_page": false,
>   "has_previous_page": false,
>   "total_count": 0
> }
> ```

Usa `page`, `page_size`, `after`, `before`, `first`, `last` y `total_count` cuando estén disponibles.

## Secciones de Workspace API

> **[General](/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/overview)**
>
> Analíticas, incidencias, búsqueda y estado del sistema.

> **[Autenticación](/es/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid)**
>
> Flujos SSO y callbacks de login/autenticación de workspace.

> **[Miembros del espacio de trabajo](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user)**
>
> Crea, actualiza y gestiona el acceso de miembros del espacio de trabajo y su pertenencia a organizaciones.

> **[Proyectos](/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project)**
>
> Aprovisiona proyectos, gestiona miembros y controla la visibilidad.

> **[Chats](/es/v1.58/developer-manual/build-with-zylon/workspace-api/chats/threads)**
>
> Crea hilos, ejecuta interacciones y transmite respuestas en streaming.

> **[Contenido](/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts)**
>
> Gestiona artefactos e integraciones como Confluence, SharePoint, Filesystem y Claromentis.

## Errores y casos límite

* **401/403**: token ausente o permisos insuficientes.
* **404**: IDs inválidos o eliminados.
* **Redirecciones**: login/callback devuelven `302` para navegadores.


# Proyectos
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project

Crea proyectos, actualiza metadatos y ejecuta chats a nivel de proyecto.

Los proyectos son la unidad del espacio de trabajo que contiene hilos, artefactos y contexto de equipo. Usa estos endpoints para crear y configurar proyectos, transferir la propiedad e iniciar chats con alcance de proyecto.

## Solicitud básica y respuesta

Crea un proyecto con `POST /api/v1/app/project`.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Body | `name` | Si | Nombre del proyecto. |
> | Body | `goal` | No | Objetivo o descripcion del proyecto. |
> | Body | `visibility` | No | `Public` o `Private`; por defecto `Private`. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Insights",
    "goal": "Summarize weekly support trends.",
    "visibility": "Private"
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{projectID}",
>   "name": "Customer Insights",
>   "goal": "Summarize weekly support trends.",
>   "default_member_role": "Viewer",
>   "default_role_enabled": false,
>   "visibility": "Private",
>   "use_citations": true,
>   "use_system_prompt": true,
>   "is_pinned": false
> }
> ```

### Campos de respuesta del proyecto

Crear, obtener, PUT, PATCH y DELETE devuelven este modelo JSON con `200`. Los campos nulos pueden omitirse. Al crear se usa `Viewer`, `default_role_enabled:false`, `use_citations:true`, `use_system_prompt:true`. Los miembros anidados usan el [modelo de Miembros del proyecto](/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project-member).

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | ID de proyecto. |
| `name` | string | Nombre. |
| `goal` | string or null | Objetivo opcional. |
| `default_member_role` | string | `Viewer`, `Commenter`, `Editor`, `Admin`, `Owner`. |
| `default_role_enabled` | boolean | Si los no miembros reciben el rol predeterminado. |
| `visibility` | string | `Public` o `Private`. |
| `member_count` | integer or null | Total incluido en operaciones de detalle/lista cuando existe. |
| `members` | object\[] or null | Miembros cuando se solicitan; cada uno tiene `id` (ID de miembro), `role`, `account`, `is_project_member`. Consulta Miembros del proyecto para el modelo de cuenta. |
| `project_context` | string or null | Instrucciones opcionales del proyecto. |
| `use_citations` | boolean | Ajuste de citas. |
| `use_system_prompt` | boolean | Ajuste del system prompt. |
| `is_pinned` | boolean or null | Estado de fijacion del miembro actual cuando existe; las respuestas de modificacion usan false por defecto. |

## Obtener un proyecto

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{projectID}",
>   "name": "Customer Insights",
>   "goal": "Summarize weekly support trends.",
>   "default_member_role": "Viewer",
>   "default_role_enabled": false,
>   "visibility": "Private",
>   "use_citations": true,
>   "use_system_prompt": true,
>   "is_pinned": false,
>   "member_count": 1
> }
> ```

## Actualizar un proyecto

PUT y PATCH aceptan los mismos campos opcionales. Los valores omitidos o null mantienen los ajustes actuales. Se recortan los espacios de `project_context`; una cadena vacia o de espacios lo elimina. La instalacion limita su longitud. `default_role_enabled:true` hace el proyecto `Public`; false lo hace `Private`, con prioridad sobre `visibility` si tambien se envia.

**PUT**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | `name` | No | Nombre del proyecto. |
> | Body | `goal` | No | Objetivo o descripcion del proyecto. |
> | Body | `visibility` | No | `Public` o `Private`. |
> | Body | `project_context` | No | Contexto del proyecto. |
> | Body | `default_member_role` | No | `Viewer`, `Commenter`, `Editor`, `Admin` u `Owner`. |
> | Body | `default_role_enabled` | No | Habilita el rol predeterminado. |
> | Body | `use_citations` | No | Habilita las citas del chat del proyecto. |
> | Body | `use_system_prompt` | No | Habilita el system prompt del chat del proyecto. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Insights",
    "goal": "Summarize weekly support and churn signals.",
    "visibility": "Public",
    "project_context": "Support analytics for Q1.",
    "default_member_role": "Editor",
    "default_role_enabled": true,
    "use_citations": true,
    "use_system_prompt": true
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{projectID}",
>   "name": "Customer Insights",
>   "goal": "Summarize weekly support and churn signals.",
>   "default_member_role": "Editor",
>   "default_role_enabled": true,
>   "visibility": "Public",
>   "use_citations": true,
>   "use_system_prompt": true,
>   "is_pinned": false,
>   "project_context": "Support analytics for Q1."
> }
> ```

**PATCH**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | Los campos de PUT anteriores | No | Actualizacion parcial; envia solo los campos a cambiar. |

```bash theme={null}
curl -X PATCH "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_context": "Support analytics for Q1 with strict PII handling."
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{projectID}",
>   "name": "Customer Insights",
>   "goal": "Summarize weekly support trends.",
>   "default_member_role": "Viewer",
>   "default_role_enabled": false,
>   "visibility": "Private",
>   "use_citations": true,
>   "use_system_prompt": true,
>   "is_pinned": false,
>   "project_context": "Support analytics for Q1 with strict PII handling."
> }
> ```

## Eliminar un proyecto

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{projectID}",
>   "name": "Customer Insights",
>   "goal": "Summarize weekly support trends.",
>   "default_member_role": "Viewer",
>   "default_role_enabled": false,
>   "visibility": "Private",
>   "use_citations": true,
>   "use_system_prompt": true,
>   "is_pinned": false
> }
> ```

DELETE elimina el proyecto y devuelve su modelo, en lugar de `204 No Content`.

## Salir de un proyecto

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/leave" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```text theme={null}
> HTTP/1.1 200 OK
>
> 200
> ```

## Transferir la propiedad de un proyecto

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | `old_owner_ws_member_id` | Si | ID de miembro del espacio de trabajo del propietario actual. |
> | Body | `new_owner_ws_member_id` | Si | ID de miembro del espacio de trabajo del nuevo propietario; debe identificar a un miembro del proyecto. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/transfer" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "old_owner_ws_member_id": "{currentOwnerWsMemberId}",
    "new_owner_ws_member_id": "{newOwnerWsMemberId}"
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{newOwnerWsMemberId}",
>   "role": "Owner",
>   "account": {
>     "id": "{accountId}",
>     "state": "Active",
>     "email": "jordan@example.com",
>     "name": "Jordan Lee",
>     "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-01-10T09:00:00Z",
>     "updated_at": "2026-02-07T09:20:12Z"
>   },
>   "is_project_member": true
> }
> ```

## Información del miembro del espacio de trabajo en el proyecto

Obtén la información del proyecto para un miembro específico del espacio de trabajo o actualízala para el miembro autenticado actualmente.

**Obtener información del miembro**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Path | `wsMemberId` | Si | ID del miembro del espacio de trabajo. No se admite el valor `me`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/info/{wsMemberId}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "project_id": "{projectId}",
>   "is_pinned": true
> }
> ```

**Actualizar información del miembro actual**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | `is_pinned` | Si | Fija o desfija el proyecto para el miembro del espacio de trabajo autenticado actualmente. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/info" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_pinned": true
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "project_id": "{projectId}",
>   "is_pinned": true
> }
> ```

## Chat con alcance de proyecto

Usa el endpoint actual `POST /api/v1/app/chat` con `project_id` en el cuerpo. La URL de compatibilidad `POST /api/v1/app/project/{projectID}/chat` sigue disponible; migra los clientes al endpoint actual. La ruta actual siempre devuelve SSE.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `project_id` | Si | Proyecto cuyo contexto se usa. |
> | Body | `pgpt` | Si | Solicitud de Messages con exactamente un mensaje de usuario. |
> | Body | `artifacts` | No | Selectores de artefactos por alcance. |

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/chat" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "artifacts": {
      "document": [
        {
          "scope": "project",
          "all_artifacts": true
        }
      ]
    },
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarize the latest support trends in three bullets."
            }
          ]
        }
      ],
      "max_tokens": 80,
      "temperature": 0.2
    }
  }'
```

Consulta [Chats](/es/v1.58/developer-manual/build-with-zylon/workspace-api/chats/threads#chat-puntual) para los eventos SSE y los modelos de cuerpo y seleccion de artefactos. La URL antigua del proyecto respeta `pgpt.stream`: true transmite eventos; false devuelve una respuesta de Message.

## Errores y casos límite

* **403**: no eres miembro del proyecto.
* **404**: proyecto no encontrado.
* **409**: el miembro del espacio de trabajo de destino no es elegible para transferir.


# Miembros del proyecto
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project-member

Agrega, actualiza y elimina miembros de un proyecto.

> [!WARNING]
>
> Los campos de miembros de proyecto y las respuestas de cuenta cambian en 1.58. Consulta [Migración de API 1.57 → 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#ids-de-cuenta-y-campos-renombrados) antes de actualizar tu integración.

Usa estos endpoints para controlar quién puede acceder a un proyecto y qué rol tiene. Roles: `Viewer`, `Commenter`, `Editor`, `Admin`, `Owner`.

Las respuestas de miembro del proyecto usan el ID del miembro del espacio de trabajo en `id` e incluyen la cuenta relacionada en `account`.

## Solicitud básica y respuesta

Lista miembros actuales con `GET /api/v1/app/project/{projectId}/member`.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Query | `page` | No | Numero absoluto de pagina, empezando en 1. |
> | Query | `page_size` | No | Numero de elementos por pagina. Predeterminado `20`. |
> | Query | `page_order` | No | `ASC` o `DESC`. Predeterminado `ASC`. |
> | Query | `after` | No | Cursor o valor desde el que paginar hacia delante. |
> | Query | `before` | No | Cursor o valor desde el que paginar hacia atras. |
> | Query | `first` | No | Limita a los primeros N elementos tras un cursor. |
> | Query | `last` | No | Limita a los ultimos N elementos antes de un cursor. |
> | Query | `total_count` | No | Incluye el total en la respuesta. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/member?page=1&page_size=50&total_count=true" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "{wsMemberId}",
>       "role": "Owner",
>       "account": {
>         "id": "{accountId}",
>         "state": "Active",
>         "email": "sasha@example.com",
>         "name": "Sasha Patel",
>         "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>         "provider": "Credentials",
>         "roles": ["Workspace"],
>         "created_at": "2026-01-10T09:00:00Z",
>         "updated_at": "2026-02-08T14:12:45Z"
>       },
>       "is_project_member": true
>     }
>   ],
>   "has_next_page": false,
>   "has_previous_page": false,
>   "total_count": 1
> }
> ```

## Agregar miembros

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | `members` | Si | Lista de miembros a agregar. |
> | Body | `members[].ws_member_id` | Si | Identificador del miembro del espacio de trabajo. |
> | Body | `members[].role` | Si | `Viewer`, `Commenter`, `Editor`, `Admin` u `Owner`. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/member" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      { "ws_member_id": "{wsMemberId}", "role": "Editor" }
    ]
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "id": "{wsMemberId}",
>     "role": "Editor",
>     "account": {
>       "id": "{accountId}",
>       "state": "Active",
>       "email": "jordan@example.com",
>       "name": "Jordan Lee",
>       "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>       "provider": "Credentials",
>       "roles": ["Workspace"],
>       "created_at": "2026-01-10T09:00:00Z",
>       "updated_at": "2026-02-07T09:20:12Z"
>     },
>     "is_project_member": true
>   }
> ]
> ```

## Actualizar roles de miembros

> **Parametros del endpoint**
>
> | Tipo | Nombre | Requerido | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Body | `members` | Si | Lista de miembros a actualizar. |
> | Body | `members[].ws_member_id` | Si | Identificador del miembro del espacio de trabajo. |
> | Body | `members[].role` | No | `Viewer`, `Commenter`, `Editor`, `Admin` u `Owner`. |
> | Body | `members[].is_pinned` | No | Fija o desfija el proyecto para ese miembro. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}/member" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      { "ws_member_id": "{wsMemberId}", "role": "Admin", "is_pinned": true }
    ]
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> [
>   {
>     "id": "{wsMemberId}",
>     "role": "Admin",
>     "account": {
>       "id": "{accountId}",
>       "state": "Active",
>       "email": "jordan@example.com",
>       "name": "Jordan Lee",
>       "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>       "provider": "Credentials",
>       "roles": ["Workspace"],
>       "created_at": "2026-01-10T09:00:00Z",
>       "updated_at": "2026-02-07T09:20:12Z"
>     },
>     "is_project_member": true
>   }
> ]
> ```

## Obtener o quitar un miembro

Usa `me` en lugar de `wsMemberId` para dirigirte al miembro autenticado del espacio de trabajo.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `projectID` | Si | Identificador del proyecto. |
> | Path | `wsMemberId` | Si | ID del miembro, o `me` para el miembro autenticado. |

**Obtener miembro**

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/member/{wsMemberId}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "role": "Admin",
>   "account": {
>     "id": "{accountId}",
>     "state": "Active",
>     "email": "jordan@example.com",
>     "name": "Jordan Lee",
>     "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-01-10T09:00:00Z",
>     "updated_at": "2026-02-07T09:20:12Z"
>   },
>   "is_project_member": true
> }
> ```

**Eliminar miembro**

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/member/{wsMemberId}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "role": "Admin",
>   "account": {
>     "id": "{accountId}",
>     "state": "Active",
>     "email": "jordan@example.com",
>     "name": "Jordan Lee",
>     "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-01-10T09:00:00Z",
>     "updated_at": "2026-02-07T09:20:12Z"
>   },
>   "is_project_member": true
> }
> ```

## Errores y casos límite

* **403**: no tienes permisos para administrar miembros.
* **404**: proyecto o miembro del espacio de trabajo no encontrado.


# Miembros del espacio de trabajo
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user

Crea y administra membresías, roles, acceso a proyectos y actividad.

> [!WARNING]
>
> Las antiguas rutas `/app/user` y el modelo de perfil de miembro cambian en 1.58. Consulta [Migración de API 1.57 → 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#miembros-del-espacio-de-trabajo) antes de actualizar tu integración.

Usa la API de miembros del espacio de trabajo para gestionar la membresía de una cuenta en un espacio de trabajo. Una cuenta representa a una persona en Zylon, mientras que un miembro almacena el estado y los roles de esa cuenta dentro del espacio de trabajo.

Las respuestas de miembro contienen `id`, `org_id`, `account_id`, `state`, `roles` y `created_at`. `id` es el ID de miembro del espacio de trabajo; `account_id` identifica la cuenta asociada y está disponible sin `include`. Conserva ambos valores separados. Si guardaste un ID de usuario antiguo para comparaciones o filtros de creador, sigue la [migración de IDs de usuario guardados](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#migrar-ids-de-usuario-guardados). Usa `include=Account` en los endpoints compatibles para incluir la cuenta relacionada en `account`.

`GET /api/v1/account/{accountId}` incluye las membresías de la cuenta en `workspace_members`. Para los listados de cuentas, solicita la misma relación con `GET /api/v1/account?include=WorkspaceMembers`. Los objetos `account` anidados que devuelven los endpoints de miembros la omiten.

Los roles válidos del espacio de trabajo son `AppGuest`, `AppMember`, `AppAdmin` y `AppOwner`.

> [!NOTE]
>
> Los nombres y las imágenes de perfil pertenecen a la cuenta, no a su membresía. Actualiza esos campos mediante `POST /api/v1/account/{accountId}`; usa `me` como ID para actualizar la cuenta autenticada. `PUT /api/v1/app/member/{wsMemberId}` solo cambia el rol del espacio de trabajo.

## Obtener el miembro actual

Usa `GET /api/v1/app/me` para verificar tu token y el contexto del miembro del espacio de trabajo.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `include` | No | Datos relacionados que se incluirán, separados por comas. Valor compatible: `Account`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/me?include=Account" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "org_id": "{orgId}",
>   "account_id": "{accountId}",
>   "state": "Active",
>   "roles": ["AppAdmin"],
>   "created_at": "2026-02-08T14:12:45Z",
>   "account": {
>     "id": "{accountId}",
>     "state": "Active",
>     "email": "sasha@example.com",
>     "name": "Sasha Patel",
>     "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-01-10T09:00:00Z",
>     "updated_at": "2026-02-08T14:12:45Z"
>   }
> }
> ```

## Listar miembros del espacio de trabajo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Query | `state` | No | Estados separados por comas: `Active` e `Inactive`. Ambos se incluyen por defecto. |
> | Query | `include` | No | Datos relacionados que se incluirán, separados por comas. Valor compatible: `Account`. |
> | Query | `page` | No | Número de página absoluto, empezando en 1. |
> | Query | `page_size` | No | Número de elementos por página. |
> | Query | `page_order` | No | `ASC` o `DESC`. |
> | Query | `after` | No | Cursor o valor desde el que paginar hacia delante. |
> | Query | `before` | No | Cursor o valor desde el que paginar hacia atrás. |
> | Query | `first` | No | Limita a los primeros N elementos después de un cursor. |
> | Query | `last` | No | Limita a los últimos N elementos antes de un cursor. |
> | Query | `total_count` | No | Incluye el total de resultados en la respuesta. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member?state=Active&include=Account&page=1&page_size=20&total_count=true" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "{wsMemberId}",
>       "org_id": "{orgId}",
>       "account_id": "{accountId}",
>       "state": "Active",
>       "roles": ["AppAdmin"],
>       "created_at": "2026-02-08T14:12:45Z",
>       "account": {
>         "id": "{accountId}",
>         "state": "Active",
>         "email": "sasha@example.com",
>         "name": "Sasha Patel",
>         "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>         "provider": "Credentials",
>         "roles": ["Workspace"],
>         "created_at": "2026-01-10T09:00:00Z",
>         "updated_at": "2026-02-08T14:12:45Z"
>       }
>     }
>   ],
>   "has_next_page": false,
>   "has_previous_page": false,
>   "total_count": 1
> }
> ```

## Crear un miembro del espacio de trabajo

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Body | `account_id` | Si | ID de la cuenta que se añadirá al espacio de trabajo. |
> | Body | `role` | Si | Rol del espacio de trabajo que se asignará. |

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/member" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "{accountId}",
    "role": "AppMember"
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "org_id": "{orgId}",
>   "account_id": "{accountId}",
>   "state": "Active",
>   "roles": ["AppMember"],
>   "created_at": "2026-02-08T14:12:45Z"
> }
> ```

## Obtener o actualizar un miembro del espacio de trabajo

`GET /member/{wsMemberId}` acepta `me` en lugar del ID del miembro. `PUT /member/{wsMemberId}` requiere un ID de miembro explícito.

**Obtener miembro**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `wsMemberId` | Si | ID del miembro, o `me` para el miembro autenticado. |
> | Query | `include` | No | Datos relacionados que se incluirán, separados por comas. Valor compatible: `Account`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member/{wsMemberId}?include=Account" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "org_id": "{orgId}",
>   "account_id": "{accountId}",
>   "state": "Active",
>   "roles": ["AppMember"],
>   "created_at": "2026-02-08T14:12:45Z",
>   "account": {
>     "id": "{accountId}",
>     "state": "Active",
>     "email": "sasha@example.com",
>     "name": "Sasha Patel",
>     "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
>     "provider": "Credentials",
>     "roles": ["Workspace"],
>     "created_at": "2026-01-10T09:00:00Z",
>     "updated_at": "2026-02-08T14:12:45Z"
>   }
> }
> ```

**Actualizar miembro**

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `wsMemberId` | Si | ID del miembro del espacio de trabajo. |
> | Body | `role` | Si | Rol del espacio de trabajo que se asignará. |

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/member/{wsMemberId}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "AppAdmin"
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "org_id": "{orgId}",
>   "account_id": "{accountId}",
>   "state": "Active",
>   "roles": ["AppAdmin"],
>   "created_at": "2026-02-08T14:12:45Z"
> }
> ```

## Activar o desactivar un miembro del espacio de trabajo

Ambos endpoints requieren un ID de miembro explícito y devuelven el miembro actualizado.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `wsMemberId` | Si | ID del miembro del espacio de trabajo. No se admite el valor `me`. |

**Desactivar**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/deactivate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "org_id": "{orgId}",
>   "account_id": "{accountId}",
>   "state": "Inactive",
>   "roles": ["AppMember"],
>   "created_at": "2026-02-08T14:12:45Z"
> }
> ```

**Activar**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/activate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "{wsMemberId}",
>   "org_id": "{orgId}",
>   "account_id": "{accountId}",
>   "state": "Active",
>   "roles": ["AppMember"],
>   "created_at": "2026-02-08T14:12:45Z"
> }
> ```

## Listar proyectos de un miembro del espacio de trabajo

Usa `me` en lugar de `wsMemberId` para listar los proyectos del miembro autenticado.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `wsMemberId` | Si | ID del miembro, o `me` para el miembro autenticado. |
> | Query | `include` | No | Datos relacionados que se incluirán, separados por comas. Valor compatible: `Members`. |
> | Query | `order_by` | No | Valor compatible: `Alphabetical`. |
> | Query | `order` | No | `ASC` o `DESC`. |
> | Query | `page` | No | Número de página absoluto, empezando en 1. |
> | Query | `page_size` | No | Número de elementos por página. |
> | Query | `page_order` | No | `ASC` o `DESC`. |
> | Query | `after` | No | Cursor o valor desde el que paginar hacia delante. |
> | Query | `before` | No | Cursor o valor desde el que paginar hacia atrás. |
> | Query | `first` | No | Limita a los primeros N elementos después de un cursor. |
> | Query | `last` | No | Limita a los últimos N elementos antes de un cursor. |
> | Query | `total_count` | No | Incluye el total de resultados en la respuesta. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/project?order_by=Alphabetical&order=ASC&page=1&page_size=20&total_count=true" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "{projectId}",
>       "name": "Customer Insights",
>       "goal": "Summarize weekly support trends.",
>       "visibility": "Private",
>       "member_count": 4,
>       "default_member_role": "Editor",
>       "default_role_enabled": true,
>       "project_context": "Support analytics for Q1.",
>       "use_citations": true,
>       "use_system_prompt": true,
>       "is_pinned": true
>     }
>   ],
>   "has_next_page": false,
>   "has_previous_page": false,
>   "total_count": 1
> }
> ```

## Últimos artefactos de un miembro del espacio de trabajo

Usa `me` en lugar de `wsMemberId` para obtener los artefactos del miembro autenticado.

> **Parametros del endpoint**
>
> | Tipo | Nombre | Obligatorio | Notas |
> | - | - | - | - |
> | Path | `wsMemberId` | Si | ID del miembro, o `me` para el miembro autenticado. |
> | Query | `latest` | No | Número máximo de artefactos recientes que se devolverán. El valor por defecto es `3`. |

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/latest-artifacts?latest=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

La respuesta es un array de objetos de artefacto. Consulta [Artefactos](/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts) para ver los campos de respuesta.

## Errores y casos límite

* **400**: estado, valor de `include`, rol o cuerpo de la solicitud no válidos.
* **400**: un miembro no puede activar ni desactivar su propia membresía.
* **403**: permisos insuficientes para cambiar la membresía o los roles.
* **404**: miembro del espacio de trabajo o cuenta relacionada no encontrados.


# Organizaciones
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user-organization

Lee y actualiza la organización actual de Workspace.

Las organizaciones son el contenedor principal de miembros del espacio de trabajo y proyectos. Estos endpoints operan sobre la organización seleccionada por el header `x-org`.

## Solicitud básica y respuesta

Obtén la organización actual con `GET /api/v1/app/organization`.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "org_2f3a9d1c7b5e4a8f",
>   "name": "Aurora Labs",
>   "slug": "aurora-labs",
>   "state": "Active",
>   "display_name": "Aurora Labs",
>   "context": "Enterprise R&D and analytics.",
>   "logo": "https://{BASE_URL}/files/org-logo.png",
>   "auto_join_enabled": true,
>   "enable_generated_resources_downloads": true,
>   "enable_uploaded_resources_downloads": true,
>   "default_role": "AppMember",
>   "email_regex": ".*@example.com",
>   "gateway_id": "gw_4b7c2a1d9e5f",
>   "created_at": "2026-02-08T14:12:45Z"
> }
> ```

## Actualizar configuración de organización

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/organization" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aurora Labs",
    "context": "Private AI platform for product and support teams.",
    "clear_context": false,
    "email_regex": ".*@example.com",
    "enable_generated_resources_downloads": true,
    "enable_uploaded_resources_downloads": true
  }'
```

> **Parametros del endpoint**
>
> | Campo | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre visible de la organización. Máximo 60 caracteres. |
> | `context` | string | No | Contexto de organización usado por funcionalidades de Workspace. |
> | `clear_context` | boolean | No | Ponlo a `true` para eliminar el contexto existente. Por defecto es `false`. |
> | `email_regex` | string | No | Regex valida para los emails de la organizacion. |
> | `enable_generated_resources_downloads` | boolean | No | Permite descargar recursos generados. Omite o envia null para mantener el ajuste. |
> | `enable_uploaded_resources_downloads` | boolean | No | Permite descargar recursos subidos. Omite o envia null para mantener el ajuste. |
> | `logo_file_name` | string | No | Nombre del archivo de logo en multipart. Obligatorio si subes un logo. |
> | `logo_content_type` | string | No | Tipo de contenido del logo en multipart. Debe ser PNG o JPEG. |
> | `logo_content_length` | integer | No | Tamaño del logo en bytes. Máximo 5 MB. |
> | `fileData` | file | No | Binario del logo solo para multipart. |

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "org_2f3a9d1c7b5e4a8f",
>   "name": "Aurora Labs",
>   "slug": "aurora-labs",
>   "state": "Active",
>   "display_name": "Aurora Labs",
>   "context": "Private AI platform for product and support teams.",
>   "logo": "https://{BASE_URL}/files/org-logo.png",
>   "auto_join_enabled": true,
>   "enable_generated_resources_downloads": true,
>   "enable_uploaded_resources_downloads": true,
>   "default_role": "AppMember",
>   "email_regex": ".*@example.com",
>   "gateway_id": "gw_4b7c2a1d9e5f",
>   "created_at": "2026-02-08T14:12:45Z"
> }
> ```

## Campos de respuesta de organizacion

GET y POST devuelven el mismo modelo. Los campos nulos pueden omitirse. La politica de descarga afecta a artefactos y descargas/exportaciones de archivos del hilo; las descargas deshabilitadas devuelven `403`.

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | ID de organizacion. |
| `name` | string | Nombre. |
| `slug` | string | Slug del espacio para `x-org`. |
| `state` | string | `Active`, `Inactive`. |
| `display_name` | string | Nombre visible. |
| `context` | string or null | Instrucciones de organizacion. |
| `logo` | string or null | URL publica del logo. |
| `auto_join_enabled` | boolean | Adhesion automatica habilitada. |
| `enable_generated_resources_downloads` | boolean | Politica de descarga de recursos generados. |
| `enable_uploaded_resources_downloads` | boolean | Politica de descarga de recursos subidos. |
| `default_role` | string | `AppGuest`, `AppMember`, `AppAdmin`, `AppOwner`. |
| `email_regex` | string | Regex de emails. |
| `gateway_id` | string | ID de gateway de la organizacion. |
| `created_at` | timestamp | Fecha de creacion generada por el servidor. |
| `member_count` | integer or null | Numero de miembros opcional; estas rutas de organizacion actual no lo incluyen. |

## Errores y casos límite

* **401/403**: token inválido o ausente.
* **400**: regex inválida, nombre de organización de más de 60 caracteres, tipo de logo no soportado o logo mayor de 5 MB.


# Embeddings
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/embeddings

Genera embeddings para búsqueda semántica y similitud.

Los embeddings convierten texto en vectores de alta dimensión. Úsalos para búsqueda semántica, agrupación (clustering) o cálculo de similitud sobre tus propios datos.

## Requisitos previos

* Un token de API. Ver [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console).
* El nombre de host de Zylon (sustituye `{BASE_URL}` en los ejemplos).

## Antes de empezar

* **El orden importa**: `data[index]` coincide con el orden de `input`.
* **Guarda los vectores** en tu base de datos o índice vectorial para búsqueda y similitud.
* **Usa el mismo preprocesamiento** (mismo formato y uso de mayúsculas/minúsculas) para resultados consistentes.

## Crear embeddings

Genera embeddings con `POST /embeddings`. `input` puede ser una cadena o una lista.

| Forma de `input` | Cuándo usar |
| - | - |
| Una sola cadena | Un texto a la vez. |
| Lista de cadenas | Entradas en lote manteniendo el orden. |

**Entrada única**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/embeddings" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Summarize Q1 support trends in one vector."
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "object": "list",
>   "model": "private-gpt",
>   "data": [
>     {
>       "index": 0,
>       "object": "embedding",
>       "embedding": [
>         0.697265625,
>         0.5078125,
>         0.01129150390625,
>         0.244873046875,
>         -0.285888671875,
>         0.058135986328125,
>         0.01922607421875,
>         -0.11431884765625
>       ]
>     }
>   ]
> }
> ```

**Lote**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/embeddings" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      "Billing issues drove 38% of cases.",
      "Priority bugs were resolved within 48 hours."
    ]
  }'
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "object": "list",
>   "model": "private-gpt",
>   "data": [
>     {
>       "index": 0,
>       "object": "embedding",
>       "embedding": [
>         -0.435546875,
>         -0.49169921875,
>         -0.48876953125,
>         1.41015625,
>         0.11114501953125,
>         -1.2626953125
>       ]
>     },
>     {
>       "index": 1,
>       "object": "embedding",
>       "embedding": [
>         -0.6748046875,
>         0.242431640625,
>         -0.31396484375,
>         0.53955078125,
>         -0.84716796875,
>         -0.006961822509765625
>       ]
>     }
>   ]
> }
> ```

## Errores y casos límite

* **401/403**: token faltante o inválido.
* **413**: input demasiado grande.
* **400**: JSON inválido o tipo de input incorrecto.


# Motivos de parada
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/handling-stop-reasons

Entiende por qué terminó una respuesta y cómo manejar errores de ZylonGPT.

Las respuestas de mensajes distinguen el `stop_reason` del modelo, el resultado global `interaction_stop_reason` y los detalles de error. Comprueba cada campo para decidir si continuar, ejecutar una herramienta o reintentar.

Para ver `stop_reason` en el esquema de respuesta, revisa [Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages).

## ¿Qué es `stop_reason`?

`stop_reason` indica cómo terminó la generación del modelo. Admite null y puede omitirse; no es un tipo de error.

Ejemplo de respuesta (truncada):

```json theme={null}
{
  "id": "msg_abf981cf3f1c449eacb7a85c064ca505",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Aquí tienes un resumen..." }
  ],
  "stop_reason": "end_turn",
  "interaction_stop_reason": "stop"
}
```

## Valores de `stop_reason`

Solo los seis valores de generación siguientes son valores de `stop_reason`.

| stop\_reason | Por qué ocurre | Qué hacer |
| - | - | - |
| `end_turn` | El modelo terminó normalmente. A veces llega vacío después de un `tool_result` si envías texto adicional junto al bloque `tool_result`. | Trátalo como completo. Si viene vacío, envía solo el `tool_result` o añade un nuevo mensaje como “Continúa”. |
| `max_tokens` | La respuesta llegó al límite de `max_tokens`. | Aumenta `max_tokens` o pide continuar. |
| `stop_sequence` | Se generó una secuencia de parada configurada por ti. | Considera la salida completa en ese punto o ajusta la secuencia. |
| `tool_use` | El modelo necesita que ejecutes una de tus herramientas personalizadas. Las herramientas integradas nunca paran con `tool_use`: Zylon las ejecuta y devuelve bloques `server_tool_use`. | Ejecuta la herramienta y devuelve un bloque `tool_result`. |
| `pause_turn` | El modelo pausó la conversación. | Continúa cuando estés listo. |
| `refusal` | El modelo se negó por razones de seguridad o políticas. | Muestra la negativa o re‑formula con contenido permitido. |

## Resultados de la interacción

`interaction_stop_reason` admite null y describe el resultado global: `stop`, `error`, `cancelled` o `refusal`. Es independiente del motivo de parada del modelo. El objeto opcional `stop_details` tiene `type` obligatorio y `category` y `explanation` opcionales; usa esos detalles para explicar el resultado al usuario.

## Errores

Los fallos anteriores a la generación pueden devolver un objeto de error HTTP. Durante el streaming, gestiona los eventos `error`; los mensajes completados también pueden incluir un array `errors`. Los tipos siguientes **no** son valores válidos de `stop_reason`. No reintentes negativas o cancelaciones como si fueran errores transitorios del servidor.

| Tipo de error | Por qué ocurre | Qué hacer |
| - | - | - |
| `invalid_request_error` | Entradas inválidas (artefactos sin ingesta completa, configuración de herramientas inexistente, IDs incorrectos). | Corrige la entrada y reintenta. |
| `permission_error` | El token no tiene acceso al recurso referenciado. | Revisa la pertenencia a la organización/proyecto y la visibilidad del artefacto. |
| `request_too_large` | La entrada excede límites de tamaño o tokens. | Reduce la entrada, divide el contenido o baja el contexto. |
| `api_error` | Error interno del servidor. | Reintenta con backoff exponencial. |
| `overloaded_error` | El sistema está temporalmente sobrecargado. | Reintenta con backoff y algo de jitter (aleatorización). |


# Visión general
Source: https://docs.zylon.ai/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview

La API de ZylonGPT te permite generar respuestas, ingestar conocimiento, crear embeddings y usar herramientas en un solo flujo.

> [!WARNING]
>
> **Cambios incompatibles en la API de 1.58**
>
> Antes de actualizar una integración desde 1.57, sigue la [guía de migración de API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58). La versión 1.58 cambia las rutas y los cuerpos de contenido de artefactos, los IDs de cuenta y de miembro del espacio de trabajo, y los bloques de respuesta de herramientas del servidor en los mensajes de Workspace y ZylonGPT. Las rutas antiguas no conservan todo el contrato de 1.57 y quedan obsoletas, con eliminación prevista para 1.59.

ZylonGPT es la API orientada al modelo. La mayoría de aplicaciones siguen un ciclo sencillo: enviar mensajes, adjuntar o referenciar artefactos, generar embeddings para búsquedas y permitir que el asistente invoque herramientas cuando necesite recuperación de información o datos estructurados.

## Autenticación y scopes

Usa un token asociado a un gateway desde [Developer Console](/es/v1.58/developer-manual/get-started/developer-console). `PrivateGPT.Read.All` permite los endpoints siguientes. Un token de cuenta con `Read.All` accede a la misma allowlist solo cuando incluye contexto de gateway mediante `gateway_id`; `Read.All` puede crearse sin `gateway_id`, pero ese token no puede llamar a ZylonGPT.

* `POST /api/gpt/v1/messages`
* `POST /api/gpt/v1/complete`
* `POST /api/gpt/v1/messages/count_tokens`
* `POST /api/gpt/v1/messages/validate`
* `POST /api/gpt/v1/embeddings`
* solicitudes `GET` y `HEAD` bajo `/api/gpt/v1/skills`
* `POST /api/gpt/v1/skills/validate`

Las rutas del ciclo de vida de mensajes asíncronos, todas las rutas de artefactos, las mutaciones de skills y las rutas fallback no reconocidas requieren un scope de lectura y escritura y devuelven `403` para un token de solo lectura. Usa `PrivateGPT.ReadWrite.All` para un token asociado a un gateway o `ReadWrite.All` cuando corresponda un token de cuenta. Los scopes múltiples combinan sus permisos, pero los permisos efectivos siguen limitados por los roles del propietario del token. Consulta [Gestión de tokens](/es/v1.58/developer-manual/get-started/token-management) para ver los valores por defecto y las reglas de validación al crear tokens.

> **[Mensajes](/es/v1.58/developer-manual/build-with-zylon/working-with-messages)**
>
> Envía mensajes síncronos con acceso de lectura; el ciclo de vida asíncrono requiere acceso de lectura y escritura.

> **[Artefactos](/es/v1.58/developer-manual/build-with-zylon/working-with-artifacts)**
>
> Ingiere, recupera, lista o elimina contenido de colecciones con acceso de lectura y escritura.

> **[Embeddings](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/embeddings)**
>
> Convierte texto en vectores para búsqueda y similitud.

> **[Herramientas](/es/v1.58/developer-manual/build-with-zylon/tools/introduction-to-tools)**
>
> Activa búsqueda semántica, análisis tabular, Web Fetch y herramientas personalizadas.


# Claude Code
Source: https://docs.zylon.ai/es/v1.58/developer-manual/get-started/claude-code-setup

Configura Claude Code CLI para trabajar con la plataforma de IA de Zylon.

**Claude Code** es la herramienta de línea de comandos de Anthropic para interactuar con los modelos Claude. Te permite usar las capacidades de Claude directamente desde tu terminal para tareas de desarrollo y análisis.

Para instrucciones de instalación, consulta la [documentación oficial de Claude Code](https://claude.com/product/claude-code).

> [!NOTE]
>
> Esta integración se verificó con **Claude Code 2.1.166** en **macOS** usando **Zylon 1.57.1**. Si no funciona, consulta otras alternativas en la [guía de configuración de Opencode](./opencode-setup).

## Versiones probadas

| Versión de Zylon | Versión de Claude Code | Sistema operativo | Resultado |
| - | - | - | - |
| 1.57.1 | 2.1.166 | macOS | Funcionando |

## Pasos de Configuración

**1. Crear un token de Gateway**

Antes de configurar Claude Code, necesitas un **token de Gateway** de Zylon.

Consulta [Gestión de Tokens](./token-management) para obtener instrucciones detalladas sobre cómo crear tokens de Gateway.

**2. Establecer variables de entorno**

Agrega lo siguiente a tu archivo de configuración de shell (`~/.zshrc` o `~/.bashrc`):

```bash theme={null}
echo 'export ZYLON_BASE_URL="https://your-host/api/gpt"' >> ~/.zshrc
echo 'export ZYLON_API_TOKEN="your-gateway-token"' >> ~/.zshrc
echo 'export ZYLON_MODEL="default"' >> ~/.zshrc
source ~/.zshrc
```

Reemplaza `your-host` con la URL de tu instancia de Zylon y `your-gateway-token` con tu token de Gateway real. El modelo predeterminado es `default`.

> [!WARNING]
>
> Nunca hagas commit de variables de entorno que contengan tokens al control de versiones. Agrégalas a tu `.gitignore`.

Confirma que las variables se establecieron correctamente:

```bash theme={null}
echo $ZYLON_BASE_URL
echo $ZYLON_API_TOKEN
echo $ZYLON_MODEL
```

**3. Configurar Claude Code**

Agrega lo siguiente a tu archivo de configuración de shell (`~/.zshrc` o `~/.bashrc`):

```bash theme={null}
echo 'export ANTHROPIC_BASE_URL="$ZYLON_BASE_URL"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="$ZYLON_API_TOKEN"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="$ZYLON_MODEL"' >> ~/.zshrc
source ~/.zshrc
```

**4. Ejecutar Claude Code**

Prueba tu configuración ejecutando:

```bash theme={null}
claude
```

Si está configurado correctamente, Claude Code se conectará a tu instancia de Zylon y estará listo para ayudarte.

## Limitaciones

* Las imágenes no son compatibles

## Solución de Problemas

### Errores de conexión

* Verifica que `ZYLON_BASE_URL` sea correcta y accesible
* Asegúrate de que tu token de Gateway sea válido y no haya expirado
* Comprueba la conectividad de red con tu instancia de Zylon

### Fallos de autenticación

* Confirma que el token se copió correctamente sin espacios en blanco adicionales
* Regenera el token si pudo haber sido comprometido
* Verifica que el token tenga los permisos apropiados


# Developer Console
Source: https://docs.zylon.ai/es/v1.58/developer-manual/get-started/developer-console

Gestión de tokens de API para desarrolladores.

## Resumen

Developer Console es el área del Backoffice para flujos de trabajo de tokens de API.

Los tokens generados en Developer Console son la opción recomendada cuando necesitas un solo token que funcione en:

* Workspace API
* ZylonGPT API
* Backoffice API

Está disponible para:

* cuentas con permisos **Developer**
* cuentas con permisos **Operator** cuando también participan en un gateway

Los tokens de API se crean dentro de gateways y quedan asociados tanto al gateway como a la cuenta que los crea.

La creación de tokens de gateway acepta `PrivateGPT.Read.All` y `PrivateGPT.ReadWrite.All`. Una lista de scopes legacy vacía explícita se convierte en `PrivateGPT.ReadWrite.All`; cualquier otro scope solicitado devuelve `400`. Consulta [Gestión de tokens](/es/v1.58/developer-manual/get-started/token-management) para ver el modelo de scopes y la allowlist de solo lectura.

> [!NOTE]
>
> Si solo necesitas acceso a Workspace API, puedes usar el flujo de [Gestión de tokens de Workspace](/es/v1.58/developer-manual/get-started/token-management).

Para el detalle de acceso por rol, consulta [Roles y permisos](/es/v1.58/operator-manual/backoffice/roles-and-permissions).

## Crear token de API

Para crear un token de API:

1. Abre **Developer Console**.
2. Selecciona el gateway de destino.
3. Haz clic en **Create API Token**.
4. Introduce un nombre para el token.
5. Genera el token.
6. Copia el secreto del token mostrado en el modal.

[Backoffice - Crear token de API](https://www.youtube.com/embed/pDVi1KfesMI)

> [!WARNING]
>
> El secreto del token solo se muestra una vez. Después de cerrar el modal no se puede recuperar. Guárdalo de inmediato en un gestor de secretos seguro.

## Uso y propiedad del token

* El token hereda las reglas y la configuración del gateway.
* La actividad del token queda asociada a la cuenta que lo creó.
* Si se pierde un token, revócalo y crea uno nuevo.


# Introducción a Zylon
Source: https://docs.zylon.ai/es/v1.58/developer-manual/get-started/intro-to-zylon

Plataforma de IA autohospedada con endpoints de Messages compatibles con Anthropic y Workspace API.

> [!WARNING]
>
> **Cambios incompatibles en la API de 1.58**
>
> Antes de actualizar una integración desde 1.57, sigue la [guía de migración de API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58). La versión 1.58 cambia las rutas y los cuerpos de contenido de artefactos, los IDs de cuenta y de miembro del espacio de trabajo, y los bloques de respuesta de herramientas del servidor en los mensajes de Workspace y ZylonGPT. Las rutas antiguas no conservan todo el contrato de 1.57 y quedan obsoletas, con eliminación prevista para 1.59.

Zylon es una plataforma de IA autohospedada que se ejecuta en tu infraestructura. Ofrece endpoints de Messages compatibles con Anthropic para interactuar con el modelo, una Workspace API para gestionar organizaciones y proyectos, y una Backoffice API para tareas operativas. En esta documentación usarás **tres APIs**:

* **API de ZylonGPT**: la capa de IA para respuestas del modelo, herramientas y chat con contenido.
* **Workspace API**: la API de administración para organizaciones, usuarios, proyectos e integraciones.
* **Backoffice API**: la API operativa para tareas de Backoffice, como recuperar registros manualmente.

## Elige tu flujo de token

Usa el flujo de token que corresponda a tu integración:

> **[Gestión de tokens de Workspace](/es/v1.58/developer-manual/get-started/token-management)**
>
> Flujo de token solo para endpoints de Workspace `/api/v1/*`.

> **[Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console)**
>
> Genera un token que funcione en Workspace API, ZylonGPT API y Backoffice API.

> **[Guía rápida](/es/v1.58/developer-manual/get-started/quickstart)**
>
> Haz tu primera llamada con un ejemplo funcional.

> **[API de ZylonGPT](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview)**
>
> Construye experiencias de IA con la API del modelo.

> **[Workspace API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/overview)**
>
> Administra organizaciones, usuarios, proyectos e integraciones.

> **[Backoffice API](/es/v1.58/developer-manual/build-with-zylon/backoffice-api/overview)**
>
> Recupera datos operativos, como los registros de Zylon.


# Opencode
Source: https://docs.zylon.ai/es/v1.58/developer-manual/get-started/opencode-setup

Instala y configura Opencode CLI para trabajar con la plataforma de IA de Zylon.

**Opencode** es una herramienta interactiva de línea de comandos que ayuda a los desarrolladores con tareas de ingeniería de software. Proporciona un asistente de codificación impulsado por IA directamente en tu terminal, permitiéndote construir, depurar y mantener código con soporte inteligente.

Para instrucciones de instalación, consulta la [documentación oficial de Opencode](https://opencode.ai).

## Pasos de Configuración

**1. Crear un token de Gateway**

Antes de configurar Opencode, necesitas un **token de Gateway** de Zylon.

Consulta [Gestión de Tokens](./token-management#token-de-gateway-zylongpt) para obtener instrucciones detalladas sobre cómo crear tokens de Gateway.

**2. Establecer variables de entorno**

Agrega lo siguiente a tu archivo de configuración de shell (`~/.zshrc` o `~/.bashrc`):

```bash theme={null}
echo 'export ZYLON_BASE_URL="https://your-host/api/gpt"' >> ~/.zshrc
echo 'export ZYLON_API_TOKEN="your-gateway-token"' >> ~/.zshrc
echo 'export ZYLON_MODEL="default"' >> ~/.zshrc
source ~/.zshrc
```

Reemplaza `your-host` con la URL de tu instancia de Zylon y `your-gateway-token` con tu token de Gateway real. El modelo predeterminado es `default`.

> [!WARNING]
>
> Nunca hagas commit de variables de entorno que contengan tokens al control de versiones. Agrégalas a tu `.gitignore`.

Confirma que las variables se establecieron correctamente:

```bash theme={null}
echo $ZYLON_BASE_URL
echo $ZYLON_API_TOKEN
echo $ZYLON_MODEL
```

**3. Configurar Opencode**

Crea el directorio de configuración de Opencode:

```bash theme={null}
mkdir -p ~/.config/opencode
```

Crea el archivo de configuración en `~/.config/opencode/opencode.json`:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "{env:ZYLON_BASE_URL}/v1",
        "apiKey": "{env:ZYLON_API_TOKEN}"
      },
      "models": {
        "{env:ZYLON_MODEL}": {
          "name": "Zylon - {env:ZYLON_MODEL}",
          "limit": {
            "context": 128000,
            "output": 20000
          }
        }
      }
    }
  }
}
```

Para más detalles sobre las opciones de configuración de Opencode, consulta la [documentación oficial de Opencode](https://opencode.ai).

**4. Ejecutar Opencode**

Prueba tu configuración ejecutando:

```bash theme={null}
opencode
```

En el primer lanzamiento, necesitarás cambiar al modelo Zylon:

1. Presiona `Ctrl+P` para abrir el panel de comandos
2. Selecciona "Switch Model"
3. Busca y selecciona "Zylon - Default"

Una vez seleccionado, Opencode se conectará a tu instancia de Zylon y estará listo para ayudarte con tareas de codificación.

## Limitaciones

* Las imágenes no son compatibles

## Solución de Problemas

### Errores de conexión

* Verifica que `ZYLON_BASE_URL` sea correcta y accesible
* Asegúrate de que tu token de Gateway sea válido y no haya expirado
* Comprueba la conectividad de red con tu instancia de Zylon

### Fallos de autenticación

* Confirma que el token se copió correctamente sin espacios en blanco adicionales
* Regenera el token si pudo haber sido comprometido
* Verifica que el token tenga los permisos apropiados


# Guía rápida
Source: https://docs.zylon.ai/es/v1.58/developer-manual/get-started/quickstart

Haz tu primera llamada a la API de Zylon en menos de 2 minutos.

Empieza con ZylonGPT para enviar mensajes o usa la Workspace API para automatizar organizaciones y proyectos.

## Requisitos previos

* Un token para la API que vas a usar:
  * Flujo de token solo para Workspace: [Gestión de tokens de Workspace](/es/v1.58/developer-manual/get-started/token-management)
  * Un token para Workspace API + ZylonGPT API + Backoffice API: [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console)
* El nombre de host de Zylon (sustituye `{BASE_URL}` en los ejemplos).
* Para la Workspace API: una cuenta y una organización creadas en el Workspace.

## Mi primera llamada a Zylon

**ZylonGPT API**

**1. Envía tu primer mensaje**

```bash theme={null}
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": 64,
    "messages": [
      { "role": "user", "content": "Write a one-sentence product description for Zylon." }
    ]
  }'
```

Ejemplo de respuesta (tu `id` y timestamps variarán):

```json theme={null}
{
  "id": "msg_d88cec8ffdf344dcafddb72026ead6be",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "start_timestamp": "2026-02-06T13:16:10.412540Z",
      "stop_timestamp": "2026-02-06T13:16:10.543884Z",
      "text": "Zylon is a private AI platform for building secure, tool-using assistants and workflows."
    }
  ],
  "model": "private-gpt",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 93,
    "output_tokens": 18
  }
}
```

**2. Streaming (opcional)**

Establece `stream: true` para recibir **Server-Sent Events (SSE)**.

```bash theme={null}
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 (recortado):

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

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

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

**Workspace API**

Las solicitudes de Workspace bajo `/api/v1/app/*` requieren la cabecera `x-org` para apuntar a la organización correcta. Puedes enviar el slug de la organización (recomendado) o el ID de la organización. En los ejemplos siguientes, usa `x-org: {org_slug}`.

**1. Inicia sesión**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/login" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "{username}",
    "password": "{password}"
  }'
```

Ejemplo de respuesta:

```json theme={null}
{
  "id": "acct_6c8a1f3b2d4e5f7a",
  "email": "sasha@example.com",
  "provider": "Credentials",
  "roles": ["AppAdmin"]
}
```

**2. Crea un proyecto**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Insights",
    "goal": "Summarize weekly support trends.",
    "deadline": 1709337600,
    "visibility": "Private"
  }'
```

Ejemplo de respuesta:

```json theme={null}
{
  "id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Customer Insights",
  "visibility": "Private"
}
```

**3. Sube un artefacto**

```bash theme={null}
printf 'Q1 support summary.\n' > q1-support-summary.txt

curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -F 'project_id={projectID}' \
  -F 'type=Document' \
  -F 'name=Q1 Support Summary' \
  -F 'props={
    "content_type":"text/plain",
    "file_name":"q1-support-summary.txt",
    "content_length":20
  };type=application/json' \
  -F 'file_data=@./q1-support-summary.txt;type=text/plain'
```

Ejemplo de respuesta:

```json theme={null}
{
  "id": "artifact_2b4d6f8a1c3e5a7b",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "Document",
  "source": "User",
  "state": "Published",
  "ingest_status": "NotStarted",
  "keep_file_after_ingestion": true
}
```

**4. Crea un hilo y consulta el artefacto**

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Support Brief",
    "visibility": "Private"
  }'
```

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "{threadID}",
    "artifact_ids": ["{artifactID}"],
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "Summarize the artifact in three bullets." }
          ]
        }
      ],
      "max_tokens": 96,
      "temperature": 0.2
    }
  }'
```

Ejemplo de respuesta:

```json theme={null}
{
  "id": "inter_5a7b9c1d3e5f7a9b",
  "state": "Completed"
}
```

## Próximos pasos

> **[Visión general de ZylonGPT API](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview)**
>
> Aprende sobre Mensajes, Artefactos y Herramientas.

> **[Visión general de Workspace API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/overview)**
>
> Gestiona organizaciones, usuarios, proyectos e integraciones.

## Solución de problemas

* **401/403**: token inválido, caducado, sin el scope necesario o emitido para el flujo incorrecto. Usa [Gestión de tokens de Workspace](/es/v1.58/developer-manual/get-started/token-management) para acceder a Workspace, o [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console) para un token que funcione en las APIs de Workspace, ZylonGPT y Backoffice.
* **404**: revisa tu base URL. Para ZylonGPT usa `https://{BASE_URL}/api/gpt/v1/`.
* **400 (model not found)**: usa `"model": "default"`.
* **405**: método incorrecto. `/messages` es `POST`.


# Gestión de Tokens
Source: https://docs.zylon.ai/es/v1.58/developer-manual/get-started/token-management

Elige el flujo de token correcto: token cross-API de Backoffice o token exclusivo de Workspace.

Usa esta página para seleccionar el flujo de token adecuado para tu integración.

## ¿Qué token necesito?

> **Token de Workspace**
>
> Rutas `/api/v1/*`.
>
> Automatiza operaciones de Workspace — crea proyectos, gestiona usuarios, interactúa con archivos ingestados y más.

> **Token de Gateway**
>
> Rutas `/api/gpt/v1/*`.
>
> Llama directamente a la API de ZylonGPT, de la misma forma que usarías la API de Anthropic.

**Token de Workspace**

Este flujo es para el acceso a la **API de Workspace** bajo `/api/v1/*`.

> [!WARNING]
>
> El flujo de token de Workspace **no** emite tokens para llamadas directas a la API de ZylonGPT bajo `/api/gpt/v1/*`.

### Crea un token de API de Workspace

1. Inicia sesión en Workspace con una cuenta que pueda gestionar tokens de API.
2. Haz clic en el logo de la organización y abre **API Tokens**.
3. Haz clic en **Create API Token**, proporciona un nombre y guarda.
4. Copia y almacena el valor del token inmediatamente. Se muestra solo una vez.

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/api-reference/images/token.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=ab58c6512c2126f7554520f77229cc51)

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/api-reference/images/create-token.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=8a4fab6ab8c63ead974b78e5815d8838)

### Verifica el acceso del token

Los endpoints de Workspace bajo `/api/v1/app/*` requieren el header `x-org`.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/me" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

> **Ejemplo de respuesta**
>
> ```json theme={null}
> {
>   "id": "user_4b7c2a1d9e5f3c8b",
>   "org_id": "org_2f3a9d1c7b5e4a8f",
>   "account_id": "acct_6c8a1f3b2d4e5f7a",
>   "name": "Sasha Patel",
>   "email": "sasha@auroralabs.com",
>   "state": "Active",
>   "roles": ["AppAdmin"],
>   "created_at": "2026-02-08T14:12:45Z"
> }
> ```

### Revoca un token de Workspace

Abre **API Tokens** y haz clic en el icono de papelera en la fila del token.

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/api-reference/images/revoke-token.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=2b4254169bb02c7948450e3716dbf22e)

**Token de Gateway (ZylonGPT)**

Este flujo otorga acceso a la **API de ZylonGPT** bajo `/api/gpt/v1/*`, así como a las APIs de Workspace y Backoffice.

### Crea un token de Gateway

1. Abre la **Consola de desarrollo**.
2. Selecciona el gateway de destino.
3. Pulsa **Nueva clave de API**.
4. Introduce un nombre.
5. Elige **Lectura y escritura** si vas a configurar una herramienta de programación.
6. Establece la fecha de caducidad y crea la clave.
7. Copia el valor secreto que aparece en el diálogo.

[Backoffice - Create API Token](https://www.youtube.com/embed/pDVi1KfesMI)

> [!WARNING]
>
> El secreto del token se muestra **solo una vez**. Una vez cerrado el modal, no podrá recuperarse. Guárdalo en un gestor de secretos seguro de inmediato.

## Scopes de token de API

La creación de tokens de cuenta acepta estos seis valores serializados de scope:

| Scope | Acceso |
| - | - |
| `Read.All` | Lectura de cuentas, tokens, gateways, Backoffice/metadatos y Workspace, búsqueda en Workspace y allowlist de solo lectura de ZylonGPT cuando el token incluye `gateway_id`. |
| `ReadWrite.All` | Lectura y escritura en las APIs, según los roles de la cuenta propietaria. |
| `Workspace.Read.All` | Lecturas y búsquedas de Workspace; las mutaciones de Workspace devuelven `403`. |
| `Workspace.ReadWrite.All` | Operaciones de lectura y escritura de Workspace. |
| `PrivateGPT.Read.All` | Solo la allowlist de ZylonGPT de lectura para el gateway seleccionado. |
| `PrivateGPT.ReadWrite.All` | Operaciones de lectura y escritura de ZylonGPT para el gateway seleccionado. |

Si un token tiene varios scopes, sus permisos se combinan. Después, los permisos efectivos se limitan a los permisos de la cuenta y el rol propietarios del token. Un scope amplio no puede elevar a su propietario y un token de API de solo lectura sigue restringido aunque su propietario sea SuperAdmin. Estas restricciones de scope solo se aplican a tokens de API; las sesiones interactivas no cambian.

> [!NOTE]
>
> Si una solicitud de token de cuenta omite `scopes`, se usa `Workspace.ReadWrite.All` por defecto. Enviar un array `scopes` vacío de forma explícita devuelve `400`. Tanto `PrivateGPT.Read.All` como `PrivateGPT.ReadWrite.All` requieren `gateway_id`.

`Read.All` no requiere `gateway_id` al crear el token. Sin ese contexto de gateway, el token puede usar sus demás permisos de lectura, pero no puede llamar a ZylonGPT.

La creación de tokens de gateway también admite `Read.All` y `ReadWrite.All`. El formulario de Backoffice ofrece **Lectura** y **Lectura y escritura**; selecciona `ReadWrite.All` de forma predeterminada para herramientas de programación. El token queda asociado al gateway elegido y, al crearlo, se comprueba el acceso de la cuenta a ese gateway. Por compatibilidad, el endpoint de tokens de gateway convierte una lista de scopes vacía explícita en `ReadWrite.All`.

Consulta la [visión general de ZylonGPT API](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview) para ver la lista de endpoints de solo lectura y los requisitos de lectura y escritura.


# Requisitos de hardware
Source: https://docs.zylon.ai/es/v1.58/operator-manual/installation/hardware-requirements



Zylon solo tiene un requisito estricto con respecto al hardware: **debe tener acceso a una GPU con capacidades NVIDIA CUDA y suficiente VRAM para ejecutar el nivel de preset `baseline-96g`**. En la práctica, eso significa planificar **80GB a 96GB de VRAM o más**, según la configuración de GPU. Dependiendo del hardware, algunos modelos de IA pueden estar restringidos, por lo que para asegurar la compatibilidad apunta a las versiones de CUDA más nuevas compatibles (12.6+).

Nuestras especificaciones recomendadas para la mejor experiencia son:

* Sistema Operativo: Ubuntu **SERVER** 22.04 LTS o 24.04 LTS, instalación limpia, sin controladores adicionales o software instalado.
* CPU: Mínimo de 12 núcleos de CPU arquitectura amd64 (x86\_64), pero se recomiendan 16 núcleos
* RAM: Mínimo de 64GB, pero se recomiendan 128GB
* Almacenamiento: Sin límite, mínimo de 4TB de almacenamiento rápido, pero se recomiendan 8TB
* GPU:
  * Bare metal
    * GPU de servidor (se requiere refrigeración externa ⚠️)
      * NVIDIA H200 (141 GB)
      * NVIDIA RTX PRO 6000 Server Edition (96 GB)
      * NVIDIA H100 (80 / 96 GB)
      * NVIDIA A100 (80 GB)
    * GPU de estación de trabajo (sistema de refrigeración integrado)
      * NVIDIA RTX PRO 6000 (Workstation) (96 GB)
  * AWS
    * g7e.2xlarge [https://instances.vantage.sh/aws/ec2/g7e.2xlarge](https://instances.vantage.sh/aws/ec2/g7e.2xlarge)
  * Azure Cloud
    * Elige una SKU de GPU de Azure que proporcione suficiente VRAM total para el nivel de preset `baseline-96g` (normalmente 80GB a 96GB de VRAM total o más).
    * NVv3 (Requiere modelos cuantizados) [https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/gpu-accelerated/nvv3-series?tabs=sizebasic](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/gpu-accelerated/nvv3-series?tabs=sizebasic)

## ¿Qué GPU debo comprar?

Encontrar la GPU adecuada para tu sistema puede ser un proceso complicado. Por ejemplo, dos GPUs con la misma vRAM pueden no tener el mismo rendimiento:

* H100 (servidor) y A100 80GB son opciones representativas del nivel de preset `baseline-96g`.

Por otro lado, dependiendo de la GPU que elijas, se habilitarán otras características que pueden afectar la calidad de la IA, si alguna de ellas es relevante para tus casos de uso, tenlo en cuenta para tu decisión:

| | A100 / H100 |
| - | - |
| Requiere Estación de Trabajo | ✅ |
| LLM | ✅ |
| Reranker\* | ✅ |
| Multi-modelo (imágenes)\* | ✅ |

\*Actualmente en desarrollo/en/v1.57 pruebas — sujeto a cambios en el futuro.

Para **entornos bare metal on-premise** (el escenario habitual para clientes de Zylon), un factor importante sería tu capacidad para refrigerar adecuadamente la GPU instalada en tu máquina. Si no quieres ocuparte de ello o careces de experiencia, opta por una opción de hardware de escritorio. Pero ten en cuenta que en caso de que quieras ejecutar modelos más grandes o proporcionar servicio a varios cientos de usuarios, es posible que necesites instalar un rack con un par en paralelo o verse obligado a cambiar a modelos de hardware de servidor.

Otro factor importante sería la inversión, especialmente con respecto a la GPU. Los rangos de precios del 5 de mayo de 2025 para los modelos mencionados son:

| **Modelo de GPU** | **vRAM (GB)** | **Precio (USD)** |
| - | - | - |
| NVIDIA RTX PRO 6000 (Workstation) | 96 | Pendiente |
| NVIDIA H100 (PCIe) | 80 | $25,000 – $30,000 |
| NVIDIA H100 (SXM) | 80 | $35,000 – $40,000 |
| NVIDIA H100 (NVL) | 96 | $40,000 - $45,000 |
| NVIDIA A100 (PCIe) | 80 | $18,000 - $20,000 |
| NVIDIA A100 (SXM) | 80 | $20,000 - $25,000 |
| NVIDIA H200 | 141 | $30,000 - $32,000 |

En cualquier caso, como respuesta directa a la pregunta de qué GPU debes comprar, nuestra recomendación base actual es una configuración que soporte el nivel de preset **`baseline-96g`**, lo que en la práctica normalmente significa **80GB a 96GB de VRAM total o más**.

## Hardware de referencia para organización de tamaño medio

Si necesitas adquirir tu equipo con capacidad de IA desde cero, a partir del 29 de julio de 2025, por favor considera la siguiente [recomendación de hardware](https://pcpartpicker.com/user/pablo.zylon/saved/#view=csWVD3):

![image.png](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/operator-manual/hardware-requirements-images/basic.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=7245534a38750a9db063c221ec94d7fa)

Esta configuración de referencia debe adaptarse para cumplir con la base actual de GPU del nivel de preset **`baseline-96g`**. En la práctica, esto significa usar una GPU como la **NVIDIA RTX PRO 6000 (Workstation) (96 GB)**, una **A100 80GB**, una **H100** o una configuración multi-GPU que alcance un nivel similar, junto con una CPU potente (16 núcleos), 128 GB de RAM, suficiente capacidad de almacenamiento para operar Zylon con margen para crecer, una solución de refrigeración robusta y una placa base adecuada para la disposición de GPU elegida.

Ten en cuenta que esto es solo una recomendación, así que siéntete libre de adaptarla a tus preferencias mientras mantienes capacidades similares para un rendimiento ideal. Hemos usado Amazon como proveedor considerando que puedes ensamblar todas las partes tú mismo, pero cualquier proveedor con el que normalmente trabajes debería poder obtener un hardware similar y ensamblarlo para ti.

## Hardware de referencia para organización de gran tamaño

En estos escenarios, no proporcionamos una configuración de hardware de referencia hasta que entendamos los requisitos no solo con respecto al número de usuarios, sino también qué tipo de operaciones internas se ejecutarán en paralelo aprovechando la API de la plataforma.

Si estás en esta situación, es probable que ya estemos discutiendo sobre esto.


# Primeros Pasos
Source: https://docs.zylon.ai/es/v1.58/operator-manual/installation/overview

Elige tu modo de instalación según tus necesidades de seguridad y conectividad

Zylon soporta tres modos de instalación. Elige según tu entorno de red y requisitos de seguridad.

## Comparación Rápida

| | Online | Semi-Airgap | Full-Airgap |
| - | - | - | - |
| **Tipo de Instalación** | Online | Online | Offline |
| **Conectividad Operacional** | Completa | Restringida/Cero o Completa | Restringida/Cero o Completa |
| **Caso de Uso** | Despliegues estándar | Acceso de red controlado | Instalación offline |
| **Complejidad** | Simple | Moderada | Compleja |
| **Tiempo de Instalación** | 30-90 min | 1-2 horas | 2-3 horas |
| **Tiempo de Actualización** | 15-40 min | 30-60 min | 1-2 horas |
| **Tiempo de Inactividad en Actualización** | Raro | Raro | Siempre (15-60 min) |

***

## Modos de Instalación

**Online**

### Instalación Online

**Usar cuando**: Despliegues estándar con acceso completo a internet

**Cómo funciona**: El servidor descarga paquetes e imágenes directamente desde repositorios oficiales.

**Características clave**:

* Configuración y actualizaciones automatizadas
* Tiempo de inactividad mínimo para actualizaciones
* Postura de seguridad estándar

**Guía de Instalación** → [Instalación Online](/es/v1.58/operator-manual/installation/online)

**Semi-Airgap**

### Instalación Semi-Airgap

**Usar cuando**: Redes con acceso a internet controlado vía proxy/firewall

**Cómo funciona**: Instalación online a través de dominios en lista blanca y configuración de proxy.

**Características clave**:

* **Instalación**: Online (requiere conectividad a internet)
* **Operación**: Puede funcionar con conectividad restringida/cero o completa
* Requiere dominios y puertos abiertos durante instalación/actualizaciones
* Tiempo de inactividad mínimo para actualizaciones
* Soporte de proxy

**Guía de Instalación** → [Instalación Semi-Airgap](/es/v1.58/operator-manual/installation/semi-airgap)

**Full-Airgap**

### Instalación Full-Airgap

**Usar cuando**: Se requiere instalación offline, sin acceso a internet durante la configuración

**Cómo funciona**: Transferir bundles de 70-100 GB desde máquina online vía medio offline al servidor objetivo.

**Características clave**:

* **Instalación**: Offline (no requiere internet en el servidor objetivo)
* **Operación**: Puede funcionar con conectividad restringida/cero o completa (proxy/internet opcional)
* Requiere dos máquinas Linux (online y offline)
* Proceso de actualización manual (descargar, transferir, aplicar)
* Siempre requiere tiempo de inactividad (15-60 min)

**Guía de Instalación** → [Instalación Airgap](/es/v1.58/operator-manual/installation/airgap)

***

## Pasos de Instalación

**1. Elige Tu Modo**

Selecciona el modo que coincida con tu política de seguridad y entorno de red.

**2. Ejecutar Instalación**

Sigue la guía para tu modo elegido. Todos los modos usan el instalador CLI de Zylon.

**3. Post-Instalación**

Configura [Presets de IA](/es/v1.58/operator-manual/ai-presets), configura [copias de seguridad](/es/v1.58/operator-manual/operations/backup), y revisa el [Manual de Usuario](/es/v1.58/user-manual/quick-start-guide).


# Cómo usar este manual
Source: https://docs.zylon.ai/es/v1.58/operator-manual/overview



¡Bienvenido al Manual de Operaciones de Zylon!

Si eres nuevo en [Zylon](https://www.zylon.ai/), probablemente has llegado aquí porque alguien
en tu organización quiere que formes parte del proceso de adopción de IA Privada.

Zylon es una plataforma de IA empresarial que ofrece IA generativa privada y software de IA en local para sectores regulados, permitiendo un despliegue seguro dentro de la infraestructura de la empresa sin dependencias de nubes externas.

Debido a que Zylon se ejecuta completamente en local, este documento proporciona instrucciones
exhaustivas para instalar, configurar y mantener la plataforma Zylon y
su espacio de trabajo colaborativo en tu infraestructura privada en local.
Puedes ver en la siguiente imagen una visión general de los sistemas más importantes
que se desplegarían como parte de tu instalación de Zylon:

![image](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/operator-manual/arch-overview.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=7e980425b41e631ef68764ece87fd334)

Esta guía cubre temas esenciales incluyendo requisitos del sistema, instalación de controladores,
configuración de red, configuración SSL e integración con OpenID.
También encontrarás procedimientos para tareas de mantenimiento como copias de seguridad y solución de problemas.

La guia de seguridad se centra en proteger y endurecer la plataforma. Para auditabilidad, gobernanza, trazabilidad, preservacion de evidencia y responsabilidad de IA, consulta [Auditabilidad y gobernanza de IA](/es/v1.58/operator-manual/auditability-ai-safety/overview).

Para poner Zylon en funcionamiento sigue los pasos del manual de operaciones paso a paso.
Algunos de ellos pueden omitirse dependiendo del tipo de instalación que elijas, en cualquier caso,
se indicará si el paso puede omitirse y por qué.

¡Comencemos tu viaje con Zylon para adoptar IA Privada!


# Bienvenido a Zylon
Source: https://docs.zylon.ai/es/v1.58/overview

Zylon es una plataforma de IA empresarial que ofrece IA generativa privada y software de IA en local para sectores regulados, permitiendo un despliegue seguro dentro de la infraestructura de la empresa sin dependencias de nubes externas.

> [!WARNING]
>
> **Cambios incompatibles en la API de 1.58**
>
> Antes de actualizar una integración desde 1.57, sigue la [guía de migración de API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58). La versión 1.58 cambia las rutas y los cuerpos de contenido de artefactos, los IDs de cuenta y de miembro del espacio de trabajo, y los bloques de respuesta de herramientas del servidor en los mensajes de Workspace y ZylonGPT. Las rutas antiguas no conservan todo el contrato de 1.57 y quedan obsoletas, con eliminación prevista para 1.59.

## Usuarios de Zylon

¿Eres usuario de Zylon? Consulta estos recursos para empezar.

> **[Manual de usuario](/es/v1.58/user-manual/what-is-zylon-workspace)**
>
> Descubre qué es Zylon Workspace y cómo transforma el conocimiento de tu empresa en ganancias de productividad

> **[Preguntas frecuentes del primer día](/es/v1.58/user-manual/first-day-faqs)**
>
> Respuestas rápidas a preguntas comunes al empezar con Zylon Workspace

> **[Inicio rápido](/es/v1.58/user-manual/quick-start-guide)**
>
> Sé productivo en 15 minutos con flujos de trabajo esenciales y ejemplos

## Desarrolladores

Dirígete a la documentación para desarrolladores para trabajar con las API de Zylon y crear agentes y flujos de trabajo personalizados.

> **[Documentación de la API](/es/v1.58/developer-manual/get-started/intro-to-zylon)**
>
> Empieza con las API de alto y bajo nivel de Zylon

> **[API de ZylonGPT](/es/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview)**
>
> Acceso directo a las capacidades de IA con endpoints de Messages compatibles con Anthropic

> **[API de Workspace](/es/v1.58/developer-manual/build-with-zylon/workspace-api/overview)**
>
> Acceso programático a proyectos, bases de conocimiento y funciones colaborativas

## Administradores

Encuentra los recursos que necesitas para desplegar Zylon, conectarlo a tus datos y gestionarlo todo.

> **[Empezar](/es/v1.58/operator-manual/overview)**
>
> Comprende cómo configurar Zylon para tu organización con nuestra guía completa de despliegue

> **[Instalación](/es/v1.58/operator-manual/installation/overview)**
>
> Despliega Zylon en local en menos de 3 horas con una instalación de un solo comando.

> **[Requisitos](/es/v1.58/operator-manual/installation/hardware-requirements)**
>
> Comprende los requisitos de hardware para ejecutar la plataforma Zylon en local

> **[Auditabilidad y gobernanza de IA](/es/v1.58/operator-manual/auditability-ai-safety/overview)**
>
> Revisa capacidades de auditabilidad, trazabilidad, preservacion de evidencia, gobernanza y responsabilidad de IA

## Beneficios clave de Zylon

> [!NOTE]
>
> **Soberanía completa de datos**: Tus datos nunca salen de tus instalaciones. Zylon se ejecuta completamente en local, incluyendo los modelos de IA, garantizando el control total y el cumplimiento de los requisitos normativos.

> [!NOTE]
>
> **Gobernanza y preparacion de auditoria**: Zylon documenta auditabilidad, gobernanza de IA, retencion, recopilacion de evidencia y mapeo de controles separado de la seguridad base de plataforma.

> [!NOTE]
>
> **Uso ilimitado de IA**: A diferencia de los servicios en la nube que cobran por token, Zylon proporciona interacciones de IA ilimitadas con costes fijos y predecibles.

> [!NOTE]
>
> **Listo para empresas**: Despliega en menos de 3 horas en cualquier infraestructura. Sin dependencia de proveedores, personalización completa y capacidades de marca blanca.

***

**¿Necesitas ayuda inmediata?** Contacta con nuestro equipo de soporte en [dev@zylon.ai](mailto:dev@zylon.ai) o [solicita una demostración](https://cal.com/zylon/demo?source=docs) para ver Zylon en acción.


# Añadir contexto de la empresa
Source: https://docs.zylon.ai/es/v1.58/user-manual/adding-company-context

Gestiona el contexto a nivel de organización en el área de administración.

Añadir contexto relevante de la empresa **es una forma rápida y efectiva de personalizar la IA privada de tu empresa**. Incluye información sobre la empresa: qué hace, el propósito general de la IA de la empresa y cualquier otra información relevante como acrónimos o términos específicos de la empresa.
La **IA tendrá en cuenta ese contexto en cada interacción en todos los proyectos**.

## Dónde encontrarlo

Haz clic en el **nombre del espacio de trabajo** en la parte superior derecha y selecciona **Contexto de la empresa**.

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/company_context.jpg?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=edde5f42f629b275d1fa66a5b889ec83)

## Para qué no usarlo

Cambiar el **nombre del asistente** u otras configuraciones a nivel de instancia **no se hace** aquí. Esa es una tarea de **configuración de plataforma/instancia**. Consulta a tu administrador de Zylon o revisa el Manual de operaciones.


# Añadir instrucciones personalizadas
Source: https://docs.zylon.ai/es/v1.58/user-manual/adding-custom-instructions

Proporciona instrucciones específicas del proyecto usadas en cada chat del proyecto.

Cada proyecto puede definir **instrucciones personalizadas** que la IA usa en **cada interacción en ese proyecto**. Estas complementan, y no reemplazan, el contexto de empresa a nivel de organización.

Abre **Project Settings**, escribe tus instrucciones en el único campo **Instructions** y guarda la configuración del proyecto.

Usa este campo para indicar, por ejemplo:

* para qué sirve el proyecto
* a quién va dirigido
* acrónimos o contexto importante del dominio
* idioma o estilo de respuesta preferido

El tamaño máximo de este campo lo controla el operador mediante `features.maxInstructionsLength` en `/etc/zylon/zylon-conf.yaml`. El límite predeterminado es `4000`, y el mismo límite se aplica tanto en la UI de Workspace como en la API. Para la configuración del lado del operador, consulta [Instrucciones personalizadas de proyecto](/es/v1.58/operator-manual/configuration/features/feat-project-custom-instructions).

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/project_context.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=47e5eecaa7233f9809d5c961680cabe2)

## Ajustes avanzados

La configuración del proyecto también incluye dos toggles avanzados:

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/advanced_settings.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=98792f00c75aacd8f14109ecde34cb2d)

* **Citations**: Habilita o deshabilita las citas en las respuestas de chat de Zylon para ese proyecto.
* **System prompt**: Mantiene o elimina la capa de prompt predeterminada de Zylon. Este prompt no se puede editar desde la UI, solo eliminar.

> [!WARNING]
>
> Estos ajustes cambian cómo responde Zylon. Cambiarlos puede reducir la calidad de la respuesta, reducir la trazabilidad o hacer que las respuestas fallen, así que úsalos con cuidado.

> **Comportamiento:** Las instrucciones personalizadas se aplican a nivel de proyecto y modelan cómo responde Zylon en ese proyecto junto con el contexto de empresa de la organización.


# Responder en masa
Source: https://docs.zylon.ai/es/v1.58/user-manual/agent-flows/answer-in-bulk

Haz muchas preguntas a la vez y obtén una tabla de respuestas con citas.

Pega una lista de **preguntas** y apunta el flow a archivos/carpetas relevantes en la Base de conocimiento. La salida es una **tabla** de **Pregunta → Respuesta** con **citas** a los pasajes exactos de la fuente.

* Ideal para RFPs, diligencia debida, cuestionarios de proveedores.
* Las opciones de exportación incluyen formatos de documento/tabla (p. ej., CSV).


# Generar borrador
Source: https://docs.zylon.ai/es/v1.58/user-manual/agent-flows/generate-draft

Crea un nuevo documento que sigue el tono y contenido de fuentes seleccionadas.

Selecciona archivos de referencia (p. ej., anuncios anteriores, políticas, especificaciones) y describe el **borrador que quieres**. El documento IA infiere las secciones requeridas y crea un nuevo documento basándose en tus fuentes e instrucciones.

> Después de la generación, coedita con tus compañeros y usa **IA en línea** para iterar.


# Abrir página en blanco
Source: https://docs.zylon.ai/es/v1.58/user-manual/agent-flows/open-blank-page

Empieza desde cero y opcionalmente usa IA para ayudarte a escribir.

Crea un documento vacío y **usa IA en línea** para componer secciones. Puedes basar los prompts en la **Base de conocimiento del proyecto** para extraer hechos y referencias precisas.


# Leer y extraer
Source: https://docs.zylon.ai/es/v1.58/user-manual/agent-flows/read-and-extract

Define temas y extrae todos los pasajes relevantes en documentos largos, con citas.

Para documentos largos, sensibles al cumplimiento o con muchas especificaciones (p. ej., RFPs), define los **temas** a extraer (p. ej., *requisitos de aplicación móvil*, *términos de pago*, *nombres de entidades*) y apúntalo al conjunto de documentos a analizar. El flow funciona de la siguiente manera:

1. **Lee el documento/s completo/s**.
2. **Resalta** frases relevantes por tema.
3. Produce una lista estructurada con **citas exactas** y **referencias** a las ubicaciones de la fuente.
4. Te permite **podar** o **postprocesar** (p. ej., "resume en cinco puntos").

> Este es un flow avanzado pero extremadamente efectivo para revisiones estructuradas y análisis posteriores.


# Resumir archivo
Source: https://docs.zylon.ai/es/v1.58/user-manual/agent-flows/summarize-file

Produce un resumen exhaustivo de documentos largos o carpetas.

Elige uno o más archivos/carpetas de la KB del proyecto y solicita un **resumen**. El flow lee el **contenido completo**, tomando el tiempo necesario para la exhaustividad.

* Proporciona orientación (p. ej., "conviértelo en una guía de incorporación", "nivel de detalle: moderado").
* Edita el resultado y usa **IA en línea** para refinar estructura/formato.


# Conector de Claromentis
Source: https://docs.zylon.ai/es/v1.58/user-manual/connectors/claromentis

Importa carpetas y archivos de Claromentis y manténlos sincronizados bajo demanda.

Puedes importar **archivos y carpetas** de Claromentis a los que tengas acceso. Después de importar, usa el botón **Actualizar** (dentro del menú de 3 puntos) para **sincronizar** con la fuente:

* Detecta **cambios de contenido** en archivos.
* Añade **archivos nuevos** y **elimina** los eliminados.
* Refleja **movimientos/renombrados** para que la estructura refleje Claromentis.

> Todos los que tengan acceso al proyecto tendrán acceso a los archivos y carpetas que conectes al proyecto, independientemente de los permisos originales en el sistema de archivos.

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/claromentis.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=0a6d133dd66220a2a69833bc75ba23a4)

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/claromentis_login.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=2ec4440583422cc647e10202351a535d)

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/claromentis_picker.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=9d492354e375f3093785fb0eb4a2bc7b)

> [!NOTE]
>
> Consulta cómo habilitar el conector en el [Manual del operador](/es/v1.58/operator-manual/knowledge-base/claromentis)


# Conector de Confluence
Source: https://docs.zylon.ai/es/v1.58/user-manual/connectors/confluence

Importa carpetas y archivos de Confluence y manténlos sincronizados bajo demanda.

Puedes importar **Espacios** de Confluence a los que tengas acceso. Después de importar, usa el botón **Actualizar** (dentro del menú de 3 puntos) para **sincronizar** con la fuente:

* Detecta **cambios de contenido** en archivos.
* Añade **archivos nuevos** y **elimina** los eliminados.
* Refleja **movimientos/renombrados** para que la estructura refleje el Espacio de Confluence.

> Todos los que tengan acceso al proyecto tendrán acceso a los archivos y carpetas que conectes al proyecto, independientemente de los permisos originales en Confluence.

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/confluence_login.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=e3cfc3b15132fb41ebe0ab79c44bbfed)

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/confluence_picker.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=54bcc95dfbcb9f1e05010525e9a5595b)

> [!NOTE]
>
> Consulta cómo habilitar el conector en el [Manual del operador](/es/v1.58/operator-manual/knowledge-base/confluence)


# Conector de Confluence Server
Source: https://docs.zylon.ai/es/v1.58/user-manual/connectors/confluence-server

Importa páginas de una instancia de Confluence Server / Data Center on-premise y manténlas sincronizadas bajo demanda.

Puedes importar **Espacios** de una instancia de **Confluence Server / Data Center** a la que tengas acceso.

Después de importar, usa el botón **Actualizar** (dentro del menú de 3 puntos) para **sincronizar** con la fuente:

* Detecta **cambios de contenido** en las páginas.
* Añade **páginas nuevas** y **elimina** las eliminadas.
* Refleja **movimientos y renombrados**, manteniendo la estructura sincronizada con la jerarquía del Espacio de Confluence.

Confluence Server no utiliza carpetas.
En su lugar, **las páginas y sus páginas hijas** se usan para recrear la jerarquía.

> Todos los que tengan acceso al Proyecto tendrán acceso a las páginas que conectes, independientemente de los permisos originales en Confluence.

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/confluence_login.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=e3cfc3b15132fb41ebe0ab79c44bbfed)

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/confluence_picker.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=54bcc95dfbcb9f1e05010525e9a5595b)

> [!NOTE]
>
> Consulta cómo habilitar el conector en el
> [Manual del operador](/es/v1.58/operator-manual/knowledge-base/confluence-server)


# Conector de sistema de archivos
Source: https://docs.zylon.ai/es/v1.58/user-manual/connectors/file-system

Importa carpetas y archivos de un servidor SMB y manténlos sincronizados bajo demanda.

Puedes importar **archivos y carpetas** de un sistema de archivos basado en SMB al que tengas acceso. Después de importar, usa el botón **Actualizar** (dentro del menú de 3 puntos) para **sincronizar** con la fuente:

* Detecta **cambios de contenido** en archivos.
* Añade **archivos nuevos** y **elimina** los eliminados.
* Refleja **movimientos/renombrados** para que la estructura refleje la estructura del sistema de archivos.

> Todos los que tengan acceso al proyecto tendrán acceso a los archivos y carpetas que conectes al proyecto, independientemente de los permisos originales en el sistema de archivos.

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/file_system.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=eb7a7f1d6550f091f1bd31ca5ad08cfd)

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/file_system_login.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=3f53aac21bf93b7e23df6d8c5618ca66)

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/file_system_picker.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=a1dd74b43992fd9709a9062fe4ea5f89)

> [!NOTE]
>
> Consulta cómo habilitar el conector en el [Manual del operador](/es/v1.58/operator-manual/knowledge-base/file-system)


# Conector de Google Drive
Source: https://docs.zylon.ai/es/v1.58/user-manual/connectors/google-drive

Importa archivos y carpetas de Google Drive a una base de conocimiento de proyecto.

Puedes importar **archivos o carpetas** de **Mi unidad** y **Compartido conmigo** a los que tu cuenta de Google tenga acceso. Después de importar, usa **Actualizar** en el menú de tres puntos para sincronizar la fuente:

* Detecta cambios de contenido en los archivos.
* Añade archivos nuevos y elimina los archivos eliminados.
* Refleja movimientos y cambios de nombre para que la estructura del proyecto refleje Google Drive.

> Todas las personas con acceso al proyecto pueden acceder a los archivos y carpetas de Google Drive que conectes, independientemente de los permisos originales de Google Drive.

\[Placeholder: Añadir una captura del flujo de inicio de sesión y Google Picker.]

> [!NOTE]
>
> Pide a tu administrador que configure el conector o consulta la [configuración de la integración de Google Drive](/es/v1.58/operator-manual/knowledge-base/google-drive).


# Conector de SharePoint
Source: https://docs.zylon.ai/es/v1.58/user-manual/connectors/sharepoint

Importa carpetas y archivos de SharePoint y manténlos sincronizados bajo demanda.

Puedes importar **archivos o carpetas** de SharePoint a los que tengas acceso. Después de importar, usa el botón **Actualizar** (dentro del menú de 3 puntos) para **sincronizar** con la fuente:

* Detecta **cambios de contenido** en archivos.
* Añade **archivos nuevos** y **elimina** los eliminados.
* Refleja **movimientos/renombrados** para que la estructura refleje SharePoint.

> Todos los que tengan acceso al proyecto tendrán acceso a los archivos y carpetas de SharePoint que conectes al proyecto, independientemente de los permisos originales en SharePoint.

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/sharepoint_picker.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=3a2ae793162b32ab58ecc97873502368)

> [!NOTE]
>
> Consulta a tu administrador o revisa el Manual del operador para aprender cómo configurar tu integración de SharePoint.


# Crear un proyecto
Source: https://docs.zylon.ai/es/v1.58/user-manual/creating-a-project

Crea un nuevo proyecto y entiende dónde se encuentra por defecto.

Los proyectos son los espacios de trabajo donde viven los chats, los documentos IA y una base de conocimiento específica del proyecto. Cuando creas un proyecto, se **crea en tu espacio privado por defecto** (visible solo para ti).

## Pasos

1. Ve a la barra lateral y selecciona **Nuevo proyecto**.
2. Introduce un nombre.
3. Crea. Serás redirigido al nuevo proyecto y el proyecto aparecerá en la lista de proyectos.

[Zylon Workspace - Create Project](https://www.youtube.com/embed/iJmQKmtkK2s)

> **Consejo:** Puedes **fijar** proyectos para mantener accesos directos personales. Fijar es una comodidad por usuario y no afecta a otros usuarios.


# Análisis de participación
Source: https://docs.zylon.ai/es/v1.58/user-manual/engagement-analytics

Solo para administradores, vista agregada (panel de uso) para entender la adopción a lo largo del tiempo.

El **Panel de uso** se usa para entender la **participación**. Es **solo para administradores** y muestra información **agregada**.

## Lo que puedes ver

* Actividad en el espacio de trabajo (p. ej., **consultas**, **chats**, **proyectos**, **documentos IA**, **documentos vinculados**).
* Vistas **temporales**: cómo participa la gente a lo largo del tiempo.
* **Usuarios y proyectos principales** lista de los N principales usuarios y proyectos mediante menú desplegable.

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/analytics-1.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=aed72f96c29460d0405496d57ecf2f1f)

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/analytics-2.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=ad2cd785c9b98b3c75fa20f43b284abd)

![](https://mintcdn.com/zylon/zWASxGOiZ3sSIIAQ/images/user-manual/analytics-3.png?fit=max\&auto=format\&n=zWASxGOiZ3sSIIAQ\&q=85\&s=8377a526f0627d3a3a21eff4b9a02b2b)

> Combinar el **Panel de uso** con los **Registros de auditoría** da una imagen más completa de la adopción y el comportamiento.

> [!NOTE]
>
> El análisis de participación está diseñado para **demostrar valor** y apoyar la habilitación—sin exponer el contenido de interacciones individuales.


# Preguntas frecuentes del primer día
Source: https://docs.zylon.ai/es/v1.58/user-manual/first-day-faqs

Respuestas rápidas a preguntas comunes al empezar con Zylon Workspace

## Empezar

**¿Cómo accedo a Zylon Workspace?**

Tu administrador de TI te proporcionará una URL de inicio de sesión y credenciales. Zylon normalmente se integra con el sistema de inicio de sesión único (SSO) de tu empresa, por lo que es posible que puedas usar tus credenciales de trabajo habituales.

Si no puedes acceder al sistema, contacta con tu administrador de TI para obtener ayuda.

**¿Qué debo hacer primero?**

1. **Crea tu primer proyecto** - Empieza con algo sencillo como "Investigación personal"
2. **Sube algunos documentos** o conéctate a una carpeta de SharePoint que uses regularmente
3. **Prueba a hacer una pregunta** sobre los documentos que subiste
4. **Revisa la respuesta y las citas** para entender cómo funciona Zylon

La [Guía de inicio rápido](/es/v1.58/user-manual/quick-start-guide) te guía paso a paso por este proceso.

**¿Necesito formación para usar Zylon?**

No se requiere formación formal. Zylon está diseñado para ser intuitivo: si puedes usar ChatGPT, puedes usar Zylon. La interfaz es conversacional y fácil de usar.

Sin embargo, revisar la [Guía para principiantes del chat](/es/v1.58/user-manual/querying-company-documents) te ayudará a obtener mejores resultados más rápido.

## Proyectos y conocimiento

**¿Qué es un proyecto y por qué necesito uno?**

Los proyectos son cómo organizas tu trabajo en Zylon. Cada proyecto tiene:

* Su propia base de conocimiento (documentos conectados)
* Instrucciones personalizadas sobre cómo debe comportarse la IA
* Miembros específicos del equipo con diferentes niveles de acceso

Piensa en los proyectos como carpetas, pero para trabajo de IA. Podrías tener proyectos separados para atención al cliente, investigación o trabajo de cumplimiento.

**¿Puedo ver los proyectos de otras personas?**

Solo si te los comparten específicamente. Los proyectos son privados por defecto. Cuando alguien comparte un proyecto contigo, lo verás en tu lista de proyectos con tu rol asignado (Visualizador, Colaborador o Administrador).

**¿Qué documentos puedo subir?**

Zylon admite formatos de archivo empresariales comunes:

* PDFs (deben ser buscables por texto, no solo imágenes escaneadas)
* Documentos de Microsoft Word (.docx, .doc)
* Hojas de cálculo de Excel (.xlsx, .xls)
* Presentaciones de PowerPoint (.pptx, .ppt)
* Archivos de texto plano (.txt, .csv)

También puedes conectarte a SharePoint, Confluence y otros sistemas.

**¿Cuánto tarda en procesar los documentos?**

La mayoría de los documentos se procesan en 2-5 minutos después de la subida. Los archivos más grandes o muchos archivos a la vez pueden tardar más. Verás un indicador de procesamiento y podrás usar los documentos una vez que el procesamiento esté completo.

## Usar el asistente de chat

**¿Cómo hago buenas preguntas?**

**Sé específico**: En lugar de "cuéntame sobre los clientes", prueba "¿cuáles son las 3 principales quejas de clientes del último trimestre?"

**Incluye contexto**: "Según nuestras políticas de ventas, ¿cuál es el proceso de aprobación de descuentos para acuerdos empresariales?"

**Referencia períodos de tiempo**: "Muéstrame los cambios de presupuesto desde enero de 2024"

La IA funciona mejor cuando le das preguntas claras y detalladas.

**¿Cómo sé si la respuesta de la IA es precisa?**

¡Siempre comprueba las citas! Cada respuesta incluye citas numeradas que enlazan directamente con los documentos fuente. Haz clic en ellas para verificar la información.

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_citations.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=ff3d3ac1cad4aa44ed655ce5c0768a8c)

Si algo parece incorrecto, comprueba el documento fuente para ver el contexto completo.

**¿Cuál es la diferencia entre chats personales y colaborativos?**

**Chats personales**: Solo tú puedes ver la conversación. Bueno para investigación sensible o análisis preliminar.

**Chats colaborativos**: Visibles para todos los miembros del proyecto. Otros pueden ver tus preguntas y añadir las suyas. Ideal para discusiones en equipo e investigación compartida.

## Problemas comunes

**¿Por qué Zylon no puede encontrar información que sé que existe?**

Comprueba estas causas comunes:

* El documento podría estar aún procesándose (espera unos minutos)
* El documento no está conectado a tu proyecto actual
* Prueba a reformular tu pregunta con diferentes palabras clave
* Asegúrate de que el documento sea buscable por texto (no una imagen escaneada)

Si el problema persiste, contacta con tu administrador.

**La respuesta de la IA parece incompleta o incorrecta**

* Comprueba si estás usando el proyecto correcto con documentos relevantes
* Prueba a hacer preguntas más específicas
* Mira las citas para ver qué fuentes se usaron
* Recuerda que la IA proporciona sugerencias, no respuestas definitivas - usa siempre tu criterio profesional

**Compartí accidentalmente un proyecto con las personas equivocadas**

Si eres administrador del proyecto, ve a la configuración del proyecto y elimina los miembros incorrectos. Si no eres administrador, contacta con la persona que creó el proyecto o con tu administrador de TI.

## Datos y privacidad

**¿Están seguros mis datos en Zylon?**

Sí. Zylon se ejecuta completamente en la infraestructura de tu empresa. Tus datos nunca salen de tus instalaciones y no hay llamadas a API externas a servicios en la nube.

Todas las interacciones se registran con fines de auditoría y el acceso está controlado por tus administradores de TI.

**¿Puedo eliminar documentos o conversaciones?**

Sí, tienes control sobre los documentos que conectas a la base de conocimiento y el contenido que generas.

**¿Quién puede ver mis conversaciones de chat?**

* **Chats personales**: Solo tú
* **Chats colaborativos**: Todos los miembros del proyecto
* **Administradores**: Pueden tener acceso con fines de auditoría y cumplimiento

Consulta las políticas de tu organización para obtener detalles específicos sobre la retención y el acceso a datos.


# Chats grupales
Source: https://docs.zylon.ai/es/v1.58/user-manual/group-chats

Inicia chats colaborativos en un proyecto y convierte chats privados cuando sea necesario.

Al iniciar un chat en un proyecto, elige:

* **Personal** — privado para ti (muestra un icono de candado).
* **Colaborativo** — visible para todos los miembros del proyecto; los compañeros pueden responder y continuar el hilo.

Puedes **convertir un chat privado a colaborativo** más tarde. Esta acción **no se puede deshacer**. Los chats colaborativos se pueden descubrir mediante **Búsqueda** por miembros que tienen acceso al proyecto.


# IA en línea en el editor
Source: https://docs.zylon.ai/es/v1.58/user-manual/inline-ai-in-editor

Usa IA en selecciones para mejorar o generar contenido, opcionalmente basado en tu base de conocimiento.

Selecciona texto en un documento de flow o escribe '/' para invocar IA. Úsala para **mejorar formato**, **reescribir** o **generar** contenido. Puedes elegir si la IA debe **usar la base de conocimiento del proyecto** o responder de forma genérica.

* Ejemplo: "Mejora el formato" (no uses la Base de conocimiento).
* Ejemplo: "Inserta más detalles sobre nuestros requisitos de aplicación Android" (usa la Base de conocimiento para recuperar los documentos de atención al cliente e insertar los hechos).


# Vincular bases de conocimiento
Source: https://docs.zylon.ai/es/v1.58/user-manual/linking-knowledge-bases

Reutiliza contenido de otros proyectos sin volver a ingerirlo.

Para **reutilizar** contenido de la Base de conocimiento de otro proyecto **sin duplicarlo**:

1. En **Subir archivos**, elige **Vincular desde otro proyecto**.
2. Selecciona el **proyecto fuente**, luego vincula su **Base de conocimiento completa** o **carpetas** específicas.
3. El contenido vinculado está **disponible inmediatamente** (sin re‑ingesta).

[Zylon Workspace - Linking files](https://www.youtube.com/embed/DM3EIVt-1LM)

**Las actualizaciones se propagan** desde el proyecto original automáticamente—las carpetas/archivos vinculados se mantienen sincronizados con su fuente.

> **Consejo:** Usa carpetas para limitar chats. Cuando inicies un chat puedes dirigirlo a la **Base de conocimiento completa** o a una **carpeta específica** para mejorar la precisión.


# Gestionar las Habilidades de la Organización
Source: https://docs.zylon.ai/es/v1.58/user-manual/managing-organization-skills

Solo para administradores. Crea una biblioteca compartida de Habilidades que cualquier proyecto de tu organización pueda usar.

Las **Habilidades** son paquetes de instrucciones listos para usar que le enseñan al asistente de Zylon cómo realizar una tarea concreta siempre de la misma manera — por ejemplo, dar formato a una hoja de cálculo de una forma determinada, o resumir un informe con una estructura fija. Como administrador, puedes publicar Habilidades a **nivel de organización** para que cualquier proyecto pueda reutilizarlas, en lugar de que cada equipo cree las suyas desde cero.

> [!NOTE]
>
> ¿Quieres saber qué es exactamente una Habilidad y cómo se usa en el chat? Consulta [Introducción a las Habilidades](/es/v1.58/user-manual/skills/introduction-to-skills).

***

## Dónde encontrarlo

Ve a **Administración → Habilidades**. Verás todas las Habilidades publicadas actualmente en tu organización, junto con su descripción y quién las creó.

![Lista de habilidades de la organización en el panel de administración](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/admin-skills-list.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=6e4063de665917eacd404789d41f1233)

***

## Añadir una Habilidad de la organización

1. Haz clic en **New Skill**.
2. Arrastra un archivo de Habilidad a la zona de carga (un archivo `.zip`, `.skill` o `SKILL.md`), o haz clic en **Add Files** para elegir uno desde tu dispositivo.
3. Revisa el nombre y la descripción que Zylon detectó a partir del archivo.
4. Haz clic en **Install** para publicarla en la organización.

![Subiendo una habilidad a la biblioteca de la organización](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/upload-skill-dialog.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=3ecf760c0d503881b798071219ffd626)

> [!WARNING]
>
> Sube únicamente Habilidades de fuentes en las que confíes. Las instrucciones de una Habilidad se ejecutan automáticamente cada vez que se usa, así que revisa su contenido antes de publicarla para toda la organización.

***

## Eliminar una Habilidad

Abre el menú **⋯** junto a una Habilidad y selecciona **Delete**. Ten en cuenta que eliminar una Habilidad de la organización también la elimina de todos los proyectos que la tenían instalada.

***

## Qué pueden hacer los equipos de proyecto con ella

Una vez publicada aquí, los administradores de proyecto pueden añadirla a su propio proyecto en un par de clics — consulta [Instalar una Habilidad de la organización](/es/v1.58/user-manual/skills/installing-from-organization). No necesitas configurar nada por proyecto; con publicarla aquí es suficiente para que esté disponible en todas partes.


# Primeros pasos en n8n
Source: https://docs.zylon.ai/es/v1.58/user-manual/n8n



n8n es una herramienta de automatización de flujo de trabajo de código abierto que permite a los usuarios conectar diversas aplicaciones y servicios para automatizar tareas repetitivas.
Por ello Zylon incluye una instancia de n8n preconfigurada y lista para usar, facilitando a los usuarios la creación y gestión de flujos de trabajo automatizados directamente desde la
plataforma Zylon.

![Integración de n8n MCP con Zylon](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/n8n-zylon.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=bd0114b5e078b6e283e515d766d43500)

> [!NOTE]
>
> Si aún no has configurado n8n en tu instancia de Zylon, puedes consultar el manual de configuración de n8n [aquí](/es/v1.58/operator-manual/configuration/n8n).

# Primeros pasos

Una vez que n8n esté configurado en la instancia de Zylon, podrás acceder a la interfaz web de n8n, la cual está disponible por defecto en la siguiente URL:
`https://n8n.<your_zylon_domain>`.

> [!NOTE]
>
> Es posible que durante el proceso de instalación se haya configurado un dominio personalizado para n8n.

## Crear una cuenta en n8n

La primera vez que accedas a la instancia de n8n se te pedirá crear una cuenta de administrador. Esta cuenta tendrá privilegios completos para gestionar usuarios, configurar ajustes globales y administrar todos los workflows de la instancia.

**Pasos para crear la cuenta de administrador:**

1. Accede a `https://n8n.<your_zylon_domain>`
2. Completa el formulario de registro
3. Acepta los términos de uso
4. Haz clic en "Crear cuenta"

## Crear nuevos usuarios

Los usuarios adicionales pueden ser invitados a la instancia de n8n mediante enlaces de invitación.

Cada usuario puede tener uno de dos roles: **Administrador** (acceso completo) o **Miembro** (acceso limitado a workflows y credenciales asignadas).

> [!WARNING]
>
> Solo los administradores pueden crear nuevos usuarios en n8n.

**Pasos para invitar usuarios:**

1. Haz clic en el icono de usuario (esquina inferior izquierda)
2. Selecciona **Settings > Users**
3. Haz clic en el botón **"Invite"**
4. Ingresa el correo electrónico del nuevo usuario
5. Selecciona el rol apropiado:
   * **Administrador**: Acceso completo a configuración, usuarios y todos los workflows
   * **Miembro**: Acceso solo a workflows y credenciales compartidas
6. Haz clic en **"Create invite link"**
7. Comparte el enlace de invitación con el nuevo usuario

# Conectar con Zylon chat model

Para conectar n8n con los modelos de chat de Zylon, se puede utilizar el nodo de Anthropic que viene integrado en n8n, ya que Zylon es compatible con los nodos de Anthropic en n8n, lo que permite una integración sencilla.

Los prerrequisitos son:

* Contar con un token de API de Zylon (consulta [Backoffice Developer Console](/es/v1.58/developer-manual/get-started/developer-console))

Una vez que se tienen los prerrequisitos, se puede proceder a configurar n8n:

### Configuración de credenciales

1. Nos dirigimos a la sección de Credenciales en n8n
2. Creamos una nueva credencial seleccionando "Anthropic"
3. Configuramos las siguientes opciones:
   * **Name**: Nombre descriptivo para la credencial (ej. Zylon) (El nombre se modifica en la parte superior izquierda del formulario)
   * **API Key**: El token de API de Zylon
   * **Base URL**: La URL de la API de Zylon, que generalmente es `https://<your_zylon_domain>/api/gpt`
4. Guardamos la credencial (si todo va bien aparece "Connection tested successfully")

### Crear un flujo de trabajo simple

Ahora que contamos con las credenciales, podemos crear un flujo de trabajo simple que utilice el modelo de chat de Zylon.

1. Nos dirigimos a la sección de Flujos de trabajo (Workflows) en n8n
2. Creamos un nuevo flujo de trabajo
3. Añadimos un nodo "Anthropic Chat Model" al flujo de trabajo
4. Configuramos el nodo con las siguientes opciones:
   * **Credentials**: Seleccionamos la credencial de Anthropic que creamos anteriormente
   * **Model**: Seleccionamos "By ID" y escribimos "default" para usar el modelo por defecto en nuestra instancia de Zylon.

Ahora ya podremos utilizar el modelo de chat de Zylon en n8n para crear flujos de trabajo automatizados.

# Usar MCP desde chat para conectar con flujo de n8n

Zylon también permite utilizar MCP (Model Call Protocol) desde el chat para interactuar con flujos de trabajo de n8n.
Esto permite a los usuarios ejecutar flujos de trabajo directamente desde la interfaz de chat.
Para ello, en primer lugar se debe crear un flujo de trabajo en n8n que esté diseñado para ser llamado desde MCP.

## Crear un flujo de trabajo en n8n para MCP

> [!WARNING]
>
> Por seguridad, configura todos los nodos MCP Server Trigger con autenticación **Bearer** y usa credenciales dedicadas con tokens robustos.

1. Nos dirigimos a la sección de Flujos de trabajo (Workflows) en n8n
2. Creamos un nuevo flujo de trabajo
3. Añadimos un nodo de tipo "MCP Server Trigger" al flujo de trabajo
4. En **Authentication** seleccionamos **Bearer** y creamos o elegimos una credencial de tipo Bearer
   * **Name**: Usa un nombre descriptivo (ej. Zylon MCP)
   * **Bearer Token**: Genera un token largo y seguro y guárdalo; lo necesitarás luego para la conexión desde Zylon
5. Copiamos la "Production URL" que se genera en el nodo MCP Server Trigger y configuramos el resto de opciones según nuestras necesidades
6. Añadimos tools al nodo MCP Server Trigger para definir las acciones que queremos que el flujo de trabajo realice cuando sea llamado desde Zylon chat
7. Vuelve a la página principal del workflow y activa el workflow haciendo clic en el botón de alternancia en la esquina superior derecha

> [!NOTE]
>
> Más información sobre el nodo MCP Server Trigger en n8n se puede encontrar [aquí](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-langchain.mcptrigger/).

## Llamar al flujo de trabajo desde Zylon chat usando MCP

Una vez que el flujo de trabajo esté configurado y probado en n8n, podemos llamarlo desde Zylon chat utilizando MCP.

1. Abrimos la interfaz de chat en Zylon
2. Seleccionamos un proyecto y nos vamos a la sección de conectores
3. Pulsamos en "New Connector" y seleccionamos "Add MCP Server"
4. Configuramos las siguientes opciones:
   * **Name**: Nombre descriptivo para el conector (ej. n8n MCP)
   * **MCP Server URL**: Pegamos la "Test URL" que copiamos del nodo MCP Server Trigger en n8n
   * **Authentication**: Seleccionamos **Bearer**
   * **Bearer Token**: Pegamos el token seguro que creamos en n8n para este conector
5. Pulsamos en "Connect" (si da error, asegurarse de que el flujo de trabajo en n8n está activo)
6. Nos dirigimos a la sección de chat y seleccionamos el conector MCP que acabamos de crear
7. Ahora podemos enviar mensajes en el chat que llamarán al flujo de trabajo en n8n a través de MCP

Documentación adicional sobre MCP y su uso en Zylon se puede encontrar [aquí](/es/v1.58/user-manual/tools/mcp-connector#conector-mcp).

***


# Recuperación de contraseña
Source: https://docs.zylon.ai/es/v1.58/user-manual/password-recovery

Cambia tu contraseña o restablécela en caso de que la hayas olvidado

## Cambiar contraseña

1. Ve a tu perfil.

   ![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/profile_password_recovery.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=f33e23f285ad16e8287df177ba1eaedc)
2. Haz clic en **cambiar contraseña** y configura tu nueva contraseña.

   ![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/profile_change_password.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=5eafd6c65d1f3c326697c79c8f734150)

## Restablecer contraseña&#x20;

Solo el administrador puede restablecer la contraseña de un usuario. Para hacerlo, el administrador necesita usar la CLI de Zylon para realizar la acción.
Si eres administrador, [aprende cómo hacerlo.](/es/v1.58/operator-manual/configuration/cli#update-password)


# Consultar documentos de la empresa
Source: https://docs.zylon.ai/es/v1.58/user-manual/querying-company-documents

Haz preguntas sobre la base de conocimiento de tu proyecto, incluyendo repositorios conectados.

1. Inicia un nuevo chat en el **proyecto** relevante.
2. (Opcional) **Limita** el chat a una **carpeta** si sabes dónde está la respuesta.
3. Haz tu pregunta. El asistente recupera fragmentos relevantes y responde con **citas** que puedes abrir al pasaje exacto.
4. Si es necesario, refina la pregunta o ajusta el alcance de la carpeta.

[Zylon Workspace - Ask Chat with sources](https://www.youtube.com/embed/KUw9oc3fZCw)

> También puedes pegar una **URL** en el prompt para obtener y usar el contenido de esa página para el turno actual.


# Guía de inicio rápido
Source: https://docs.zylon.ai/es/v1.58/user-manual/quick-start-guide

Sé productivo con Zylon Workspace en 15 minutos

Completa estas tareas esenciales para empezar a usar Zylon de forma efectiva. Esta guía tarda unos 15 minutos y cubre todo lo que necesitas para ser productivo.

## Paso 1: Crea tu primer proyecto (3 minutos)

Los proyectos organizan tu trabajo de IA por tema o equipo. Empieza con un proyecto personal sencillo.

1. **Haz clic en "Crear proyecto"** desde tu panel de control
2. **Nómbralo de forma descriptiva** - p. ej., "Investigación personal" o "Atención al cliente"
3. **Mantenlo privado** por ahora (puedes compartirlo más tarde)

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_project_creation.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=ab9f7e0353a10f9667df913d697a555e)

> [!NOTE]
>
> Los proyectos son privados por defecto. Solo tú puedes verlos a menos que los compartas explícitamente con otros.

## Paso 2: Conecta tu conocimiento (5 minutos)

Añade documentos para que Zylon pueda ayudarte con tu trabajo real. Navega a la sección de Base de conocimiento de tu proyecto.

**Opción A: Subir archivos**

1. **Arrastra y suelta** 2-3 documentos con los que trabajas regularmente
2. **Espera el procesamiento** (normalmente 2-5 minutos)
3. **Comprueba la base de conocimiento** para confirmar que están listos

**Opción B: Conectarte a una fuente externa, como SharePoint**

1. **Haz clic en "Conectar SharePoint"** en tu proyecto
2. **Autentícate** con tus credenciales
3. **Selecciona una carpeta específica** (no todo el sitio)

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_knowledge_base.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=2098a47869cf3ec590c92c807a438e44)

**Tipos de archivo admitidos:**

* PDFs, documentos de Word, hojas de cálculo de Excel
* Presentaciones de PowerPoint, archivos de texto plano
* Carpetas de SharePoint, espacios de Confluence, FTP/Samba

## Paso 3: Haz tu primera pregunta (3 minutos)

Ahora prueba Zylon con una pregunta real sobre tus documentos.

1. **Inicia un nuevo chat** (elige Personal por ahora)
2. **Haz una pregunta específica** sobre los documentos que subiste
3. **Revisa la respuesta** y haz clic en las citas
4. **Haz una pregunta de seguimiento** para ver cómo Zylon mantiene el contexto

**Buenos ejemplos de preguntas:**

```
"¿Cuáles son los requisitos clave mencionados en [nombre del documento]?"
"¿Cuál es nuestra política sobre [tema específico]?"
```

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_chat.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=28c4d01dd4757a7b198d833f66da4287)

## Paso 4: Prueba un Documento IA (4 minutos)

Los documentos IA gestionan tareas complejas automáticamente en segundo plano.

1. **Ve a Documentos IA** en tu proyecto
2. **Elige "Resumir un archivo"**
3. **Selecciona uno de tus documentos subidos**
4. **Añade instrucciones** como "Crea un resumen ejecutivo centrado en decisiones clave"
5. **Haz clic en Iniciar** y déjalo ejecutarse en segundo plano

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_summarization.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=2b01969d874a803b11a8c78b4d6e7e94)

**Otros documentos IA para probar:**

* **Responder en masa**: Sube una lista de preguntas para respuestas automáticas
* **Generar un borrador**: Crea nuevos documentos a partir de indicaciones
* **Leer y extraer**: Extrae información específica de múltiples documentos

## Lo que has conseguido

✅ **Creado y organizado** tu primer proyecto\
✅ **Conectado fuentes de conocimiento** para que Zylon pueda ayudar con trabajo real\
✅ **Mantenido conversaciones de IA** con citas y contexto\
✅ **Usado flujos de trabajo automatizados** para tareas documentales complejas


# Colaboración en tiempo real
Source: https://docs.zylon.ai/es/v1.58/user-manual/real-time-collaboration

Coedita las salidas de documentos IA con tus compañeros.

Las salidas de documentos IA (p. ej., resúmenes, borradores) son documentos editables. En proyectos compartidos, los compañeros pueden **editar juntos en tiempo real**—verás los cursores de los demás e incluso los prompts usados para acciones de IA en línea.


# Roles y permisos
Source: https://docs.zylon.ai/es/v1.58/user-manual/roles-and-permissions

El acceso a la base de conocimiento está controlado por los roles del proyecto.

Los permisos de la base de conocimiento se rigen por **roles del proyecto**:

* **Visualizador** — puede iniciar chats y documentos IA que *usan* la Base de conocimiento; **no puede** modificar la Base de conocimiento.
* **Editor** — puede **añadir/eliminar** contenido y estructura de la Base de conocimiento.
* **Administrador / Propietario** — control completo; también puede **transferir la propiedad**.

[Zylon Workspace - Invite members](https://www.youtube.com/embed/IiGaD3lYeyg)

> No hay roles separados "por documento"—el rol del proyecto determina lo que puedes hacer con la Base de conocimiento del proyecto.


# Buscar documentos de la empresa
Source: https://docs.zylon.ai/es/v1.58/user-manual/search-company-documents

Usa la búsqueda para descubrir documentos importados de repositorios de la empresa a los que puedes acceder.

Cuando los repositorios de la empresa (p. ej., **SharePoint**) y los archivos se conectan e importan en las bases de conocimiento del proyecto, esos archivos se **indexan**. La búsqueda los devuelve junto con tus otros elementos del espacio de trabajo.

* Escribe palabras clave o conceptos; los documentos coincidentes aparecen con su **fuente**.
* Selecciona un resultado para abrir el contexto del archivo o el chat/flujo donde se referencia.

> Solo ves elementos de repositorios y proyectos a los que tienes permiso para acceder.


# Buscar en el espacio de trabajo
Source: https://docs.zylon.ai/es/v1.58/user-manual/search-workspace-content

Encuentra proyectos, chats, Documentos AI y archivos a los que tienes acceso.

Usa la **búsqueda** para encontrar contenido al que tienes acceso en tu espacio de trabajo:

* **Proyectos** por nombre.
* **Chats**, incluidas las conversaciones personales y colaborativas.
* **Documentos AI**, como los resúmenes. También puedes buscar dentro de los documentos de texto creados por el asistente.
* **Archivos**, tanto subidos directamente como importados desde conectores.

Pulsa **Cmd/Ctrl-K** para abrir la búsqueda y escribe lo que quieres encontrar. Filtra por proyectos, documentos o chats para acotar los resultados. Las coincidencias de contenido muestran un fragmento del texto y el proyecto al que pertenecen.

Los resultados respetan los permisos: solo verás contenido de proyectos a los que tienes acceso.


# Autenticación para acciones sensibles
Source: https://docs.zylon.ai/es/v1.58/user-manual/security/authentication-for-sensitive-actions

Descubre cuándo Zylon solicita volver a autenticarse antes de realizar una acción sensible.

Zylon puede solicitarte que vuelvas a autenticarte antes de realizar acciones que podrían tener un impacto importante en la seguridad o en la operación. Esta comprobación adicional ayuda a proteger tu espacio de trabajo si una sesión activa queda desatendida o es utilizada por otra persona.

![Modal de reautenticación para una acción sensible](https://mintcdn.com/zylon/cq403Pwu3_JL-3jZ/images/user-manual/authentication-for-sensitive-actions.png?fit=max\&auto=format\&n=cq403Pwu3_JL-3jZ\&q=85\&s=f5c830ac2e48bcaa11e04e40e8bb7175)

> [!WARNING]
>
> La vigencia de autenticación no se aplica a las peticiones a la API autenticadas con tokens. Las integraciones basadas en tokens no muestran este modal, por lo que los usuarios que ejecuten flujos automatizados con tokens de API no necesitan modificar sus flujos actuales.

## Cuándo se solicita la reautenticación

La comprobación puede aplicarse a acciones sensibles del espacio de trabajo y del backoffice, como:

* eliminar organizaciones, proyectos, gateways, artefactos, usuarios o tokens;
* crear tokens de API o gateways;
* cambiar membresías, roles o el estado de una cuenta; y
* otros cambios administrativos protegidos según su nivel de riesgo.

Consulta la [referencia de seguridad del Manual del Operador](/es/v1.58/operator-manual/security/authentication-for-sensitive-actions) para ver la lista completa de acciones protegidas y sus niveles de riesgo.

## Cómo funciona

Cuando tu autenticación reciente deja de estar vigente para la acción, Zylon muestra un modal de **Confirmar acceso**. Según los proveedores de autenticación habilitados en tu instancia, puedes:

1. introducir tu contraseña de Zylon; o
2. volver a autenticarte con Google o Microsoft SSO.

Después de validar correctamente la autenticación, Zylon normalmente continúa la acción de forma automática. Con Google o Microsoft SSO, la redirección al proveedor puede interrumpir la petición original. Si la acción no continúa automáticamente al volver a Zylon, repite la acción.

El tiempo durante el que una autenticación permanece vigente depende del nivel de riesgo de la acción y lo configura el operador. Consulta [Configuración de la vigencia de autenticación](/es/v1.58/operator-manual/configuration/features/authentication-freshness) para obtener más información.


# Compartir con colegas
Source: https://docs.zylon.ai/es/v1.58/user-manual/sharing-with-colleagues

Comparte un proyecto con todos en la organización o invita a compañeros específicos para colaborar.

Hay dos modelos de colaboración:

## 1) Disponible para todos en la organización

* Haz el proyecto visible para **todos los miembros actuales y futuros**.
* Asigna un rol por defecto: **Visualizador** o **Editor**.
  * **Visualizador:** puede iniciar chats y documentos IA (p. ej., resumir documentos) pero **no puede cambiar la base de conocimiento**.
  * **Editor:** puede modificar la base de conocimiento del proyecto (añadir/eliminar contenido).

Los proyectos compartidos a nivel de organización muestran el **icono de la organización**.

[Zylon Workspace - Share Project](https://www.youtube.com/embed/qYTmk2VK058)

## 2) Invitar a personas específicas

* Invita por nombre y elige un rol por persona: **Visualizador**, **Editor** o **Administrador**.
* El **propietario** (creador) puede **transferir la propiedad** si es necesario.
* Los proyectos compartidos muestran el **avatar del propietario con un contador de miembros**.

[Zylon Workspace - Invite members](https://www.youtube.com/embed/IiGaD3lYeyg)

> **Chats privados → colaborativos:** Al iniciar un chat puedes elegir **Personal** (privado) o **Colaborativo** (compartido con miembros del proyecto). Los chats privados se pueden **convertir a colaborativos** más tarde (esto **no se puede deshacer**).


# Crear una Habilidad
Source: https://docs.zylon.ai/es/v1.58/user-manual/skills/creating-a-skill

Crea una Habilidad con el chat o el editor, o instala un archivo de Habilidad en tu proyecto.

Los administradores y editores de proyecto pueden añadir una nueva Habilidad directamente dentro de un proyecto

## Crear una Habilidad con el chat

Puedes describir la tarea que necesitas con tus propias palabras; no hace falta escribir código.

1. Primero, [instala la Habilidad de la organización **Skill Creator**](/es/v1.58/user-manual/skills/installing-from-organization) en tu proyecto. Abre **Skills > New Skill > Install from organization**, busca **Skill Creator** y haz clic en **Install**. Si no está disponible, pide a tu administrador de la organización que la ponga a tu disposición.
2. Vuelve a **Skills > New Skill** y elige **Create with Chat**. Zylon abre un chat nuevo con Skill Creator seleccionada.
3. Describe qué quieres que haga la nueva Habilidad. Responde a las preguntas del asistente y pide cambios hasta que las instrucciones se ajusten a tu tarea.
4. Descarga el archivo `.skill` que proporciona el asistente y después [súbelo e instálalo](#subir-un-archivo-de-habilidad) en el proyecto. Ya puedes [seleccionar tu nueva Habilidad en el chat](/es/v1.58/user-manual/skills/using-skills-in-chat) para probarla.

Por ejemplo:

> Ayúdame a crear una Habilidad que convierta nuestras notas semanales de soporte en un informe corto. Incluye los principales problemas, lo que hemos resuelto y lo que sigue pendiente. Usa un lenguaje sencillo y listas con viñetas.

> [!NOTE]
>
> **Create with Chat** solo aparece cuando Skill Creator está instalada y habilitada en este proyecto. Un administrador o editor del proyecto puede instalarla; los lectores deben pedirles ayuda. Si tu operador ha desactivado la ejecución de código en Workspace, Skill Creator no puede ejecutar los pasos de código necesarios para empaquetar y probar una Habilidad. Consulta [Ejecución de código](/es/v1.58/user-manual/tools/code-execution).

## Crear una Habilidad en el editor

Elige **Skills > New Skill > Create from editor**. Completa el nombre, la descripción y **Skill Instructions**, y guarda los cambios. Usa esta opción si ya sabes qué instrucciones quieres que siga el asistente.

## Subir un archivo de Habilidad

1. Abre tu proyecto y ve a la pestaña **Skills** en el menú lateral.
2. Haz clic en **New Skill** y elige **Upload from your device**.
3. Arrastra un archivo de Habilidad a la zona de carga (un archivo `.zip`, `.skill` o `SKILL.md`), o haz clic en **Add Files** para explorar tu dispositivo.
4. Revisa el nombre y la descripción que Zylon detectó a partir del archivo.
5. Haz clic en **Install**.

![Eligiendo cómo crear una nueva Habilidad](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/new-skill-dropdown.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=e68ff7338c2403dc16cc976005c68430)

Tu nueva Habilidad aparece ahora en la lista de Habilidades del proyecto y está lista para usarse en el chat.

> [!WARNING]
>
> Sube únicamente Habilidades de fuentes en las que confíes — las instrucciones de una Habilidad se ejecutan automáticamente cada vez que alguien la usa.

> [!NOTE]
>
> ¿Necesitas una Habilidad que todo el mundo en la organización pueda reutilizar, no solo este proyecto? Pide a un administrador que la publique desde [Gestionar las Habilidades de la Organización](/es/v1.58/user-manual/managing-organization-skills), y luego [instálala](/es/v1.58/user-manual/skills/installing-from-organization) en cualquier proyecto que la necesite.


# Instalar una Habilidad de la organización
Source: https://docs.zylon.ai/es/v1.58/user-manual/skills/installing-from-organization

Reutiliza una Habilidad que tu administrador ya publicó, sin construirla tú mismo.

Si el administrador de tu organización ha publicado Habilidades a nivel de organización, puedes añadir cualquiera de ellas a tu proyecto en un par de clics — sin necesidad de recrearla desde cero.

## Pasos

1. Abre tu proyecto y ve a la pestaña **Skills** en el menú lateral.
2. Haz clic en **New Skill** y elige **Install from organization**.
3. Explora la lista de Habilidades publicadas por tu administrador.
4. Haz clic en **Install** junto a la que quieras.

![Explorando e instalando una Habilidad desde la biblioteca de la organización](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/install-from-org-dialog.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=c0244b0d4bf171eafd310d7062bcda70)

La Habilidad aparece ahora en la lista de Habilidades de tu proyecto, junto a cualquier Habilidad creada directamente en el proyecto, y está lista para usarse en el chat.

> [!NOTE]
>
> Una Habilidad de la organización instalada se comparte, no se copia — si tu administrador la actualiza o la elimina, ese cambio se aplica en todos los lugares donde esté instalada.


# Introducción a las Habilidades
Source: https://docs.zylon.ai/es/v1.58/user-manual/skills/introduction-to-skills

Qué es una Habilidad y cuándo usar una en lugar de simplemente preguntar en el chat.

Una **Habilidad** es un paquete de instrucciones listo para usar por el asistente de Zylon. En lugar de volver a explicar cómo quieres que se haga una tarea cada vez — "dale este formato", "incluye siempre estas secciones", "sigue esta lista de comprobación" — tú (o tu administrador) la escribís una vez como Habilidad, y luego cualquiera con acceso puede activarla en el chat con un clic.

Piensa en ella como una receta repetible: una Habilidad llamada `xlsx`, por ejemplo, puede indicarle a Zylon exactamente cómo limpiar, crear o corregir una hoja de cálculo cada vez que trabajes con una.

***

## Dónde viven las Habilidades

Las Habilidades existen en dos niveles:

* **Habilidades de la organización** — publicadas por un administrador desde el panel de administración, y disponibles para añadirse a cualquier proyecto. Consulta [Gestionar las Habilidades de la Organización](/es/v1.58/user-manual/managing-organization-skills).
* **Habilidades del proyecto** — creadas directamente dentro de un único proyecto, o instaladas allí desde la biblioteca de la organización. Visibles desde la pestaña **Skills** en el menú lateral de tu proyecto.

![La página de Habilidades de un proyecto con las Habilidades disponibles](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/project-skills-list.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=e828636a6b5a7bc4cccb7f90fcb50827)

***

## Qué puedes hacer con las Habilidades

* **[Crea una Habilidad](/es/v1.58/user-manual/skills/creating-a-skill)** con el chat, el editor o un archivo de Habilidad. Para crearla con el chat, instala primero **Skill Creator** en tu proyecto.
* **[Instalar una Habilidad de la organización](/es/v1.58/user-manual/skills/installing-from-organization)** en tu proyecto sin construir nada tú mismo.
* **[Usar una Habilidad en el chat](/es/v1.58/user-manual/skills/using-skills-in-chat)** seleccionándola desde la caja de mensajes, o hacer que se aplique automáticamente a cada chat nuevo.

> [!NOTE]
>
> Solo los administradores y editores de proyecto pueden añadir o eliminar Habilidades. Los usuarios con permiso de solo lectura pueden seguir usando cualquier Habilidad ya disponible en el proyecto.


# Usar una Habilidad en el chat
Source: https://docs.zylon.ai/es/v1.58/user-manual/skills/using-skills-in-chat

Aplica una Habilidad a una conversación, o haz que se active automáticamente.

Una vez que una Habilidad está disponible en tu proyecto, puedes incorporarla a cualquier conversación desde la caja de mensajes del chat.

## Pasos

1. Empieza a escribir en la caja de mensajes y haz clic en el botón **+**.
2. Selecciona **Skills**.
3. Elige una o varias Habilidades de la lista.

![La opción Skills dentro del menú de la caja de mensajes del chat](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/chat-plus-menu.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=af1d07cef93936373ce4cf4cae168fc6)

![Eligiendo una Habilidad de la lista del proyecto](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/chat-skills-submenu.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=9fbeaed5df28a1757564758de1d22313)

Las Habilidades seleccionadas aparecen como chips encima de la caja de mensajes. Haz clic en la **×** de un chip para quitarla antes de enviar.

![Una Habilidad seleccionada y lista para usar en un mensaje de chat](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/skills/chat-skill-selected.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=cc4388305dab72391f6e7e95b5ce0777)

***

## Activar una Habilidad por defecto

Si una Habilidad debe aplicarse a cada chat nuevo de un proyecto — sin tener que seleccionarla manualmente cada vez — un administrador del proyecto puede activar **Enable on chat by default** para ella desde la página **Skills** del proyecto.

> [!NOTE]
>
> Puedes seleccionar más de una Habilidad en el mismo mensaje. Zylon las usa todas juntas para dar forma a su respuesta.


# Adjuntar archivos en el chat
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/attachments

Suelta imágenes y documentos directamente en un mensaje de chat para que Zylon pueda leerlos y usarlos.

Adjunta archivos directamente a tus mensajes de chat — imágenes, hojas de cálculo, PDF, documentos de Word, presentaciones y más — para que Zylon pueda leerlos y usarlos como contexto al responder.

> [!WARNING]
>
> Pide a tu administrador de TI que habilite los archivos adjuntos en la configuración del sistema [con el Manual del operador](/es/v1.58/operator-manual/configuration/features/overview) si no ves esta opción.

***

## Qué puedes hacer con los archivos adjuntos

* Hacer preguntas sobre un documento, hoja de cálculo o imagen que acabas de adjuntar
* Obtener un resumen, explicación o análisis de su contenido
* Usar un archivo como contexto para resolver problemas o tomar decisiones
* Adjuntar más de un archivo al mismo mensaje
* Combinar los archivos adjuntos con un prompt de texto para instrucciones más precisas

***

## Cómo adjuntar un archivo

Hay dos formas de adjuntar un archivo a un mensaje:

1. Haz clic en el botón **+** de la caja de chat, elige **Add images & files** y selecciona uno o varios archivos desde tu dispositivo.
2. O simplemente **arrastra y suelta** los archivos directamente sobre la caja de chat.

![La opción Add images & files en la caja de mensajes del chat](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/attachments/chat-plus-menu.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=5a76007ad35249a3bd67b879656b047e)

Una vez adjuntado, cada archivo aparece como un chip encima de la caja de mensajes — añade tu pregunta o instrucciones y envía.

![Un archivo adjuntado y listo para enviar con un mensaje de chat](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/attachments/chat-attachment-chip.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=83bb3522bdb76c8e8d33a2e72059a673)

Tu mensaje conserva el archivo adjunto junto a él en la conversación, así que siempre puedes ver qué estaba viendo Zylon.

![Un mensaje de chat enviado mostrando el archivo adjunto](https://mintcdn.com/zylon/HVCbakIYBmuFT72i/images/user-manual/attachments/chat-message-with-attachment.png?fit=max\&auto=format\&n=HVCbakIYBmuFT72i\&q=85\&s=017efd0eef10c0e8b3e209076d7a888a)

***

## Tipos de archivo admitidos

* **Imágenes** — JPG, PNG, GIF, WebP, SVG, BMP
* **Documentos** — PDF, Word, PowerPoint, Excel, CSV/TSV, texto plano, HTML, RTF, ODT, EPUB, correo de Outlook (`.msg`, `.eml`)

> [!NOTE]
>
> Los tipos de archivo exactos y cuántos archivos puedes adjuntar dependen de cómo tu administrador haya configurado Zylon para tu organización.

***

## Limitaciones

* El número de archivos por mensaje y el tamaño máximo de archivo los establece tu administrador, y pueden variar según el tipo de archivo.
* Si un archivo es más grande de lo habitual, Zylon te avisa antes de continuar — puedes enviarlo igualmente, o añadirlo a la Base de Conocimiento del proyecto, que gestiona mejor los archivos grandes.
* La comprensión de una imagen depende de su claridad y resolución; los archivos muy grandes o complejos pueden producir resultados menos detallados.
* El modelo de IA seleccionado por tu organización debe admitir el tipo de archivo que estás adjuntando (por ejemplo, comprensión de imágenes).


# Ejecución de código
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/code-execution

Deja que Zylon ejecute código para analizar datos, transformar archivos y crear documentos, gráficos y hojas de cálculo.

> [!NOTE]
>
> La ejecución de código está **habilitada por defecto en los despliegues estándar de Zylon 1.58**. Si tu operador la desactiva en el Workspace, puedes seguir chateando y usando las demás herramientas disponibles, pero el asistente no puede ejecutar código ni completar los pasos de una Skill que lo requieran. Si no está disponible, pide a tu administrador de TI que revise la [configuración de Ejecución de código](/es/v1.58/operator-manual/configuration/features/feat-code-execution).

Con **Ejecución de código**, Zylon puede escribir y ejecutar código en un entorno privado y aislado (un **sandbox**) para trabajar con tus archivos. En lugar de estimar una respuesta, Zylon la calcula, comprueba el resultado y te entrega los archivos que ha generado.

## Qué obtienes

* **Cálculos exactos** sobre tus datos, en lugar de aproximaciones.
* **Archivos nuevos** que puedes previsualizar y descargar: hojas de cálculo, gráficos, informes y documentos convertidos.
* **Trabajo en varios pasos**: Zylon puede ejecutar código, revisar el resultado, corregir errores y volver a intentarlo hasta dar con la solución.

## Cuándo usarla

* "Analiza esta hoja de cálculo y dime qué región ha crecido más."
* "Representa los ingresos mensuales de este CSV en un gráfico de líneas."
* "Combina estos dos archivos de Excel y elimina los clientes duplicados."
* "Convierte esta exportación JSON en una tabla limpia que pueda abrir en Excel."
* "Calcula el cuadro de amortización del préstamo con estas condiciones y dámelo en una hoja de cálculo."

Para preguntas sencillas, conversación o redacción, Zylon responde directamente sin ejecutar código. Si quieres que Zylon calcule o verifique algo, pídelo explícitamente (por ejemplo, "ejecuta código para comprobarlo").

## Cómo funciona

1. **Adjunta tus archivos** al chat, o haz referencia a documentos de tu proyecto.
2. **Pide** lo que necesites. Zylon escribe el código, lo ejecuta en el sandbox y lee los resultados.
3. **Obtén tus archivos.** Cuando Zylon crea un archivo, aparece en el chat y se guarda en tu proyecto, para que puedas previsualizarlo, descargarlo o reutilizarlo más adelante.

Cada chat tiene su **propio sandbox**:

* Los archivos que subes y los que crea Zylon siguen disponibles durante todo el chat, así que puedes seguir haciendo preguntas de seguimiento ("ahora agrúpalo por trimestre").
* Otros chats, y otros usuarios, no pueden ver los archivos del sandbox de tu chat.

## Archivos compatibles

Zylon puede trabajar con la mayoría de formatos habituales, entre ellos:

* Hojas de cálculo y datos: CSV, Excel (`.xlsx`, `.xls`), JSON, XML
* Documentos: PDF, Word (`.docx`), PowerPoint (`.pptx`), texto y Markdown
* Imágenes: PNG, JPEG, GIF, WebP
* Archivos comprimidos: ZIP, 7z, RAR

## Notas y buenas prácticas

* **Indica las columnas o campos** que te interesan. Zylon solo conoce la estructura de los datos después de examinar el archivo.
* **Di qué resultado quieres**: "un gráfico de barras en PNG", "un archivo de Excel con una hoja por región", "una tabla resumen breve".
* **Itera en el mismo chat.** Tus archivos siguen ahí, así que las pequeñas preguntas de seguimiento son rápidas.
* **El sandbox no tiene acceso a internet.** Si necesitas información de la web, combínalo con [Búsqueda web](/es/v1.58/user-manual/tools/web-search).
* **Las descargas dependen de la configuración de tu organización.** Si puedes previsualizar un archivo pero no descargarlo, consulta a tu administrador.


# Conector de base de datos
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/database-connector



El Conector de base de datos te permite conectar de forma segura una base de datos compartida a un **Proyecto**, haciendo que sus datos estén disponibles para todos los miembros del proyecto a través del chat.

> **Cambio importante**: Los conectores de base de datos ya no se añaden directamente dentro de un chat. Ahora son **conectores compartidos a nivel de proyecto**, gestionados desde la barra lateral del proyecto.

> [!WARNING]
>
> Pide a tu administrador de TI que habilite el Conector de base de datos en la configuración del sistema [con el Manual del operador](/es/v1.58/operator-manual/configuration/features/overview).

***

## Crear un conector de base de datos

Para crear un conector de base de datos:

1. Abre tu **Barra lateral del proyecto**
2. Haz clic en **Conectores**
3. Haz clic en **Crear conector**
4. Selecciona **Base de datos**
5. Introduce los **detalles de conexión** requeridos
6. Establece la conexión

Una vez que la conexión sea exitosa, estarán disponibles opciones de configuración adicionales.

[Zylon Workspace - Creating Database Server Connector](https://www.youtube.com/embed/SbGSwFeFqAY)

***

### Cadenas de conexión simplificadas

Una cadena de conexión es como una dirección que le dice al sistema dónde encontrar tu base de datos y cómo acceder a ella. Tu equipo de TI puede ayudarte a construir la cadena de conexión correcta para tu base de datos.

#### Tipos de base de datos admitidos

* Microsoft SQL Server
* PostgreSQL
* MySQL
* DB2

#### Cadena de conexión

> [!WARNING]
>
> **Notas de seguridad**:
>
> * Nunca compartas tus cadenas de conexión con otros
> * Usa solo las bases de datos que tu equipo de TI ha aprobado
> * Asegúrate de que el usuario sea de solo lectura

Esto es lo que significa cada parte (pide a tu equipo de TI los valores correctos):

```
SQL Server: mssql+pyodbc://username:password@server:1433/database
PostgreSQL: postgresql://username:password@server:5432/database
MySQL: mysql+mysqldb://username:password@server:3306/database
DB2: db2+ibm_db://username:password@server:50000/database
```

**Examples**

```sql Microsoft SQL Server theme={null}
mssql+pyodbc://sa:password123@server.company.com:1433/SalesDatabase

mssql+pyodbc://dbuser:mypassword@192.168.1.50:1433/CustomerData

mssql+pyodbc://localhost:1433/TestDB?TrustServerCertificate=yes
```

```sql PostgreSQL theme={null}
postgresql://postgres:admin123@database.company.com:5432/company_data

postgresql://user:password@10.0.0.25:5432/sales_db

postgresql://localhost:5432/public_data
```

```sql MySQL theme={null}
mysql+mysqldb://root:password@mysql.company.com:3306/customer_info

mysql+mysqldb://appuser:secret123@127.0.0.1:3306/inventory

mysql+mysqldb://localhost:3306/reports
```

```sql DB2 theme={null}
db2+ibm_db://db2admin:password123@db2server.company.com:50000/SALESDB

db2+ibm_db://dbuser:mypassword@192.168.1.50:50000/PRODDATA

db2+ibm_db://localhost:50000/TESTDB
```

Recuerda: Reemplaza `username`, `password`, `server` y `database` con tus valores reales.

## Configuración avanzada

Después de que se haya establecido la conexión de la base de datos, puedes configurar parámetros avanzados para controlar cómo se usa la base de datos.

### Restricciones de tabla y esquema

Puedes limitar el acceso del conector a:

* **Esquemas** específicos
* **Tablas** específicas

Esto ayuda a:

* Reducir la exposición innecesaria de datos
* Mejorar la precisión de las consultas
* Evitar que el LLM consulte datos irrelevantes

### Descripción del conector

Puedes definir una **descripción** para el conector de base de datos.
Esta descripción se proporciona al LLM y debe explicar:

* Qué contiene la base de datos
* Cómo están estructurados los datos
* Cualquier regla o convención importante

Una buena descripción mejora significativamente la calidad de las consultas generadas por el LLM.

***

## Usar el conector de base de datos en el chat

Una vez creado, el conector de base de datos se puede usar en chats:

1. Abre o crea un chat dentro del proyecto
2. Usa el **selector de conectores** en la entrada del chat
3. Habilita el conector de base de datos

Cuando está habilitado, el LLM puede consultar la base de datos como parte de la conversación.

[Zylon Workspace - Using connectors](https://www.youtube.com/embed/me9j6soj6gQ)

***

## Conectores preseleccionados

Los administradores del proyecto pueden configurar los conectores de base de datos para que estén **preseleccionados para cada chat nuevo** en el proyecto.

Esto es especialmente útil cuando:

* La base de datos es una parte central del flujo de trabajo del proyecto
* Los usuarios no técnicos necesitan acceso a MCPs o bases de datos sin tener que lidiar con configuración compleja
* Se requiere acceso consistente a datos en todas las conversaciones

***

## Uso personal y privado

Si un usuario quiere configurar sus **propios conectores de base de datos** sin compartirlos:

1. Crea un **proyecto privado**
2. Crea conectores de base de datos usando el mismo proceso
3. Úsalos exclusivamente dentro de ese proyecto privado

Los proyectos privados permiten experimentación o integraciones personales sin afectar entornos compartidos.

***

## Requisitos y consideraciones

* La base de datos debe ser accesible desde el entorno del conector
* El acceso de red, firewalls y listas de permitidos de IP pueden necesitar configuración
* Las consultas generadas por el LLM respetan el alcance configurado del conector

***

## Seguridad

* Las credenciales se almacenan de forma segura
* El LLM solo puede acceder a datos permitidos por la configuración del conector
* Las restricciones de esquema y tabla se aplican en el momento de la consulta

***

## Solución de problemas de conectividad con bases de datos

Si tu conector de base de datos se queda cargando indefinidamente o da timeout, verifica la conectividad de red desde la máquina donde está instalado Zylon.

### Probar la conexión

Ejecuta este comando desde la máquina donde está instalado Zylon:

```bash theme={null}
curl -v telnet://tu-servidor-db:puerto
```

### Interpretar resultados

**Conexión exitosa:**

```
* Connected to tu-servidor-db (xxx.xxx.xxx.xxx) port xxxx
```

La conectividad de red funciona correctamente. Si los problemas persisten, contacta a soporte.

**Timeout de conexión:**

```
* Failed to connect to tu-servidor-db port xxxx: Operation timed out
```

Problema de red detectado. Revisa reglas de firewall, security groups y listas de permitidos de IP.

**Conexión rechazada:**

```
* Connection refused
```

El servidor de base de datos no está escuchando en ese puerto. Verifica que la base de datos esté en ejecución y configurada para aceptar conexiones externas.

### Causas comunes

* Firewall bloqueando tráfico saliente desde el host de Zylon
* Security groups/ACLs bloqueando el puerto de la base de datos
* Hostname o puerto incorrecto
* Base de datos no aceptando conexiones desde la IP de Zylon

***


# Pensamiento extendido
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/extended-thinking

Habilita razonamiento más profundo paso a paso para respuestas más ricas.

Activa **Pensamiento extendido** cuando quieras que el modelo **reflexione antes de responder**. Verás un rastro de "pensamiento" mientras planifica y critica su propio enfoque.

* Bueno para prompts abiertos (redactar correos, planificar, decisiones multicriterio).
* Particularmente útil para razonamiento **matemático/cuantitativo**.
* Se puede combinar con otras herramientas como **Análisis numérico**.

> El pensamiento extendido puede tardar más que una respuesta directa porque realiza una planificación deliberada primero.


# Usar herramientas — resumen
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/introduction-to-tools

Las herramientas amplían el agente de chat para razonamiento más profundo y análisis de datos.

El chat puede usar herramientas para mejorar la calidad y gestionar tareas de datos:

* **Pensamiento extendido** — permite al modelo pensar antes de responder; útil para problemas abiertos o de varios pasos.
* **Análisis numérico** — ejecuta consultas tipo SQL y gráficos contra un **único CSV** de tu base de conocimiento.
* **Obtener URL** — pega una **URL** web y el asistente obtendrá y usará el contenido de esa página para la respuesta.

> Puedes habilitar **múltiples herramientas juntas** (p. ej., Pensamiento extendido + Análisis numérico) cuando sea apropiado.


# Conector MCP
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/mcp-connector



El Conector MCP (Protocolo de contexto de modelo) te permite integrar servidores MCP externos en un **Proyecto**, exponiendo sus herramientas al LLM de forma controlada y compartible.

> **Cambio importante**: Los conectores MCP ya no se añaden directamente dentro de chats. Ahora son **conectores compartidos a nivel de proyecto**.

> [!WARNING]
>
> Pide a tu administrador de TI que habilite el Conector MCP en la configuración del sistema [con el Manual del operador](/es/v1.58/operator-manual/configuration/features/overview).

***

## Crear un conector MCP

Para crear un conector MCP:

1. Abre tu **Barra lateral del proyecto**
2. Haz clic en **Conectores**
3. Haz clic en **Crear conector**
4. Selecciona **MCP**
5. Configura los **detalles de conexión MCP**
6. Habilita el **Bearer Auth** y añade tu token si tu MCP lo requiere
7. Establece la conexión

Una vez que la conexión sea exitosa, puedes configurar qué herramientas MCP están disponibles.

[Zylon Workspace - Creating MCP Connector](https://www.youtube.com/embed/bycnajstmu8)

***

## Selección de herramientas

Después de que se establezca la conexión MCP, debes seleccionar las herramientas que el conector expondrá.

### Por qué importa la selección de herramientas

* Limita lo que el LLM puede invocar
* Reduce ruido y comportamiento no deseado
* Mejora la confiabilidad y seguridad

Puedes:

* Habilitar o deshabilitar herramientas individuales
* Actualizar la selección de herramientas más tarde sin recrear el conector

Solo las herramientas seleccionadas estarán disponibles cuando se use el conector en un chat.

***

## Usar el conector MCP en el chat

Una vez creados, los conectores MCP se pueden usar en chats:

1. Abre o crea un chat dentro del proyecto
2. Usa el **selector de conectores** en la entrada del chat
3. Habilita el conector MCP

El LLM podrá entonces invocar las herramientas MCP seleccionadas durante la conversación.

[Zylon Workspace - Using connectors](https://www.youtube.com/embed/me9j6soj6gQ)

***

## Conectores preseleccionados

Los administradores del proyecto pueden configurar los conectores MCP para que estén **habilitados automáticamente para cada chat nuevo** en el proyecto.

Esto se recomienda cuando:

* Las herramientas MCP son una parte estándar del flujo de trabajo
* Los usuarios no deben gestionar manualmente la selección de herramientas
* El proyecto depende de la disponibilidad consistente de herramientas

***

## MCPs personales y privados

Si un usuario quiere añadir o experimentar con **conectores MCP personales**:

1. Crea un **proyecto privado**
2. Crea conectores MCP usando el mismo flujo de creación
3. Usa esos conectores solo dentro de ese proyecto

Esto permite experimentación segura sin afectar proyectos compartidos.

***

## Requisitos y consideraciones

* El servidor MCP debe ser accesible desde el entorno del conector
* Solo se admiten herramientas compatibles con MCP
* Los permisos de herramientas se aplican según la configuración del conector

***

## Seguridad

* Solo las herramientas seleccionadas se exponen al LLM
* Los conectores MCP no otorgan acceso sin restricciones
* La disponibilidad de herramientas se controla a nivel del conector


# Análisis numérico
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/numeric-analysis

Analiza un CSV de tu base de conocimiento con consultas en lenguaje natural.

Usa **Análisis numérico** para analizar un **único CSV** almacenado en la base de conocimiento de tu proyecto.

**Cómo funciona**

* Seleccionas el archivo CSV a analizar.
* Activas la herramienta **Análisis numérico**.
* Tu prompt en lenguaje natural se traduce a una **consulta SQL** y se ejecuta contra el CSV **como si fuera una base de datos**.
* Los resultados se renderizan como **tablas o gráficos**.

**Consejos**

* El CSV debe estar **bien formado** (una sola fila de encabezado; sin fórmulas ni múltiples hojas).
* Pide **tablas** o **gráficos** específicos (barras, líneas, mapa de calor, etc.).
* Sé lo más explícito posible respecto a los **nombres de columnas a usar**. El agente no conoce tu estructura de datos.
* Mantén las consultas basadas en los datos presentes; los **factores externos** no se infieren a menos que se proporcionen como documentos o mediante una URL obtenida en el mismo chat.

> Puedes usar **Pensamiento extendido + Análisis numérico** juntos para análisis de varios pasos.


# Búsqueda web
Source: https://docs.zylon.ai/es/v1.58/user-manual/tools/web-search

Navega por internet para encontrar información actualizada.

> [!WARNING]
>
> Pide a tu administrador de TI que habilite la herramienta de búsqueda web en la configuración del sistema [con el Manual del operador](/es/v1.58/operator-manual/configuration/features/overview).

Habilita **Búsqueda web** cuando quieras que Zylon **busque cosas en línea** en lugar de depender solo de lo que ya sabe. Cuando está activada, Zylon puede **abrir páginas web** y usar información de internet para elaborar una respuesta.

Esto es ideal para cualquier cosa que cambie a menudo (nuevas versiones, precios, regulaciones, especificaciones de productos, puntos de referencia, eventos actuales, etc.).

[Zylon Workspace - Using Web Search tool](https://www.youtube.com/embed/f9rhjC-N9Uk)

## Lo que obtienes

* **Respuestas actualizadas** basadas en contenido web en vivo
* **Enlaces y referencias de fuentes** para que puedas verificar de dónde viene la información
* Mejores resultados para consultas que requieren **contexto fresco** o **detalles específicos** (fechas, números de versión, cambios de políticas)

## Cuándo usarla

* "¿Qué cambió en X recientemente?"
* "¿Cuál es la última versión de Y y cuáles son los cambios importantes?"
* "Encuentra la documentación oficial de Z y resume los pasos de configuración."
* "Compara estos productos usando especificaciones y precios actuales."

## Cómo aparece en el chat

Cuando la búsqueda web está habilitada, la verás disponible en la entrada del chat (junto con otras opciones como fuentes de conocimiento y conectores). Una vez habilitada para la conversación, Zylon puede buscar en la web e incluir fuentes útiles en su respuesta.

## Notas y mejores prácticas

* Prefiere **prompts específicos** (qué quieres comparar, qué región, qué período de tiempo).
* Pide **fuentes** cuando la precisión importa ("incluye enlaces" / "cita tus fuentes").
* Los resultados web pueden variar en calidad—Zylon priorizará fuentes reputables cuando sea posible, pero aún debes verificar detalles críticos.


# Subir archivos
Source: https://docs.zylon.ai/es/v1.58/user-manual/uploading-files

Añade conocimiento a un proyecto subiendo archivos locales o importando desde un conector.

Cada proyecto tiene su **propia base de conocimiento**. Puedes poblarla mediante:

* **Subir archivos desde tu dispositivo.** Arrastra y suelta o selecciona archivos. Las subidas locales son **estáticas**—vuelve a subir si la fuente cambia.
* **Importar mediante un conector (p. ej., SharePoint).** Puedes seleccionar **archivos o carpetas completas** a las que tengas acceso. Se muestra el progreso de ingesta.

[Zylon Workspace - Upload files](https://www.youtube.com/embed/vb4fzWUNRKo)

> **Combina fuentes:** Está bien mezclar subidas locales e importaciones de conectores en el mismo proyecto.


# ¿Qué es Zylon Workspace?
Source: https://docs.zylon.ai/es/v1.58/user-manual/what-is-zylon-workspace

Descubre el espacio de trabajo colaborativo de IA de Zylon y cómo transforma el conocimiento de la empresa en productividad

Zylon es una plataforma de IA empresarial que ofrece IA generativa privada y software de IA en local para sectores regulados, permitiendo un despliegue seguro dentro de la infraestructura de la empresa sin dependencias de nubes externas. Zylon Workspace es la interfaz colaborativa de IA donde tu equipo trabaja con inteligencia artificial a diario. Está diseñado para reemplazar ChatGPT o Claude con una solución segura y en local.

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_general.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=33b2b072bd0084fc07b225d090ec4a4d)

## Componentes principales

**Proyectos**
Organiza tu trabajo de IA por tema, equipo o caso de uso. Cada proyecto tiene su propia base de conocimiento y configuraciones personalizadas.

**Búsqueda**
Encuentra documentos usando cualquier frase o palabra clave que recuerdes, no solo títulos. Zylon busca en todo el contenido de la base de conocimiento de tu empresa y presenta los documentos coincidentes.

**Asistente de chat**
Haz preguntas y obtén respuestas de los documentos de tu empresa. Incluye citas y herramientas integradas para análisis.

**Documentos IA**
Flujos de trabajo automatizados que gestionan tareas complejas como el resumen de documentos y preguntas y respuestas masivas en segundo plano.

## Beneficios clave

* **Uso ilimitado** - Sin límites de tokens ni costes por consulta
* **Privacidad completa** - Tus datos nunca salen de tu infraestructura
* **Comportamiento personalizado** - Adapta las respuestas de IA para diferentes casos de uso
* **Colaboración en equipo** - Comparte proyectos y trabajad juntos en tareas de IA

## Empezar

1. **[Preguntas frecuentes del primer día](/es/v1.58/user-manual/first-day-faqs)** - Respuestas rápidas a preguntas comunes
2. **[Guía de inicio rápido](/es/v1.58/user-manual/quick-start-guide)** - Completa tus primeras tareas en 15 minutos
3. **[Trabajar en proyectos](/es/v1.58/user-manual/what-is-zylon-workspace)** - Aprende los conceptos básicos de organización de proyectos

> [!NOTE]
>
> Verifica siempre las respuestas de IA usando las citas proporcionadas, especialmente para decisiones críticas para el negocio.


# Cuándo usar documentos IA
Source: https://docs.zylon.ai/es/v1.58/user-manual/when-to-use-agent-flows

Usa documentos IA para trabajo documental exhaustivo que va más allá de respuestas rápidas de chat.

Usa **documentos IA** en lugar de chat cuando necesites **procesamiento exhaustivo**:

* **Archivos grandes / cobertura completa del documento** (p. ej., RFPs de 300 páginas).
* Operaciones por lotes (haz muchas preguntas a la vez).
* Redacción de documentos más largos a partir de múltiples fuentes.
* Extracción estructurada a gran escala.

Los documentos IA **se ejecutan en segundo plano**, por lo que no están optimizados para respuestas rápidas y parciales—**procesan todo lo necesario de la base de conocimiento** para producir resultados completos.

El resultado es un documento editable que se puede exportar como PDF o documento de Word para su posterior edición.


# Cuándo usar el asistente de chat
Source: https://docs.zylon.ai/es/v1.58/user-manual/when-to-use-chat-assistant

Haz preguntas directas o úsalo como compañero de pensamiento para tareas abiertas.

Usa el chat para dos patrones:

1. **Preguntas y respuestas directas sobre tu base de conocimiento** — cuando sabes que la respuesta debería estar en los documentos de tu proyecto. Las respuestas incluyen **citas en línea** a pasajes exactos de la fuente.
2. **Trabajo abierto como "compañero de pensamiento"** — habilita **Pensamiento extendido** para razonamiento más profundo (p. ej., redactar respuestas, planificar reuniones o tareas de varios pasos).

[Zylon Workspace - Ask Chat](https://www.youtube.com/embed/KUw9oc3fZCw)

> Puedes **limitar** un chat a la **base de conocimiento completa** o a una **carpeta** o **archivo específico** para ayudar al modelo a enfocarse.


# Aspecto del espacio de trabajo
Source: https://docs.zylon.ai/es/v1.58/user-manual/workspace-look-and-feel

Personaliza la marca y apariencia de Zylon Workspace para tu organización

Como administrador, puedes personalizar Zylon Workspace para que coincida con la marca y preferencias de tu organización. Zylon es una solución completamente de marca blanca.

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_white_label.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=008e429c61564f0c585a0907f41238a2)

## Opciones de personalización

**Marca de la empresa**

* **Nombre del espacio de trabajo**: Elige el nombre del espacio de trabajo (p. ej., "Acme GPT")
* **Logo de la empresa**: Sube el logo de tu organización para la interfaz
* **Nombre del asistente de IA**: Durante la instalación, también puedes elegir cómo llamar a tu IA (p. ej., "Asistente Acme", "CompanyBot").
  Consulta el Manual del operador para aprender cómo hacerlo.

## Acceder a la configuración de personalización

> [!WARNING]
>
> Solo los usuarios con privilegios de Administrador pueden modificar la apariencia del espacio de trabajo. Contacta con tu equipo de TI si necesitas estos permisos.

1. **Haz clic en el nombre del espacio de trabajo** en la parte superior derecha
2. **Selecciona la sección "Configuración"**
3. **Haz tus cambios** al nombre del espacio de trabajo y al logo
4. **Guarda y aplica** los cambios a nivel de organización

![](https://mintcdn.com/zylon/mIL8Q5kyLQ_jxoci/images/user-manual/workspace_admin_settings.png?fit=max\&auto=format\&n=mIL8Q5kyLQ_jxoci\&q=85\&s=ef98844a03b272e4422d0f1abcc78e08)


# Registro de cambios
Source: https://docs.zylon.ai/es/v1.58/changelog/overview



**1.58.0**

22 de octubre de 2026

> [!CAUTION]
>
> **⚠️ Acción requerida antes de actualizar a la versión 1.58.X**
>
> Usa Zylon CLI **2.9.0 o posterior**. Cuando termine la instalación y todos los pods estén listos, previsualiza el backfill de Skills y Documentos con `backfill-projections --dry-run`, ejecuta el backfill y después aplica `configure --max-pods 200`. Cambiar el límite de pods interrumpe brevemente todos los servicios de Zylon. Sigue la [guía de actualización a 1.58](/es/v1.58/changelog/guides/1-58-0) completa.
>
> **Los cambios incompatibles en la API requieren migrar las integraciones afectadas.** Han cambiado las rutas y los cuerpos de contenido de artefactos, y los mensajes de Workspace y ZylonGPT usan nuevos bloques de respuesta de herramientas del servidor. Los campos de creador identifican ahora **cuentas**; las operaciones de pertenencia siguen usando **IDs de miembros del workspace**. Migra las llamadas afectadas y actualiza los mapas de IDs guardados aunque las URLs legacy sigan funcionando. Revisa la [guía de migración de API de 1.57 a 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58).

## 💼 Workspace

### ✨ Novedades

* **Ejecución de código — Beta**: Ejecuta código en un entorno aislado para analizar archivos, realizar cálculos y generar hojas de cálculo, gráficos e informes. Está habilitada por defecto en los despliegues estándar de 1.58. Si un operador la desactiva en Workspace, el chat y las demás herramientas disponibles siguen funcionando, pero el asistente no puede ejecutar código ni completar los pasos de una Skill que lo requieran. Consulta [Ejecución de código](/es/v1.58/user-manual/tools/code-execution) y la [configuración del operador](/es/v1.58/operator-manual/configuration/features/feat-code-execution#cuando-está-desactivada).
* **Creador y editor de Skills**: Crea Skills reutilizables con el chat, edita sus instrucciones y archivos de apoyo, y reutiliza paquetes de Skills compatibles con Anthropic. Para crear una con el chat, instala primero **Skill Creator** desde la biblioteca de tu organización en tu proyecto y elige **Skills > New Skill > Create with Chat**. Sigue la [guía paso a paso](/es/v1.58/user-manual/skills/creating-a-skill), que también explica cómo instalar y usar la Skill generada.
* **Archivos generados en Documentos AI**: Los archivos creados en el chat pueden guardarse en el proyecto, previsualizarse y descargarse desde Documentos AI.
* **Búsqueda en texto generado por IA**: Encuentra documentos de texto creados por el asistente buscando palabras de su contenido. Consulta [Buscar en el espacio de trabajo](/es/v1.58/user-manual/search-workspace-content).
* **Cronología de ejecución de herramientas**: Consulta pasos desplegables, descripciones, tiempo empleado, salida de comandos y errores.
* **Indicadores de chats sin leer**: Identifica en el menú lateral los chats que contienen respuestas del asistente sin leer.
* **Modo oscuro y preferencias compartidas**: Ampliado el soporte de temas en Workspace y Backoffice, con preferencias de cuenta compartidas entre ambos.

## 🛠️ Backoffice

### ✨ Novedades

* **Gestor de conectores**: Busca y consulta los conectores de las organizaciones, comprueba a qué proyecto pertenecen y quién los creó, y revoca sus credenciales sin eliminar los archivos importados.
* **System Monitor**: Consulta en directo el uso de CPU, RAM, disco, GPU y VRAM, además de las colas de modelos, solicitudes de inferencia activas y velocidad de generación de tokens. Requiere habilitar System Monitor. Consulta [System Monitor](/es/v1.58/operator-manual/backoffice/system-monitor).
* **Soporte de idiomas**: Añadidas preferencias de idioma en Backoffice y traducciones al español.
* **Cuotas y límites de uso**: Los operadores pueden configurar límites de solicitudes y tokens para cuentas y gateways, consultar el uso y reiniciar cuotas. Requiere la opción `features.quotas.enabled`, desactivada por defecto.

## 🔌 APIs para desarrolladores

### ✨ Novedades

* **APIs unificadas**: Consolidadas las rutas de artefactos y separados los perfiles de cuenta de las pertenencias al workspace. Las rutas legacy de artefactos, integraciones y miembros quedan obsoletas en 1.58, con eliminación prevista para 1.59. Consulta la [guía de migración de API](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) para los límites de compatibilidad y ejemplos.
* **Tokens de API de solo lectura**: Elige permisos de lectura o de lectura y escritura al crear tokens de Workspace y gateway. Consulta [gestión de tokens](/es/v1.58/developer-manual/get-started/token-management).
* **Respuestas de herramientas actualizadas**: Las herramientas integradas usan `server_tool_use` y bloques de resultado tipados. Las herramientas personalizadas mantienen su flujo de herramientas del cliente. Consulta los [ejemplos de migración](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#bloques-de-herramientas-de-servidor).
* **Filtros de la API de búsqueda**: Acota las búsquedas por tipo de recurso, proyectos incluidos o excluidos, tipo de artefacto y fecha de creación. Consulta la [API de búsqueda](/es/v1.58/developer-manual/build-with-zylon/workspace-api/general/search).

## 🛠️ Plataforma

### ✨ Novedades

* **Qwen3.8 en `baseline-96g`**: El preset ahora usa `nvidia/Qwen3.8-27B-NVFP4`. Descarga el nuevo modelo antes de actualizar o selecciona el preset de compatibilidad documentado para mantener el modelo anterior. Consulta la [guía de actualización a 1.58](/es/v1.58/changelog/guides/1-58-0) y los [presets de IA](/es/v1.58/operator-manual/ai-presets/presets).
* **Documentación offline**: Los operadores pueden servir la documentación incluida en el despliegue en `/docs` activando `zylonDocs.enabled`; está desactivada por defecto.
* **Verificación de artefactos**: Las descargas de la CLI se comprueban con los checksums de la versión.
* **Backup y restauración más seguros**: Las cargas de trabajo se detienen de forma ordenada antes de copiar o reemplazar los datos, y después se reanuda la programación. Consulta [backup y restauración](/es/v1.58/operator-manual/operations/backup).
* **n8n actualizado**: Actualizado el despliegue de n8n incluido a 2.39.9 y corregida la compatibilidad del ingress MCP.

### 🐛 Correcciones

* **Búsqueda de archivos más clara**: Los resultados muestran el proyecto desde el que puedes abrir cada archivo enlazado.
* **Sincronización más fluida**: Las carpetas conectadas se sincronizan de forma más fiable y los operadores pueden ajustar el límite de tamaño de los archivos importados.
* **Conexiones más fiables**: Mejoradas las comprobaciones de conexión de MCP y la renovación de credenciales durante las conversaciones.
* **Mejor gestión de archivos**: Mejor lectura de documentos, errores más claros si falta un archivo y descargas que respetan las políticas de tu organización.
* **Mejoras en el chat**: Las conversaciones usan el contexto del proyecto adecuado, respetan la desactivación de herramientas y reciben títulos automáticos más claros.
* **Gestión de Skills más sencilla**: Mensajes más claros sobre conflictos con nombres de Skills integradas. Las Skills existentes ya no impiden instalar las predeterminadas.

**1.57.0**

August 17, 2026

> [!CAUTION]
>
> **⚠️ Acción requerida antes de actualizar a la versión 1.57.X**
>
> Sigue la [guía de migración 1.57](/es/v1.58/changelog/guides/1-57-0) completa antes de actualizar.

## 💼 Workspace

### ✨ Novedades

* **Skills**: Enseña a tu agente de Zylon a realizar tareas complejas con paquetes de instrucciones ya preparados. [Más información](/es/v1.58/user-manual/skills/introduction-to-skills)
* **Skills de Organización**: Añade y gestiona Skills a nivel de organización, permitiendo un despliegue centralizado de skills en todos los workspaces. [Más información](/es/v1.58/user-manual/managing-organization-skills)
* **Integración con Google Drive**: Conecta tu Google Drive directamente a Zylon para un acceso y colaboración documental sin fricciones. [Más información](/es/v1.58/user-manual/connectors/google-drive)
* **Interfaz de Guardrails**: Interfaz visual para configurar y gestionar guardrails de IA, para interacciones más seguras y controladas. [Más información](/es/v1.58/operator-manual/backoffice/guardrails)
* **Frescura de Sesión**: Gestión de sesión mejorada con comprobaciones automáticas de frescura para mantener la estabilidad de la conexión.
* **Adjuntar documentos en el chat**: Arrastra imágenes y documentos directamente a un mensaje de chat para que Zylon pueda leerlos y usarlos como contexto. [Más información](/es/v1.58/user-manual/tools/attachments)
* **Bloqueo de descargas por configuración del administrador de la organización**: Los administradores pueden bloquear ahora las descargas de archivos subidos a la Base de conocimiento y de recursos generados por IA a nivel de organización.

## 🛠️ Plataforma

### ✨ Novedades

* **Monitor de Recursos**: Nueva API para monitorizar los recursos del sistema y las métricas de carga de trabajo de IA en tiempo real.
* **Soporte ARM64**: Soporte completo para despliegues en arquitectura ARM64.
* **Rendimiento mejorado**: Inferencia más rápida, mejor gestión de la concurrencia y una búsqueda web más eficiente.

**1.56.0**

June 17, 2026

## 💼 Workspace

### ✨ Novedades

* **Rediseño completo empresarial**: Workspace se ha rediseñado por completo con una nueva apariencia y experiencia orientada a entornos empresariales.
* **Rediseño de la Base de conocimiento**: La Base de conocimiento se ha rediseñado por completo para ser mucho más flexible.
  * Ahora puedes soltar carpetas completas desde tu sistema dentro de la Base de conocimiento.
  * Puedes navegar por carpetas con una interacción de doble clic al estilo macOS.
  * Puedes subir documentos o carpetas directamente dentro de una carpeta específica.
  * Puedes seleccionar varios documentos o carpetas y moverlos.
  * También se soporta menú contextual con clic derecho.
* **Agent Flows pasa a llamarse Documentos AI**: Agent Flows pasa a llamarse Documentos AI en todo el producto.
* **Mejor soporte para pantallas pequeñas**: Aunque Zylon no es una aplicación móvil, el nuevo rediseño mejora de forma notable la experiencia en pantallas más pequeñas.

## 🛠️ Backoffice

### ✨ Novedades

* **Panel de uso para consumo de tokens**: Backoffice incluye ahora un panel de uso para hacer seguimiento del consumo de tokens. Esta funcionalidad requiere tener el [registro de auditoría](/es/v1.58/operator-manual/configuration/features/feat-audit) habilitado.

## 🛠️ Plataforma

### ✨ Novedades

* **Logs de auditoría para flujos SIEM y seguridad**: Zylon ofrece ahora capacidades reforzadas de auditabilidad y logs de seguridad para integraciones SIEM y revisiones operativas. Consulta [Auditabilidad y gobernanza de IA](/es/v1.58/operator-manual/auditability-ai-safety/), [entrega y almacenamiento de logs](/es/v1.58/operator-manual/backoffice/log-delivery-storage) y [configuración de entrega de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage).
* **Controles de política de retención de logs**: Se añade soporte de política de retención para logs almacenados. Consulta la [configuración de hard delete](/es/v1.58/operator-manual/configuration/cron-tasks/hard-delete).
* **Soporte para Active Directory / LDAP**: Zylon soporta ahora integración con directorio corporativo mediante [Active Directory / LDAP](/es/v1.58/operator-manual/authentication/ldap).
* **Contraseña de un solo uso para root admin tras cada login por CLI**: El acceso de administrador root mediante CLI requiere ahora una contraseña de un solo uso después de cada inicio de sesión. Consulta la [configuración de CLI](/es/v1.58/operator-manual/configuration/cli).
* **Pipeline de extracción de PPTX basado en visión**: Se añade un nuevo pipeline para archivos PPTX que aprovecha modelos de visión para mejorar la precisión y la calidad de la extracción de información. Consulta [procesamiento visual de archivos](/es/v1.58/operator-manual/configuration/features/feat-file-vision).

### 🐛 Correcciones de errores

* Se corrigió un error que podía hacer que los MCP fallaran en un chat aunque no estuvieran seleccionados.
* **Mejor gestión de memoria en Web Search**: Se mejora la gestión de memoria en la [herramienta de Web Search](/es/v1.58/user-manual/tools/web-search).
* Se incluyen múltiples correcciones y mejoras de interfaz como parte del despliegue del rediseño.

**1.55.0**

April 15, 2026

> [!CAUTION]
>
> **⚠️ Acción requerida antes de actualizar a la versión 1.55.X**
>
> Esta versión cambia la familia de modelos de IA predeterminada a Qwen 3.5 y deshabilita la descarga automática de modelos por defecto.
> Si instalas la actualización de la plataforma antes de descargar el modelo necesario, los servicios de IA no arrancarán.
>
> Consulta la [guía de migración a la versión 1.55](/es/v1.58/changelog/guides/1-55-0) antes de actualizar.

## 💼 Workspace

### ✨ Novedades

* **Nuevos modelos y nueva familia predeterminada**: Se ha añadido compatibilidad con Qwen 3.5 y, de forma experimental, con Ministral, GLM 4.7 y los modelos NVIDIA Nemotron. Qwen 3.5 pasa a ser la familia base predeterminada, mejorando la calidad de razonamiento, el comportamiento agéntico y la calidad de las respuestas.
* **Nuevas herramientas de Workspace en el chat**: Con el nuevo conjunto de modelos, el chat puede ahora listar contenido, obtener contenido, crear resúmenes y análisis, y generar documentos en blanco a partir del contexto del chat.
* **Rediseño de las instrucciones en ajustes de proyecto**: Los ajustes de proyecto utilizan ahora un único campo de instrucciones personalizadas en lugar de dos, simplificando la configuración y mejorando la experiencia de usuario.
* **Sincronización automática de la base de conocimiento**: Las integraciones pueden ahora sincronizarse automáticamente tras su configuración. Los flujos de sincronización manual ya no son necesarios para el uso habitual.
* **Tokens personales de Workspace**: Todos los usuarios pueden ahora generar sus propios tokens de API personales de Workspace directamente desde los ajustes de su cuenta, sin necesidad de intervención de un administrador.

## 🛠️ Backoffice

### ✨ Novedades

* **Rediseño completo del Backoffice**: El Backoffice ha sido completamente rediseñado con importantes mejoras de interfaz y experiencia de usuario para hacer la administración de la plataforma más clara, ágil y coherente.

## 🛠️ Plataforma

### ✨ Novedades

* **Métricas de plataforma para visibilidad de IA/GPU**: Ahora es posible recopilar y consumir métricas de plataforma, incluyendo métricas de GPU y de cargas de trabajo de IA, para mejorar la observabilidad y la visibilidad operativa. Consulta la [configuración de observabilidad](/en/v1.58/operator-manual/configuration/observability/overview).

### 🐛 Corrección de errores

* Corregidos errores cuando el sistema se ejecuta en una máquina con IPv6 habilitado.

**1.54.0**

March 09, 2026

> [!CAUTION]
>
> **⚠️ Acción requerida antes de actualizar a la versión ≥ 1.54.0**
>
> Esta versión requiere migrar a la nueva versión de la CLI antes de actualizar. Omitir este paso causará un fallo crítico y Zylon no podrá iniciarse.
> Esta actualización requiere entre 45 y 60 minutos de inactividad planificada. Planifícalo con antelación y notifica a tus usuarios antes de comenzar.
> Esta versión contiene un cambio incompatible con versiones antiguas con los tokens de API del Workspace.
>
> Consulta la [guía de migración completa de la versión 1.54.0](/es/v1.58/changelog/guides/1-54-0) para todos los detalles.

## 💼 Workspace

### ✨ Funcionalidades

* **Renovación de los registros de auditoría:** mayor visibilidad y capacidades de filtrado en las entradas de auditoría con seguimiento granular de las acciones de los usuarios.
* **Conector de Confluence On-Prem:** integración con instancias on-premises de Confluence para un acceso y colaboración documental sin fricciones. [Más información](/es/v1.58/user-manual/connectors/confluence-server)

### 🐛 Correcciones de errores

* Se corrigieron cierres inesperados al procesar consultas SQL excesivamente grandes con el conector de base de datos.
* Se añadieron títulos correctos para conectores MCP cuando solo hay una herramienta.
* Se corrigió un error en chats cuando ocurría la compresión de contexto.
* Se optimizó el selector de organización para listas largas, mejorando la usabilidad.

## 🛠️ Plataforma

### ✨ Funcionalidades

* **Backoffice:** el Backoffice de la plataforma es utilizado por los operadores para gestionar el acceso a nivel de plataforma y los entornos de desarrollo. [Más información](/es/v1.58/operator-manual/backoffice/introduction)
* **AI Gateways:** un servicio de software dedicado y aislado que se sitúa entre los clientes y las APIs internas de Zylon. [Más información](/es/v1.58/operator-manual/backoffice/platform-backoffice#gateways)

**1.53.0**

February 23, 2026

> [!CAUTION]
>
> **⚠️ Acción requerida antes de actualizar a la versión ≥ 1.53.0**
>
> Esta versión requiere migrar a la nueva versión del CLI antes de actualizar. Omitir este paso causará un fallo crítico y Zylon no podrá iniciarse.
> Esta actualización requiere 45–60 minutos de tiempo de inactividad planificado. Planifica en consecuencia y notifica a tus usuarios antes de comenzar.
>
> Sigue la [guía de migración completa de 1.53.0](/es/v1.58/changelog/guides/1-53-0) para obtener todos los detalles.

## 🛠️ Plataforma

### ✨ Funcionalidades

* **Instalación Airgap Completa**: Zylon ahora puede operar en entornos completamente aislados de extremo a extremo — incluyendo actualizaciones — no solo en tiempo de ejecución. Para entornos con aislamiento de red estricto, esto desbloquea la gestión completa del ciclo de vida sin acceso a internet.
  * Consulta la nueva [guía de instalación airgap](/es/v1.58/operator-manual/installation/airgap) para comenzar o migrar tu instancia existente.

* **Zylon CLI 2.0.0**: Una renovación importante de la interfaz de línea de comandos que simplifica todo el proceso de instalación a un solo comando — `sudo zylon-cli install <version>`. No más secuencias de configuración de múltiples pasos.

  * **Asistente de Configuración**: Configura cada aspecto de tu instancia de Zylon de forma interactiva, sin editar manualmente archivos YAML. El asistente te guía a través de todas las opciones de configuración paso a paso.

  ![](https://mintcdn.com/zylon/shRcITnBV57PgrXV/images/changelog/1.53.0/image1.png?fit=max\&auto=format\&n=shRcITnBV57PgrXV\&q=85\&s=1bbf65267da7bed20ff0e36b35b60afc)

  ![](https://mintcdn.com/zylon/shRcITnBV57PgrXV/images/changelog/1.53.0/image2.png?fit=max\&auto=format\&n=shRcITnBV57PgrXV\&q=85\&s=b7673331d3cc926a8cf22c8dfd40e40f)

**1.52.0**

January 28, 2026

## 💼 Workspace

* **Soporte para DB2**: Ahora puedes conectar tus bases de datos DB2 directamente a Zylon, permitiendo que la IA razone sobre tus datos empresariales mientras mantienes control total y seguridad.
* **Mejoras en integraciones MCP**: Ahora se admite autenticación con token Bearer para integraciones MCP, proporcionando opciones de seguridad más flexibles. También puedes activar o desactivar todas las herramientas MCP a la vez, facilitando la configuración de tu workspace.
* **Selección de Carpeta de SharePoint**: Al usar el selector de SharePoint, ahora puedes establecer una carpeta de inicio predeterminada para toda la organización, ahorrando tiempo al navegar a ubicaciones frecuentemente utilizadas.
* **Ventana de Analíticas Extendida**: Los datos de analíticas ahora están disponibles durante los últimos 12 meses, proporcionándote una vista más amplia del uso del workspace y las tendencias.
* **Visibilidad del Conector**: Ahora puedes ver quién creó cada conector, mejorando la transparencia y facilitando la gestión de integraciones en tu equipo.
* **Columna de Proyecto en Reporte de Problemas**: El rastreador de problemas ahora muestra una columna de proyecto con nombres de proyectos, facilitando la organización y el filtrado de problemas reportados.

## 🛠️ Plataforma

* **Despliegues Privados de N8N**: Ahora puedes desplegar tu propio clúster privado de N8N dentro de tu infraestructura. Úsalo de forma independiente para construir flujos de trabajo personalizados, o crea tus propios servidores MCP para capacidades de IA extendidas. N8N maneja tu automatización personalizada mientras Zylon proporciona la capa de IA, asegurando que todos los datos permanezcan seguros dentro de tu entorno.

## 🐛 Correcciones de Errores

* **Mejoras en redirección** en toda la plataforma.
* **Estabilidad en Creación y Edición de Conectores**: Se corrigieron múltiples casos donde las operaciones de creación y edición de conectores fallaban inesperadamente.

**1.51.0**

December 16, 2025

## 💼 Workspace

### ✨ Funcionalidades

* **Adjuntar imágenes en el chat**: Ahora puedes adjuntar imágenes directamente en conversaciones de chat. Esta función requiere que tu modelo admita capacidades de imagen.
* **Conectores a nivel de proyecto**: Los MCPs y las bases de datos ahora se pueden configurar a **nivel de proyecto**, haciéndolos reutilizables en múltiples agentes y flows manteniendo un control de acceso consistente.
* **Herramienta de búsqueda web en el chat**: La búsqueda web ahora está disponible directamente dentro del chat, permitiendo a los usuarios obtener información actualizada sin salir de la conversación.
* **Editar y eliminar última interacción**: Corrige errores o refina prompts rápidamente editando o eliminando tu **última interacción** directamente desde la interfaz del chat.

### 🐛 Bug Fixes

* **Visibilidad mejorada**: Hemos mejorado el contraste y la colocación de algunos elementos de la interfaz para mejor descubribilidad y usabilidad.
* **Duplicar Documento IA para flows en ejecución**: Ahora puedes duplicar Documentos IA incluso mientras aún están en ejecución, permitiendo iteración y experimentación más rápidas.
* **Corrección de duplicación de preguntas y respuestas masivas**: Se resolvió un problema donde la duplicación de preguntas y respuestas masivas fallaba bajo ciertas condiciones.
* **Bloqueo de chat cuando se selecciona herramienta MCP**: Se corrigió un error donde seleccionar una herramienta rota impedía a los usuarios continuar las interacciones de chat mientras MCP estaba activo.

## Tiempo de inactividad esperado

Alrededor de 1 hora porque hay cambios en la capa de IA de bajo nivel que requieren que se descargue contenido grande.

## Recomendaciones sobre cuándo actualizar

Actualice fuera del horario comercial para evitar impactar a los usuarios durante un período prolongado.

**1.50.0**

December 9, 2025

## 💼 Workspace

### ✨ Funcionalidades

* **Edición y eliminación de mensajes**: ¿Cometiste un error en el chat? ¡No hay problema! Ahora puedes eliminar y editar tus últimos mensajes en chats privados y colaborativos, dándote más control sobre tu historial de conversación y reduciendo la fricción al refinar tus entradas.
* **Mejoras del conector de base de datos**: El conector de base de datos ahora admite vistas y procedimientos almacenados, proporcionando acceso rápido a tus datos sin riesgos de fuga. Esto permite una integración de datos más flexible manteniendo los límites de seguridad.
* **Mejoras de rendimiento de la base de conocimiento**: Hemos entregado mejoras importantes de rendimiento en toda la Base de conocimiento, especialmente al cargar y buscar documentos en toda la aplicación.

### 🐛 Bug Fixes

* **UX mejorada al vincular desde proyectos**: más espacio para navegar tus artefactos

**1.49.1**

November 18, 2025

## 💼 Workspace

### ✨ Funcionalidades

* **Carga masiva de usuarios CSV**: Ahora puedes subir múltiples usuarios a la vez mediante CSV, totalmente integrado con control de asientos y seguimiento de licencias. Ahorra tiempo para administradores que incorporan equipos grandes y reduce errores manuales.
* **Mejoras en gestión de contraseñas**: Los usuarios ahora pueden actualizar sus propias contraseñas y los administradores pueden restablecer contraseñas directamente desde el espacio de trabajo. Mejor higiene de seguridad y menos sobrecarga administrativa.
* **Modo desarrollador**: Estamos introduciendo **Zylon Developer Mode**, permitiendo a los usuarios autenticarse e interactuar con la API de Zylon, desbloqueando integraciones más profundas y personalización de flujos de trabajo.
  Esto permitirá a las organizaciones automatizar operaciones del espacio de trabajo desde scripts internos y conectar Zylon en servicios backend personalizados.
  * **Gestión de tokens**: Los desarrolladores y administradores de Zylon ahora pueden crear, revocar y gestionar tokens de API directamente dentro del espacio de trabajo. Este cambio reduce la fricción operativa al construir integraciones.
* **Actualización de permisos**: Los visualizadores ahora están **restringidos de descargar archivos** en la Base de conocimiento, asegurando que la información sensible permanezca controlada.

### 🐛 Bug Fixes

* Barra de búsqueda centrada en el rastreador de problemas para mejor usabilidad.
* Los visualizadores ahora tienen prohibido descargar archivos.

## 🛠️ Platform

### ✨ Funcionalidades

* **Amplía Zylon con tus propias herramientas y flujos de trabajo sin infraestructura adicional: Zylon** ahora admite **endpoints de API estilo Messages**, permitiendo integraciones de herramientas sin problemas.
  Esto desbloquea compatibilidad con:
  * **N8N**
  * **Herramientas LangChain**
  * **Automatizaciones personalizadas** construidas internamente
  * **Monitoreo mejorado y seguimiento de rendimiento**: Hemos mejorado la observabilidad de cargas de trabajo de inferencia para un ajuste de rendimiento más preciso y diagnóstico de problemas

**1.48.2**

October 30, 2025

## 🛠️ Platform

### 🐛 Bug Fixes

* Página de estado:
  * Ahora requiere inicio de sesión para acceder.

## 💼 Workspace

### 🐛 Bug Fixes

* Estabilidad mejorada de Omnisearch al trabajar con archivos vinculados.

**1.48.1**

October 27, 2025

## 🛠️ Platform

### ✨ Funcionalidades

* Zylon ahora ofrece soporte de proxy. Aprende más sobre ello [aquí](/es/v1.58/operator-manual/configuration/network/proxy).
* Se introdujo una página de Estado que proporciona información sobre la salud general del sistema en `https://your-zylon-instance.com/status`

### 🐛 Bug Fixes

* Mejora de estabilidad para chats largos: Se corrigieron fallos que ocurrían al reducir el tamaño de la ventana de contexto.
* Rendimiento del sistema mejorado durante pruebas de estrés.
* Se aumentó el número de conexiones de base de datos permitidas.

## 💼 Workspace

### 🐛 Bug Fixes

* Conector de base de datos: ahora admite todos los tipos de columna SQL.
* Panel de análisis: Precisión mejorada de informes semanales.
* Panel de problemas:
  * El contenido completo del chat ahora se muestra al reportar un problema.
  * Se añadió la capacidad de limpiar el filtro de fecha.
* Documento IA:
  * Se corrigió un problema que impedía usar Zylon AI como fuente para crear flow de borrador.
  * Se permitió el uso de comillas dobles en preguntas para el flow de preguntas y respuestas masivas.

**1.47.1**

October 3, 2025

## 💼 Workspace

### ✨ Funcionalidades

* **Mejoras del conector de base de datos**: Ahora admite vistas de base de datos y proporciona datos contextuales más ricos, permitiendo al modelo generar respuestas más precisas y fundamentadas.
* **Vista de usuarios principales personalizable**: Ajusta el número de usuarios principales mostrados en el Panel de uso para adaptarse a las necesidades de tu organización.
* **Integración del conector MCP**: Ahora puedes usar conectores MCP en tu instancia de Zylon.
  * Esta función está en **fase Alpha** y [necesita ser habilitada](/es/v1.58/operator-manual/configuration/features/overview).
  * Aprende cómo usarla con el [Manual de usuario](/es/v1.58/user-manual/tools/mcp-connector).
* **Soporte de imágenes en chats**: Ahora puedes chatear con tus imágenes, *si el modelo de imagen está habilitado*.

### 🐛 Bug Fixes

* Estabilidad y rendimiento mejorados de los selectores de archivos en todos los módulos de la aplicación.
* Mecanismos de manejo de errores refinados para una mejor experiencia de usuario durante casos límite.
* Funciones de colaboración mejoradas en entornos de chat compartidos para trabajo en equipo más fluido.

## 🛠️ Platform

* Se resolvió el problema de validación de licencia en la interfaz de línea de comandos (CLI).

**1.46.2**

September 24, 2025

> [!WARNING]
>
> Una nueva versión de CLI está ahora disponible, con un proceso de actualización mejorado que es más robusto. El proceso ahora valida la preparación del sistema antes de continuar e incluye capacidades de autorreparación automática cuando ocurren errores.
> Debes descargar la nueva versión ejecutando sudo zylon-cli self-update.

## 💼 Workspace

### ✨ Funcionalidades

* **Modelo GPT-OSS ahora disponible**: Ahora puedes acceder a nuestro modelo experimental GPT-OSS en configuraciones de 24GB y 48GB, dándote capacidades de IA más potentes para tareas complejas. Más información en [presets experimentales](/es/v1.58/operator-manual/ai-presets/presets#presets-experimentales).

### 🐛 Bug Fixes

* Estabilidad y confiabilidad de conexión mejoradas.
* Se corrigió un error que podía causar fallos al configurar nuevos Documentos IA.
* Se corrigió un problema raro que podía hacer que la IA se quedara bloqueada mientras procesaba solicitudes.
* Se corrigió un error donde no se podían crear nuevos documentos IA si no se generaba un título automáticamente.
* El sistema ahora elige el modelo de lenguaje correcto para cada tarea de forma más consistente.
* Se corrigió un problema que afectaba la sincronización de datos entre sistemas.
* Se corrigió un problema que ocasionalmente afectaba la interpretación de imágenes en archivos PPTX.

## 🛠️ Platform

* Usa tus propios modelos de IA: Ahora puedes conectar tus propios modelos de IA ajustados sin perder ninguna de las funciones de la plataforma. Esto te da más control y flexibilidad sobre cómo se comporta la IA. Más información en [personalizar los presets por defecto](/es/v1.58/operator-manual/ai-presets/advanced-customization).
* Soporte de visión mejorado: Se corrigió un error que a veces impedía que las herramientas de IA se cargaran cuando las funciones visuales (imagen) estaban activadas.

**1.45.1**

September 17, 2025

## 💼 Workspace

### ✨ Funcionalidades

* Conector de base de datos: Conéctate sin problemas a bases de datos PostgreSQL, MySQL y MSSQL y haz preguntas en chats, permitiendo recuperación de datos intuitiva sin
  escribir consultas SQL.
  * Esta función está en **fase Alpha** y [necesita ser habilitada](/es/v1.58/operator-manual/configuration/features/overview).
  * Aprende cómo usarla con el [Manual de usuario](/es/v1.58/user-manual/tools/database-connector).
* Documento IA - Nuevas opciones de menú para una experiencia de usuario mejorada:
  * Reintentar: Permite a los usuarios reiniciar flujos de trabajo fallidos con un solo clic.
  * Duplicar: El usuario es llevado a un nuevo flujo de trabajo prellenado con los mismos datos que el original

### 🐛 Bug Fixes

* Al añadir nuevos miembros a proyectos, la búsqueda encuentra usuarios por correo electrónico.
* Cuando la base de conocimiento solo tenía archivos en procesamiento, el selector de fuentes mostraba 0 archivos en lugar de estado vacío.
* Omnisearch encuentra carpetas correctamente.

## 🛠️ Platform

* Refactorización de API: API ZGPT mejorada con gestión automática de contexto e integración directa de herramientas, optimizando flujos de trabajo de desarrollo mediante manejo inteligente de solicitudes

**1.44.0**

September 15, 2025

> [!CAUTION]
>
> Esta actualización implica 15-30 minutos de tiempo de inactividad.
> Sigue [esta guía de migración antes de actualizar.](/es/v1.58/changelog/guides/1-43-0)

## 🛠️ Platform

* ¡Zylon se vuelve multimodal! Ahora nuestra plataforma es capaz de gestionar varios modelos de IA ejecutándose en paralelo dentro de la misma instancia.

## 💼 Workspace

### ✨ Funcionalidades

* Extracción de contenido de diapositivas mejorada gracias a ejecutar un modelo de lenguaje visual (VLM) en conjunto con un modelo de lenguaje grande (LLM). Por favor consulta los nuevos presets alternativos para entender [cómo configurarlo y habilitarlo](/es/v1.58/operator-manual/ai-presets/presets#presets-alternativos). Las nuevas capacidades añadidas son:
  * **Comprensión inteligente de contenido**: Extracción impulsada por VLM implementada que puede analizar y entender contenido visual complejo incluyendo diapositivas, diagramas, gráficos e imágenes.
  * **Análisis contextual**: La integración VLM permite mejor comprensión del contexto de diapositivas, relaciones entre elementos visuales y contenido textual dentro de imágenes.
* Mostrar la última hora de actualización para Documentos IA.

### 🐛 Bug Fixes

* Soporte para exportar archivos DOCX con elementos personalizados (p. ej., citas, fuentes de conocimiento).
* Se resolvió un problema donde las exportaciones PDF tenían problemas de formato con listas anidadas.
* Se corrigió un problema con el análisis de respuestas parciales durante el streaming.
* Se abordó un problema donde el panel de reporte de problemas mostraba una fecha vacía.
* Se resolvió un problema de visualización en el modal de vinculación de artefactos en Microsoft Edge.

**1.43.1**

September 10, 2025

> [!CAUTION]
>
> This update involves a 15-30 minutes of downtime.
>
> Sigue [esta guía de migración antes de actualizar.](/es/v1.58/changelog/guides/1-43-0)

## 💼 Workspace

### ✨ Funcionalidades

* 🔎 **Omnisearch**: Ahora capaz de buscar contenido dentro de Documentos IA y documentos de la Base de conocimiento
  * Sigue las [instrucciones para habilitarlo](/es/v1.58/changelog/guides/1-43-0#post-update)
* 📝 **Reporte de problemas**: Los usuarios ahora pueden reportar chats a organizaciones de administradores cuando encuentran problemas con las respuestas de Zylon.

![](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/changelog/1.43.0/image1.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=bf3e1b3093095fe40219052de549cc4b)

![](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/changelog/1.43.0/image2.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=914b31fc859b966626f361fea96081b9)

![](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/changelog/1.43.0/issue_reporting_panel_filters.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=0c0e0941eeb5bdb550bad2fbea67af2a)

* 🎨 **Nuevo motor de renderizado**: Chats más rápidos y fluidos con Zylon
  * Zylon ahora puede entender y renderizar diagramas Mermaid directamente en el chat
  * Legibilidad mejorada de bloques de código para mayor claridad y atractivo visual
  * Las respuestas del chat ahora se renderizan suavemente sin causar saltos de formato durante el streaming
* 💬 **Comportamiento de chat por defecto mejorado**: Uso forzado de búsqueda semántica cuando se seleccionan archivos y no se eligen otras herramientas
* 🔐 **Control de registros de auditoría**: Se añadió la capacidad de desactivar los registros de auditoría — sigue la guía de configuración para deshabilitarlos

### 🐛 Bug Fixes

* Asegurar que el proyecto esté cargado antes de navegar al primer chat
* Prevenir que el usuario acceda a chats eliminados por URL y mostrar advertencia al intentar acceder a recursos eliminados (chat, proyectos)
* Se corrigió un problema con las migas de pan en Omnisearch que causaba problemas de accesibilidad
* Se resolvió un problema donde el análisis numérico se deshabilitaba incorrectamente durante el procesamiento de documentos
* Se corrigió la navegación a proyectos eliminados limpiando el último proyecto visitado si ya no existe
* Se impidió que los usuarios naveguen a documentos IA eliminados vía Omnisearch
* Se corrigieron bloques de código rotos en streaming cuando el lenguaje de programación no se detectaba

## 🛠️ Platform

* Ingest: Un endpoint unificado para ingesta que admite texto, archivos y URIs, incluyendo soporte para ingesta asíncrona.
* Reorganizar la estructura de endpoints para mayor claridad agrupando endpoints relacionados bajo una ruta base común.

> [!WARNING]
>
> Si estás usando la API de bajo nivel directamente, por favor revisa cuidadosamente nuestro [Manual de desarrollador](https://docs.zylon.ai/es/v1.58/api-reference/how-to-use)

**1.40.1**

August 21, 2025

### ✨ Funcionalidades

* 📁 **Carpetas**: Organiza tu base de conocimiento sin esfuerzo usando carpetas para mejor gestión de documentos subidos directamente

  ![](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/changelog/1.40.0/image1.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=f5d8f0218c35400c7e76d5a938ecaee5)

* 💬 **Chats asíncronos**: Ahora puedes cerrar Zylon mientras tu chat continúa en segundo plano — ¡multitarea más fácil!

* 🔎 **Omnisearch**: Busca instantáneamente en tu contenido para navegar rápidamente a tus recursos: Documentos, Chats, Documentos IA.

  ![image.png](https://mintcdn.com/zylon/_j0w7hJa3Cg0VgjU/images/image.png?fit=max\&auto=format\&n=_j0w7hJa3Cg0VgjU\&q=85\&s=97b2d88ca5cab7c910dda91740d248bd)

💡 *Consejo: Usa* `Cmd + K` *(Mac)* *o* `Ctrl + K` *(Windows/Linux)* *para abrir Omnisearch aún más rápido!*

* 🔗 **Enlaces**: Los archivos vinculados en una base de conocimiento de otro proyecto ahora se mantienen sincronizados con el original — sin duplicados o versiones desactualizadas

### 🛠️ Platform

* 🚫 Los endpoints deprecados en la API de bajo nivel han sido eliminados

**1.39.0**

August 12, 2025

### ✨ Funcionalidades

* Los usuarios ahora pueden crear carpetas en la base de conocimiento
* Los usuarios ahora pueden mover carpetas y archivos dentro de la base de conocimiento mediante arrastrar y soltar

  ![](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/changelog/1.39.0/image1.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=25bb63328927fd28570150dd314d7641)

**1.38.0**

August 8, 2025

### ✨ Funcionalidades

* Nuevo Documento IA. Leer y extraer.

  ![](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/changelog/1.38.0/image1.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=2da880dc148b703929d4ac78baa15797)

  ![](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/changelog/1.38.0/image2.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=a4c9abb311c829a40648e79afb8383b3)

**1.37.1**

August 7, 2025

### ✨ Funcionalidades

* Exportar Documento IA a PDF/DOCX

![CleanShot 2025-07-15 at 15.46.03.png](https://i.imgur.com/r39V4S9.png)

* Reanudabilidad en chat (ahora el usuario puede conectarse en tiempo real a una respuesta de zylon y el usuario puede actualizar o dejar la aplicación y volver sin detener la respuesta)

### Bugfixes & improvements

* Se corrigió un error que impedía dejar las instrucciones del proyecto vacías
* Las conexiones a la base de datos se cierran correctamente para evitar alcanzar el límite
* Crear una nueva integración de Claromentis no era posible debido a un error

**1.34.2**

July 16, 2025

> [!WARNING]
>
> Es esencial actualizar la aplicación web de Zylon inmediatamente al recibir la notificación de actualización, haciendo clic en el
> botón Actualizar. La aplicación no funcionará correctamente hasta que se complete la actualización. Si algún usuario tiene problemas, limpia
> la caché y actualiza.

### ✨ Funcionalidades

* **Selector de herramientas**: El usuario tiene la capacidad de seleccionar herramientas entre disponibles: Análisis numérico y Pensamiento
  extendido (solo disponible con Qwen 3).
* Análisis numérico (actualmente en beta): Habilita operaciones estándar en datos tabulares en formato textual, incluyendo
  cálculos como promedios, filtrado, selección y visualización de datos usando gráficos. En la actualidad, esta
  funcionalidad está disponible solo cuando se selecciona un archivo CSV de la base de conocimiento. Para un rendimiento óptimo, recomendamos
  adherirse a las siguientes directrices:
* Se debe incluir una sola fila de encabezado.
* Las fechas deben formatearse como yyyy-mm-dd.
* Los números deben seguir el formato XXXXXXX(.XX).
* Las celdas vacías deben contener uno de los siguientes
  valores: "nan", "none", "null", "", "undefined", "n/a", "na", "nat".

### Bugfixes & improvements

* Se corrigió un error que impedía a Qwen generar gráficos en ciertas situaciones
* Se corrigió un problema con el nombre del asistente cuando se establecía el contexto de la empresa
* Mejor experiencia de usuario en dispositivos pequeños en la vista de análisis

**1.33.0**

July 11, 2025

> [!NOTE]
>
> Esta actualización implica entre 15m y 30m de tiempo de inactividad.

### ✨ Funcionalidades

* Nuevo modelo disponible y establecido como predeterminado en todos los presets de línea base. Echa un vistazo a la página [Qwen
  3](https://qwenlm.github.io/blog/qwen3/) para información más detallada.
* Para presets pequeños (24, 32 GB), nuestro nuevo modelo predeterminado es `Qwen 3 14B`.
* Para presets más grandes (48, 96 GB), nuestro nuevo modelo predeterminado es `Qwen 3 32B`.
* Pensamiento extendido: Nuevas capacidades de pensamiento gracias a los modelos Qwen 3.

![](https://i.imgur.com/mua1O7B.png)

### Bugfixes & improvements

* Se corrigió un problema en la generación de títulos de chat que creaba títulos sin letras mayúsculas.
* Mostrar toda la vista de árbol para documentos de confluence al seleccionar archivos para vincular
* Al hacer una interacción, los documentos sin contenido se ignoran
* En una integración de confluence existente, en caso de error durante la autenticación ahora intenta iniciar sesión nuevamente
* Forzar modo streaming en API de bajo nivel

> [!NOTE]
>
> Esta versión cambia el modelo actual a los modelos Qwen 3. **Esta es la forma en que recomendamos usar Zylon para
> admitir nuevas funciones y funcionalidades.**
>
> En caso de que quieras mantener cualquiera de las configuraciones anteriores (modelo, ventana de contexto, etc.), tienes que revertir el preset
> como se detalla en [**Presets deprecados**](/es/v1.58/operator-manual/ai-presets/presets) en la sección de reversión.

**1.32.0**

July 9, 2025

### Bugfixes & improvements

* Experiencia de usuario mejorada cuando un usuario se elimina de un proyecto, mostrando una advertencia.

**1.31.1**

TODO: Add release date

* Lanzado a Sandbox: July 8, 2025
* Lanzado a Stable: -

### Bugfixes & improvements

* Optimizado cómo funciona la caché del frontend
* Añadido soporte para citas en bloques de pensamiento
* Se corrigió un problema que causaba que los resúmenes fallaran en algunos escenarios
* Se corrigió un problema en el selector de fuentes que impedía usar Zylon AI incluso cuando estaba seleccionado

**1.31.0**

July 4, 2025

### Selector de herramientas

Ahora es posible seleccionar qué herramienta usar

### IA agéntica de Zylon

Varias mejoras y correcciones para tener mejor estabilidad.

### Bugfixes & improvements

* Intentar ingerir documentos de Confluence fallaba debido a un cambio importante en la API de Atlassian
* Eliminar archivo del selector de fuentes cuando el documento original ha sido eliminado
* Interfaz de chat mejorada
* Mostrar estado vacío para integración de sistema de archivos
* Las citas con archivos PDF ahora abren la página correcta

**1.30.1**

June 30, 2025

### IA agéntica de Zylon - Programa de pruebas alfa

El núcleo de IA de Zylon ahora está impulsado por agentes que usan diferentes herramientas dependiendo de la tarea a resolver.

El primer agente disponible para probadores alfa proporciona capacidades de **consulta analítica** para extraer
información valiosa de fuentes de datos tabulares como CSVs.

Háznoslo saber si quieres unirte al programa para empezar a probarlo.

### Transferir propiedad del proyecto

En caso de que quieras dejar de ser el propietario de un proyecto, ahora puedes transferir la propiedad a un usuario diferente.

![image.png](https://i.imgur.com/ambkIvz.png)

![image.png](https://i.imgur.com/JRJEgui.png)

### Vincular archivos de diferentes proyectos

Ahora es posible subir archivos una vez y reutilizarlos en diferentes proyectos sin necesidad de ingerirlos nuevamente,
mejorando así la usabilidad y gestión de recursos.

![image.png](https://i.imgur.com/FNFv2c1.png)

![image.png](https://i.imgur.com/7rww4mp.png)

![image.png](https://i.imgur.com/lidZHlY.png)

![image.png](https://i.imgur.com/3p9usWU.png)

![image.png](https://i.imgur.com/kvOcDG1.png)

**Bugfixes and improvements:**

* Los archivos ligeros obtienen mayor prioridad que los archivos pesados en la cola de ingesta para acelerar el proceso y evitar colas
  bloqueadas por un solo archivo pesado. Más información en [(Opcional) Ajustes de rendimiento](/es/v1.58/operator-manual/configuration/performance)
* Cuando se ingiere un HTML no UTF-8, ahora el contenido se procesa correctamente
* Mejora en la detección automática de delimitador y encabezado CSV
* Mejora en la ingesta de tablas para mayor precisión en la recuperación de datos
* En caso de que las credenciales de Claromentis hayan cambiado, aparece un modal para actualizarlas

**1.29.0**

June 17, 2025

### Integración de base de conocimiento de sistema de archivos

Ahora es posible añadir una nueva integración para la Base de conocimiento, en caso de que tengas un sistema de archivos basado en SMB.
Consulta cómo configurar esta integración [1. Recopila información de tu servidor Samba](/es/v1.58/operator-manual/knowledge-base/file-system)

![image.png](https://i.imgur.com/grtGwyG.png)

![image.png](https://i.imgur.com/IBpzwqr.png)

![image.png](https://i.imgur.com/eN3OGJO.png)

![image.png](https://i.imgur.com/LC2CO9N.png)

**Bugfixes and improvements:**

* Cambiar contenido de Documentos IA lanzaba un error aunque el contenido se guardara correctamente
* Cambiar organización en diferentes pestañas ya no genera parpadeo
* Navegar a configuración sin proyectos
* La extensión de bloques de código dentro del editor ha sido mejorada

**1.28.5**

May 30, 2025

### Panel de análisis para administradores

Como administrador ahora puedes revisar cómo los usuarios están interactuando con el sistema para una organización determinada. Comprueba
proyectos totales, chats, consultas de chat y ve análisis agregados por semanas.

![image.png](https://i.imgur.com/jaT4oPh.png)

### Nombre automático de chat

Similar a los Documentos IA, ahora los chats obtienen un nombre automático basado en el mensaje inicial del usuario

### Marca blanca

Hemos añadido soporte completo de marca blanca, así que ahora puedes personalizar el nombre del asistente de IA para que coincida con la marca de tu empresa.

![Screenshot 2025-06-03 at 11.01.22.png](https://i.imgur.com/SsK65Ic.png)

Por defecto, el nombre del asistente está establecido en **Zylon**. Para cambiarlo, simplemente actualiza el campo `assistantName` en tu
archivo de configuración con tu nombre preferido.

**Directrices de nomenclatura**

* Mantén el nombre de tu agente bajo 20 caracteres.
* Evita usar mayúsculas y minúsculas mezcladas (p. ej., "MyAIAssistant").
* No incluyas símbolos inusuales, caracteres especiales o puntuación excesiva (por ejemplo, "\$uper\_Bot!").

```yaml theme={null}

assistantName: "Zylon"
```

**1.27.4**

May 19, 2025

**Bugfixes and improvements:**

* `Qwen 2.5 14B` es el nuevo modelo predeterminado en el preset `baseline-24g`.

**1.27.3**

May 13, 2025

> [!CAUTION]
>
> Esta actualización implica 30m/1h de tiempo de inactividad.
>
> Se requiere una actualización de controladores antes de actualizar a esta versión!
> ejecuta `sudo zylon-cli install-drivers --force` para actualizar los controladores.

### Los propietarios de integraciones de Confluence, Claromentis o SharePoint pueden sincronizar archivos y carpetas ingeridos

![image.png](https://i.imgur.com/ZeWRNYL.png)

\*\* Solo los archivos ingeridos después de la actualización son elegibles para sincronización.\*

### Fija tus proyectos favoritos para acceso rápido

![image.png](https://i.imgur.com/lTbhjcW.png)

**Bugfixes and improvements:**

* Rendimiento de UI
* Mejorar legibilidad en columnas largas en tablas dentro de documentos IA
* Añadido preset de IA para 32Gb (Mistral Small 3 2501)
* GPUs Blackwell admitidas (RTX 5080, RTX 5090)
* La UI de resumen de organización de proyectos ha sido mejorada. Ahora puedes comprobar fácilmente proyectos privados, compartidos y fijados.
* Las fuentes en Documentos IA de preguntas y respuestas masivas ahora apuntan a la referencia del documento en lugar de mostrar el nombre del archivo y la página.
* Los chats largos ahora están admitidos, anteriormente cuando había un chat largo, los nuevos mensajes desaparecían después de la respuesta de Zylon.
* Los archivos PPT ahora se ingieren correctamente.
* Recuperación de documentos mejorada.

## Cambios requeridos antes de actualizar a Zylon 1.27.3

Los controladores Nvidia CUDA necesitan actualizarse a la versión 12.9. Para hacerlo, sigue estos pasos:

1. Actualiza Zylon-CLI:

```bash theme={null}
sudo zylon-cli self-update
```

1. (Opcional) Haz una [copia de seguridad usando
   zylon-cli](/es/v1.58/operator-manual/operations/backup) antes de comenzar el proceso.
2. Prepara y actualiza los controladores y toolkit de Nvidia:

```bash theme={null}
sudo zylon-cli setup
```

1. Reinicia la máquina y comprueba que `nvidia-smi` funciona bien:

```bash theme={null}
sudo reboot
nvidia-smi
```

1. Actualiza Zylon a 1.27.0 usando:

```bash theme={null}
sudo zylon-cli update
```

**1.25.0**

April 24, 2025

### Nuevo selector de organización para cambiar de organización sin cerrar sesión

![Screenshot 2025-04-24 at 19.50.23.png](https://i.imgur.com/sQfoh6H.png)

### Conector de SharePoint

![Screenshot 2025-04-24 at 19.44.14.png](https://i.imgur.com/Zftol5l.png)

**Otras funciones:**

* Marco de observabilidad
* Ahora se muestra un tooltip con el nombre completo cuando un nombre de fuente es demasiado largo en la Base de conocimiento.

**Bugfixes and improvements:**

* Restablecer modal de instrucciones personalizadas a estado vacío cuando se cerró sin guardar
* El flujo para añadir usuarios manualmente a una organización ha sido mejorado para hacerlo más fácil.
* Mejoras de usabilidad en varios flujos de aplicación

**Cambios requeridos debido al nuevo marco de métricas de observabilidad**

Para proporcionar mejor soporte en caso de que algo salga mal, en esta versión hemos actualizado cómo funciona el
marco de observabilidad incluyendo una nueva herramienta basada en Grafana, más allá del mecanismo de reporte de fallos que teníamos
con Sentry. Para que funcione, por favor asegúrate de que tu firewall no esté bloqueando conexiones a cualquiera de estos sitios web:

* sentry.io (deberías tener esto ya configurado correctamente)
* \*.grafana.net (este es el nuevo requerido)

Recuerda que cualquier dato que enviamos es completamente anónimo y agregado, y nos ayudará a diagnosticar cualquier
mal funcionamiento en la plataforma y entender cómo se está usando Zylon para acelerar acciones de soporte.

Para aquellos que quieran saber más sobre lo que ha cambiado, hemos evolucionado el archivo de configuración antiguo:

```yaml theme={null}
sentry:
enabled: true
environment: "my-company"
```

a este nuevo y más granular:

```yaml theme={null}
observability:
crashReporting: true
usageMetrics: true

companyIdentifier: "my-company"
```

En caso de que quieras optar por no participar en esto, puedes añadir el siguiente fragmento al archivo de configuración, pero recuerda que
hacerlo nos dejará ciegos contra cualquier acción de soporte de nuestra parte:

```yaml theme={null}
observability:
crashReporting: false
usageMetrics: false
```

**1.23.10**

April 9, 2025

### Nuevas funciones

* Los chats ahora se pueden copiar y pegar y respetará el formato
* El selector de archivos permite carga de múltiples archivos

### Bugfixes

* Integración de Claromentis mejorada para tener en cuenta archivos con enlaces simbólicos que hacían fallar la integración. Los enlaces simbólicos no se
  ingieren.
* Hacer la extracción de archivos de Claromentis más resistente. Un archivo fallido no hará fallar el proceso de ingesta; el archivo será
  marcado como fallido y el proceso continuará.

**1.23.1**

April 7, 2025

## **Editor de IA mejorado**

Hemos renovado completamente el editor de texto en Documentos IA, enfocándonos en funcionalidad mejorada y una mejor experiencia de usuario:

* **IA en línea**: Ahora puedes hacer prompts en línea dentro de un documento para incluir más información o modificar texto existente.
  Simplemente comienza a escribir `/zylon`.
* **Colaboración en tiempo real**: ¡Co-crea con tus compañeros en tiempo real!
* **Exportación CSV para tablas**: Descarga los resultados de preguntas y respuestas masivas o cualquier otra tabla como archivo CSV.
* **UX mejorada**: Disfruta de una experiencia de edición de tablas más flexible y funciones de edición de texto más versátiles.

## **Búsqueda de base de conocimiento**

Hemos añadido una barra de búsqueda dedicada a la página de Base de conocimiento de cada Proyecto para que puedas encontrar contenido más rápido.

## **Soporte EML**

La plataforma ahora admite el formato de correo electrónico EML popular. Sube tus archivos .eml y úsalos en Chats y Documentos IA
para resumir hilos largos, consultar información específica y más.

## **Exportación CSV en chat**

Ahora puedes descargar tablas de conversaciones de Chat como archivos CSV.


# Manual de usuario de Zendesk – Clientes
Source: https://docs.zylon.ai/es/v1.58/customer-support-manual/zendesk-client-manual

Cómo enviar, rastrear y gestionar solicitudes de soporte a través del Centro de ayuda de Zylon.

Esta guía explica cómo los usuarios de Zylon pueden **enviar, rastrear y gestionar solicitudes de soporte** a través del Centro de ayuda.

Cada sección incluye instrucciones paso a paso.

***

## 1. Acceder al Centro de ayuda

### Paso 1: Navegar al Centro de ayuda

Ve al **Centro de ayuda de Zylon (HC)**:

👉 [https://zylonsupport.zendesk.com/hc/](https://zylonsupport.zendesk.com/hc/)

Encontrarás opciones para:

* **Enviar una solicitud**
* **Ver mis solicitudes**
* Acceder a la documentación

![Zendesk Help Center - Submit a request](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/customer-support-manual/hub.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=dc725d7c8671ad0e75b8cc8cad59d058)

***

## 2. Enviar una solicitud

### Paso 1: Abrir el formulario de solicitud

1. En la barra de navegación superior, haz clic en **Enviar una solicitud**.

### Paso 2: Completar los detalles de la solicitud

El formulario de solicitud incluye varios campos requeridos:

#### 1. Asunto

* Escribe un resumen breve y claro de tu problema o solicitud.

*Ejemplo: "No se puede instalar la aplicación Zylon v1.45 en macOS"*

#### 2. Descripción

* Describe tu problema o solicitud en detalle.
* Incluye contexto relevante, pasos para reproducir (para errores) o capturas de pantalla.

#### 3. Tipo de problema

Selecciona la categoría más apropiada:

* **Interrupción / Sistema caído**
  Zylon está completamente no disponible o inaccesible para todos los usuarios.
* **Error importante**
  Un defecto crítico que impide flujos de trabajo principales o funcionalidad clave.
* **Error menor**
  Un problema no crítico que causa inconvenientes pero no bloquea flujos de trabajo.
* **Solicitud de función / Mejora**
  Sugerencias para nueva funcionalidad o mejoras.
* **Problema de instalación / actualización de aplicación**
  Problemas durante la instalación o actualizaciones.

#### 4. Versión de Zylon

* Elige la versión del producto relacionada con tu problema (p. ej. **v1.45**).
* Puedes encontrar esto en la esquina inferior derecha de la aplicación Zylon.

***

### Paso 3: Enviar tu solicitud

Una vez que todos los campos estén completos:

* Haz clic en **Enviar** en la parte inferior del formulario.
* Aparecerá un mensaje de confirmación y se creará tu solicitud.

***

## 3. Rastrear tus solicitudes

### Paso 1: Ver solicitudes enviadas

1. Desde el Centro de ayuda, haz clic en **Mis solicitudes** en la barra de navegación.
2. Verás una lista de todas tus solicitudes, incluyendo:

* **Asunto**
* **ID**
* **Fecha de creación**
* **Última actividad**
* **Estado** (Abierta, Resuelta, Cerrada)

![Zendesk My Requests list](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/customer-support-manual/my-requests.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=758f7a30919f87be232a861dea45f5af)

***

### Paso 2: Comprobar detalles de la solicitud

1. Haz clic en cualquier solicitud (p. ej. "El botón de descarga no funciona").
2. La página de detalles de la solicitud muestra:

* **Solicitante**
* **Fecha de creación / Última actividad**
* **ID de solicitud**
* **Estado**
* **Prioridad**
* **Tipo de problema**
* **Versión de Zylon**
* **Output de Zylon Doctor** (opcional)

![Zendesk request details view.](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/customer-support-manual/submit-request.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=d4eaa5c86fb466121a02cfdec06f5e3f)

***

### Paso 3: Añadir a la conversación

Para responder o proporcionar actualizaciones:

1. Desplázate a la sección **Añadir a la conversación**.
2. Escribe tu mensaje o sube archivos si es necesario.
3. Haz clic en **Enviar**.

![Add to conversation section in Zendesk](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/customer-support-manual/request-view.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=e601a660a1542267e7d0633f25f878b2)

***

## Resumen rápido

| Acción | Dónde ir | Qué hacer |
| - | - | - |
| Enviar una nueva solicitud | **Enviar una solicitud** | Completa asunto, descripción, tipo de problema, versión de Zylon |
| Comprobar estado de solicitud | **Mis solicitudes** | Ver todos los tickets enviados |
| Responder o actualizar | **Detalle de solicitud** | Añadir a la conversación |

***

## Consejos

* Siempre incluye tu **versión de Zylon** al reportar problemas.
* Intenta adjuntar la salida de Zylon Doctor si tu problema está relacionado con el estado de tu plataforma.
* Adjunta capturas de pantalla o registros para acelerar la solución de problemas.
* Recibirás **notificaciones por correo electrónico** cuando haya una actualización en tu solicitud.


# Personalización Avanzada
Source: https://docs.zylon.ai/es/v1.58/operator-manual/ai-presets/advanced-customization

Personaliza modelos de IA para cargas de trabajo especializadas incluyendo modelos fine-tuned y configuraciones multi-modelo

> [!WARNING]
>
> Las configuraciones personalizadas pueden causar mal funcionamiento del sistema. Realiza pruebas exhaustivas antes del despliegue.

## Cuándo Usar Configuraciones Personalizadas

Considera la personalización avanzada cuando:

* Tienes **modelos fine-tuned** optimizados para dominios o tareas específicas
* Necesitas **parámetros de muestreo diferentes** a los valores por defecto del preset
* Quieres ejecutar **múltiples modelos especializados** simultáneamente (ej., uno para visión, uno para texto, uno para razonamiento)
* Requieres modelos de **familias de modelos alternativas** no incluidas en los presets estándar

Antes de proceder, asegúrate de:

* Entender los principios de gestión de memoria GPU
* Tener acceso a repositorios de modelos HuggingFace compatibles
* Conocer las limitaciones de tu hardware
* Tener un entorno de prueba para validación

## Familias de Modelos Soportadas

Zylon admite estas familias de modelos para configuraciones personalizadas:

| Familia de Modelo | Repositorio de Ejemplo | Casos de Uso |
| - | - | - |
| **Qwen 3** | `Qwen/Qwen3-14B` | Propósito general (por defecto) |
| **Mistral Small** | `mistralai/Mistral-Small-24B-Instruct-2501` | Generación de texto de alta calidad |
| **Gemma 3** | `google/gemma-3-12b-it` | Inferencia eficiente |
| **Gemma 3n** | `google/gemma-3n-E4B-it` | Modelos pequeños optimizados |
| **GPT-OSS** | `openai/gpt-oss-20b` | Arquitectura alternativa |

> [!NOTE]
>
> Solo los modelos de estas familias están oficialmente soportados. Usar familias no soportadas puede resultar en inestabilidad del sistema.

## Entendiendo la Estructura de Configuración

Todas las configuraciones personalizadas siguen este patrón:

```yaml theme={null}
ai:
  preset: "<base-preset>"           # Comienza con un preset base
  gpuCount: <number>                 # Opcional: para configuraciones multi-GPU
  config:
    models:
      - id: llm                      # Obligatorio: modelo de lenguaje principal
        # ... configuración
      - id: embed                    # Obligatorio: modelo de embeddings
        # ... configuración
      - id: <custom-id>              # Opcional: modelos adicionales
        # ... configuración
```

**Principios clave:**

* Cada configuración debe incluir modelos `llm` y `embed`
* Cada modelo necesita un `id` único
* La memoria GPU debe gestionarse manualmente al agregar/eliminar modelos

***

## Caso de Uso 1: Personalizar Modelos Existentes

**Objetivo**: Modificar los modelos por defecto del preset sin agregar nuevos. Esto es útil para usar versiones fine-tuned de modelos existentes o ajustar parámetros de inferencia.

### Cuándo Usar Este Enfoque

* Intercambiar el modelo por defecto por una **versión fine-tuned** (ej., `Qwen3-14B-Medical` en lugar de `Qwen3-14B`)
* Cambiar **parámetros de muestreo** (temperature, max tokens, etc.) para un comportamiento diferente
* Usar un **modelo de embeddings diferente** para búsqueda semántica mejorada
* Ajustar el tamaño de la **ventana de contexto** según tu caso de uso

### Cómo Funciona

Como no estás agregando modelos, no necesitas preocuparte por la reasignación de memoria. Simplemente especifica los cambios del modelo en la sección `config`, y el preset maneja la asignación de memoria automáticamente.

### Esquema de Configuración

```yaml theme={null}
ai:
  preset: "<preset>"
  config:
    models:
      - id: llm | embed                    # Qué modelo personalizar
        modelRepo: string                  # Ruta del modelo HuggingFace
        tokenizer: string                  # Opcional: ruta del tokenizer (solo LLMs)
        promptStyle: string                # Opcional: qwen, mistral, gemma, gpt-oss
        contextWindow: integer             # Opcional: longitud máxima de contexto
        samplingParams:                    # Opcional: parámetros de inferencia
          temperature: float (0.0-2.0)
          maxTokens: integer (1-8192)
          topP: float (0.0-1.0)
          # ... otros parámetros de muestreo
```

### Ejemplos

#### Ejemplo 1: Usar un Modelo Fine-Tuned

Reemplaza el modelo por defecto con tu versión fine-tuned específica del dominio:

```yaml theme={null}
ai:
  preset: "baseline-48g"
  config:
    models:
      - id: llm
        modelRepo: "your-org/qwen3-14b-medical-finetuned"
        tokenizer: "Qwen/Qwen3-14B-Instruct"  # Usa el tokenizer original
```

#### Ejemplo 2: Ajustar Parámetros de Muestreo

Modifica el comportamiento de inferencia sin cambiar el modelo:

```yaml theme={null}
ai:
  preset: "baseline-48g"
  config:
    models:
      - id: llm
        samplingParams:
          temperature: 0.3        # Más determinista
          maxTokens: 2048         # Respuestas más cortas
          topP: 0.85              # Muestreo enfocado
          repetitionPenalty: 1.3  # Reducir repetición
```

#### Ejemplo 3: Usar Familia de Modelo Alternativa

Cambia a una familia de modelo diferente manteniendo la misma huella de memoria:

```yaml theme={null}
ai:
  preset: "experimental.gpt-oss-24g"
  config:
    models:
      - id: llm
        modelRepo: "your-org/gpt-oss-20b-finetuned"
        tokenizer: "openai/gpt-oss-20b"
        promptStyle: gpt-oss
```

#### Ejemplo 4: Modelo de Embeddings Personalizado

Usa embeddings especializados para búsqueda semántica específica del dominio:

```yaml theme={null}
ai:
  preset: "baseline-48g"
  config:
    models:
      - id: embed
        modelRepo: "your-org/legal-embeddings-v1"
        vectorDim: 1024
```

***

## Caso de Uso 2: Agregar Nuevos Modelos

**Objetivo**: Ejecutar múltiples modelos especializados simultáneamente. Esto es más complejo porque debes gestionar manualmente la asignación de memoria GPU en todos los modelos.

### Cuándo Usar Este Enfoque

* Ejecutar un **modelo de visión** junto con tu modelo de texto principal
* Usar **modelos diferentes para diferentes tareas** (ej., modelo de razonamiento + modelo de respuesta rápida)
* Crear **pipelines especializados** que requieren múltiples tipos de modelos
* Construir **sistemas multi-modales** que procesan texto, imágenes, audio y otros tipos de datos

### Entendiendo la Gestión de Memoria GPU

El concepto crítico: **La memoria GPU es un recurso fijo que debe dividirse manualmente entre todos los modelos.**

Cada modelo usa una fracción de la memoria GPU total, controlada por `gpuMemoryUtilization` (un valor entre 0.0 y 1.0). La suma de todas las asignaciones de memoria de los modelos no puede exceder **0.95** (reservando 5% para sobrecarga del sistema).

**Asignación por defecto para baseline-48g:**

```
llm:   0.85  (85% de 24GB = ~20.4GB)
embed: 0.10  (10% de 24GB = ~2.4GB)
─────────────
Total: 0.95  (con 0.05 reservado para el sistema)
```

**Para agregar un nuevo modelo**, debes:

1. Reducir las asignaciones de los modelos existentes para liberar memoria
2. Asignar la memoria liberada al nuevo modelo
3. Ajustar las ventanas de contexto si la memoria se reduce significativamente

### Entendiendo KV Cache

Para entender por qué la asignación de memoria afecta las ventanas de contexto, necesitas saber sobre **KV Cache**.

**¿Qué es KV Cache?**

Durante la inferencia, los modelos de lenguaje almacenan cálculos intermedios (Keys y Values) para cada token que procesan. Esto se llama **KV Cache**, y es lo que permite a los modelos mantener el contexto a través de una conversación o documento sin recalcular todo desde cero.

El KV Cache crece con:

* **Longitud del contexto**: Más tokens en contexto = más almacenamiento de caché necesario
* **Tamaño del modelo**: Modelos más grandes requieren más caché por token
* **Tamaño del lote**: Procesar múltiples solicitudes simultáneamente multiplica los requisitos de caché

**Desglose de asignación de memoria:**

Cuando asignas memoria GPU a un modelo, esa memoria se divide entre:

1. **Pesos del modelo**: Los parámetros del modelo (tamaño fijo, \~2 bytes por parámetro para FP16)
2. **KV Cache**: Almacenamiento para tokens de contexto (crece con la longitud del contexto)
3. **Memoria de activación**: Espacio de cálculo temporal durante la inferencia

**Ejemplo para un modelo de 14B parámetros:**

```
Asignación completa (0.85 en 24GB = 20.4GB):
├─ Pesos del modelo: ~14GB (cuantizado; el tamaño FP32 original sería ~28GB)
├─ KV Cache: ~5GB (soporta contexto de 16k)
└─ Activaciones: ~1.4GB

Asignación reducida (0.50 en 24GB = 12GB):
├─ Pesos del modelo: ~14GB (igual, pero más ajustado)
├─ KV Cache: ~2GB (ahora solo soporta contexto de 8k)
└─ Activaciones: margen mínimo
```

**Por qué esto importa:**

Si reduces la asignación total de memoria de 0.85 a 0.50, los pesos del modelo aún necesitan el mismo espacio, pero tienes significativamente menos espacio para KV Cache. Esto significa que debes reducir el parámetro `contextWindow` proporcionalmente para evitar errores de falta de memoria durante la inferencia.

**Asignaciones de KV Cache por defecto de baseline:**

| Preset | Asignación de Memoria | Ventana de Contexto | KV Cache Aprox |
| - | - | - | - |
| baseline-48g | 0.85 | 16384 (16k) | \~4-6GB |
| baseline-96g | 0.85 | 32768 (32k) | \~8-12GB |

> [!WARNING]
>
> Establecer `contextWindow` demasiado alto para la memoria asignada causará errores de falta de memoria durante la inferencia, especialmente durante conversaciones largas o al procesar documentos grandes. Los errores típicamente aparecen como "CUDA out of memory" en los logs de Triton.

### Proceso Paso a Paso

#### Paso 1: Conoce tu Memoria GPU

Primero, identifica tu memoria GPU total disponible:

```bash theme={null}
nvidia-smi
```

Configuraciones comunes:

* **24GB**: RTX 4090, L4
* **48GB**: RTX A6000, L40, L40s
* **80-96GB**: A100, H100

Reserva **5% para sobrecarga del sistema**, dejando **95% para modelos**:

* 24GB → 22.8GB utilizables
* 48GB → 45.6GB utilizables
* 96GB → 91.2GB utilizables

#### Paso 2: Calcula los Requisitos de Memoria del Modelo

La memoria del modelo depende del **conteo de parámetros** y la **cuantización**. Usa esta tabla para estimar:

| Tamaño del Modelo | FP16 (precisión completa) | FP8 | FP4/AWQ | Uso Típico |
| - | - | - | - | - |
| 3-4B | 6-8 GB | 3-4 GB | 2-3 GB | Inferencia rápida, razonamiento |
| 7B | 14-16 GB | 7-8 GB | 4-5 GB | Modelos de visión, tareas especializadas |
| 14B | 28-32 GB | 14-16 GB | 8-10 GB | Uso común |
| 20B | 40-44 GB | 20-22 GB | 12-14 GB | Generación de alta calidad |
| 32B | 64-68 GB | 32-34 GB | 18-20 GB | Razonamiento avanzado |
| 70B | 140-150 GB | 70-75 GB | 40-45 GB | Tareas complejas |

**Notas sobre cuantización:**

* **FP16**: Precisión completa, mejor calidad, mayor memoria
* **FP8**: Reducción de memoria del 50%, pérdida mínima de calidad
* **FP4/AWQ**: Reducción de memoria del 70-75%, ligera degradación de calidad
* La mayoría de los modelos de HuggingFace usan FP16 por defecto a menos que se especifique (ej., sufijo `-AWQ`, `-GPTQ`)

**Ejemplos de cálculos para GPU de 24GB (22.8GB utilizables):**

```
Escenario 1: Principal + Visión
- Qwen3-14B (FP16): 28GB → Demasiado grande solo
- Qwen3-14B (FP4): 10GB → Encaja
- Qwen2.5-VL-7B (AWQ): 5GB → Encaja
- Embeddings: 2-3GB → Encaja
- Total: 17-18GB → ✓ Encaja en 22.8GB

Escenario 2: Múltiples modelos más pequeños
- Gemma-3n-4B: 3GB → Encaja
- Qwen2.5-VL-7B (AWQ): 5GB → Encaja
- GPT-OSS-20B (FP4): 12GB → Encaja
- Embeddings: 2GB → Encaja
- Total: 22GB → ✓ Encaja en 22.8GB
```

#### Paso 3: Convierte GB a Porcentajes de Utilización de Memoria

Una vez que conoces los requisitos en GB, convierte a `gpuMemoryUtilization`:

**Fórmula**: `gpuMemoryUtilization = (Model GB / Total GPU GB)`

**Ejemplo para GPU de 24GB:**

| Modelo | Memoria (GB) | Cálculo | gpuMemoryUtilization |
| - | - | - | - |
| Qwen3-14B (FP4) | 10 GB | 10 / 24 = 0.417 | 0.42 |
| Qwen2.5-VL-7B | 5 GB | 5 / 24 = 0.208 | 0.21 |
| GPT-OSS-20B (FP4) | 12 GB | 12 / 24 = 0.500 | 0.50 |
| Embeddings | 2.5 GB | 2.5 / 24 = 0.104 | 0.10 |
| **Total** | **29.5 GB** | **29.5 / 24** | **1.23** (sobre 1.00 ✗) |

**Ejemplo para GPU de 48GB:**

| Modelo | Memoria (GB) | Cálculo | gpuMemoryUtilization |
| - | - | - | - |
| Qwen3-14B (FP16) | 30 GB | 30 / 48 = 0.625 | 0.63 |
| Qwen2.5-VL-7B | 5 GB | 5 / 48 = 0.104 | 0.10 |
| Gemma-3n-4B | 3 GB | 3 / 48 = 0.063 | 0.07 |
| Embeddings | 5 GB | 5 / 48 = 0.104 | 0.10 |
| **Total** | **43 GB** | **43 / 48** | **0.90** (bajo 1.00 ✓) |

> [!TIP]
>
> Siempre redondea ligeramente hacia abajo para dejar margen. Si el cálculo da 0.417, usa 0.40 o 0.42.

#### Paso 4: Ajusta las Ventanas de Contexto Basado en la Memoria

Cuando reduces la asignación de memoria de un modelo, también debes reducir su `contextWindow` porque hay menos espacio disponible para [KV Cache](#entendiendo-kv-cache).

**Regla general**: La ventana de contexto escala aproximadamente linealmente con la huella de memoria.

**Ejemplos:**

```
Escenario 1: GPU de 24GB con modelo de visión
- LLM Principal: 0.85 → 0.50
  Contexto: 16384 → 8192
- Visión: 0.25
  Contexto: 2048

Escenario 2: GPU de 48GB con múltiples modelos  
- LLM Principal: 0.85 → 0.60
  Contexto: 16384 → 12288
- Razonamiento: 0.15
  Contexto: 4096
- Visión: 0.10
  Contexto: 2048
```

#### Paso 5: Escribe la Configuración Completa

Ahora combina todos los modelos con sus asignaciones calculadas:

```yaml theme={null}
ai:
  preset: "baseline-48g"
  config:
    models:
      - id: llm
        gpuMemoryUtilization: 0.42  # 10GB para Qwen3-14B FP4
        contextWindow: 4096          # Reducido desde 8192
        
      - id: llmvision
        gpuMemoryUtilization: 0.21  # 5GB para modelo de visión
        contextWindow: 1024          # Pequeño para tareas de visión
        
      - id: llmfast
        gpuMemoryUtilization: 0.12  # 3GB para modelo rápido
        contextWindow: 2048
        
      - id: embed
        gpuMemoryUtilization: 0.10  # 2.5GB para embeddings
```

> [!WARNING]
>
> **Modelos cuantizados en HuggingFace**:
> Busca sufijos como `-AWQ` o `-GPTQ` en el nombre del modelo. Si no hay sufijo, asume FP16.
>
> Ejemplos:
>
> * `Qwen/Qwen3-14B-Instruct` → FP16 (28-32GB)
> * `Qwen/Qwen3-14B-Instruct-AWQ` → FP4 (8-10GB)
> * `mistralai/Mistral-Small-24B-Instruct-2501` → FP16 (44-48GB)

### Esquema de Configuración

```yaml theme={null}
ai:
  preset: "<base-preset>"
  gpuCount: integer                         # Opcional: para multi-GPU
  config:
    models:
      - id: string                         # Requerido: identificador único
        name: string                       # Opcional: nombre para mostrar
        type: llm | embedding              # Requerido: tipo de modelo
        modelRepo: string                  # Requerido: ruta HuggingFace
        tokenizer: string                  # Opcional: ruta del tokenizer (LLMs)
        promptStyle: string                # Opcional: qwen, mistral, gemma, gpt-oss
        contextWindow: integer             # Opcional: longitud máxima de contexto
        gpuMemoryUtilization: float        # Requerido al agregar modelos (0.0-1.0)
        supportReasoning: boolean          # Opcional: habilitar razonamiento (LLMs)
        multimodal:                        # Opcional: soporte multimodal (LLMs)
          images:
            enabled: boolean
            maxNumber: integer
        samplingParams:                    # Opcional: parámetros de inferencia
          temperature: float (0.0-2.0)
          maxTokens: integer (1-8192)
          minP: float (0.0-1.0)
          topP: float (0.0-1.0)
          topK: integer (1-100)
          repetitionPenalty: float (1.0-2.0)
          presencePenalty: float (-2.0-2.0)
          frequencyPenalty: float (-2.0-2.0)
```

> [!WARNING]
>
> **Reglas Críticas:**
>
> * La suma de todos los `gpuMemoryUtilization` no debe exceder 1.00
> * Cada `id` debe ser único
> * `llm` y `embed` son obligatorios y no se pueden eliminar
> * Reducir la asignación de memoria requiere reducir `contextWindow` proporcionalmente

### Ejemplo Completo: Configuración Multi-Modelo

Este ejemplo demuestra agregar modelos de visión y razonamiento para manejar diferentes tipos de cargas de trabajo:

**Escenario**: Quieres tres modelos:

1. **LLM Principal** para tareas de texto generales
2. **LLM de Visión** para comprensión de imágenes
3. **Modelo de Audio Rápido** para tareas de transcripción

**Estrategia de asignación de memoria**:

```
LLM Principal:   0.50  (reducido desde 0.85)
Modelo de Visión:  0.25  (nuevo)
Modelo de Audio:   0.10  (nuevo)
Embeddings:    0.10  (sin cambios)
───────────────────────────────
Total:         0.95
```

**Configuración completa**:

```yaml theme={null}
ai:
  preset: "baseline-48g"
  gpuCount: 1
  config:
    models:
      # LLM Principal - Maneja generación de texto general
      - id: llm
        name: qwen-3-14b-awq
        type: llm
        contextWindow: 9600              # Reducido desde 16384 (~41%) para coincidir con asignación de memoria
        promptStyle: qwen
        gpuMemoryUtilization: 0.50       # Reducido desde el defecto 0.85
        supportReasoning: true
        samplingParams:
          temperature: 0.7
          maxTokens: 4096
          topP: 0.9

      # Embeddings - Obligatorio para procesamiento de documentos (sin cambios)
      - id: embed
        gpuMemoryUtilization: 0.10

      # LLM de Visión - Maneja tareas de comprensión de imágenes
      - id: llmvision
        name: qwen-2-5-vl-7b-awq
        type: llm
        contextWindow: 1024              # Más pequeño para tareas de imagen
        promptStyle: qwen
        gpuMemoryUtilization: 0.25       # Nueva asignación
        multimodal:
          images:
            enabled: true
            maxNumber: 1
        supportReasoning: false
        samplingParams:
          temperature: 0.1               # Más determinista para visión
          maxTokens: 2048
          topP: 0.85

      # Modelo de audio rápido - Maneja tareas de transcripción
      - id: llmaudio
        name: gemma-3n-e4b
        type: llm
        contextWindow: 2048
        modelRepo: "<repo>/gemma-3n-4b-it-audio"  # Fine-tuned para audio
        promptStyle: gemma
        gpuMemoryUtilization: 0.10                # Nueva asignación
        supportReasoning: true
        samplingParams:
          temperature: 0.5
          maxTokens: 1024
          topP: 0.9

# Verificación de memoria: 0.50 + 0.25 + 0.10 + 0.10 = 0.95 ✓
```

### Mejores Prácticas para Configuraciones Multi-Modelo

1. **Comienza mínimo**: Empieza con asignaciones viables más pequeñas, aumenta basado en el uso real
2. **Monitorea continuamente**: Usa `nvidia-smi` para rastrear el consumo real de memoria
3. **Prueba individualmente**: Valida que cada modelo funciona antes de combinar. Es mejor aislar problemas en lugar de depurar múltiples modelos a la vez
4. **Planifica margen**: No asignes toda la memoria. Deja algo de buffer para picos de memoria
5. **Prueba de estrés**: Simula cargas de trabajo pico para asegurar estabilidad bajo carga

***

## Referencia de Parámetros de Configuración

Referencia completa de todos los parámetros disponibles.

### Parámetros Principales (Todos los Modelos)

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `id` | string | Sí | Identificador único del modelo |
| `type` | string | Sí | Tipo de modelo: `llm` o `embedding` |
| `modelRepo` | string | Sí | Ruta del modelo HuggingFace |
| `name` | string | No | Nombre personalizado para mostrar |
| `gpuMemoryUtilization` | float | No | Fracción de memoria GPU (0.0-1.0) |

### Parámetros Específicos de LLM

| Parámetro | Tipo | Descripción |
| - | - | - |
| `contextWindow` | integer | Longitud máxima de contexto |
| `tokenizer` | string | Ruta del tokenizer HuggingFace |
| `promptStyle` | string | Formato: `qwen`, `mistral`, `gemma`, `gpt-oss` |
| `supportReasoning` | boolean | Habilitar capacidades de razonamiento |
| `supportImage` | integer | Número de imágenes soportadas |
| `supportAudio` | integer | Número de entradas de audio soportadas |
| `samplingParams` | object | Configuración de muestreo por defecto |
| `reasoningSamplingParams` | object | Muestreo para modo de razonamiento |

### Parámetros Específicos de Embedding

| Parámetro | Tipo | Descripción |
| - | - | - |
| `vectorDim` | integer | Dimensiones del vector de salida |

### Parámetros de Muestreo

| Parámetro | Tipo | Rango | Descripción |
| - | - | - | - |
| `temperature` | float | 0.0-2.0 | Aleatoriedad en la generación |
| `maxTokens` | int | 1-8192 | Tokens máximos de respuesta |
| `minP` | float | 0.0-1.0 | Umbral de probabilidad mínimo |
| `topP` | float | 0.0-1.0 | Umbral de muestreo de núcleo |
| `topK` | int | 1-100 | Límite de muestreo Top-K |
| `repetitionPenalty` | float | 1.0-2.0 | Penalización por tokens repetidos |
| `presencePenalty` | float | -2.0-2.0 | Penalización por presencia de token |
| `frequencyPenalty` | float | -2.0-2.0 | Penalización por frecuencia de token |

### Parámetros Multimodales (LLMs)

```yaml theme={null}
multimodal:
  images:
    enabled: boolean      # Habilitar entrada de imagen
    maxNumber: integer    # Máximo de imágenes por solicitud
  audio:
    enabled: boolean      # Habilitar entrada de audio
    maxNumber: integer    # Máximo de archivos de audio por solicitud
```

***

## Lista de Verificación de Validación

Antes de desplegar configuraciones personalizadas:

* [ ] Todos los valores de `id` son únicos
* [ ] Los modelos `llm` y `embed` están presentes
* [ ] Suma de `gpuMemoryUtilization` ≤ 0.95
* [ ] `promptStyle` coincide con la familia del modelo
* [ ] `contextWindow` apropiado para la asignación de memoria
* [ ] `tokenizer` coincide o es compatible con el modelo
* [ ] Configuración probada en entorno de staging
* [ ] Monitoreo en su lugar para uso de memoria

## Errores Comunes

1. **Exceder asignación de memoria de 1.0**: Siempre verifica tus cálculos
2. **No reducir ventanas de contexto**: Los contextos grandes necesitan más memoria, ajusta en consecuencia
3. **Tokenizers incompatibles**: Usa tokenizers compatibles para cada modelo
4. **Estilo de prompt incorrecto**: Cada familia de modelo requiere formato específico
5. **Sin pruebas**: Siempre valida en no-producción primero


# Opciones de Configuración
Source: https://docs.zylon.ai/es/v1.58/operator-manual/ai-presets/configuration

Configura capacidades mejoradas, configuraciones multi-GPU y memoria compartida para un rendimiento óptimo

## Capacidades Mejoradas

Zylon admite capacidades adicionales que se pueden combinar con cualquier preset base o alternativo. Estas capacidades extienden la funcionalidad pero **no están habilitadas por defecto**.

### Capacidades Disponibles

| Capacidad | Descripción | Casos de Uso de Ejemplo | Modelos |
| - | - | - | - |
| `multilingual` | Soporte mejorado para idiomas más allá del inglés | Documentos internacionales, procesamiento de contenido no inglés | intfloat/multilingual-e5-large |

### Agregar Capacidades

Las capacidades se agregan a los presets usando un formato separado por comas: `<base_preset>,<capability1>,<capability2>`

**Ejemplos:**

```yaml theme={null}
# Preset base con capacidad multilingüe
ai:
  preset: "baseline-48g,capabilities.multilingual"

# Preset alternativo con capacidad multilingüe
ai:
  preset: "alternatives.baseline-48g-context,capabilities.multilingual"

# Múltiples capacidades (si más están disponibles)
ai:
  preset: "baseline-48g,capabilities.multilingual,capabilities.feature2"
```

> [!TIP]
>
> Las capacidades se pueden apilar con cualquier tipo de preset incluyendo presets base, alternativos y experimentales.

## Configuración Multi-GPU

Si tu sistema tiene múltiples GPUs, puedes combinar su capacidad de memoria para usar presets de nivel superior. Selecciona el preset basado en **VRAM total combinado** en todas las GPUs.

### Pasos de Configuración

1. **Calcula el VRAM total**: Suma la memoria de todas las GPUs
2. **Selecciona el preset apropiado**: Elige el preset para la memoria total
3. **Configura el conteo de GPU**: Establece el parámetro `gpuCount`

**Ejemplo de Configuración:**

```yaml theme={null}
ai:
  preset: "baseline-48g"
  gpuCount: 2  # Usando 2 GPUs con 24GB cada una (48GB total)
```

### Ejemplos de Configuración Multi-GPU

| Configuración de Hardware | Memoria GPU Individual | VRAM Total | Preset Recomendado | Configuración |
| - | - | - | - | - |
| 2x RTX 4090 | 24GB cada una | 48GB | `baseline-48g` | `gpuCount: 2` |
| 2x L4 | 24GB cada una | 48GB | `baseline-48g` | `gpuCount: 2` |
| 4x RTX 4090 | 24GB cada una | 96GB | `baseline-96g` | `gpuCount: 4` |
| 2x RTX A6000 | 48GB cada una | 96GB | `baseline-96g` | `gpuCount: 2` |

### Mejores Prácticas Multi-GPU

* Asegúrate de que todas las GPUs sean del mismo modelo para un rendimiento óptimo
* Verifica un ancho de banda PCIe adecuado entre las GPUs
* Monitorea la utilización de GPU para asegurar una carga equilibrada
* Considera conexiones NVLink para mejor comunicación entre GPUs cuando esté disponible

**Ejemplo Completo Multi-GPU:**

```yaml theme={null}
ai:
  preset: "baseline-96g,capabilities.multilingual"
  gpuCount: 4  # 4x RTX 4090 (24GB cada una = 96GB total)
```

## Configuración de Memoria Compartida

El Servidor de Inferencia Triton usa memoria compartida para habilitar transferencia de datos sin copia entre los servicios de Zylon y el motor de inferencia. Esto elimina la sobrecarga de serialización y mejora significativamente el rendimiento de inferencia y reduce la latencia para cargas de trabajo de alto volumen.

### Asignación por Defecto

Por defecto, el servidor de inferencia asigna **2GB de RAM** para memoria compartida. Esto es suficiente para la mayoría de las cargas de trabajo de inferencia basadas en texto.

### Cuándo Aumentar la Memoria Compartida

Puedes encontrar errores de `Shared memory allocation failed` en estos escenarios:

* **Colas de solicitudes grandes**: Procesar grandes volúmenes de solicitudes concurrentes donde la entrada en cola excede la memoria compartida disponible
* **Modelos basados en imágenes**: Cargas de trabajo de visión que requieren múltiples megabytes por imagen donde lotes de imágenes de alta resolución agotan rápidamente la asignación por defecto
* **Procesamiento de documentos grandes**: Manejar documentos muy grandes o múltiples documentos simultáneamente

### Configuración

Para aumentar el límite de memoria compartida, actualiza tu archivo de configuración de Zylon:

```yaml theme={null}
triton:
  sharedMemory:
    limit: "4Gi"  # Aumentar desde el defecto 2Gi
```

### Memoria Compartida Recomendada por Caso de Uso

| Caso de Uso | Límite Recomendado | Razón |
| - | - | - |
| Inferencia solo texto | 2Gi (defecto) | Suficiente para la mayoría de cargas de trabajo de texto |
| Tareas de visión de bajo volumen | 4Gi | Maneja procesamiento ocasional de imágenes |
| Tareas de visión de alto volumen | 8Gi | Soporta procesamiento por lotes de imágenes |
| Cargas de trabajo mixtas pesadas | 8-16Gi | Acomoda texto y visión concurrentes |

> [!WARNING]
>
> **Consideraciones importantes al aumentar la memoria compartida:**
>
> * Asignar memoria compartida excesiva puede causar que los pods sean OOMKilled
> * Sé conservador con los aumentos—comienza con incrementos pequeños (ej., 2Gi → 4Gi)
> * Monitorea el uso real con métricas de Kubernetes antes de aumentos adicionales
> * La memoria compartida se reserva de la RAM del sistema, reduciendo la memoria disponible para otros procesos


# Primeros Pasos
Source: https://docs.zylon.ai/es/v1.58/operator-manual/ai-presets/getting-started

Aprende los fundamentos de los presets de IA y cómo configurarlos para tu hardware

## Resumen

El motor de inferencia de IA de Zylon es el componente central que ejecuta modelos de inteligencia artificial en tu hardware. Para asegurar un rendimiento óptimo y prevenir fallos de inicio, debes configurar el sistema con el preset correcto basado en la memoria de GPU (Unidad de Procesamiento de Gráficos) disponible.

### ¿Qué son los Presets de IA?

Los presets de IA son configuraciones predefinidas que optimizan los modelos de IA y la asignación de memoria para tu configuración de hardware específica. Cada preset está cuidadosamente ajustado para:

* Cargar el tamaño de modelo de IA apropiado para tu memoria GPU/RAM
* Asignar memoria eficientemente para prevenir fallos
* Equilibrar el rendimiento con los recursos disponibles
* Habilitar capacidades específicas cuando sea necesario

> [!WARNING]
>
> Seleccionar un preset incorrecto impedirá que el motor de inferencia se inicie. El sistema no detecta automáticamente la capacidad de tu GPU, por lo que se requiere configuración manual.

## Entendiendo los Requisitos de Memoria GPU

Tu GPU (Unidad de Procesamiento de Gráficos) tiene una cantidad específica de VRAM (Memoria de Acceso Aleatorio de Video) que determina qué modelos de IA pueden ejecutarse efectivamente. Los modelos de IA requieren memoria sustancial para operar, y los modelos más grandes con mejores capacidades necesitan más VRAM.

### Cómo Verificar tu Memoria GPU

Puedes verificar tu memoria GPU usando:

* **Línea de comandos**: Ejecuta el comando `nvidia-smi`
* **Documentación de hardware**: Consulta las especificaciones del fabricante de tu GPU

La salida de `nvidia-smi` mostrará tu modelo de GPU y la capacidad total de memoria.

## Guía de Inicio Rápido

### Paso 1: Identifica tu Memoria GPU

Ejecuta el siguiente comando para verificar tu memoria GPU disponible:

```bash theme={null}
nvidia-smi
```

Busca la columna "Memory" para encontrar tu VRAM total.

### Paso 2: Selecciona el Preset Apropiado

Basado en tu memoria GPU, elige el preset correspondiente:

| Memoria GPU | Preset a Usar | Ejemplo de Hardware |
| - | - | - |
| 32GB | `baseline-32g` | RTX 5090 |
| 48GB | `baseline-48g` | RTX A6000, A40, L40 |
| 96GB | `baseline-96g` | A100 80GB, H100 |

> [!TIP]
>
> Siempre selecciona un preset que coincida o sea menor que tu VRAM disponible.

### Paso 3: Configura tu Sistema

Edita tu archivo de configuración de Zylon en `/etc/config/zylon-config.yaml`:

```yaml theme={null}
ai:
  preset: "baseline-48g"  # Reemplaza con tu preset seleccionado
```

### Paso 4: Aplica la Configuración

Después de modificar el archivo de configuración, reinicia los servicios de Zylon para aplicar los cambios:

```bash theme={null}
# Reinicio de despliegue de Triton
kubectl rollout restart deploy/zylon-triton
```

### Paso 5: Verifica la Instalación

Verifica que el motor de inferencia se inició exitosamente:

```bash theme={null}
# Verifica los logs para carga exitosa del modelo
 kubectl logs deploy/zylon-triton -n zylon --tail=100
```

Busca mensajes de log que indiquen inicialización exitosa del modelo.

## ¿Qué sigue?

* Explora [presets disponibles](/es/v1.58/operator-manual/ai-presets/presets) para encontrar configuraciones especializadas
* Aprende sobre [opciones de configuración](/es/v1.58/operator-manual/ai-presets/configuration) para multi-GPU y capacidades
* Sumérgete en [personalización avanzada](/es/v1.58/operator-manual/ai-presets/advanced-customization) para modelos personalizados
* Soluciona problemas comunes en la [guía de solución de problemas](/es/v1.58/operator-manual/ai-presets/troubleshooting)


# Referencia de Presets de IA
Source: https://docs.zylon.ai/es/v1.58/operator-manual/ai-presets/presets

Referencia completa de presets de IA disponibles incluyendo configuraciones base, alternativas, experimentales y deprecadas

Establece el preset de IA en tu archivo de configuración de Zylon usando la propiedad `ai.preset`.

## Presets Base

Los presets base proporcionan configuraciones estándar optimizadas para cargas de trabajo de IA de propósito general.

| Preset | Memoria GPU Requerida | Ejemplos de Hardware Compatible | Modelos |
| - | - | - | - |
| `baseline-32g` | 32GB | RTX 5090 | cyankiwi/qwen3.5-9b-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `baseline-48g` | 48GB | RTX A6000, A40, L40, L40s | txn545/qwen3.5-35b-a3b-nvfp4, mixedbread-ai/mxbai-embed-large-v1 |
| `baseline-96g` | 96GB | A100 80GB, H100, A6000 (dual) | nvidia/Qwen3.8-27B-NVFP4, mixedbread-ai/mxbai-embed-large-v1 |

### Ejemplo de Configuración

```yaml theme={null}
ai:
  preset: "baseline-48g"  # Para un sistema con L40s (48GB)
```

> [!TIP]
>
> Elige el preset que coincida con la capacidad de memoria de tu GPU. Siempre selecciona un preset que coincida o sea menor que tu VRAM disponible.

## Presets Alternativos

Zylon proporciona presets alternativos que ofrecen configuraciones especializadas intercambiando ciertas capacidades por otras. Estos son opcionales y solo deben usarse cuando tienes requisitos específicos que difieren de los presets estándar.

### Alternativa Optimizada para Throughput

Este preset utiliza un modelo más pequeño y ligero que genera tokens significativamente más rápido. Aunque puede no igualar al modelo estándar en calidad y profundidad de razonamiento, pero a cambio ofrece respuestas notablemente más rápidas.

**Cuándo usar:**

* Principalmente manejas consultas sencillas o directas
* Tienes un alto número de usuarios concurrentes y necesitas tiempos de respuesta rápidos
* La velocidad de generación importa más que la máxima calidad de respuesta

| Preset | Memoria GPU Requerida | Modelos |
| - | - | - |
| `baseline-throughput-96g` | 96GB (A100 80GB, H100, A6000 dual) | txn545/qwen3.5-35b-a3b-nvfp4, mixedbread-ai/mxbai-embed-large-v1 |

### Alternativa de Modelo Grande

Este preset utiliza un modelo más grande y capaz, con mayor conocimiento intrínseco. La contrapartida es una ventana de contexto más reducida.

**Cuándo usar:**

* Necesitas mayor rendimiento en tareas complejas o especializadas
* El conocimiento intrínseco del modelo es prioritario
* Puedes trabajar con una ventana de contexto más pequeña

| Preset | Memoria GPU Requerida | Modelos |
| - | - | - |
| `baseline-large-96g` | 96GB (A100 80GB, H100, A6000 dual) | cyankiwi/Qwen3.5-122B-A10B--4bit, mixedbread-ai/mxbai-embed-large-v1 |

### Ejemplo de Configuración

```yaml theme={null}
ai:
  preset: "alternatives.baseline-throughput-96g"
```

> [!NOTE]
>
> Cada preset alternativo implica una compensación. Considera tu caso de uso específico — volumen de usuarios, complejidad de las consultas y necesidades de contexto — antes de cambiar del preset estándar.

## Presets Experimentales

> [!WARNING]
>
> Los presets experimentales están en desarrollo activo y pueden no ser estables. Usa solo en entornos de prueba.

Los presets experimentales proporcionan acceso a modelos y configuraciones de vanguardia que están siendo evaluados para futuras versiones. Estos presets pueden tener características de rendimiento o estabilidad diferentes comparados con los presets base.

| Preset | Memoria GPU Requerida | Familia de Modelo | Estado | Modelos |
| - | - | - | - | - |
| `experimental.mistral-24g` | 24GB | Mistral | Beta | mistralai/mistral-small-24b-instruct-2501-awq, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.mistral-48g` | 48GB | Mistral | Beta | mistralai/mistral-small-24b-instruct-2501-awq, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gpt-oss-24g` | 24GB | GPT-OSS | Beta | openai/gpt-oss-20b, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gpt-oss-48g` | 48GB | GPT-OSS | Beta | openai/gpt-oss-20b, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gpt-oss-96g` | 96GB | GPT-OSS | Beta | openai/gpt-oss-120b, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gemma-24g` | 24GB | Gemma 3 | Alpha | google/gemma-3n-e4b-it, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-instruct-24g` | 24GB | Mistral | Alpha | cyankiwi/ministral-3-14b-instruct-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-instruct-48g` | 48GB | Mistral | Alpha | cyankiwi/ministral-3-14b-instruct-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-reasoning-24g` | 24GB | Mistral | Alpha | cyankiwi/ministral-3-14b-reasoning-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-reasoning-48g` | 48GB | Mistral | Alpha | cyankiwi/ministral-3-14b-reasoning-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `nemotron-3-nano-48g` | 48GB | Nemotron | Alpha | stelterlab/nvidia-nemotron-3-nano-30b-a3b-awq, mixedbread-ai/mxbai-embed-large-v1 |
| `glm-47-flash-32g` | 32GB | GLM | Alpha | cyankiwi/glm-4.7-flash-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `glm-47-flash-48g` | 48GB | GLM | Alpha | cyankiwi/glm-4.7-flash-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |

**Ejemplo de Configuración:**

```yaml theme={null}
ai:
  preset: "experimental.gpt-oss-24g"
```

### Notas Importantes Sobre Presets Experimentales

* Los presets experimentales pueden ser eliminados o cambiados significativamente entre versiones
* El rendimiento y la estabilidad no están garantizados
* No recomendados para entornos de producción
* Pueden requerir parámetros de configuración adicionales
* El soporte puede ser limitado

## Presets Deprecados

> [!WARNING]
>
> Los presets deprecados se mantienen solo para compatibilidad hacia atrás y no recibirán actualizaciones.

Para clientes que requieren configuraciones más antiguas, los presets deprecados están disponibles pero no se recomiendan para nuevas instalaciones.

| Preset | Memoria GPU | Descripción |
| - | - | - |
| `deprecated.24g.20250710` | 24GB | Configuración Pre-Qwen 3 |
| `deprecated.24g.20260327` | 24GB | Configuración Pre-Qwen 3.5 |
| `deprecated.32g.20250710` | 32GB | Configuración Pre-Qwen 3 |
| `deprecated.32g.20260327` | 32GB | Configuración Pre-Qwen 3.5 |
| `deprecated.48g.20250710` | 48GB | Configuración Pre-Qwen 3 |
| `deprecated.48g.20260327` | 48GB | Configuración Pre-Qwen 3.5 |
| `deprecated.48g.20260327-context` | 48GB | Configuración optimizada para contexto Pre-Qwen 3.5 |
| `deprecated.48g.20260327-vision` | 48GB | Configuración optimizada para visión Pre-Qwen 3.5 |
| `deprecated.96g.20250710` | 96GB | Configuración Pre-Qwen 3 |
| `deprecated.96g.20260327` | 96GB | Configuración Pre-Qwen 3.5 |
| `deprecated.96g.20260327-context` | 96GB | Configuración optimizada para contexto Pre-Qwen 3.5 |
| `deprecated.96g.20260327-vision` | 96GB | Configuración optimizada para visión Pre-Qwen 3.5 |
| `deprecated.96g.qwen3-32b-96g` | 96GB | Configuración Qwen 3 32B Pre-Qwen 3.5 |
| `deprecated.96g.20261008` | 96GB | Configuración Pre-Qwen 3.8 (Qwen 3.5 27B) |

**Ejemplo de Configuración:**

```yaml theme={null}
ai:
  preset: "deprecated.24g.20260327"
```

### Migración desde Presets Deprecados

Si estás usando un preset deprecado, recomendamos encarecidamente migrar a presets base o alternativos actuales:

1. Revisa los [presets base](#presets-base) para encontrar una configuración equivalente
2. Prueba el nuevo preset en un entorno de staging
3. Actualiza tu configuración de producción
4. Monitorea el rendimiento y ajusta si es necesario

La migración proporciona acceso a modelos mejorados, mejor rendimiento y soporte continuo.


# Solución de Problemas
Source: https://docs.zylon.ai/es/v1.58/operator-manual/ai-presets/troubleshooting

Diagnostica y resuelve problemas con presets de IA y configuraciones personalizadas

## Problemas Comunes

### El Motor Falla al Iniciar con Error de Memoria

**Soluciones:**

1. **Verifica tu memoria GPU real**
   ```bash theme={null}
   nvidia-smi
   ```

2. **Prueba el siguiente preset inferior**
   ```yaml theme={null}
   # Si estás usando baseline-32g, prueba baseline-48g en su lugar
   ai:
     preset: "baseline-48g"
   ```

3. **Elimina capacidades opcionales para reducir el uso de memoria**
   ```yaml theme={null}
   # Elimina capacidades
   ai:
     preset: "baseline-48g"  # En lugar de "baseline-48g,capabilities.multilingual"
   ```

4. **Verifica otras aplicaciones usando memoria GPU**

5. **Reinicia la máquina**

### Rendimiento Pobre o Respuestas Lentas

**Soluciones:**

1. **Asegúrate de estar usando el preset correcto para tu hardware**

2. **Considera disminuir a un preset de nivel inferior**

3. **Comunícate con los ingenieros de Zylon para entender qué está pasando**

### Pod en Estado Fallido o CrashLoopBackOff

Si los pods de Triton o inferencia están atascados en un estado fallido:

```bash theme={null}
# Reinicia el despliegue
kubectl rollout restart deploy/zylon-triton -n zylon
```

Esto fuerza a Kubernetes a recrear los pods con un estado fresco.

***

## Problemas Avanzados

Problemas específicos de configuraciones de modelos personalizados y configuraciones multi-modelo.

### Fallos de Inicio

#### El Servidor de Inferencia Triton Falla al Iniciar

**Soluciones:**

1. **Verifica los logs de Triton para identificar qué modelo específico está causando el fallo**
   ```bash theme={null}
   kubectl logs deploy/zylon-triton -n zylon --tail=200
   ```

2. **Verifica la asignación de memoria para el modelo problemático** - ajusta `gpuMemoryUtilization` si es necesario

3. **Si has reducido demasiado la asignación de memoria, reduce el parámetro `contextWindow` para ese modelo**

4. **Usa `nvidia-smi` para verificar el uso y disponibilidad real de memoria GPU**
   ```bash theme={null}
   nvidia-smi
   ```

#### Versión de Modelo No Soportada

**Síntoma**: Triton falla al cargar un modelo aunque la familia del modelo esté soportada.

**Causa**: VLLM (el backend de inferencia) puede no soportar la versión específica de tu modelo aún. Por ejemplo:

* Mistral Small 3 (2501) está soportado
* Mistral Small 3 (2509) podría no estar soportado aún

**Soluciones:**

1. **Verifica la versión del modelo soportada** en la documentación

2. **Prueba una versión anterior** de la misma familia de modelo si está disponible

3. **Verifica las notas de lanzamiento de Zylon** para versiones de modelos soportadas

4. **Contacta a los ingenieros de Zylon** para confirmar la compatibilidad del modelo

### Errores de Memoria

#### El Motor Falla al Iniciar con Error "Out of Memory"

**Soluciones:**

1. **Verifica que el total de `gpuMemoryUtilization` no exceda 0.95**
   ```yaml theme={null}
   # Calcula el total en todos los modelos
   ai:
     config:
       models:
         - id: llm
           gpuMemoryUtilization: 0.60
         - id: llmvision
           gpuMemoryUtilization: 0.25
         - id: embed
           gpuMemoryUtilization: 0.10
   # Total: 0.95 ✓
   ```

2. **Reduce la asignación para uno o más modelos basado en los logs de fallo**
   ```bash theme={null}
   kubectl logs deploy/zylon-triton -n zylon
   ```

3. **Verifica la memoria GPU real con `nvidia-smi`** durante el inicio
   ```bash theme={null}
   watch -n 1 nvidia-smi
   ```


# Auditabilidad y gobernanza de IA
Source: https://docs.zylon.ai/es/v1.58/operator-manual/auditability-ai-safety/overview

Auditabilidad, trazabilidad, preservacion de evidencia, gobernanza y capacidades de responsabilidad de IA en Zylon.

## Resumen

Auditabilidad y gobernanza de IA cubre transparencia, responsabilidad, preparacion de auditoria y fuentes de evidencia para despliegues Zylon. Es distinto de seguridad de plataforma: seguridad protege la plataforma; auditabilidad explica como los clientes pueden demostrar que ocurrio, preservar evidencia, gobernar el uso de IA y apoyar flujos de assurance.

Use esta seccion cuando equipos de seguridad, riesgo, cumplimiento, legal, works council o auditoria necesiten entender que registra Zylon, como puede preservarse evidencia, que controles son configurables por el cliente y como Zylon puede aportar evidencia para programas de gobernanza del cliente.

> [!NOTE]
>
> ¿Quieres conectar un SIEM? Empieza con [Enviar logs a tu SIEM](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#enviar-logs-a-tu-siem), con el archivo de configuración, ejemplo HTTP, comando para aplicar cambios y pasos de verificación. Esta página explica las capacidades de gobernanza y evidencia.

## Areas de capacidad

| Area | Que proporciona Zylon | Uso del cliente |
| - | - | - |
| Auditabilidad y trazabilidad | Logs estructurados de auditoria, seguridad, backoffice, gateway y ciclo de vida de IA. | Reconstruir quien actuo, que se solicito, que se respondio, que herramientas fueron visibles y que organizacion o proyecto participo. |
| Preservacion de evidencia | Almacenamiento interno, controles de limpieza por retencion y entrega externa a colectores controlados por el cliente. | Preservar logs para investigaciones, auditorias, legal hold y respuesta a incidentes segun politica. |
| Responsabilidad de IA | Metadatos de ciclo de vida de chat, recuperacion opcional de prompts/respuestas, uso de tokens, herramientas usadas, latencia y resultado. | Revisar uso de IA, explicar comportamiento operativo y apoyar supervision humana. |
| Transparencia operativa | Recuperacion por API de Backoffice, vistas de uso, entrega syslog, entrega HTTP y enlaces de observabilidad. | Alimentar SIEM, data lake, monitoreo y flujos de auditoria. |
| Residencia de datos | El comportamiento predeterminado de almacenamiento conserva los logs almacenados en el despliegue Zylon del cliente salvo que se configure entrega externa. | Apoyar requisitos soberanos, on-premise y regulados. |
| Derechos de usuario y retencion | Retencion configurable y guia para tratar datos personales en logs. | Alinear retencion de auditoria con GDPR, works council, legal y minimizacion de datos. |
| Mapeo de controles | Guia de mapeo de evidencia para EU AI Act, ISO 27001, SOC 2, DORA, NIS2 y GDPR. | Preparar procurement, revision de riesgo y conversaciones de evidencia de control sin tratar los logs de Zylon como cumplimiento independiente. |

## Empezar aqui

> **[Logging, evidencia y entrega a SIEM](/es/v1.58/operator-manual/backoffice/log-delivery-storage)**
>
> Vista de gobernanza de logs, preservacion de evidencia, residencia de datos, mapeo de controles, retencion y entrega a SIEM.

> **[Configuracion de entrega de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage)**
>
> Ajustes tecnicos de almacenamiento interno, entrega syslog, entrega HTTP, filtros, colas, TLS y limpieza por retencion.

> **[Borrado permanente y retencion](/es/v1.58/operator-manual/configuration/cron-tasks/hard-delete)**
>
> Configure ventanas de borrado permanente y comportamiento de limpieza de logs almacenados.

> **[Registro de auditoria](/es/v1.58/operator-manual/configuration/features/feat-audit)**
>
> Habilite eventos y trazas de auditoria y conectelos con almacenamiento interno de logs.

## Flujo de gobernanza sugerido

1. Clasifique sus casos de uso de IA y decida que eventos, prompts, respuestas, metricas de uso y registros operativos deben retenerse.
2. Habilite capacidades de auditoria y logging requeridas, luego configure ventanas de retencion y entrega externa.
3. Envie logs a un SIEM, archivo o data lake controlado por el cliente cuando se requiera retencion independiente o evidencia anti-manipulacion.
4. Defina quien puede recuperar logs, como se aprueban exportaciones y como se revisan los eventos registrados de recuperacion.
5. Mapee la evidencia recopilada a su marco de control, como EU AI Act, ISO 27001, SOC 2, DORA, NIS2 o GDPR.
6. Revise retencion, masking, tratamiento de prompts/respuestas y procesos de derechos de usuario antes de produccion.

## Limite con seguridad

La documentacion de seguridad sigue centrada en endurecer el despliegue: aislamiento de red, operacion airgap, cifrado, controles de acceso y proteccion de plataforma.

Auditabilidad y gobernanza de IA se centra en prueba y responsabilidad: trazabilidad, evidencia, monitoreo, mapeo de controles, revision de uso de IA y preparacion regulatoria. Muchos programas necesitan ambas secciones durante procurement y assurance en produccion.


# Autenticación con Directorio LDAP
Source: https://docs.zylon.ai/es/v1.58/operator-manual/authentication/ldap

Configura Zylon para autenticar usuarios contra un directorio LDAP o Active Directory, permitiendo el inicio de sesión centralizado sin necesidad de un proveedor de identidad externo.

La autenticación LDAP permite a los usuarios iniciar sesión en Zylon con sus credenciales de directorio existentes, ya sea en un servidor LDAP estándar o en Microsoft Active Directory. Como LDAP no requiere conexión a proveedores de identidad externos como Google o Microsoft, es el método de autenticación recomendado para despliegues en air-gap y estrictamente en instalaciones locales.

> [!NOTE]
>
> Esta página cubre únicamente la configuración del operador. No hay configuración disponible a través de la interfaz de usuario; todos los ajustes se aplican mediante el archivo de configuración ubicado en `/etc/zylon/zylon-conf.yaml`.

***

## Prerrequisitos

Antes de habilitar LDAP, confirma lo siguiente:

* El host LDAP o Active Directory es accesible desde el clúster de Zylon en el puerto en el que tu servidor está configurado para escuchar.
* Existe una **cuenta de servicio de solo lectura** en el directorio. Zylon utiliza esta cuenta (la cuenta de bind) para buscar usuarios y resolver la pertenencia a grupos. No necesita permisos de escritura.
* Conoces el **Base DN** bajo el cual residen todos los usuarios y grupos (por ejemplo, `dc=empresa,dc=local`).
* Tienes los **Distinguished Names (DNs)** de los grupos de directorio que deseas mapear a roles de Zylon.

***

## Cómo funciona el inicio de sesión

Cuando LDAP está habilitado, los usuarios continúan usando el formulario de inicio de sesión estándar de Zylon. No hay una página de inicio de sesión LDAP separada.

1. El usuario introduce su nombre de usuario del directorio en el campo de email y su contraseña de directorio.
2. Zylon normaliza el nombre de usuario: el prefijo `DOMAIN\user` se convierte a `user`; una dirección de email (`user@empresa.com`) y un nombre de usuario simple (`user`) se usan tal cual.
3. Zylon busca el usuario en el directorio y luego realiza un bind para verificar la contraseña.
4. En caso de éxito, Zylon resuelve los grupos del directorio del usuario y los mapea a roles de Zylon usando la configuración de `roleMapping`.
5. Si la cuenta no existe aún en Zylon, se **crea automáticamente** con los roles derivados de la pertenencia a grupos.

> [!NOTE]
>
> Los roles se asignan en el momento de la creación de la cuenta. Si la pertenencia a grupos del directorio de un usuario cambia después de su primer inicio de sesión, los roles de Zylon no se actualizan automáticamente. Para cambiar los roles de un usuario después de la creación, actualízalos a través del Backoffice. Consulta [Roles y Permisos](/es/v1.58/operator-manual/backoffice/roles-and-permissions) para más detalles.

> [!NOTE]
>
> Si LDAP está habilitado y el directorio no está disponible temporalmente o devuelve un error, Zylon recurre a la autenticación con credenciales locales.

***

## Configuración

Si LDAP está habilitado y falta algún campo requerido o es inválido, la aplicación **rechazará iniciarse** y registrará un error descriptivo. Esto evita que despliegues mal configurados fallen silenciosamente.

### `/etc/zylon/zylon-conf.yaml`

Añade el bloque `auth.ldap` al archivo de configuración:

> [!WARNING]
>
> El archivo de configuración es un archivo `.yaml`, por lo que la indentación, los espacios y las comillas son importantes. Revisa cuidadosamente antes de guardar.

```yaml theme={null}
auth:
  ldap:
    enabled: true
    host: "ldap.empresa.local"
    port: "389"
    tls:
      enabled: false
      caCrt: ""
      caFile: ""
    bindDn: "cn=LDAP Bind,ou=service,dc=empresa,dc=local"
    bindPassword: "CAMBIA_ESTO"
    baseDn: "dc=empresa,dc=local"
    userFilter: "(|(sAMAccountName={username})(userPrincipalName={username})(mail={username}))"
    groupFilter: "(member={userDn})"
    attributes:
      username: "sAMAccountName"
      email: "mail"
      group: "memberOf"
    roleMapping:
      defaultRole: "Workspace"
      mappings: '[{"match":"CN=admins,OU=groups,DC=empresa,DC=local","role":"Operator"},{"match":"CN=developers,OU=groups,DC=empresa,DC=local","role":"Developer"},{"match":"CN=workspace-users,OU=groups,DC=empresa,DC=local","role":"Workspace"}]'
```

Aplica los cambios:

```bash theme={null}
sudo zylon-cli sync
```

***

## Referencia de configuración

La tabla a continuación lista todos los ajustes de LDAP, su valor por defecto en el chart, y si son obligatorios cuando `enabled` es `true`.

| Clave | Por defecto | Requerido | Descripción |
| - | - | - | - |
| `enabled` | `false` | - | Establece a `true` para activar la autenticación LDAP. La aplicación no iniciará si está habilitado con una configuración inválida. |
| `host` | `""` | Sí | Nombre de host o dirección IP del servidor LDAP o Active Directory. |
| `port` | `"389"` | Sí | Puerto como cadena de texto. Debe coincidir con el puerto en el que escucha tu servidor LDAP. Los valores comunes son `389` para LDAP simple y `636` para LDAPS, pero tu servidor puede estar configurado de forma diferente. |
| `tls.enabled` | `false` | No | Establece a `true` para abrir una conexión LDAPS. |
| `tls.caCrt` | `""` | No | Certificado CA como cadena de texto en línea. Se utiliza para verificar el certificado TLS del servidor LDAP. Tiene precedencia sobre `tls.caFile` si ambos están establecidos. |
| `tls.caFile` | `""` | No | Ruta al archivo de certificado CA en el host. Se utiliza cuando el certificado está montado como archivo en lugar de pasarse en línea. Se ignora si `tls.caCrt` está establecido. |
| `bindDn` | `""` | Sí | Distinguished Name completo de la cuenta de servicio utilizada para buscar en el directorio. Ejemplo: `cn=LDAP Bind,ou=service,dc=empresa,dc=local`. |
| `bindPassword` | `""` | Sí | Contraseña de la cuenta de bind. |
| `baseDn` | `""` | Sí | Raíz del subárbol del directorio donde se realizan las búsquedas de usuarios y grupos. Ejemplo: `dc=empresa,dc=local`. |
| `userFilter` | `(\|(sAMAccountName={username})(userPrincipalName={username})(mail={username}))` | No | Filtro LDAP utilizado para localizar la entrada del usuario. Debe contener `{username}`, que se reemplaza con el nombre de inicio de sesión normalizado en tiempo de ejecución. El filtro por defecto apunta a Active Directory y admite los formatos `sAMAccountName`, UPN y mail. |
| `groupFilter` | `(member={userDn})` | No | Filtro LDAP utilizado para encontrar grupos cuando `memberOf` no está poblado en la entrada del usuario. Debe contener `{userDn}`. |
| `attributes.username` | `sAMAccountName` | No | Atributo del directorio a utilizar como nombre de visualización en Zylon. |
| `attributes.email` | `mail` | No | Atributo del directorio a utilizar como email de la cuenta en Zylon. Este atributo debe estar presente en cada entrada de usuario; si falta, el inicio de sesión es rechazado. |
| `attributes.group` | `memberOf` | No | Atributo del directorio en la entrada del usuario que lista la pertenencia a grupos. Si este atributo está ausente o vacío, Zylon recurre a una búsqueda de grupos separada usando `groupFilter`. |
| `roleMapping.defaultRole` | `Workspace` | No | Rol asignado a un usuario cuando ningún mapeo de grupo coincide. Valores válidos: `Workspace`, `Developer`, `Operator`. |
| `roleMapping.mappings` | `""` | No | Array JSON en formato de cadena de texto con los mapeos de grupo a rol. Ver [Mapeo de roles](#mapeo-de-roles) más abajo. Cuando está vacío, todos los usuarios reciben `defaultRole`. |

## Mapeo de roles

El mapeo de grupo a rol se define como un **array JSON en formato de cadena de texto** en el campo `roleMapping.mappings`. El valor siempre debe ser una cadena codificada en JSON, tanto en `values.yaml` como en `zylon-conf.yaml`. Zylon evalúa el mapeo en el momento del inicio de sesión y asigna roles basándose en los grupos del directorio a los que pertenece el usuario.

```yaml theme={null}
roleMapping:
  mappings: '[{"match":"CN=admins,OU=groups,DC=empresa,DC=local","role":"Operator"},{"match":"CN=developers,OU=groups,DC=empresa,DC=local","role":"Developer"},{"match":"CN=workspace-users,OU=groups,DC=empresa,DC=local","role":"Workspace"}]'
```

**Comportamiento de la coincidencia:**

* Cada valor `match` se compara con todos los DN de grupo a los que pertenece el usuario. La comparación no distingue entre mayúsculas y minúsculas.
* Si un usuario pertenece a varios grupos mapeados, recibe todos los roles coincidentes.
* Si ningún mapeo coincide, el usuario recibe `defaultRole`.
* Varios grupos pueden mapearse al mismo rol; los duplicados se eliminan.

Para una descripción completa de lo que puede hacer cada rol, consulta [Roles y Permisos](/es/v1.58/operator-manual/backoffice/roles-and-permissions).

> [!NOTE]
>
> Los roles se calculan una sola vez en la creación de la cuenta (primer inicio de sesión). Los cambios posteriores en la pertenencia a grupos del directorio no se reflejan automáticamente en Zylon. Actualiza los roles manualmente a través del Backoffice si es necesario.

***

## Notas sobre Active Directory

La configuración por defecto apunta a Active Directory sin configuración adicional:

* `userFilter` acepta inicios de sesión en tres formatos: nombre de usuario simple (`jdoe`), UPN (`jdoe@empresa.com`) y formato de dominio Windows (`DOMAIN\jdoe`, normalizado a `jdoe` antes de la búsqueda).
* `attributes.username` tiene por defecto `sAMAccountName` y `attributes.email` tiene por defecto `mail`, coincidiendo con los esquemas estándar de AD.
* La pertenencia a grupos se lee del atributo `memberOf` en la entrada del usuario.

Para servidores LDAP estándar (OpenLDAP, 389 Directory Server, etc.) normalmente necesitarás ajustar `userFilter`, `groupFilter` y `attributes.*` para que coincidan con tu esquema. Un punto de partida habitual:

```yaml theme={null}
userFilter: "(uid={username})"
groupFilter: "(member={userDn})"
attributes:
  username: "uid"
  email: "mail"
  group: "memberOf"
```

***

## Verificar la configuración

Después de aplicar la configuración, sigue estos pasos para confirmar que LDAP funciona correctamente:

**1. Confirma que la aplicación se inició correctamente**

Comprueba que el pod del backend está en ejecución. Si falta un campo requerido, el servicio no iniciará y registrará el campo específico que falló la validación.

**2. Prueba el inicio de sesión con un usuario del directorio**

Inicia sesión en el workspace de Zylon con una cuenta de usuario del directorio. Usa el nombre de usuario o el formato de dirección de email que admite tu directorio.

**3. Verifica los roles en el Backoffice**

Abre el Backoffice y localiza la cuenta recién creada. Confirma que tiene los roles esperados según la pertenencia a grupos del usuario y la configuración de `roleMapping`.

**4. Prueba cada grupo de roles**

Repite la prueba para al menos un usuario por grupo mapeado (Operator, Developer, Workspace) para confirmar que el mapeo de roles funciona correctamente en todos los grupos.

***

## Resolución de problemas

| Síntoma | Causa probable | Qué comprobar |
| - | - | - |
| La aplicación no inicia | Falta un campo requerido o `port` no es un entero válido | Comprueba los logs para el error de validación específico; confirma que `host`, `baseDn`, `bindDn`, `bindPassword` y `port` están todos configurados |
| El inicio de sesión falla para un usuario válido del directorio | Servidor inaccesible, `bindPassword` incorrecto, o `userFilter` no coincide con la entrada del usuario | Verifica la conectividad de red en el puerto configurado; prueba las credenciales de la cuenta de bind con un cliente LDAP; revisa `userFilter` |
| Error "Ambiguous LDAP user" al iniciar sesión | `userFilter` devuelve más de una entrada de directorio para el nombre de usuario | Ajusta el filtro para apuntar a un atributo único, o elimina los matchers de formato de inicio de sesión que se solapan |
| El inicio de sesión es exitoso pero el usuario tiene el rol incorrecto | El DN del grupo en `roleMapping.mappings` no coincide con el DN real del grupo (comprueba errores tipográficos, diferencias en la OU, o el formato del DN) | Compara los valores de `match` con los DN exactos de los grupos en tu directorio; la coincidencia no distingue mayúsculas/minúsculas pero la estructura del DN debe ser correcta |
| El inicio de sesión es exitoso pero el usuario solo tiene `defaultRole` | Ningún mapeo de grupo coincidió, o `mappings` está vacío | Comprueba que `memberOf` está poblado en la entrada del usuario; verifica la sintaxis JSON de `mappings` |
| El usuario LDAP no puede iniciar sesión - falta el email | El atributo `mail` (o el `attributes.email` configurado) está ausente en la entrada del directorio | Rellena el atributo de email para el usuario en el directorio, o actualiza `attributes.email` para que apunte a un atributo diferente que esté presente |
| Los usuarios parecen iniciar sesión con credenciales locales a pesar de que LDAP está habilitado | LDAP devolvió un error (servidor inaccesible, contraseña de bind incorrecta), activando el fallback | Comprueba la conectividad del servidor y las credenciales de la cuenta de bind; revisa los logs del backend para el error LDAP que causó el fallback |

***

## Consideraciones de seguridad

* Usa una cuenta de servicio **de solo lectura y con los mínimos privilegios** para las credenciales de bind. La cuenta necesita permiso de búsqueda en usuarios y grupos bajo `baseDn`, nada más.
* Habilita `tls.enabled: true` para cifrar las credenciales en tránsito. Proporciona `tls.caCrt` o `tls.caFile` para fijar tu CA.
* Los cambios en la pertenencia a grupos del directorio no se reflejan en Zylon después de la creación de la cuenta. Los operadores deben actualizar los roles manualmente en el Backoffice si cambia la pertenencia a grupos.

Para despliegues en air-gap, LDAP no requiere acceso a internet saliente. Consulta [Aislar tu Servidor](/es/v1.58/operator-manual/instance-hardening/airgap-your-server) para orientación sobre la configuración del firewall.


# Acceso al Backoffice
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/accessing-the-backoffice

Abre el Backoffice desde Workspace o por URL directa.

Hay dos formas de acceder al Backoffice. Ambas requieren una cuenta con permisos **Operator** o **Developer**.

1. **Desde la navegación de Workspace**
   Abre el menú de navegación izquierdo y selecciona **Platform Backoffice** o **Developer Console**. Estas opciones solo aparecen cuando tu cuenta tiene el rol requerido.

2. **Desde una URL directa**
   Navega a `https://<your_zylon_domain>/backoffice`. Serás redirigido a la pantalla de inicio de sesión del Backoffice.

Puedes iniciar sesión con:

* credenciales de cuenta de Zylon, o
* un proveedor SSO habilitado (por ejemplo, Google o Microsoft)

Después de iniciar sesión, puedes cambiar entre **Platform Backoffice**, **Developer Console** y **Workspace**.


# Guardrails
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/guardrails

Crea guardrails basados en regex y asígnalos a gateways para bloquear peticiones de IA que coincidan con patrones sensibles.

## Resumen

Los **Guardrails** permiten a los Operadores definir reglas que inspeccionan el tráfico de IA que pasa por un gateway. Cuando se activa un guardrail, la petición de IA se **bloquea** antes de llegar al modelo.

Los guardrails son útiles para evitar que datos sensibles o no conformes (como DNI, cuentas bancarias o tarjetas de crédito) se envíen a la IA, ayudándote a aplicar tus políticas de protección de datos y cumplimiento.

Cada guardrail:

* **Se asigna a uno o varios gateways**, por lo que solo se aplica al tráfico de esos gateways.
* **Se evalúa en cada petición de IA** gestionada por los gateways asignados.
* **Bloquea**: cuando el guardrail coincide, la petición se rechaza.

> [!NOTE]
>
> Por ahora, los guardrails solo admiten **expresiones regulares (regex)**. En el futuro podrían añadirse otros tipos de guardrail.

Solo los usuarios con rol **Operator** pueden gestionar guardrails. La disponibilidad y los límites dependen de la licencia activa.

## Cómo funcionan los guardrails

Un guardrail contiene uno o varios **patrones regex**. En cada petición de IA enrutada por un gateway asignado:

1. El contenido de la petición se comprueba contra los patrones regex del guardrail.
2. Si **cualquier** patrón coincide, el guardrail se activa.
3. La petición de IA se **bloquea** y no llega al modelo.

Como los guardrails de regex se ejecutan localmente como una coincidencia de texto, apenas añaden latencia a la petición.

## Crear un guardrail

Para crear un guardrail:

1. Abre **Guardrails** en el Backoffice de Plataforma.
2. Haz clic en **Add guardrail**.
3. Introduce un **nombre** y una **descripción** opcional.
4. Selecciona los **gateways** a los que se aplicará este guardrail.
5. Añade uno o varios patrones **regex**. Usa **Add regex** para definir varios patrones en el mismo guardrail.
6. Guarda el guardrail.

Una vez guardado, el guardrail queda activo en cada gateway asignado y empieza a bloquear las peticiones coincidentes de inmediato.

## Gestionar guardrails

Desde la lista de guardrails puedes revisar el nombre, la descripción, el tipo, el efecto y los gateways asignados de cada guardrail.

* **Edita** un guardrail para actualizar sus patrones o reasignarlo a otros gateways.
* **Elimina** un guardrail para dejar de bloquear peticiones.

## Ejemplos de regex

La siguiente tabla muestra patrones regex habituales que puedes usar como punto de partida para tus guardrails. Ajústalos para que coincidan con los formatos exactos que usa tu organización.

| Tipo de dato | Ejemplo de regex |
| - | - |
| DNI español | `\b\d{8}[A-Za-z]\b` |
| NIE español | `\b[XYZ]\d{7}[A-Za-z]\b` |
| IBAN (cuenta bancaria) | `\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b` |
| CCC español (cuenta bancaria) | `\b\d{4}[ -]?\d{4}[ -]?\d{2}[ -]?\d{10}\b` |
| Número de tarjeta de crédito | `\b(?:\d[ -]?){13,16}\b` |
| Dirección de correo electrónico | `\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b` |
| Número de teléfono (España) | `(?:\+34\|0034)?[ -]?[6-9]\d{2}[ -]?\d{3}[ -]?\d{3}` |
| Número de la Seguridad Social | `\b\d{2}[ -]?\d{8}[ -]?\d{2}\b` |
| Dirección IPv4 | `\b(?:\d{1,3}\.){3}\d{1,3}\b` |

### Snippets regex listos para copiar

Usa los siguientes bloques de código cuando quieras una acción de copia con un clic.

#### DNI español

```txt theme={null}
\b\d{8}[A-Za-z]\b
```

#### NIE español

```txt theme={null}
\b[XYZ]\d{7}[A-Za-z]\b
```

#### IBAN

```txt theme={null}
\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b
```

#### CCC español

```txt theme={null}
\b\d{4}[ -]?\d{4}[ -]?\d{2}[ -]?\d{10}\b
```

#### Número de tarjeta de crédito

```txt theme={null}
\b(?:\d[ -]?){13,16}\b
```

#### Dirección de correo electrónico

```txt theme={null}
\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b
```

#### Número de teléfono (España)

```txt theme={null}
(?:\+34|0034)?[ -]?[6-9]\d{2}[ -]?\d{3}[ -]?\d{3}
```

#### Número de la Seguridad Social

```txt theme={null}
\b\d{2}[ -]?\d{8}[ -]?\d{2}\b
```

#### Dirección IPv4

```txt theme={null}
\b(?:\d{1,3}\.){3}\d{1,3}\b
```

> [!WARNING]
>
> Los patrones regex coinciden exactamente como se escriben. Prueba siempre tus patrones con datos representativos para evitar falsos positivos (bloquear peticiones válidas) o falsos negativos (dejar pasar datos sensibles).


# Introducción
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/introduction

Visión general del Backoffice de Zylon.

El Backoffice de Zylon es el entorno de administración centralizado para gestionar la plataforma Zylon. Es independiente del Workspace y se usa para tareas de administración de plataforma y operaciones de desarrollo con API.

Las capacidades principales del Backoffice incluyen:

* Gestión de cuentas
* Gestión de roles y permisos
* Gestión de gateways
* Gestión de tokens de API
* Supervisión del estado de los servicios de la plataforma

El acceso al Backoffice requiere una cuenta válida con el rol adecuado:

* Rol **Operator** para administración de plataforma
* Rol **Developer** para flujos de tokens de API

Una misma cuenta puede tener varios roles. Las secciones visibles dependen de los roles asignados a esa cuenta.

> **[Backoffice de Plataforma](/es/v1.58/operator-manual/backoffice/platform-backoffice)**
>
> Controles de operador para cuentas, roles, gateways y estado del servicio.

> **[Panel de uso](/es/v1.58/operator-manual/backoffice/usage-dashboard)**
>
> Supervisa el uso de IA por gateways, tokens de API y actividad de Workspace.

> **[Monitor del sistema](/es/v1.58/operator-manual/backoffice/system-monitor)**
>
> Consulta en vivo la presión sobre los recursos del host y la actividad del servicio de modelos.

> **[Roles y permisos](/es/v1.58/operator-manual/backoffice/roles-and-permissions)**
>
> Comprende roles de cuenta, roles de gateway y niveles de acceso.

> **[Cuentas](/es/v1.58/operator-manual/backoffice/platform-backoffice#cuentas)**
>
> Crea cuentas, asigna roles y gestiona accesos.

> **[Gateways](/es/v1.58/operator-manual/backoffice/platform-backoffice#gateways)**
>
> Gestiona nodos de software aislados para desarrollo con API.

> **[Logging, evidencia y entrega a SIEM](/es/v1.58/operator-manual/backoffice/log-delivery-storage)**
>
> Revisa auditabilidad, trazabilidad, preservacion de evidencia, almacenamiento, entrega a SIEM y acceso operativo.

> **[Developer Console](/es/v1.58/developer-manual/get-started/developer-console)**
>
> Crea y gestiona tokens de API por gateway.

> **[Crear token de API](/es/v1.58/developer-manual/get-started/developer-console#crear-token-de-api)**
>
> Genera y almacena de forma segura un secreto de token de un solo uso.


# Logging, evidencia y entrega a SIEM
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/log-delivery-storage

Guia de gobernanza para logging, preservacion de evidencia, auditabilidad, trazabilidad y entrega a SIEM en Zylon.

## Resumen

Zylon registra eventos estructurados de auditoria, seguridad, aplicacion y ciclo de vida de chats de IA cuando el almacenamiento o la entrega de logs estan habilitados. Los operadores pueden usar estos logs para investigar que ocurrio, quien lo inicio, que se solicito, que se respondio y que herramientas o rutas de datos observables se usaron.

Zylon puede:

* Almacenar logs estructurados internamente cuando `logging.storage.enabled` esta habilitado.
* Enviar logs a SIEMs y colectores mediante syslog, incluidos RFC 5424 JSON y CEF.
* Enviar logs JSON estructurados a destinos HTTP.
* Permitir que usuarios autorizados de Backoffice recuperen logs almacenados manualmente.

**El comportamiento predeterminado de almacenamiento de logs conserva los logs almacenados dentro del despliegue Zylon del cliente salvo que se configure entrega externa de logs.** Los operadores deben confirmar por separado la configuracion especifica del despliegue para observabilidad, telemetria y crash reporting.

Para conectar tu SIEM, sigue [Enviar logs a tu SIEM](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#enviar-logs-a-tu-siem). La guía cubre el colector, archivo de configuración, comando para aplicar cambios y primer evento de prueba. Esta página cubre evidencia, gobernanza y retención.

La captura de contenido de chat del gateway, el almacenamiento interno y la entrega externa son controles independientes. La captura de contenido y el almacenamiento están habilitados por defecto; syslog y HTTP deben habilitarse explícitamente. Los eventos de Workspace, Backoffice y seguridad se emiten independientemente del flag de contenido de chat. La API de Backoffice es una alternativa para recuperar logs almacenados; no es necesaria para configurar la entrega push.

> [!NOTE]
>
> La entrega externa es asincrona. Con `failurePolicy=drop`, la entrega evita bloquear el camino critico cuando las colas estan bajo presion.

## Antes de configurar la entrega

* Confirme que logs deben almacenarse en Zylon y que logs deben entregarse a sistemas controlados por el cliente.
* Confirme el host y puerto del colector syslog, o la URL del colector HTTP, desde la red del despliegue Zylon.
* Seleccione syslog `rfc5424_json`, syslog `cef` o HTTP `canonical_json` segun el input del colector.
* Decida si se requiere verificacion de certificados TLS y prepare una ruta CA confiable si hace falta.
* Decida la retencion en el almacenamiento interno de Zylon y en sistemas externos.
* Revise filtros de accion y organizacion para no excluir eventos de auditoria requeridos.
* Confirme que los nodos de Zylon usan una fuente horaria confiable como NTP. La correlacion forense depende de relojes sincronizados y revision en UTC.

## Que registra Zylon

Zylon almacena un sobre de log compartido y datos estructurados especificos del evento. Los campos exactos dependen de la familia de evento y de los ajustes de logging habilitados.

| Categoria | Ejemplos de campos almacenados | Por que importa |
| - | - | - |
| Contexto de actor | Identificadores de usuario, cuenta, token y tipo de actor | Ayuda a determinar quien o que inicio una accion. |
| Contexto de organizacion y proyecto | Identificadores de organizacion, gateway y proyecto | Ayuda a acotar la investigacion a un workspace, gateway o proyecto. |
| Contexto de chat de IA | Metadatos de request, respuesta, tokens, latencia y uso de herramientas cuando auditoria los captura | Ayuda a reconstruir el ciclo de vida observable del chat. |
| Eventos de seguridad y auditoria | Fallos de autenticacion, tokens invalidos o expirados, creacion de cuentas, login, reset de password, creacion o borrado de tokens API, recuperacion de logs | Soporta revision de seguridad y monitoreo de acceso. |
| Tiempo y resultado | Inicio, fin, error, resultado y severidad | Ayuda a correlacionar eventos e identificar fallos. |
| Metadatos de entrega | Esquema externo, severity, outcome, actor y entorno para syslog | Ayuda a clasificar eventos en SIEM y colectores. |

> [!WARNING]
>
> Las claves sensibles se enmascaran antes de almacenar los datos de entrada de las solicitudes. Los valores enmascarados se guardan como `***`: los logs de Zylon no conservan un hash, un token ni sus últimos cuatro caracteres. La información de usuario de las URI contenidas en valores de texto también se oculta antes del almacenamiento.

> **Claves de request enmascaradas**
>
> Zylon enmascara estos nombres exactos de clave de request antes de almacenar: `password`, `new_password`, `current_password`, `secret`, `api_key`, `apikey`, `private_key`, `privatekey`, `token`, `id_token`, `access_token`, `refresh_token`, `session_token`, `bearer_token`, `client_secret`, `secret_key`, `credentials`, `connection_string`, `cookie`, `set_cookie` y `authorization`.
>
> Zylon tambien enmascara claves que terminan en `_token`, `_password`, `_secret`, `_credential`, `_credentials`, `_connection_string` o `_cookie`.

## Confianza e integridad

Los logs almacenados deben tratarse como registros operativos con una superficie de recuperacion Backoffice de solo lectura:

* El acceso documentado a logs de Backoffice es solo para recuperacion.
* La recuperacion de logs mediante Backoffice tambien queda registrada, para que los operadores puedan revisar quien accedio a registros de plataforma o gateway.
* No hay flujo documentado de UI o API de Backoffice para que un operador modifique o borre un registro individual.
* La ruta documentada de borrado de logs almacenados es la limpieza de retencion configurada.
* La limpieza esta deshabilitada por defecto. Cuando se habilita, el umbral predeterminado es `180` dias.

Zylon no documenta una cadena criptografica de hashes, una cadena de firmas o un almacenamiento interno de logs con evidencia anti-manipulacion. Para mayor evidencia anti-manipulacion, entregue logs a un SIEM o archivo append-only controlado por el cliente, restrinja acceso de administradores de base de datos, conserve backups y monitorice auditoria de Kubernetes/base de datos. El acceso directo a base de datos por administradores de infraestructura queda fuera del modelo de permisos de Backoffice.

### Administracion del sistema de logging

El almacenamiento, retencion y entrega de logs son configuracion del despliegue. Cambios como deshabilitar almacenamiento, reducir retencion o cambiar destinos de entrega deben capturarse en change management, historial GitOps, auditoria Kubernetes o logs de infraestructura del cliente.

## Auditabilidad de IA

Zylon proporciona auditabilidad del ciclo de vida observable del chat y de acciones visibles para el agente. Los logs pueden ayudar a reconstruir:

* quien inicio un chat;
* que organizacion, gateway o proyecto participo;
* que metadatos de request se almacenaron;
* que respuesta se almaceno cuando auditoria la capturo;
* que herramientas fueron visibles en el payload de respuesta;
* que acciones, integraciones, archivos, chats y proyectos se usaron.

> [!NOTE]
>
> Zylon registra entradas, salidas, acciones, herramientas, rutas de datos, actores y eventos de sistema observables. No expone razonamiento interno privado o propietario salvo que ese razonamiento se haya emitido y almacenado explicitamente como parte de la respuesta.

## Logging y trazabilidad para EU AI Act

El logging de Zylon puede apoyar flujos de trazabilidad y record-keeping para EU AI Act, segun la configuracion y el despliegue. Debe tratarse como una fuente tecnica de evidencia dentro de un programa mas amplio de gobierno, monitoreo y retencion.

| Tema relacionado | Como ayuda Zylon | Responsabilidad del cliente |
| - | - | - |
| Logging automatico | Zylon registra eventos configurados de auditoria, seguridad, aplicacion y ciclo de vida de chats. | Habilitar almacenamiento o entrega para los eventos requeridos y confirmar cobertura. |
| Trazabilidad | Los logs ayudan a reconstruir actores, timestamps, prompts o datos de request, respuestas, herramientas y contexto de organizacion/proyecto. | Mantener controles de acceso y decidir que campos se conservan. |
| Monitoreo | Los logs pueden revisarse mediante recuperacion de logs en Backoffice o entregarse a SIEM/syslog/HTTP. La actividad de recuperacion de logs tambien queda registrada para revision posterior. | Configurar monitoreo, alertas, revisiones y escalado. |
| Investigacion | Los logs soportan revision de incidentes en usuarios, tokens, workspace, seguridad y ciclo de vida de IA. | Correlacionar logs de Zylon con infraestructura, identidad, red y SIEM del cliente. |
| Retencion | Zylon puede limpiar logs almacenados tras una ventana configurada. El predeterminado de aplicacion es `180` dias cuando la limpieza de logs esta habilitada. | Mantener retencion alineada con requisitos legales, de seguridad y operativos. |

> [!NOTE]
>
> Esta documentacion no es asesoramiento legal. Los clientes son responsables de determinar si su despliegue esta sujeto al EU AI Act u otras leyes, que rol ocupan y que controles de logging, monitoreo y retencion requieren.

## Mapeo de evidencia de control

Esta tabla ayuda en procurement y mapeo de evidencia de control; no es una declaracion de certificacion ni una afirmacion de cumplimiento. La aplicabilidad final depende del despliegue, politicas, procedimientos, monitoreo, retencion y caso de uso del cliente.

| Marco o regla | Expectativa de logging | Zylon soporta |
| - | - | - |
| ISO/IEC 27001:2022 A.8.15 | Registrar eventos relevantes de actividad de usuario, excepciones, fallos y seguridad. | Logs estructurados de workspace, seguridad, backoffice, gateway y ciclo de vida de IA. |
| ISO/IEC 27001:2022 A.8.16 | Monitorizar actividades y logs para detectar comportamiento anomalo e incidentes. | Entrega syslog y HTTP para SIEM, alertas y monitoreo del cliente. |
| SOC 2 CC7.2 | Monitorizar componentes y detectar anomalias que puedan indicar actividad maliciosa. | Eventos de seguridad/auth, tokens, cuentas y uso de gateway. |
| DORA Articulo 17 | Registrar, clasificar y gestionar incidentes TIC. | Inputs para reconstruccion de incidentes: actor, organizacion, proyecto, request, respuesta, tiempo y resultado. |
| NIS2 | Apoyar deteccion, respuesta y preservacion de evidencia. | Entrega y retencion controladas por el cliente para operaciones de seguridad y reporting. |
| GDPR Articulo 30 | Mantener registros de actividades de tratamiento. | Los logs pueden ayudar a identificar actores, sistemas y contexto; el cliente mantiene responsabilidad del registro. |
| GDPR Articulo 32 | Proteger confidencialidad, integridad, disponibilidad y resiliencia. | Control de acceso, masking, retencion, TLS y forwarding a SIEM apoyan controles de seguridad. |
| GDPR Articulo 33 | Notificar brechas de datos personales cuando aplique. | Logs apoyan timeline de investigacion, sistemas afectados y recopilacion de evidencia. |

## Almacenamiento y retencion de logs

Cuando el almacenamiento esta habilitado, Zylon persiste logs estructurados internamente. Cuando esta deshabilitado, los logs nuevos no se persisten internamente.

Zylon puede limpiar logs almacenados tras una ventana configurada. La limpieza de logs almacenados esta deshabilitada por defecto. El valor predeterminado de retencion es `180` dias cuando la limpieza de logs esta habilitada.

Para el borrado interno programado, sigue [Limpieza solo de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#configurar-limpieza-solo-de-logs). Ambos flags de limpieza deben estar habilitados. Cada ejecución correcta borra definitivamente los registros vencidos y sus detalles asociados en todas las organizaciones, según su momento de persistencia en la base de datos. Los filtros de entrega externa no restringen esta limpieza. Deshabilitar el almacenamiento detiene la persistencia nueva sin borrar registros existentes.

Los colectores externos mantienen sus propias políticas de retención fuera de Zylon; borrar un log interno no borra sus copias en un SIEM o data lake.

| Ubicacion | Quien controla la retencion | Notas |
| - | - | - |
| Almacenamiento interno de Zylon | Operador y configuracion de limpieza | El almacenamiento esta habilitado por defecto. La limpieza de logs usa `180` dias por defecto cuando se habilita. |
| SIEM o colector syslog del cliente | Cliente | Controlado por input, indice, archivo y politica de borrado del colector. |
| Colector HTTP o data lake del cliente | Cliente | Controlado por ingesta, transformacion y almacenamiento downstream. |

### Derecho de supresion y retencion

Los logs de auditoria y seguridad pueden contener identificadores de usuario, cuenta, organizacion, IP, prompts, respuestas u otro contexto que puede ser dato personal segun el despliegue. Una solicitud de borrado de usuario no implica necesariamente borrado inmediato de todo registro historico de auditoria; muchos entornos regulados retienen logs de seguridad durante un periodo definido para preservar evidencia de fraude, abuso e incidentes.

Configure retencion, filtros de entrega externa y retencion downstream segun base legal y politica de minimizacion. Si su politica exige pseudonimizacion o borrado anticipado de campos vinculados a usuarios, implemente esa obligacion en el colector/SIEM controlado por el cliente o valide el comportamiento de producto de la version desplegada.

## Tiempo y marcadores de esquema

Los registros exponen timestamps ISO como `start_timestamp` y `end_timestamp`. Use UTC para investigaciones entre sistemas y mantenga todos los nodos de Zylon sincronizados con NTP o fuente horaria equivalente.

Los payloads entregados incluyen marcadores de esquema como `zylon.rfc5424_json.v1` y `zylon.canonical_json.v1`. Estos marcadores permiten que los parsers SIEM enruten e identifiquen formas de payload. No imponen por si mismos una politica de deprecacion o migracion; valide la compatibilidad de parsers al actualizar.

## Formas de consumir logs

| Metodo | Uso | Documentacion |
| - | - | - |
| Backoffice UI | Revision interactiva de uso por operadores. | [Backoffice de Plataforma](/es/v1.58/operator-manual/backoffice/platform-backoffice) |
| Syslog | Un SIEM o colector syslog debe recibir eventos. | [Configuracion de entrega y almacenamiento de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#entrega-por-syslog) |
| HTTP | Un gateway de ingesta o pipeline personalizado debe recibir JSON estructurado. | [Configuracion de entrega y almacenamiento de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#entrega-por-http) |

## Recomendaciones operativas

* Mantenga el almacenamiento interno habilitado salvo aprobacion de seguridad, legal y operaciones.
* Entregue logs a un SIEM o colector controlado por el cliente cuando se requiera monitoreo o retencion independiente.
* Prefiera TLS para syslog cuando el colector lo soporte.
* Habilite verificacion de certificados en produccion cuando exista una ruta de confianza.
* Use filtros con cuidado para no excluir eventos necesarios para investigacion.
* Confirme retencion downstream por separado de la retencion interna de Zylon.
* Pruebe recuperacion y entrega despues de cambiar configuracion de logging.


# Backoffice de Plataforma
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/platform-backoffice

Controles de operador para cuentas, roles, gateways y estado del servicio.

## Resumen

El Backoffice de Plataforma lo usan los Operadores para gestionar el acceso a nivel de plataforma y los entornos de desarrollo.

Desde esta sección, los Operadores pueden:

* Crear y gestionar cuentas
* Asignar y actualizar roles de cuenta
* Crear y gestionar gateways
* Supervisar el estado de los servicios de la plataforma

Solo los usuarios con permisos **Operator** pueden acceder a esta sección. Los permisos, la visibilidad y los límites dependen de la licencia activa.

## Cuentas

Una **Cuenta** representa a una persona en la plataforma Zylon. Las cuentas definen el acceso a la plataforma y determinan qué secciones del Backoffice están disponibles.

### Roles y permisos

Los roles de cuenta definen el acceso a nivel de plataforma:

* Los roles **Super Admin** y **Operator** pueden acceder a funciones de administración de plataforma.
* El rol **Developer** puede acceder a Developer Console.
* El rol **Workspace** no concede acceso a Platform Backoffice.

Para la matriz completa de roles y el modelo de permisos, consulta [Roles y permisos](/es/v1.58/operator-manual/backoffice/roles-and-permissions).

### Crear una cuenta

Puedes crear usuarios de dos formas.

1. **Crear desde el modal**

* Haz clic en **Add account**.
* Introduce nombre (opcional), email y contraseña.
* Asigna uno o varios roles de cuenta.
* Guarda la cuenta.

2. **Crear en bloque por CSV**

* Descarga la plantilla CSV disponible en la página de Cuentas.
* Rellena la plantilla con los datos de usuarios y sus roles.
* Sube el CSV para crear múltiples cuentas.

[Backoffice - Crear cuenta](https://www.youtube.com/embed/ryAGkaC2o5U)

### Editar cuentas y asignaciones de rol

Para actualizar una cuenta, ábrela desde la lista y modifica sus datos o asignaciones de rol.

La asignación de roles controla si un usuario puede:

* acceder a Workspace,
* acceder a Developer Console,
* administrar la plataforma.

El número de cuentas y de cuentas habilitadas por rol está determinado por la licencia activa.

## Gateways

Un **Gateway** es un servicio de software dedicado y aislado que se sitúa en el límite entre los clientes y las APIs internas de Zylon. Proporciona un único punto de entrada controlado para el desarrollo de API, gestionando el enrutamiento de solicitudes, la autenticación/autorización, el tráfico y la observabilidad.

Los gateways se usan para:

* Agrupar la actividad de desarrollo de API limitando el acceso a la base de datos vectorial solo a los vectores que pertenecen al gateway
* Controlar qué usuarios pueden trabajar con tokens en cada entorno
* Registrar el uso de cuentas y tokens en cada gateway

### Roles de usuario en Gateway

Las cuentas con rol **Developer** (y los Operadores añadidos a un gateway) pueden tener un rol específico en gateway: **Owner**, **Admin** o **Member**.

Para ver las capacidades de cada rol, consulta [Roles y permisos](/es/v1.58/operator-manual/backoffice/roles-and-permissions).

### Crear un gateway

Para crear un gateway:

1. Abre **Gateways**.
2. Haz clic en **New gateway**.
3. Introduce el nombre del gateway.
4. Haz clic en **Create**.

[Backoffice - Crear gateway](https://www.youtube.com/embed/Z1ZcJMw4RFo)

### Gestionar gateways

Desde la lista de gateways, los Operadores pueden abrir gateways existentes para gestionar usuarios y mantener la configuración que usan los equipos de desarrollo.

El número total de gateways está limitado por la licencia activa.


# Roles y permisos
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/roles-and-permissions

Roles del Backoffice, niveles de acceso y responsabilidades.

## Resumen

El acceso al Backoffice se basa en roles. Lo que un usuario puede ver y hacer depende de:

1. El **rol de cuenta** asignado en Backoffice.
2. El **rol de gateway** asignado dentro de cada gateway.

Una misma cuenta puede tener más de un rol.

## Roles de cuenta

Los roles de cuenta definen el acceso a nivel de plataforma.

| Rol de cuenta | Qué hace este rol | Acceso en Backoffice |
| - | - | - |
| **Super Admin** | Cuenta administrativa inicial para la configuración y gobernanza de la plataforma | Mismo acceso de plataforma que **Operator** |
| **Operator** | Gestiona cuentas, roles, gateways y operación de la plataforma | Acceso completo a **Platform Backoffice** |
| **Developer** | Trabaja con gateways y tokens de API para desarrollo | Acceso a **Developer Console** |
| **Workspace** | Usa Workspace para proyectos y colaboración | Sin acceso a Platform Backoffice |

## Roles de gateway

Los roles de gateway definen qué puede hacer un usuario dentro de un gateway concreto.

| Rol en gateway | Qué hace este rol |
| - | - |
| **Owner** | Gestiona usuarios y roles del gateway, crea y gestiona tokens |
| **Admin** | Gestiona usuarios del gateway, crea y gestiona tokens |
| **Member** | Crea y gestiona sus propios tokens |

## Cómo funciona el acceso en la práctica

* El **rol de cuenta** controla qué secciones del Backoffice están disponibles.
* El **rol de gateway** controla las acciones dentro de cada gateway.
* Un **Operator** que entra en flujos de gateway usa los mismos permisos de rol de gateway que cualquier otro usuario de gateway.
* Los permisos siempre están limitados al rol y al contexto actuales.


# Monitor del sistema
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/system-monitor

Supervisa en vivo los recursos del host y la carga del servicio de modelos desde Backoffice.

## Resumen

El Monitor del sistema ofrece a los Operadores una vista en vivo de la presión sobre los recursos del host y de la actividad del servicio de modelos de IA. Úsalo para detectar presión en CPU, memoria, disco, GPU o colas de inferencia mientras la plataforma está en funcionamiento.

La página está disponible en **Backoffice > Platform > System Monitor** cuando la [función Monitor del sistema](/es/v1.58/operator-manual/configuration/features/feat-system-monitor) está habilitada.

![Monitor del sistema en Backoffice](https://mintcdn.com/zylon/xEQWiY88m24R2pSN/images/operator-manual/backoffice/system-monitor.png?fit=max\&auto=format\&n=xEQWiY88m24R2pSN\&q=85\&s=83156d15a1ac806f8fd109cda071fb91)

> [!NOTE]
>
> El diseño exacto puede variar entre versiones de Zylon.

## Información disponible

Las métricas se actualizan una vez por segundo. Los gráficos conservan las 30 muestras más recientes, incluidas las muestras recientes que se recuperan al abrir la página.

### Métricas del sistema

| Métrica | Qué muestra |
| - | - |
| **System Load** | La mayor presión normalizada entre GPU, solicitudes de inferencia, CPU y RAM. La GPU alcanza la presión máxima al 80 %; las solicitudes en ejecución más las encoladas, al llegar a 60; CPU y RAM contribuyen cuando el uso supera el 95 %. |
| **Active Inferences** | Inferencias de chat que se están procesando en la plataforma. |
| **Disk** | Porcentaje usado y capacidad total del sistema de archivos que almacena los datos de Zylon. |
| **CPU** | Uso actual de CPU del host y su historial reciente. |
| **GPU** | Uso general actual de cómputo de GPU y su historial reciente. |
| **RAM** | Uso actual de memoria del host, GB usados y totales, e historial reciente. |
| **VRAM** | Uso actual de memoria de GPU en todas las GPU, GB usados y totales, e historial reciente. |

### Métricas por modelo

Selecciona un modelo cargado para consultar:

| Métrica | Qué muestra |
| - | - |
| **Queue Inferences** | Solicitudes en espera en Triton o en el planificador del backend del modelo. |
| **Running Inferences** | Solicitudes que se están ejecutando en el backend del modelo. |
| **Tokens/sec** | Velocidad de generación de tokens de salida calculada entre muestras consecutivas. |
| **GPU Memory Usage** | VRAM asignada al modelo seleccionado como porcentaje de la VRAM total. |
| **GPU Compute** | Uso de los núcleos de cómputo de la GPU atribuido al modelo seleccionado. |
| **GPU Memory Bandwidth** | Uso del bus de memoria de la GPU atribuido al modelo seleccionado; no es lo mismo que la VRAM asignada. |

## Fuentes de datos y limitaciones

* CPU y RAM proceden de las métricas del nodo de Kubernetes cuando están disponibles, con lecturas del host como alternativa.
* El uso de disco corresponde al sistema de archivos que contiene `/var/zylon`.
* Los datos de GPU, VRAM y servicio de modelos proceden del endpoint de métricas Prometheus de Triton.
* Las métricas de GPU por modelo dependen de métricas de GPU por proceso. Los despliegues que no las exponen muestran valores a cero.
* La página es una vista operativa en vivo, no un informe histórico persistente. Al recargarla se solicitan de nuevo las últimas muestras disponibles.
* **System Load** es una señal instantánea para visualización. La protección frente a sobrecarga también tiene en cuenta el uso sostenido de recursos y los umbrales del despliegue.


# Panel de uso
Source: https://docs.zylon.ai/es/v1.58/operator-manual/backoffice/usage-dashboard

Supervisa el uso de IA por gateways, tokens de API y actividad de Workspace.

## Resumen

El Panel de uso ofrece a los Operadores una vista centralizada del uso de IA en la plataforma Zylon. Ayuda a responder preguntas operativas como cuánto consumo de tokens hay, qué gateways tienen actividad y si se están usando búsquedas de conocimiento, archivos y web.

Usa este panel cuando necesites:

* Supervisar el uso de IA a lo largo del tiempo.
* Comparar el uso total con el uso por gateway.
* Revisar el uso de uno o varios gateways.
* Inspeccionar actividad asociada a tokens de API.
* Entender cómo la actividad de Workspace contribuye al uso de la plataforma.

El panel está disponible en **Backoffice > Platform > Usage** para usuarios con acceso **Operator** o **Super Admin**. Las métricas de uso requieren que el almacenamiento de uso/auditoría esté habilitado en el despliegue.

## Información disponible

El panel muestra tarjetas de resumen y gráficos según los filtros seleccionados.

### Total tokens in

**Total tokens in** es el número total de tokens de entrada consumidos por solicitudes de chat dentro del rango de fechas y el alcance de gateways seleccionados.

Usa esta métrica para entender la cantidad de entrada de usuario, sistema y contexto enviada a los proveedores de IA.

### Total tokens out

**Total tokens out** es el número total de tokens de salida generados por respuestas de chat dentro del rango de fechas y el alcance de gateways seleccionados.

Usa esta métrica para entender cuánto contenido generado por IA se está produciendo.

### Token usage

El gráfico **Token usage** muestra el consumo total de tokens de chat a lo largo del tiempo. Combina tokens de entrada y salida para cada día del rango seleccionado.

Cuando **Group by** está en **All Gateways**, el gráfico muestra una única serie total. Cuando **Group by** está en **Gateways**, el gráfico separa el mismo total en una serie por cada gateway seleccionado.

### Files ingested

El gráfico **Files ingested** muestra el número de archivos únicos ingeridos a lo largo del tiempo.

Ayuda a los Operadores a confirmar si la ingestión de conocimiento está ocurriendo y cuándo ocurrió.

### Embeddings

El gráfico **Embeddings** muestra actividad de embeddings a lo largo del tiempo. Cada evento de embedding registrado cuenta una vez.

Usa este gráfico para entender cuándo se producen cargas de trabajo de embeddings.

### File searches

El gráfico **File searches** muestra el uso de herramientas de búsqueda en archivos encontrado en la actividad de chat.

Usa este gráfico para entender cuándo los usuarios o aplicaciones piden a Zylon buscar en conocimiento y archivos disponibles durante interacciones de IA.

### Web searches

El gráfico **Web searches** muestra el uso de herramientas de búsqueda web encontrado en la actividad de chat.

Usa este gráfico para entender cuándo las interacciones de IA usan búsqueda web.

## Filtros

El estado de los filtros se mantiene en la URL de la página, por lo que una vista filtrada se puede refrescar o compartir con otro usuario autorizado de Backoffice.

### Group by

**Group by** controla cómo se muestran los gráficos.

* **All Gateways** muestra una única serie total combinada.
* **Gateways** divide los gráficos por gateway.

Este filtro solo cambia la agrupación visual. No cambia qué registros de uso se incluyen.

### Show

**Show** controla el alcance de gateways.

* **All** incluye todos los gateways disponibles.
* Seleccionar uno o varios gateways limita el panel a esos gateways.

Cuando **Show** cambia, **Keys** se restablece a **All tokens**. Esto evita que una selección de tokens de un alcance de gateway anterior siga activa después de cambiar el alcance.

### Keys

**Keys** filtra la actividad de tokens de API para los gateways seleccionados.

* **All tokens** incluye todo el uso dentro del alcance de gateways seleccionado, incluida la actividad generada desde Workspace.
* Seleccionar uno o varios tokens de API muestra solo el uso asociado a esos tokens.

El uso generado desde Workspace no se asocia a un token de API. Por eso, la actividad de Workspace aparece cuando **Keys** está en **All tokens**, pero no aparece al filtrar por un token de API específico.

### Date range

**Date range** controla el periodo mostrado por el panel.

Los presets disponibles son:

* **Week to date**
* **Month to date**
* **Last 7 days**
* **Last 14 days**
* **Last 30 days**

El rango predeterminado es **Last 14 days**. También puedes seleccionar un rango personalizado. Las fechas futuras no están disponibles y el calendario empieza el **1 de enero de 2026**.

Si un rango personalizado se introduce con la fecha final antes de la fecha inicial, Zylon normaliza el rango.

## Entender la recopilación de uso

Cada Workspace está asociado a un Gateway predeterminado. Las solicitudes de IA realizadas por usuarios de Workspace, como Chat y otras interacciones de IA, se enrutan a través de ese Gateway.

Estas interacciones consumen tokens de proveedores de IA de la misma forma que las solicitudes realizadas con tokens de API. Por eso, la actividad de Workspace contribuye al Panel de uso general del Gateway que gestionó la solicitud.

Los usuarios de Workspace se autentican con sesiones de Workspace, no con tokens de API. Como resultado, el uso generado desde Workspace no se asocia a un token de API específico.

Esto significa que:

* **All tokens** incluye uso generado desde Workspace.
* Seleccionar un token de API específico filtra solo la actividad de ese token.
* El uso generado desde Workspace no puede filtrarse actualmente por token de API individual.
* Este comportamiento es esperado y refleja cómo se recopila el uso.

## Notas y limitaciones

* El panel es de solo lectura. No crea, edita ni elimina datos de la plataforma.
* No hay controles de exportación o descarga disponibles desde este panel.
* No hay filtros por organización, proyecto, usuario o email de cuenta.
* Si no hay gateways disponibles, el panel muestra un estado vacío.
* Si existen gateways pero ningún uso coincide con los filtros seleccionados, los gráficos muestran un estado sin datos.
* Las métricas de uso dependen del almacenamiento de uso/auditoría. Si está deshabilitado, el panel no puede mostrar métricas de uso.
* El uso almacenado es más útil cuando los relojes del sistema están sincronizados en todo el despliegue.


# CLI de Zylon
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/cli

Todos los comandos disponibles en la CLI

## admin-password

Obtener una contraseña de un solo uso para el usuario administrador

Uso: `sudo zylon-cli admin-password`

Llama al backend para generar una contraseña temporal para `admin@zylon.ai` y la imprime en stdout. Úsalo después de ejecutar `seed` para obtener la contraseña de inicio de sesión inicial del administrador.

## backfill-projections

Rellenar las proyecciones de Skills y Documentos (necesario al actualizar a Zylon v1.58)

Uso: `sudo zylon-cli backfill-projections --help`

**Banderas:**

* `--dry-run`: Mostrar qué se rellenaría sin escribir ningún cambio

## backup

Crear una copia de seguridad

Uso: `sudo zylon-cli backup --help`

**Banderas:**

* `-o, --backup-dir`: Ruta al directorio de copias de seguridad (predeterminado: `/var/backups/zylon`)
* `-k, --keep-last`: Número de copias de seguridad a mantener (predeterminado: `10`)
* `-u, --unsafe`: No detener k0s antes de tomar la copia de seguridad. Úselo solo cuando evitar el tiempo de inactividad sea más importante que la seguridad de los datos (por ejemplo, en entornos de no producción o de prueba), ya que esto puede provocar corrupción de datos y no se recomienda para copias de seguridad de producción.
* `-y, --yes`: Omitir confirmación del usuario

## completion

Generar el script de autocompletado para el shell especificado

Uso: `sudo zylon-cli completion`

## config

Administrar configuración

Uso: `sudo zylon-cli config`

## configure

Cambiar ajustes del clúster y aplicarlos al nodo en ejecución

> [!CAUTION]
>
> Cambiar --max-pods reinicia k0s, todos los servicios de Zylon estarán brevemente no disponibles.

Uso: `sudo zylon-cli configure --max-pods 200`

`--max-pods` solo edita `/etc/k0s/k0s.yaml` cuando coincide con el formato generado por zylon-cli; si no, explica cómo hacerlo manualmente.

**Banderas:**

* `--max-pods`: Número máximo de pods que puede ejecutar el kubelet de k0s

## create-api-token

Crear un token API para Zylon

Uso: `sudo zylon-cli create-api-token`

## doctor

Verificar el estado de salud de la instalación de Zylon

Uso: `sudo zylon-cli doctor`

## download

Descargar una versión específica de Zylon

Uso: `sudo zylon-cli download --help`

**Banderas:**

* `--airgap`: Habilitar modo airgap (instala todo)
* `--arch`: Arquitectura de CPU de destino
* `--binaries`: Instalar binarios portátiles
* `--drivers`: Instalar controladores NVIDIA
* `--force`: Forzar reinstalación de componentes existentes
* `--images`: Instalar imágenes de contenedor
* `--models`: Modelos de IA (se puede especificar varias veces o separados por comas) (predeterminado: `[]`)
* `--os`: SO de destino (ubuntu22, ubuntu24)
* `--packages`: Instalar paquetes APT
* `--source`: Fuente desde la cual descargar artefactos (s3 o source) (predeterminado: `s3`)

## export

Exportar una versión específica de artefactos de Zylon

Uso: `sudo zylon-cli export --help`

**Banderas:**

* `--arch`: Arquitectura de destino
* `--from`: Versión base para exportación incremental (exporta solo las diferencias)
* `--models`: Modelos de IA (se puede especificar varias veces o separados por comas) (predeterminado: `[]`)
* `--no-binaries`: Excluir binarios portátiles
* `--no-cluster-chart`: Excluir gráficos Helm del clúster
* `--no-drivers`: Excluir controladores NVIDIA
* `--no-images`: Excluir imágenes de contenedor
* `--no-packages`: Excluir paquetes APT
* `--no-zylon-chart`: Excluir gráficos Helm de Zylon
* `--os`: Sistema operativo de destino
* `--output`: Ruta del archivo tar o tar.gz de salida (predeterminado: `zylon-{version}-{os}-{arch}.tar`)
* `--yes`: Omitir confirmación del usuario

## forge

Forjar modelos para Zylon

Uso: `sudo zylon-cli forge`

## forward

Reenviar un comando a un servicio en ejecución

Uso: `sudo zylon-cli forward --help`

**Banderas:**

* `-a, --args`: Argumentos a pasar al comando
* `-c, --command`: Comando a ejecutar
* `-s, --service`: Nombre del servicio

## help

Ayuda sobre cualquier comando

Uso: `sudo zylon-cli help`

## import

Importar artefactos de Zylon desde un archivo tar o tar.gz

Uso: `sudo zylon-cli import`

## install

Instalar Zylon con la configuración actual

Uso: `sudo zylon-cli install --help`

**Banderas:**

* `--airgap`: Habilitar modo airgap (instala todo)
* `--force`: Forzar reinstalación de componentes existentes
* `--images`: Instalar imágenes de contenedor
* `--models`: Modelos de IA (se puede especificar varias veces o separados por comas) (predeterminado: `[]`)
* `--no-binaries`: Excluir binarios portátiles
* `--no-cluster-chart`: Excluir gráficos Helm del clúster
* `--no-drivers`: Excluir controladores NVIDIA
* `--no-packages`: Excluir paquetes APT
* `--no-zylon-chart`: Excluir gráficos Helm de Zylon
* `--skip-final-checks`: Omitir verificaciones finales después de la instalación
* `--skip-migrations`: Omitir la ejecución de migraciones antes de la instalación
* `--skip-preflight`: Omitir verificaciones previas antes de la instalación
* `--source`: Fuente desde la cual descargar artefactos (s3 o source). Solo aplicable en modo no airgap (predeterminado: `s3`)

## install-drivers

Instalar controladores NVIDIA

Uso: `sudo zylon-cli install-drivers --help`

**Banderas:**

* `-f, --force`: Forzar instalación de controladores

## list-versions

Listar la versión de Zylon actualmente instalada

Uso: `sudo zylon-cli list-versions --help`

**Banderas:**

* `--changelog`: Mostrar enlaces de registro de cambios (predeterminado: `true`)
* `--offline`: Indicar instalación sin conexión (sin acceso a S3)

## preflight

Ejecutar verificaciones previas

Uso: `sudo zylon-cli preflight --help`

**Banderas:**

* `--fresh-system`: Validar instalaciones de sistema nuevo
* `--network`: Validar acceso de red a los dominios requeridos (para instalaciones semi-airgap)
* `-v, --verbose`: Habilitar salida detallada con información detallada

## restart

Reiniciar servicios de Zylon

Uso: `sudo zylon-cli restart`

## restore

Restaurar desde una copia de seguridad

Uso: `sudo zylon-cli restore --help`

**Banderas:**

* `-f, --backup-file`: Ruta al archivo tar de copia de seguridad. Si está vacío, se predetermina a la copia de seguridad más reciente

## run-sql

Ejecutar comandos SQL contra la base de datos de Zylon

Uso: `sudo zylon-cli run-sql --help`

**Banderas:**

* `--db`: Base de datos de destino (predeterminado es 'main') (predeterminado: `main`)
* `-f, --file`: Ruta a un archivo que contiene comandos SQL a ejecutar
* `-s, --sql`: Comando SQL a ejecutar

## seed

Poblar la base de datos

Uso: `sudo zylon-cli seed --help`

**Banderas:**

* `-e, --email-regex`: Todos los correos electrónicos que coincidan con esta expresión regular podrán unirse a la organización. Normalmente esto sería .\*@.sudominio.com
* `-o, --org-name`: Nombre de la organización

Después de hacer el seed, ejecuta `sudo zylon-cli admin-password` para obtener la contraseña de un solo uso para `admin@zylon.ai`.

## self-update

Actualizar la CLI

Uso: `sudo zylon-cli self-update`

## sync-kube-config

Sincronizar configuración de kube

Uso: `sudo zylon-cli sync-kube-config`

## update

Actualizar configuración de Zylon

**Alias:** sync

Uso: `sudo zylon-cli update`

## update-password

Restablecer la contraseña para un usuario

Uso: `sudo zylon-cli update-password --help`

**Banderas:**

* `-e, --email`: Correo electrónico de la cuenta

## upgrade

Actualizar Zylon a la última versión

Uso: `sudo zylon-cli upgrade`


# Borrado permanente
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/cron-tasks/hard-delete

Configure la politica de retencion usada por la tarea de limpieza

La tarea de borrado permanente elimina definitivamente los elementos despues de que primero se hayan eliminado en Zylon o marcado como inactivos.

Cuando se eliminan chats, proyectos, archivos u organizaciones en Zylon, siguen siendo recuperables hasta que vence la ventana de retencion. Esta configuracion de limpieza permite que cada organizacion alinee el borrado permanente de Zylon con su propia politica de retencion de datos.

## Configuracion predeterminada

La limpieza programada está deshabilitada por defecto. Los valores de Helm configuran una programación diaria a las `03:00 UTC` y un umbral de retención de Workspace de `14` días, que se usa al habilitar la limpieza. Helm define `timezone: "UTC"`; si se omite la zona horaria del runtime fuera de Helm, se usa la de la máquina servidor.

La limpieza de logs almacenados usa el mismo programador de limpieza. Esta desactivada por defecto; cuando se activa, el umbral predeterminado de retencion de logs almacenados es `180` dias.

```yaml theme={null}
zylonBackend:
  scheduler:
    cleanup:
      enabled: false
      cron: "0 3 * * *"
      timezone: "UTC"
      minimumIntervalMinutes: 1440
      workspace:
        enabled: true
      deleteAfterDays: 14
      logging:
        enabled: false
        deleteAfterDays: 180
```

## Ejemplo de configuracion

Edite `/etc/zylon/zylon-conf.yaml` y luego aplique el cambio con `sudo zylon-cli sync`.

Use una ventana de retencion que coincida con la politica de su empresa. Muchas organizaciones necesitan un valor bastante mayor que el predeterminado.

```yaml theme={null}
zylonBackend:
  scheduler:
    cleanup:
      enabled: true
      cron: "0 3 * * *"
      timezone: "Europe/Madrid"
      workspace:
        enabled: true
      deleteAfterDays: 365
      logging:
        enabled: true
        deleteAfterDays: 180
```

`enabled` activa o desactiva las revisiones programadas de limpieza. `cron` determina cada cuanto tiempo el sistema revisa elementos inactivos y logs almacenados, `timezone` define de forma opcional la zona horaria usada para interpretar la expresion cron y `workspace.enabled` activa o desactiva el borrado permanente de datos de workspace. `deleteAfterDays` es el numero de dias que deben pasar antes de que un elemento inactivo o un elemento eliminado previamente se elimine de forma definitiva por la ejecucion del cron. `logging.enabled` activa o desactiva la limpieza de logs almacenados, y `logging.deleteAfterDays` elimina registros de log almacenados con mas antiguedad que ese umbral. Helm usa `UTC` por defecto; si se omite la zona horaria del runtime fuera de Helm, se usa la de la máquina servidor.

> [!TIP]
>
> Sugerimos configurar una [zona horaria IANA](#valores-de-zona-horaria) que coincida con la zona horaria de la empresa.

## Valores aceptados

### Valores de cron

La limpieza usa el mismo formato cron de 5 partes que la sincronizacion:

```text theme={null}
minute hour day-of-month month day-of-week
```

Use valores dentro de estos rangos:

| Campo | Valores aceptados |
| - | - |
| Minuto | `0-59` o `*` |
| Hora | `0-23` o `*` |
| Dia del mes | `1-31` o `*` |
| Mes | `1-12` o `*` |
| Dia de la semana | `0-6` o `*` |

Ejemplos:

* `0 3 * * *` se ejecuta todos los dias a las 03:00
* `15 4 * * 0` se ejecuta cada domingo a las 04:15

### Valores de zona horaria

`zylonBackend.scheduler.cleanup.timezone` usa `UTC` por defecto en Helm. Si se omite el ajuste del runtime fuera de Helm, el cron usa la zona horaria de la máquina servidor. El cron también debe cumplir `minimumIntervalMinutes`, cuyo valor predeterminado en Helm es `1440`; un cron más frecuente se rechaza salvo que se reduzca ese valor.

Cuando configure `zylonBackend.scheduler.cleanup.timezone`, use un identificador IANA valido. Ejemplos comunes:

* `UTC`
* `Europe/Madrid`
* `America/New_York`
* `America/Los_Angeles`
* `Asia/Tokyo`
* `Pacific/Auckland`
* `Africa/Johannesburg`

Para una lista practica de identificadores de zona horaria IANA, consulte [IANA Time Zones](https://datetime.app/iana-timezones).

### Valores de retencion

Para `zylonBackend.scheduler.cleanup.deleteAfterDays`, use un numero entero positivo de dias como `14`, `30`, `90` o `365`, segun su politica de retencion.

Para `zylonBackend.scheduler.cleanup.logging.deleteAfterDays`, use un numero entero positivo de dias. El valor predeterminado es `180` dias, aproximadamente seis meses.

> [!WARNING]
>
> Usa ventanas de retención positivas según la política de tu empresa. Para logs almacenados, `logging.deleteAfterDays: 0` no deshabilita el borrado: hace que los logs existentes sean elegibles para limpieza. Para deshabilitar la limpieza de logs, configura `logging.enabled: false`. Para retener logs sin borrado permanente de Workspace, sigue [Limpieza solo de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#configurar-limpieza-solo-de-logs).

## Acceso antes del borrado permanente

Antes de que expire la ventana de retencion, los datos eliminados todavia no se han borrado de forma definitiva. Durante ese tiempo, un operador puede usar el flujo de migracion y restauracion por CLI para recuperar organizaciones, proyectos, chats o archivos.

Si necesita ayuda para realizar esa recuperacion, tambien puede contactar con [Atencion al cliente](/es/v1.58/customer-support-manual/zendesk-client-manual).

## Ejecucion y manejo de fallos

La tarea de limpieza se ejecuta segun el cron configurado y revisa si los elementos inactivos y los elementos eliminados previamente ya superaron la ventana de retencion `deleteAfterDays`. Cuando la superan, el sistema los marca para borrado permanente y los elimina de Zylon.

Una ejecucion de limpieza puede borrar definitivamente chats, archivos, proyectos y organizaciones, junto con otros datos en cascada.

Los fallos por elemento se registran. La tarea continua con los demas elementos y la siguiente ejecucion programada reintenta los pendientes.


# Sincronizacion
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/cron-tasks/sync

Configure la tarea programada de sincronizacion de integraciones

La tarea de sincronizacion mantiene actualizado el contenido de la base de conocimiento respaldado por integraciones revisando las fuentes externas conectadas y actualizando en Zylon el contenido sincronizado cuando el contenido de origen se agrega, cambia o elimina.

Use esta tarea cuando quiera que el contenido de [SharePoint](/es/v1.58/operator-manual/knowledge-base/sharepoint), [Confluence](/es/v1.58/operator-manual/knowledge-base/confluence), [File System](/es/v1.58/operator-manual/knowledge-base/file-system), [Claromentis](/es/v1.58/operator-manual/knowledge-base/claromentis) u otras integraciones compatibles se mantenga fresco sin resincronizaciones manuales.

## Configuracion predeterminada

Por defecto, la sincronizacion programada de integraciones esta deshabilitada. Cuando se habilita, la programacion predeterminada es diaria a la `01:00`. Si `timezone` no esta definido, Zylon usa la zona horaria predeterminada de la maquina servidor.

```yaml theme={null}
integration:
  sync:
    enabled: false
    cron: "0 1 * * *"
```

## Ejemplo de configuracion

Edite `/etc/zylon/zylon-conf.yaml` y luego aplique el cambio con `sudo zylon-cli sync`.

```yaml theme={null}
integration:
  sync:
    enabled: true
    cron: "0 1 * * *"
    timezone: "Europe/Madrid"
```

`enabled` activa o desactiva la sincronizacion programada. `cron` define cuando se ejecuta y `timezone` define de forma opcional la zona horaria usada para interpretar esa expresion cron. Si `timezone` se omite, se usa la zona horaria predeterminada de la maquina servidor.

> [!TIP]
>
> Sugerimos configurar una [zona horaria IANA](#valores-de-zona-horaria) que coincida con la zona horaria de la empresa.

## Valores aceptados para cron y zona horaria

### Valores de cron

Las programaciones cron usan un formato de 5 partes:

```text theme={null}
minute hour day-of-month month day-of-week
```

Use valores dentro de estos rangos:

| Campo | Valores aceptados |
| - | - |
| Minuto | `0-59` o `*` |
| Hora | `0-23` o `*` |
| Dia del mes | `1-31` o `*` |
| Mes | `1-12` o `*` |
| Dia de la semana | `0-6` o `*` |

Ejemplos:

* `0 3 * * *` se ejecuta todos los dias a las 03:00
* `30 2 * * 1` se ejecuta cada lunes a las 02:30

### Valores de zona horaria

`integration.sync.timezone` es opcional. Si no se define, el cron de sincronizacion se ejecuta en la zona horaria predeterminada de la maquina servidor.

Cuando configure `integration.sync.timezone`, use un identificador IANA valido. Ejemplos comunes:

* `UTC`
* `Europe/Madrid`
* `America/New_York`
* `America/Los_Angeles`
* `Asia/Tokyo`
* `Pacific/Auckland`
* `Africa/Johannesburg`

Para una lista practica de identificadores de zona horaria IANA, consulte [IANA Time Zones](https://datetime.app/iana-timezones).

## Ejecucion y manejo de fallos

Una ejecucion programada de sincronizacion revisa el contenido activo de integraciones y puede llamar APIs externas, descargar contenido, crear o eliminar contenido sincronizado de la base de conocimiento, disparar la ingesta y emitir mensajes de fin de sincronizacion.

Si falla un objetivo de sincronizacion, el error se registra y la tarea continua con los demas. La siguiente ejecucion programada lo intentara de nuevo.


# Vigencia de autenticación
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/authentication-freshness

Configure la vigencia de autenticación para acciones sensibles del espacio de trabajo y del backoffice.

La vigencia de autenticación obliga a los usuarios a volver a autenticarse cuando su autenticación anterior es demasiado antigua para una acción sensible. Se controla mediante el bloque de configuración `features.authChallenge`.

> [!WARNING]
>
> La vigencia de autenticación no se aplica a las peticiones a la API autenticadas con tokens. Las integraciones basadas en tokens siguen funcionando sin cambios en sus flujos actuales.

## Activar o desactivar la vigencia de autenticación

Establece `features.authChallenge.enabled` en `true` para activar la función o en `false` para desactivarla. La función está desactivada de forma predeterminada en los valores del chart.

```yaml theme={null}
features:
  authChallenge:
    enabled: true
```

Después de cambiar la configuración, aplícala con:

```bash theme={null}
sudo zylon-cli sync
```

Cuando la función está desactivada, las acciones protegidas siguen aplicando sus comprobaciones normales de autorización y permisos, pero no requieren una autenticación reciente.

## Configurar los periodos de vigencia

La vigencia de autenticación se configura por separado para cada nivel de riesgo. Los valores se expresan en segundos:

| Nivel de riesgo | Clave del chart | Valor predeterminado | Duración predeterminada |
| - | - | -: | - |
| Bajo | `features.authChallenge.maxAgeSeconds.low` | `86400` | 24 horas |
| Medio | `features.authChallenge.maxAgeSeconds.medium` | `3600` | 1 hora |
| Alto | `features.authChallenge.maxAgeSeconds.high` | `900` | 15 minutos |

Por ejemplo:

```yaml theme={null}
features:
  authChallenge:
    enabled: true
    maxAgeSeconds:
      low: "86400"
      medium: "3600"
      high: "900"
```

En la configuración de la aplicación generada, el bloque equivalente se llama `maxAuthAgeSeconds`:

```yaml theme={null}
features:
  authChallenge:
    maxAuthAgeSeconds:
      low: "86400"
      medium: "3600"
      high: "900"
```

Utiliza el formato de clave correspondiente a la capa de configuración que estés editando: `maxAgeSeconds` es la clave de los valores de Helm, mientras que `maxAuthAgeSeconds` es la clave de configuración de la aplicación que genera el chart.

## Niveles de riesgo y acciones protegidas

El nivel de riesgo determina qué periodo de vigencia se utiliza; no sustituye los permisos del usuario. Consulta las acciones actuales que activan esta comprobación en [Autenticación para acciones sensibles](/es/v1.58/operator-manual/security/authentication-for-sensitive-actions).


# Registro de Auditoría
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-audit

Configure la captura de contenido de chat del gateway, el almacenamiento interno y la entrega externa.

`features.audit.enabled` controla si los logs de chat del gateway capturan mensajes de solicitud y contenido de respuesta. Está habilitado por defecto. Los eventos de Workspace, Backoffice y seguridad siguen emitiéndose cuando este flag está deshabilitado.

La captura de contenido de chat, el almacenamiento interno y la entrega externa son ajustes independientes. El almacenamiento está habilitado por defecto; la entrega por syslog y HTTP está deshabilitada por defecto.

### Configuración

| Clave | Predeterminado | Valores | Descripción |
| - | - | - | - |
| `features.audit.enabled` | `true` | `true`, `false` | Captura mensajes de solicitud y contenido de respuesta en logs de chat del gateway. |
| `logging.storage.enabled` | `true` | `true`, `false` | Persiste logs estructurados internamente para recuperarlos después. |
| `logging.delivery.syslog.enabled` | `false` | `true`, `false` | Envía logs nuevos a un colector syslog. |
| `logging.delivery.http.enabled` | `false` | `true`, `false` | Envía logs nuevos a un colector HTTP. |

### Ejemplo

Este ejemplo habilita la captura de contenido de chat del gateway y el almacenamiento interno:

```yaml theme={null}
features:
  audit:
    enabled: true

logging:
  storage:
    enabled: true
```

Para instalaciones gestionadas con la CLI, combina estos ajustes con `/etc/zylon/zylon-conf.yaml` y ejecuta `sudo zylon-cli sync`.

> [!NOTE]
>
> El contenido de chat capturado puede aparecer en logs almacenados y registros entregados externamente. Configura `features.audit.enabled: false` para omitir mensajes de solicitud y contenido de respuesta del chat del gateway. Este flag no aplica una redacción general a todos los campos de cada evento. El parámetro `include` de la API de Backoffice solo controla la recuperación; no filtra los registros entregados externamente.

Para conectar un SIEM, sigue [Enviar logs a tu SIEM](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#enviar-logs-a-tu-siem). Para programar el borrado de logs almacenados, consulta [Limpieza solo de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#configurar-limpieza-solo-de-logs). Habilitar solo el ejemplo anterior no reenvía logs externamente ni activa la limpieza.


# Ejecución de código
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-code-execution

Permite que el asistente ejecute código y trabaje con archivos en sandboxes aislados.

> [!NOTE]
>
> **Característica en Beta**

La ejecución de código permite al asistente ejecutar comandos bash y crear, editar y presentar archivos dentro de un sandbox aislado. Cada hilo de chat (o `container` de la API) tiene su propio sandbox, que crea bajo demanda el servicio OpenSandbox incluido en el mismo clúster de Kubernetes.

Los usuarios la ven en el Workspace cuando trabajan con Skills o generan archivos. Los desarrolladores pueden usarla a través de la API; ver [Herramienta de ejecución de código](/es/v1.58/developer-manual/build-with-zylon/tools/built-in/code-execution-tool).

La ejecución de código está **habilitada por defecto en los despliegues estándar de Zylon 1.58**. Los operadores pueden controlar su disponibilidad en el chat del Workspace con la siguiente configuración.

### Configuración

| Clave | Por defecto | Valores | Descripción |
| - | - | - | - |
| `features.codeExecution.enabled` | `true` | `true \| false` | Permite las herramientas de ejecución de código en el chat del Workspace; consulta [Cuando está desactivada](#cuando-está-desactivada) para las limitaciones de la API |
| `features.codeExecution.timeout` | `60` | segundos | Tiempo de espera por defecto para cada comando que se ejecuta en el sandbox |
| `external.opensandbox.sessionTTLSeconds` | `600` | segundos | Tiempo que un sandbox inactivo se mantiene en ejecución antes de apagarse. Los archivos se conservan; la siguiente solicitud arranca un sandbox nuevo con los mismos archivos. |

### Ejemplo

```yaml theme={null}
features:
    codeExecution:
        enabled: true
        timeout: 60
```

Para desactivar las herramientas de ejecución de código en el chat del Workspace:

```yaml theme={null}
features:
    codeExecution:
        enabled: false
```

### Cuando está desactivada

Después de configurar `features.codeExecution.enabled: false`, ejecuta `sudo zylon-cli sync` para aplicar el cambio. El chat del Workspace elimina las herramientas de ejecución de código antes de enviar las solicitudes al modelo, incluso cuando una Skill las añadiría. El chat normal y las demás herramientas disponibles siguen funcionando; los pasos de una Skill que requieren ejecutar código no pueden ejecutarse a través de ese flujo de chat.

> [!WARNING]
>
> En Zylon 1.58, este flag **no desactiva globalmente la ejecución de código a través de la API de ZylonGPT** ni elimina el servicio OpenSandbox. El proveedor de GPT se configura por separado y usa OpenSandbox por defecto. Este flag controla el Workspace; la ejecución de código por API puede seguir disponible.

### Cómo funciona

* **Un sandbox por hilo.** Cada sandbox es un pod en el namespace `opensandbox-runtimes`, que se crea cuando el asistente ejecuta código por primera vez en un hilo y se apaga tras `sessionTTLSeconds` de inactividad.
* **Archivos persistentes.** Los archivos subidos, las salidas y los archivos del espacio de trabajo se almacenan en el bucket `sessions` del almacenamiento de objetos de la plataforma, por lo que sobreviven a los reinicios del sandbox y a las actualizaciones de la plataforma.
* **Imágenes descargadas previamente.** Las imágenes del sandbox se descargan durante la instalación y la actualización, así que no se necesita acceso al registro cuando arranca un sandbox. Esto también funciona en instalaciones airgapped.

### Acceso a la red

Los sandboxes no tienen acceso a internet. Por defecto, un sandbox de ejecución de código solo puede acceder a:

* DNS.
* La API de Zylon, para que el código del sandbox pueda llamar al modelo con los permisos del usuario que envió la solicitud.

Para que los sandboxes puedan acceder a otros servicios dentro del clúster, como una base de datos o una API internas, añádelos a `external.opensandbox.codeExecution.internal.services`. Cada entrada selecciona pods por sus etiquetas: `namespaceSelector` recibe las etiquetas del namespace y `podSelector` las de los pods. Escribe las etiquetas directamente, sin `matchLabels` (Zylon lo añade), y da al menos una etiqueta a cada selector: uno vacío permitiría a los sandboxes acceder a cualquier pod del clúster.

```yaml theme={null}
external:
    opensandbox:
        codeExecution:
            internal:
                services:
                    - namespaceSelector:
                          kubernetes.io/metadata.name: analytics
                      podSelector:
                          app: postgres
```

> [!WARNING]
>
> El código del sandbox lo escribe el modelo de IA. Permite únicamente servicios que no te importe exponer a cualquier usuario que pueda chatear con el asistente.

### Recursos

Por defecto, los sandboxes no tienen límites de CPU ni de memoria. Para limitar el total de recursos que pueden usar los sandboxes, habilita la cuota y el rango de límites para el namespace de los sandboxes:

```yaml theme={null}
opensandbox:
    runtime:
        resourceQuota:
            enabled: true    # Total para todos los sandboxes: 50 pods, 20 CPU, 40Gi de memoria (límites)
        limitRange:
            enabled: true    # Por sandbox: 1 CPU, 512Mi de memoria por defecto
```

### Imágenes del sandbox

| Clave | Por defecto |
| - | - |
| `external.opensandbox.codeExecution.image.repository` | `zylon-sandbox-templates/code-execution` |
| `external.opensandbox.codeExecution.image.tag` | `1.1.0` |

La imagen incluye Python 3 con las librerías de datos más habituales (pandas, numpy, matplotlib, openpyxl, python-docx, pypdf, entre otras) y herramientas de línea de comandos como `unzip`, `rg` y `sqlite3`.

### Resolución de problemas

Comprueba los sandboxes que están en ejecución:

```bash theme={null}
sudo kubectl get pods -n opensandbox-runtimes
```

Revisa los logs del servidor de OpenSandbox:

```bash theme={null}
sudo kubectl logs -n opensandbox deploy/opensandbox-server --tail=200
```

Si la ejecución de código no está disponible en el chat del Workspace, comprueba `features.codeExecution.enabled` y ejecuta `sudo zylon-cli sync` después de cambiarlo.

El error `code_execution provider is not configured.` significa que falta el proveedor de ejecución de código de GPT. Comprueba la configuración del proveedor de GPT y el servicio OpenSandbox; este error no es el resultado esperado de desactivar únicamente el flag del Workspace.


# Conector de Herramienta de Base de Datos
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-database



> [!NOTE]
>
> **Característica en Alpha**

Muestra la herramienta conectora de base de datos en los chats.

### Configuración

| Clave | Por Defecto | Valores | Descripción |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Muestra la herramienta conectora de base de datos en los chats |

### Ejemplo

```yaml theme={null}
features:
    database:
        enabled: false
```


# Procesamiento de Archivos con Visión
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-file-vision



> [!NOTE]
>
> **Disponible desde la versión 1.56**

> [!NOTE]
>
> **Característica en Alpha**

> [!NOTE]
>
> **Esta característica requiere un modelo con capacidades de visión. Consulta [Preajustes de IA](/es/v1.58/operator-manual/ai-presets/presets).**

Habilita el procesamiento de archivos con visión para documentos y presentaciones.

### Modos

| Modo | Descripción |
| - | - |
| `none` | Desactiva el procesamiento con visión. Los archivos se procesan únicamente mediante extracción de texto. |
| `lite` | Combina la extracción de texto y visual para mejorar la comprensión de la estructura, imágenes, gráficos y diagramas. Diseñado para equilibrar calidad y eficiencia. |

### Configuración

| Clave | Por Defecto | Valores | Descripción |
| - | - | - | - |
| `features.transformation.pptx.vision.mode` | `none` | `none \| lite` | Controla el modo de visión para archivos PPTX (`.pptx`). |
| `features.transformation.docling.vision.mode` | `none` | `none \| lite` | Controla el modo de visión para archivos procesados con Docling (`.pdf`, `.docx`, `.xlsx`). |

### Recomendaciones

* Usa `lite` cuando los documentos incluyan gráficos, diagramas o imágenes importantes.
* Usa `lite` en PPTX cuando sea importante comprender la estructura de las diapositivas e interpretar gráficos.

> [!WARNING]
>
> Activar `lite` aumenta el consumo de recursos y el tiempo de procesamiento de los documentos.

### Ejemplo

```yaml theme={null}
features:
    transformation:
        pptx:
            vision:
                mode: lite
        docling:
            vision:
                mode: lite
```


# Conector de Herramienta MCP
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-mcp



> [!NOTE]
>
> **Característica en Alpha**

Muestra la herramienta conectora MCP en los chats.

### Configuración

| Clave | Por Defecto | Valores | Descripción |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Muestra la herramienta conectora MCP en los chats |

### Ejemplo

```yaml theme={null}
features:
    mcp:
        enabled: false
```


# Capacidades Multimodales
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-multimodal



> [!NOTE]
>
> **Disponible desde la versión 1.51**

> [!NOTE]
>
> **Esta característica requiere que tu modelo actual tenga capacidades de imagen**

> [!NOTE]
>
> **Característica en Alpha**

Extrae y analiza contenido de imágenes si las capacidades del modelo lo soportan.

### Configuración

| Clave | Por Defecto | Valores | Descripción |
| - | - | - | - |
| `enabled` | `true` | `true \| false` | Habilita capacidades multimodales para procesamiento de imágenes |

### Ejemplo

```yaml theme={null}
features:
    multimodal:
        enabled: true
```


# Instrucciones personalizadas de proyecto
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-project-custom-instructions



Los usuarios pueden personalizar las instrucciones del proyecto desde el dialogo de configuracion del proyecto, como se explica en [Añadir instrucciones personalizadas](/es/v1.58/user-manual/adding-custom-instructions).

Estas instrucciones se aplican a nivel de proyecto e influyen en como responde Zylon en los chats.

### Configuración

Use la siguiente clave para controlar la longitud maxima de las instrucciones:

```yaml theme={null}
features:
  maxInstructionsLength: 4000
```

### Detalles de configuración

| Clave | Valor predeterminado | Valores | Descripción |
| - | - | - | - |
| `maxInstructionsLength` | `4000` | Entero positivo | Longitud maxima de instrucciones aceptada tanto por la UI de Workspace como por la API |


# Monitor del sistema
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-system-monitor

Habilita métricas en vivo de infraestructura y servicio de modelos en Backoffice.

Habilita la página Monitor del sistema en Backoffice para consultar métricas en vivo de los recursos del host y del servicio de inferencia.

### Configuración

| Clave | Valor predeterminado | Valores | Descripción |
| - | - | - | - |
| `features.systemMonitor.enabled` | `false` | `true`, `false` | Muestra u oculta **Backoffice > Platform > System Monitor**. |

### Ejemplo

```yaml theme={null}
features:
  systemMonitor:
    enabled: true
```

Ejecuta `sudo zylon-cli sync` después de cambiar la configuración.

Cuando el ajuste está habilitado, Backoffice muestra el elemento de navegación e inicia el flujo de métricas en vivo al abrir la página. Cuando está deshabilitado, el elemento de navegación se oculta y el acceso directo a la página muestra un estado no disponible.

> [!NOTE]
>
> Este ajuste controla la disponibilidad en Backoffice; no inicia ni detiene el recolector de métricas del backend. Es independiente de `observability.platformMetrics` y `observability.usageMetrics`, que configuran la observabilidad externa y la telemetría de producto.

El chart proporciona al backend los endpoints de métricas del nodo de Kubernetes y de Triton que usa el monitor. Si las métricas de Triton no están disponibles, la información de GPU y por modelo puede estar vacía o mostrar valores a cero. La CPU y la RAM usan las métricas del nodo de Kubernetes cuando están disponibles y, en caso contrario, recurren a lecturas del host.

Consulta [Monitor del sistema](/es/v1.58/operator-manual/backoffice/system-monitor) para conocer las métricas que muestra Backoffice.


# Extracción Web
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-webextract



> [!NOTE]
>
> **Característica en Alpha**

Cuando se proporciona una URL, la IA tiene capacidades para extraer y analizar contenido.

### Configuración

| Clave | Por Defecto | Valores | Descripción |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Habilita la extracción y análisis de páginas web |
| `timeout` | `15` | Entero positivo | Tiempo de espera en segundos para cada extracción web |
| `poolSize` | `5` | Entero positivo | Número de instancias de navegador que se mantienen en el pool |
| `poolIdleTimeout` | `300` | Entero positivo | Segundos antes de que una instancia inactiva se termine |

### Ejemplo

```yaml theme={null}
features:
    webExtract:
        enabled: true
        timeout: 15
        poolSize: 5
        poolIdleTimeout: 300
```

### Uso

Cuando está habilitada, esta característica permite a Zylon extraer y analizar contenido de páginas web, habilitando capacidades de análisis de contenido y extracción de datos.


# Búsqueda Web
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/feat-websearch



> [!NOTE]
>
> **Disponible desde la versión 1.51**

> [!NOTE]
>
> **Característica en Alpha**

Habilita capacidades de búsqueda web en los chats impulsadas por Brave Search.

### Configuración

| Clave | Por Defecto | Valores | Descripción |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Habilita capacidades de búsqueda web en los chats |

### Requisitos

> [!WARNING]
>
> **Extracción Web Requerida**: Esta característica requiere que `webExtract` esté habilitada para funcionar correctamente.

> [!WARNING]
>
> **API de Brave Search Requerida**: Necesitas una clave de API válida de Brave Search para usar esta característica.

### Cómo Obtener una Clave de API de Brave Search

1. **Visita el sitio web de la API de Brave Search**
   * Navega a [brave.com/search/api](https://brave.com/search/api/)
   * Haz clic en "Get Started" o "Sign Up"

2. **Crea una cuenta o inicia sesión**
   * Regístrate con tu correo electrónico o inicia sesión si ya tienes una cuenta
   * Accede al panel de API en [api-dashboard.search.brave.com](https://api-dashboard.search.brave.com/app/keys)

3. **Suscríbete a un plan**
   * Ve a la pestaña **Subscriptions** en el menú izquierdo
   * Elige un plan "Data for Search" según tus necesidades:

4. **Genera tu clave de API**
   * Navega a **API Keys** en el menú izquierdo
   * Haz clic en **"Add API Key"**
   * Nombra tu clave (ej., "Integración de Búsqueda Web de Zylon")
   * Selecciona el plan de suscripción para asociar con la clave
   * Copia y guarda tu clave de API de forma segura

### Configuración de la API de Brave

La Búsqueda Web requiere una configuración de proveedor de API de Brave Search con los siguientes parámetros:

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `apiKey` | string | Sí | Tu token de suscripción de API de Brave Search |
| `rateLimit` | number | Sí | Solicitudes por segundo basadas en tu nivel de suscripción |

### Niveles de Límite de Tasa

Basado en tu nivel de suscripción de API de Brave Search:

* **Free AI**: `1.0` (1 consulta/segundo, hasta 2,000 consultas/mes)
* **Base AI**: `20.0` (hasta 20 consultas/segundo, hasta 20M consultas/mes)
* **Pro AI**: `50.0` (hasta 50 consultas/segundo, consultas ilimitadas/mes)
* **Enterprise**: Límites de tasa personalizados

### Ejemplo de Configuración

```yaml theme={null}
features:
    webExtract:
        enabled: true
    webSearch:
        enabled: true
external:
    brave:
        apiKey: YOUR_BRAVE_API_KEY_HERE
        rateLimit: 1.0
```

### Primeros Pasos

1. Regístrate para una clave de API de Brave Search en [brave.com/search/api](https://brave.com/search/api/)
2. Configura el `apiKey` y `rateLimit` según tu nivel de suscripción
3. Habilita ambas características `webExtract` y `webSearch`
4. La funcionalidad de Búsqueda Web estará disponible en tus chats


# Entrega y almacenamiento de logs
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/features/log-delivery-storage

Configure el almacenamiento de logs de Zylon, la entrega por syslog y la entrega por HTTP.

## Resumen

Zylon admite almacenamiento interno de logs y entrega externa por syslog y HTTP.

* La entrega por syslog esta pensada para SIEMs y colectores que aceptan eventos syslog o CEF.
* La entrega por HTTP esta pensada para endpoints de ingesta estructurada, destinos cloud y pipelines gestionados por el cliente.
* La entrega es asincrona.
* Con `failurePolicy: "drop"`, la entrega evita bloquear el camino critico cuando las colas estan llenas.
* Los eventos entregados se pueden filtrar por patrones de accion e IDs de organizacion.
* Los logs almacenados permanecen en el despliegue Zylon del cliente salvo que se habilite entrega externa de logs por syslog o HTTP.

Para instalaciones gestionadas con la CLI, edita `/etc/zylon/zylon-conf.yaml` y ejecuta `sudo zylon-cli sync` para aplicar los cambios. Para instalaciones gestionadas directamente con Helm, usa las mismas claves en el YAML de valores de Helm de Zylon. El chart mapea estos valores a la configuración interna del backend.

Para gobernanza, auditabilidad, soporte de trazabilidad para EU AI Act, preservacion de evidencia y retencion, consulte [Auditabilidad y gobernanza de IA: Logging, evidencia y entrega a SIEM](/es/v1.58/operator-manual/backoffice/log-delivery-storage).

## Enviar logs a tu SIEM

Para un SIEM propio con un endpoint HTTPS de ingesta JSON, empieza con la entrega HTTP de esta sección. Si tu colector acepta syslog o CEF, usa la [configuración de syslog](#entrega-por-syslog).

El almacenamiento interno (`logging.storage.enabled`) está habilitado por defecto. La entrega externa por syslog y HTTP está deshabilitada por defecto. Habilitar solo el almacenamiento no envía eventos a tu SIEM. La entrega reenvía eventos nuevos; no reproduce automáticamente el historial almacenado. Usa la [API de logging de Backoffice](/en/v1.58/developer-manual/build-with-zylon/backoffice-api/logging) para recuperar registros históricos.

### 1. Preparar el colector

Crea un endpoint HTTPS accesible desde el backend de Zylon que acepte solicitudes `POST` con registros de log JSON. Devuelve una respuesta HTTP `2xx` después de aceptar la solicitud. Si requiere autenticación bearer, prepara su token de ingesta.

El payload HTTP usa el marcador de esquema `zylon.canonical_json.v1`. Una solicitud con un evento contiene un objeto JSON; los lotes con varios eventos contienen un array JSON. El ejemplo usa `maxEvents: 1` para validar un registro cada vez. Para usar después el tamaño predeterminado de `25`, confirma que tu colector también acepta arrays.

El sobre HTTP contiene `schema`, `severity`, `outcome`, `actor` y `log`. Mapea `log.event`, `log.action`, `log.id` y `log.start_timestamp` a los campos de tu SIEM. Estos campos están anidados bajo `log`, no en el nivel superior. Deduplica los reintentos usando `log.id`.

> **Metadatos de entrega e identificadores de actor**
>
> | Campo | Valores y significado |
> | - | - |
> | `severity` | `low`, `medium`, `high`, `critical`. Se asigna según la acción, familia y resultado del evento. Los mapeos actuales de 1.58 usan `low`, `medium` y `high`; `critical` también es un valor del esquema. |
> | `outcome` | `success` o `failure` del evento original, no de la entrega al colector. Un `log.error` no nulo o un código de estado de evento de seguridad de `400` o superior produce `failure`; en los demás casos es `success`. |
> | `actor` | Siempre contiene `actor_type`, `actor_id` y `actor_display`. Un actor no identificado usa valores literales en lugar de campos omitidos. |
>
> La selección de actor usa la primera fila que coincide:
>
> | `actor.actor_type` | Se selecciona cuando | `actor.actor_id` |
> | - | - | - |
> | `api_token` | Existe `log.token_id`. | El ID del token. |
> | `user` | No hay ID de token; existe `log.account_id`. | `log.ws_member_id` si existe; en caso contrario, `log.account_id`. |
> | `system` | No hay ID de token ni de cuenta; `log.system_event` es `true`. | Literal `system`. |
> | `unknown` | No coincide ninguna condición anterior. | Literal `unknown`. |
>
> Para actores de token/usuario, `actor_display` es `log.account_email` si no está vacío ni contiene solo espacios; en caso contrario, el ID de actor seleccionado. Los actores de sistema/desconocidos también usan su valor literal como etiqueta. Un ID de miembro o correo por sí solo no selecciona `user`; la identidad de token/cuenta tiene prioridad sobre `system_event`.
>
> **Usa `log.account_id` para correlacionar cuentas y `log.ws_member_id` para correlacionar miembros del espacio de trabajo, cuando estén disponibles.** Un ID de actor `user` puede identificar cualquiera de esos dos tipos de registro; no lo trates siempre como un ID de cuenta. `actor_display` es una etiqueta, no una clave estable para relacionar registros.
>
> Si una acción no tiene un mapeo específico de severidad, los eventos correctos de Backoffice usan `medium` y los demás eventos correctos usan `low`; los fallos de Backoffice usan `high` y los demás fallos usan `medium`. Un actor `unknown` no implica un resultado desconocido ni cambia la severidad.

> **Ejemplo de evento HTTP (campos seleccionados)**
>
> ```json theme={null}
> {
>   "schema": "zylon.canonical_json.v1",
>   "severity": "low",
>   "outcome": "success",
>   "actor": {
>     "actor_type": "user",
>     "actor_id": "01985a4d-3c21-7000-8003-0e10dd81d901",
>     "actor_display": "operator@example.com"
>   },
>   "log": {
>     "id": "01985a4d-3c21-7000-8003-0e10dd81d902",
>     "event": "zylon.workspace",
>     "action": "ws.project.create",
>     "request_id": "example-request",
>     "start_timestamp": "2026-10-14T10:00:00Z",
>     "end_timestamp": "2026-10-14T10:00:00Z"
>   }
> }
> ```

Valida el parser con un evento de prueba recibido. Los campos opcionales pueden estar ausentes y no todos los eventos incluyen `action`. Con lotes habilitados, acepta tanto un objeto como un array, según el número de eventos listos para enviar.

> [!NOTE]
>
> La captura de mensajes de solicitud y respuestas del chat del gateway (`features.audit.enabled`) está habilitada por defecto. Los registros reenviados pueden contener ese contenido de chat capturado. Revisa [Registro de Auditoría](/es/v1.58/operator-manual/configuration/features/feat-audit) antes de habilitar la entrega. El parámetro `include` de la API no filtra los registros reenviados.

### 2. Configurar Zylon

Combina este ejemplo con `/etc/zylon/zylon-conf.yaml`, conservando los ajustes existentes. Sustituye la URL y el token por los de tu colector; el token pertenece a tu SIEM, no a la API de Backoffice de Zylon. Si el colector no requiere autenticación bearer, omite el bloque `auth`.

```yaml theme={null}
logging:
  storage:
    enabled: true
  delivery:
    http:
      enabled: true
      format: "canonical_json"
      endpoint:
        url: "https://siem.example.com/ingest/zylon"
        method: "POST"
      auth:
        type: "bearer"
        token: "replace-with-siem-ingestion-token"
      delivery:
        batch:
          maxEvents: 1
```

Deja vacíos los filtros de acción y organización durante la primera prueba para no excluir el evento que generes. Conserva los valores predeterminados de cola, reintentos y política de fallos salvo que tu colector necesite otro comportamiento. Consulta [Entrega por HTTP](#entrega-por-http) para la referencia completa.

### 3. Aplicar la configuración

```bash theme={null}
sudo zylon-cli sync
```

Para despliegues gestionados directamente con Helm, aplica los valores mediante tu proceso habitual de despliegue Helm. Consulta [Resumen de configuración](/es/v1.58/operator-manual/configuration/overview) para el flujo con la CLI.

### 4. Verificar un evento nuevo

Tras aplicar la configuración, crea un proyecto de prueba en el Workspace. Inspecciona la solicitud recibida por tu colector y confirma el marcador `zylon.canonical_json.v1` y `log.action: "ws.project.create"`. Confirma después que el registro aparece en la búsqueda o vista de eventos de tu SIEM.

Si no llega, revisa las advertencias de entrega del backend, la conectividad, las respuestas del colector, la autenticación y los filtros. Las respuestas HTTP `4xx` no se reintentan; corrige la URL, autenticación, cabeceras o parser antes de repetir la prueba. Consulta [Resolución de problemas](#resoluci%C3%B3n-de-problemas) para otros síntomas.

> [!NOTE]
>
> La política predeterminada `failurePolicy: "drop"` puede descartar eventos cuando la cola está llena. La entrega externa no tiene spool persistente en disco. Conserva el almacenamiento interno para investigar y verifica por separado la retención del colector.

### 5. Elegir la retención interna y del SIEM

La limpieza de logs almacenados está deshabilitada por defecto: los logs no se borran automáticamente tras `180` días. Para activar el borrado programado, usa [Limpieza solo de logs](#configurar-limpieza-solo-de-logs). Configura por separado la retención de las copias de tu SIEM.

## Vista rapida

| Canal | Se habilita con | Formatos | Uso recomendado |
| - | - | - | - |
| Almacenamiento interno | `logging.storage.enabled: true` | Registros estructurados de Zylon | Revision en Backoffice y recuperacion manual |
| Syslog | `logging.delivery.syslog.enabled: true` | `rfc5424_json`, `cef` | SIEMs, colectores syslog y colectores CEF |
| HTTP | `logging.delivery.http.enabled: true` | `canonical_json` | Colectores HTTP, gateways de ingesta y destinos cloud |

> [!NOTE]
>
> Syslog y HTTP pueden habilitarse al mismo tiempo. Cuando ambos estan habilitados, Zylon envia los logs coincidentes a ambos destinos.

## Antes de configurar la entrega

* Confirme que el endpoint del colector es accesible desde el backend de Zylon.
* Confirme host o URL y puerto.
* Seleccione transporte y formato.
* Decida el comportamiento de verificacion de certificados TLS.
* Configure el input, indice, parser o ruta de ingesta en el colector.
* Revise los requisitos de retencion en Zylon y en los sistemas externos.
* Revise filtros para no excluir eventos de auditoria requeridos.

## Almacenamiento y retencion

El almacenamiento interno se controla bajo `logging.storage`.

### Claves de almacenamiento

| Clave | Predeterminado | Valores | Descripcion |
| - | - | - | - |
| `enabled` | `true` | `true`, `false` | Habilita la persistencia interna de logs estructurados. |

### Claves de retencion

La limpieza de logs internos se controla bajo `zylonBackend.scheduler.cleanup`.

Configuracion del programador:

| Clave | Predeterminado | Valores | Descripcion |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Habilita el programador de limpieza. |
| `cron` | `0 3 * * *` | expresion cron | Programacion de limpieza. Compartida con el borrado permanente. |
| `minimumIntervalMinutes` | `1440` | minutos enteros | Intervalo mínimo predeterminado en Helm para el cron. Un cron más frecuente se rechaza salvo que se reduzca este ajuste. |
| `timezone` | `UTC` | zona horaria | Zona horaria usada por la programacion. Compartida con el borrado permanente. Si el ajuste runtime se omite fuera de Helm, el backend usa la zona horaria JVM del servidor. |

Bajo `logging`:

| Clave | Predeterminado | Valores | Descripcion |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Habilita la limpieza de logs almacenados. |
| `deleteAfterDays` | `180` | días enteros positivos | Borra definitivamente logs persistidos antes del umbral de retención. |

> [!NOTE]
>
> La limpieza de logs almacenados esta deshabilitada por defecto. El valor `180` dias aplica solo despues de habilitar tanto el programador de limpieza como la limpieza de logs almacenados.

> [!WARNING]
>
> La limpieza de logs usa el mismo cron y la misma zona horaria que el borrado permanente. Revise [Borrado permanente](/es/v1.58/operator-manual/configuration/cron-tasks/hard-delete) antes de cambiar la programacion compartida.

### Configurar limpieza solo de logs

Combina este ejemplo con tu configuración solo cuando quieras activar el borrado interno de logs. Programa revisiones diarias a las `03:00 UTC` con una ventana de retención de `180` días:

```yaml theme={null}
zylonBackend:
  scheduler:
    cleanup:
      enabled: true
      cron: "0 3 * * *"
      timezone: "UTC"
      minimumIntervalMinutes: 1440
      workspace:
        enabled: false
      logging:
        enabled: true
        deleteAfterDays: 180
```

Tanto `cleanup.enabled` como `cleanup.logging.enabled` deben ser `true`. `workspace.enabled: false` mantiene deshabilitado el borrado permanente de Workspace en este ejemplo; el valor predeterminado en Helm es `true`, por lo que debes revisar este flag antes de habilitar el programador compartido. Conserva tu política de limpieza de Workspace si ya la utilizas.

Tras aplicar la configuración con `sudo zylon-cli sync`, cada ejecución programada borra definitivamente registros persistidos hace más de `180` días, junto con sus detalles de log asociados. La antigüedad usa el timestamp `created_at` del registro almacenado, asignado al persistir logs nuevos. Los registros históricos migrados desde versiones anteriores pueden usar la hora de inicio del evento. Los registros elegibles permanecen hasta una ejecución de limpieza correcta. La limpieza afecta a todas las organizaciones y familias de logs; los filtros de entrega externa no limitan el borrado.

Para detener la limpieza de logs, configura `zylonBackend.scheduler.cleanup.logging.enabled: false`. Deshabilitar `logging.storage.enabled` detiene la persistencia de logs nuevos; no borra registros existentes. La limpieza no borra copias enviadas a tu SIEM ni cambia su política de retención.

> [!WARNING]
>
> Usa un número entero positivo para `cleanup.logging.deleteAfterDays`. `0` no significa retención ilimitada: hace que los logs existentes sean elegibles para borrado. Los valores negativos también pueden borrar registros recientes. Deshabilita la limpieza mediante su flag `enabled`.

## Entrega por syslog

La entrega por syslog envia registros formateados a un colector por TCP, TLS o UDP.

Use `rfc5424_json` para pipelines syslog estructurados. Use `cef` cuando el colector tenga un input CEF nativo.

| Formato | Descripcion | Uso |
| - | - | - |
| `rfc5424_json` | Syslog RFC 5424 con un sobre JSON en el cuerpo. El esquema es `zylon.rfc5424_json.v1`. | Eventos estructurados para SIEM o busqueda. |
| `cef` | Formato CEF bruto. La extension CEF incluye el registro estructurado bajo `cs1`. | Colectores con input CEF nativo. |

| Transporte | Comportamiento |
| - | - |
| `tls` | Socket TLS persistente. Admite verificacion de certificado y CA personalizada. |
| `tcp` | Socket TCP persistente sin TLS. |
| `udp` | Entrega por datagrama. Un evento por datagrama; el framing se ignora. |

### Claves de syslog

Bajo `logging.delivery.syslog`:

| Clave | Predeterminado | Valores | Descripcion |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Habilita entrega por syslog. |
| `format` | `rfc5424_json` | `rfc5424_json`, `cef` | Formato del payload syslog. |
| `endpoint.host` | vacio | hostname o IP | Host del colector. Requerido cuando syslog esta habilitado. |
| `endpoint.port` | `6514` | puerto TCP/UDP valido | Puerto del colector. |
| `endpoint.transport` | `tls` | `tls`, `tcp`, `udp` | Transporte del socket. |
| `endpoint.framing` | `newline` | `newline`, `octet_counting` | Framing para TCP/TLS. Ignorado para UDP. |

> **Claves opcionales de syslog**
>
> Los filtros y ajustes opcionales de entrega, cola, lotes y TLS se configuran bajo sus bloques anidados correspondientes en `logging.delivery.syslog`.
>
> Bajo `filters`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `includeActionPatterns` | `[]` | lista wildcard | Si no esta vacia, solo se entregan acciones coincidentes. |
> | `excludeActionPatterns` | `[]` | lista wildcard | Las acciones coincidentes se excluyen antes de evaluar inclusiones. |
> | `includeOrgIds` | `[]` | lista de UUIDs | Si no esta vacia, solo se entregan logs de esas organizaciones. |
>
> Bajo `delivery`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `timeoutSeconds` | `10` | entero positivo | Timeout de conexion y escritura. |
> | `failurePolicy` | `drop` | `drop`, `block` | Comportamiento cuando la cola asincrona esta llena. |
>
> Bajo `delivery.reconnect`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `enabled` | `true` | `true`, `false` | Habilita reconexion tras fallo. |
> | `backoffSeconds` | `5` | entero no negativo | Espera antes de reconectar. |
>
> Bajo `delivery.queue`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `maxEvents` | `10000` | entero positivo | Capacidad de la cola asincrona. |
>
> Bajo `delivery.batch`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `maxEvents` | `25` | entero positivo | Eventos maximos por lote. Forzado a `1` en UDP. |
> | `maxDelayMillis` | `250` | entero positivo | Espera maxima antes de enviar un lote parcial. |
> | `drainTimeoutMillis` | `1000` | entero positivo | Tiempo de drenaje durante apagado. |
>
> Bajo `tls`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `verifyCertificate` | `false` | `true`, `false` | Habilita verificacion de certificado y hostname TLS. |
> | `caCrt` | vacio | datos PEM | Certificado CA inline. Si se define y `caFile` esta vacio, el chart lo monta para el backend. |
> | `caFile` | vacio | ruta legible | Bundle CA personalizado usado cuando la verificacion esta habilitada. |

### Ejemplo completo de syslog

```yaml theme={null}
logging:
  storage:
    enabled: true
  delivery:
    syslog:
      enabled: true
      format: "rfc5424_json"
      endpoint:
        host: "syslog.example.com"
        port: 6514
        transport: "tls"
        framing: "newline"
      filters:
        includeActionPatterns:
          - "ws.*"
          - "backoffice.*"
        excludeActionPatterns:
          - "ws.user.enable"
        includeOrgIds:
          - "01985a4d-3c21-7000-8003-0e10dd81d901"
      delivery:
        timeoutSeconds: 10
        failurePolicy: "drop"
        reconnect:
          enabled: true
          backoffSeconds: 5
        queue:
          maxEvents: 10000
        batch:
          maxEvents: 25
          maxDelayMillis: 250
          drainTimeoutMillis: 1000
      tls:
        verifyCertificate: true
        caFile: "/etc/zylon/certs/syslog-ca.pem"
```

El ejemplo completo limita la entrega a acciones de Workspace y Backoffice coincidentes de una organización. Elimina o revisa esos filtros si también necesitas eventos de seguridad o del gateway sin acción o ID de organización.

## Entrega por HTTP

La entrega por HTTP envia registros JSON estructurados a un colector HTTP. El formato admitido es `canonical_json`; el esquema es `zylon.canonical_json.v1`.

HTTP admite `POST`, autenticacion bearer opcional, cabeceras estaticas con `Header=Value` o `Header: Value`, reintentos para errores de red y respuestas `5xx`, y no reintenta respuestas `4xx`.

### Claves de HTTP

Bajo `logging.delivery.http`:

| Clave | Predeterminado | Valores | Descripcion |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Habilita entrega por HTTP. |
| `format` | `canonical_json` | `canonical_json` | Formato del payload HTTP. |
| `endpoint.url` | vacio | URL | Requerido cuando HTTP esta habilitado. |
| `endpoint.method` | `POST` | `POST` | Metodo HTTP. |
| `headers` | `[]` | lista YAML, hasta 5 entradas | Cabeceras salientes estáticas. |

> **Claves opcionales de HTTP**
>
> La autenticacion y los ajustes opcionales de filtros, entrega, cola y lotes se configuran bajo sus bloques anidados correspondientes en `logging.delivery.http`.
>
> Bajo `auth`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `type` | `none` | `none`, `bearer` | Modo de autenticacion. |
> | `token` | vacio | string | Requerido cuando `type` es `bearer`. |
>
> Bajo `filters`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `includeActionPatterns` | `[]` | lista wildcard | Si no esta vacia, solo se entregan acciones coincidentes. |
> | `excludeActionPatterns` | `[]` | lista wildcard | Las acciones coincidentes se excluyen antes de evaluar inclusiones. |
> | `includeOrgIds` | `[]` | lista de UUIDs | Si no esta vacia, solo se entregan logs de esas organizaciones. |
>
> Bajo `delivery`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `timeoutSeconds` | `10` | entero positivo | Timeout HTTP de conexion, lectura y escritura. |
> | `failurePolicy` | `drop` | `drop`, `block` | Comportamiento cuando la cola asincrona esta llena. |
>
> Bajo `delivery.retry`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `enabled` | `true` | `true`, `false` | Habilita reintentos HTTP. |
> | `maxAttempts` | `3` | entero positivo | Intentos maximos cuando los reintentos estan habilitados. |
> | `backoffSeconds` | `3` | entero no negativo | Espera entre reintentos. |
>
> Bajo `delivery.queue`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `maxEvents` | `10000` | entero positivo | Capacidad de la cola asincrona. |
>
> Bajo `delivery.batch`:
>
> | Clave | Predeterminado | Valores | Descripcion |
> | - | - | - | - |
> | `maxEvents` | `25` | entero positivo | Eventos maximos por peticion HTTP. Los lotes se envian como array JSON. |
> | `maxDelayMillis` | `250` | entero positivo | Espera maxima antes de enviar un lote parcial. |
> | `drainTimeoutMillis` | `1000` | entero positivo | Tiempo de drenaje durante apagado. |

### Ejemplo completo de HTTP

```yaml theme={null}
logging:
  delivery:
    http:
      enabled: true
      format: "canonical_json"
      endpoint:
        url: "https://collector.example.com/logs"
        method: "POST"
      auth:
        type: "bearer"
        token: "replace-me"
      headers:
        - "X-Collector-Token=replace-me"
        - "X-Customer: default"
      filters:
        includeActionPatterns: []
        excludeActionPatterns: []
        includeOrgIds: []
      delivery:
        timeoutSeconds: 10
        failurePolicy: "drop"
        retry:
          enabled: true
          maxAttempts: 3
          backoffSeconds: 3
        queue:
          maxEvents: 10000
        batch:
          maxEvents: 25
          maxDelayMillis: 250
          drainTimeoutMillis: 1000
```

## Filtrado de eventos entregados

Syslog y HTTP usan el mismo comportamiento bajo `filters`.

| Clave | Predeterminado | Valores | Descripcion |
| - | - | - | - |
| `includeActionPatterns` | `[]` | lista wildcard | Si no está vacía, solo se entregan acciones coincidentes; los logs sin acción se excluyen. `*` coincide con cualquier número de caracteres. |
| `excludeActionPatterns` | `[]` | lista wildcard | Las acciones coincidentes se excluyen antes de evaluar inclusiones. |
| `includeOrgIds` | `[]` | lista de UUIDs | Si no esta vacia, solo se entregan logs de esas organizaciones. Los logs sin `organization_id` no se entregan. |

Orden de evaluacion:

1. Patrones de exclusion de accion.
2. Patrones de inclusion de accion.
3. IDs de organizacion incluidos.

## Controles operativos

Mantenga todos los nodos backend de Zylon sincronizados con una fuente horaria confiable como NTP. El chart Helm configura `UTC` por defecto para el programador de limpieza; si el ajuste runtime se omite fuera de Helm, el backend usa la zona horaria JVM del servidor. Los registros deben revisarse en UTC para correlacion forense entre sistemas.

Trate cambios en `logging.storage`, `logging.delivery`, filtros, retencion y destinos de colector como cambios de despliegue auditables. Capture aprobaciones y diffs en GitOps, change management, auditoria Kubernetes o el sistema de auditoria de infraestructura usado por el cliente.

Los esquemas entregados usan marcadores como `zylon.rfc5424_json.v1` y `zylon.canonical_json.v1`. Los parsers SIEM deben enrutar por marcador y validar compatibilidad al actualizar.

## Politicas de fallo

| Politica | Comportamiento | Uso |
| - | - | - |
| `drop` | Descarta eventos cuando la cola esta llena y evita bloquear requests. | Predeterminado recomendado para produccion. |
| `block` | Aplica backpressure cuando la cola esta llena. | Use solo si la completitud de entrega es mas importante que la latencia. |

> [!WARNING]
>
> `failurePolicy: "block"` puede ralentizar requests cuando la cola de entrega esta llena. Uselo solo despues de dimensionar colas y confirmar disponibilidad del colector.

El spooling de entrega externa respaldado por disco no esta implementado.

Estas políticas solo controlan la presión de la cola. `block` no garantiza la entrega: una respuesta no reintentable o el agotamiento de reintentos puede descartar el lote. Las respuestas HTTP `4xx`, incluido `429`, no se reintentan; los errores de red y HTTP `5xx` sí se reintentan según la configuración. No hay spool persistente ni recuperación automática desde el almacenamiento interno.

## Validacion local

1. Habilite un canal de entrega.
2. Aplique la configuracion.
3. Ejecute una accion de API que emita un log, como crear un proyecto o un token de API.
4. Consulte el colector.
5. Confirme que aparecen `event`, `action`, `log.id` y campos de actor esperados.
6. Revise logs del backend si la entrega no llega.

Marcadores utiles:

* `zylon.rfc5424_json.v1` para syslog RFC 5424 JSON.
* `CEF:0|Zylon` para CEF.
* `zylon.canonical_json.v1` para HTTP.
* Una accion conocida como `ws.project.create`.

## Resolución de problemas

| Síntoma | Qué revisar |
| - | - |
| No llegan eventos | `logging.delivery.http.enabled` o `logging.delivery.syslog.enabled`, ajustes anidados de `endpoint`, conectividad, filtros y advertencias del backend. Aplica los cambios con `sudo zylon-cli sync` en instalaciones gestionadas con la CLI. |
| Falla la entrega HTTP | `endpoint.url`, `endpoint.method`, token bearer del colector, cabeceras y respuestas HTTP. Confirma que el colector acepta arrays JSON para lotes con varios eventos o configura `delivery.batch.maxEvents: 1`. |
| HTTP falla sin reintentos | Las respuestas HTTP `4xx` no se reintentan. Corrige autenticación, URL, cabeceras o ruta de ingesta. |
| Falla la conexión TLS de syslog | Verificación del certificado, archivo CA, certificado del colector y hostname. |
| Faltan eventos durante picos | Tamaño de cola, capacidad del colector y política `failurePolicy: "drop"`. La entrega externa no tiene spool persistente en disco. |


# n8n
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/n8n



> [!TIP]
>
> El soporte de n8n está disponible a partir de Zylon 1.52

## Integración de n8n

[n8n](https://n8n.io/) es una herramienta de automatización de flujos que ahora está integrada en Zylon, permitiendo crear flujos conectando diferentes servicios y sistemas. El despliegue y la configuración de n8n son gestionados automáticamente por Zylon, requiriendo una configuración mínima por parte del usuario.

### Consideraciones importantes

* **Gestión de versiones**: Zylon gestiona la versión de n8n desplegada para asegurar la compatibilidad con el resto del sistema. Las actualizaciones manuales de n8n no están disponibles.
* **Acceso**: n8n está disponible en su propio subdominio (por defecto: `https://n8n.tu-instancia-zylon.com`)
* **Gestión de usuarios**: La gestión de usuarios en n8n es independiente de los usuarios de Zylon. Los usuarios deben crearse y gestionarse directamente dentro de la interfaz de n8n.

### Configuración

Para habilitar n8n en tu entorno solo necesitas modificar la opción correspondiente en el archivo `/etc/zylon/zylon-conf.yaml`:

```yaml theme={null}
n8n:
  enabled: true  # Establecer en false para deshabilitar n8n
  host: ""  # (opcional) Especifica un host personalizado.
  publicApi:
    enabled: false  # Habilitar la API REST pública de n8n
  externalConnection:
    enabled: false  # Permitir conexiones salientes a servicios de n8n
  license:
    key: ""  # Clave de licencia de n8n
```

> [!NOTE]
>
> La API pública de n8n permite gestionar workflows, ejecuciones, credenciales
> y otros recursos de forma programática mediante endpoints REST ([Documentación de la API](https://docs.n8n.io/api/))

> [!WARNING]
>
> Los campos de `license` solo aplican cuando `externalConnection.enabled` está configurado en `true` y se tiene conexión a internet.

> [!WARNING]
>
> En modo Semi/Full AirGap, `externalConnection.enabled` siempre estará en `false` independientemente del valor configurado.

### Configuración de Certificados SSL (Opcional)

> [!WARNING]
>
> Esta sección es necesaria únicamente si no estás utilizando certificados de Let's Encrypt

Si tu instalación de Zylon utiliza certificados SSL manuales (no Let's Encrypt), necesitarás crear un secret adicional de Kubernetes específicamente para n8n.

#### Crear un Secret para n8n

Una vez tengas tus archivos de certificado listos (`tls.crt` y `tls.key`), crea un secret en el cluster de Kubernetes específicamente para n8n:

```bash theme={null}
# Crear el secret SSL de n8n
sudo k0s kubectl create secret tls zylon-tls-n8n --key tls.key --cert tls.crt -n zylon

# Verifica que se creó correctamente
sudo k0s kubectl describe secret zylon-tls-n8n -n zylon
```

Después de crear el secret, recarga la configuración:

```bash theme={null}
sudo zylon-cli sync
```

Tu instancia de n8n ahora utilizará HTTPS con los certificados SSL configurados.

### External Connections

Cuando las conexiones externas están deshabilitadas, ciertas funcionalidades de n8n se desactivan automáticamente:

* **Paquetes de la comunidad**: La instalación de paquetes desde el registro NPM está deshabilitada
* **Templates de flujos de trabajo**: Los templates de flujos de trabajo de la comunidad están deshabilitados
* **Activación de licencias**: Las licencias no se validan y no funcionarán en este modo

Estas restricciones aseguran que n8n opere sin dependencias externas.

### Configuración de Proxy

n8n utiliza la configuración global de proxy de Zylon. El propio sistema se encarga de gestionar automáticamente los certificados y endpoints del proxy,
por lo que no se requiere configuración adicional específica para n8n.

Si tu organización usa un proxy, configúralo siguiendo la [guía de configuración de proxy](/es/v1.58/operator-manual/configuration/network/proxy).

### Solución de Problemas

#### DNS

Si experimentas problemas de resolución DNS con n8n (por ejemplo, búsquedas lentas o fallidas para servicios internos), puedes necesitar ajustar la configuración `dnsConfig.options.ndots`.
Para aplicar configuraciones DNS personalizadas, añade lo siguiente a tu configuración:

```yaml theme={null}
n8n:
  dnsConfig:
    options:
      - name: ndots
        value: "1" # El valor por defecto es 5
```

Después de hacer cambios, ejecuta `sudo zylon-cli sync` para aplicarlos.

#### Rechazo de Certificados

Si tienes un certificado autofirmado, n8n podría rechazarlo. Para evitar la verificación TLS en llamadas internas puedes configurar el siguiente flag:

```yaml theme={null}
n8n:
  tlsRejectUnauthorized: "0"  # El valor por defecto es "1". Entre comillas: un 0 sin comillas se ignora
```

Después de hacer cambios, ejecuta `sudo zylon-cli sync` para aplicarlos.

## Gestión de  Backups

n8n utiliza PostgreSQL como base de datos, lo que significa que toda la información de n8n se incluye automáticamente en los backups estándar de base de datos de Zylon. Para más información sobre la gestión de backups, consulta la [documentación de backups de Zylon](/es/v1.58/operator-manual/operations/backup).

Para casos específicos de migración o transferencia de workflows entre entornos, consulta la sección [Importación y Exportación de Workflows](#importación-y-exportación-de-workflows).

## Aplicar Configuración

Después de modificar el archivo de configuración, aplica los cambios:

```bash theme={null}
sudo zylon-cli sync
```

## Importación y Exportación de Workflows

n8n proporciona comandos CLI que permiten la exportación e importación selectiva de entidades. Estos comandos son especialmente útiles para:

* **Migración desde otros entornos**: Si se desea migrar a Zylon información de n8n desde otro entorno existente.
* **Importación selectiva**: Exportar workflows específicos desde otros entornos e importarlos en Zylon sin necesidad de migrar la instancia completa.

> [!NOTE]
>
> Para más información sobre comandos CLI, consulta la [documentación oficial de n8n](https://docs.n8n.io/hosting/cli-commands/).

### Comandos básicos de Exportación

**Exportar todos los workflows:**

```bash theme={null}
n8n export:workflow --all --output=/home/node/.n8n/workflows.json
```

**Exportar un workflow específico:**

```bash theme={null}
n8n export:workflow --id=42 --output=/home/node/.n8n/workflow-42.json
```

**Exportar credenciales:**

```bash theme={null}
n8n export:credentials --all --output=/home/node/.n8n/credentials.json
```

**Exportar credenciales desencriptadas**:

```bash theme={null}
n8n export:credentials --all --output=/home/node/.n8n/credentials.json --decrypted
```

> [!TIP]
>
> Usa la opción `--decrypted` cuando migres entre instancias con diferentes claves de encriptación.

**Exportar instancia completa:**

```bash theme={null}
n8n export:entities --outputDir=./outputs --includeExecutionHistoryDataTables=true
```

### Comandos básicos de Importación

**Importar workflows:**

```bash theme={null}
n8n import:workflow --input=/home/node/.n8n/workflows.json
```

**Importar un workflow específico:**

```bash theme={null}
n8n import:workflow --input=/home/node/.n8n/workflow-42.json
```

**Importar credenciales:**

```bash theme={null}
n8n import:credentials --input=/home/node/.n8n/credentials.json
```

Se espera que la base de datos esté vacía antes de la importación, esto se puede forzar con el --truncateTables parámetro.

**Importar instancia completa:**

> [!WARNING]
>
> Solo funciona si el tipo de base de datos de exportación coincide con el tipo de base de datos de destino. Zylon n8n utiliza PostgreSQL.

```bash theme={null}
n8n import:entities --inputDir ./outputs --truncateTables true
```

### Transferir archivos desde tu máquina local

Si necesitas importar workflows, credenciales u otros archivos ubicados en tu máquina local, primero debes transferirlos al pod de n8n:

#### 1. Obtener el ID del volumen persistente

```bash theme={null}
# Obtener el ID del Persistent Volume de n8n
N8N_PV_ID=$(kubectl get pvc zylon-n8n-data -o jsonpath='{.spec.volumeName}' -n zylon)

# Construir la ruta del directorio
N8N_PV_DIR="/var/zylon/data/$N8N_PV_ID"

# Ver el resultado
echo $N8N_PV_DIR
```

#### 2. Copiar archivos al volumen

```bash theme={null}
# Copiar archivo desde tu máquina local
sudo cp /ruta/local/workflows.json $N8N_PV_DIR/
```

#### 3. Acceder al pod y verificar el archivo

```bash theme={null}
kubectl exec -it deployment/zylon-n8n -n zylon -- /bin/sh
# Dentro del pod, verifica que el archivo esté disponible
ls /home/node/.n8n/
```

### Notas Importantes

> [!WARNING]
>
> Las entidades exportadas conservan sus IDs originales, por lo que importarlas sobrescribirá las entidades existentes con el mismo ID.

> [!WARNING]
>
> Los archivos de exportación deben ubicarse en un directorio accesible dentro del pod, típicamente `/home/node/.n8n/`.


# Puertos y DNS
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/network/ports-and-dns



Estos puertos **deben estar abiertos** para que Zylon funcione:

* 80: Puerto http por defecto. Solo se usa durante la generación de certificados SSL con [https://letsencrypt.org/](https://letsencrypt.org/). Si planeas proporcionar tus propios certificados SSL, este puerto es opcional.
* 443: Puerto https por defecto. Se usa para el resto del tráfico.

Mapea el tráfico a los puertos 80 y 443

* Puerto Zylon 80 ↔ Puerto Host 80
* Puerto Zylon 443 ↔ Puerto Host 443

Puertos adicionales / Temporalmente abiertos:

* 22: Puerto SSH. Durante la instalación y configuración inicial, este puerto debe estar abierto para que tu equipo de TI o el equipo de operaciones de Zylon puedan ayudarte a poner la aplicación en funcionamiento. Como práctica general de seguridad, debes cerrar este puerto tan pronto como se complete la instalación.
* 6443: Servicio API de Kubernetes. Para ayudar a nuestro equipo a depurar aún más tu instalación, también puedes abrir el puerto 6443 **temporalmente**. Todas las conexiones al servicio de Kubernetes están autenticadas, tener este puerto abierto no pone tus datos en riesgo. Durante el tiempo que el puerto esté abierto, permitirá al equipo de Operaciones de Zylon acceder a tu máquina.

### Configuración DNS

Se necesitan los siguientes requisitos para que Zylon funcione:

* Elige un dominio para Zylon, por ejemplo: `zylon.company.com.` Se requiere un nombre de dominio para una conexión segura.
* Configura las entradas DNS para que `zylon.company.com` apunte a la máquina donde está instalado Zylon

Después de haber instalado Zylon en tu entorno, se deben realizar algunos pasos adicionales para poder acceder a él a través de internet (o VPN).

Ten en cuenta estos puntos:

* La aplicación web se ejecuta localmente en el navegador web del usuario.
* El servidor se ejecuta en la máquina donde fue instalado.
* **DEBES** configurar SSL/HTTPS tú mismo o delegar a Zylon para que lo haga automáticamente por ti
* **NO** actives el redireccionamiento SSL a menos que planees proporcionar certificados SSL personalizados.

Durante la instalación, se eligió un dominio para ser el punto de entrada de Zylon. Esto se usará como el parámetro `host` en la configuración (por ejemplo [`zylon.company.com`](http://zylon.company.com))

```yaml theme={null}
# /etc/zylon/zylon-conf.yaml
# ...
ingress:
  host: "zylon.company.com"
# ...
```

### Ejemplo de configuración DNS

Zylon está instalado en una máquina con IP `32.41.12.123`. Tu entrada DNS podría verse así:

```bash theme={null}
**# Configuración DNS para un EC2 alojado en AWS
zylon.company.com. 1800 IN CNAME ec2-32-41-12-123.compute-1.amazonaws.com.

# Similar con un Registro A, usando la IP directamente 
zylon.company.com. 1800 IN A** 32.41.12.123
```

```bash theme={null}
**# Configuración DNS para un Registro A, usando la IP directamente 
zylon.otacv.com. 1800 IN A** 32.41.12.123
```


# Proxy
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/network/proxy



> [!TIP]
>
> El soporte de proxy está disponible a partir de Zylon 1.48 y CLI versión 1.23

Si tu instalación de Zylon se está ejecutando en una red LAN que requiere un proxy para el acceso a internet,
sigue estos pasos para configurar los ajustes del proxy.

**1. Determinar el tipo de proxy**

Hay dos tipos de proxies:

**Proxy de Inspección SSL:**

* Intercepta e inspecciona el tráfico HTTPS
* Descifra el tráfico usando su propio certificado SSL, luego lo vuelve a cifrar
* Permite inspección profunda de paquetes y filtrado de contenido

**Proxy Transparente:**

* Reenvía el tráfico HTTPS sin inspeccionarlo
* No modifica los certificados SSL/TLS
* Actúa como un simple paso para conexiones cifradas

Para determinar qué tipo tienes, ejecuta el siguiente comando, reemplazando `your-proxy-address:port` con los detalles de tu proxy:

```bash theme={null}
curl -x your-proxy-address:port -v https://example.com 2>&1 | grep -A 5 "Server certificate" | grep "issuer:"
```

Mira la salida:

* Si obtienes un **error SSL**, tienes un **proxy de inspección SSL**
* Si el comando tiene éxito, verifica el campo `issuer`:
  * Si el emisor es una autoridad de certificación pública (DigiCert, Let's Encrypt, etc.),
    tienes un **proxy transparente**
  * Si el emisor es la CA interna de tu organización o el nombre del servidor proxy,
    tienes un **proxy de inspección SSL**

**2. Configurar los ajustes del proxy**

Edita `/etc/zylon/zylon-conf.yaml` según tu tipo de proxy:

**Proxy de Inspección SSL**

```yaml theme={null}
proxy:
  enabled: true
  httpProxy: "http://your-proxy-address:port"
  httpsProxy: "http://your-proxy-address:port"
  noProxy: "your,no,proxy,exceptions"
  crt: |-
    -----BEGIN CERTIFICATE-----
    MIIDoTCCAomgAwIBAgIGEAHcBPNvMA0GCSqGSIb3DQEBCwUAMCgxEjAQBgNVBAMM
    ...
    ipRF9TO2AlABfLmTR7uN8o0Opc92
    -----END CERTIFICATE-----
```

> [!TIP]
>
> Para obtener el certificado CA de tu proxy, puedes intentar ejecutar:
>
> ```bash theme={null}
> echo | openssl s_client -showcerts -connect your-proxy-address:port 2>/dev/null | openssl x509
> ```
>
> Ten en cuenta que esto puede no funcionar con todos los proveedores de proxy. Si falla, contacta a tu administrador de red
> para obtener el certificado CA.

**Proxy Transparente**

```yaml theme={null}
proxy:
  enabled: true
  httpProxy: "http://your-proxy-address:port"
  httpsProxy: "http://your-proxy-address:port"
  noProxy: "your,no,proxy,exceptions"
```

> [!CAUTION]
>
> No establezcas el campo `crt` para proxies transparentes. Si requieres capacidades de inspección SSL, debes reconfigurar tu infraestructura de proxy para inspección SSL y luego seguir las instrucciones en la pestaña **Proxy de Inspección SSL** arriba.

**3. Aplicar la configuración**

Ejecuta el comando de actualización para aplicar los cambios:

```bash theme={null}
sudo zylon-cli sync
```

**4. Reiniciar servicios (opcional, si tu clúster ya estaba ejecutándose)**

Si el clúster estaba ejecutándose antes de aplicar los ajustes del proxy, reinicia el controlador k0s y
recrea los pods de Zylon:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart k0scontroller
# Espera unos segundos hasta que el clúster se inicie de nuevo
kubectl delete pods -n zylon --all
```


# Destinos de métricas
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/observability/destinations



Usa destinos cuando quieras enviar las métricas de Zylon a tu propio backend de monitorización.

Esto requiere:

* `observability.monitoring: true`
* un destino bajo `k8s-monitoring.extraDestinations`

Si necesitas reemplazar los destinos por defecto de Zylon en lugar de añadir nuevos, consulta [Sobrescribir los destinos por defecto de Zylon](#sobrescribir-los-destinos-por-defecto-de-zylon).

## Backends compatibles

Zylon soporta tres familias de backend:

| Backend | Tipo YAML | URL típica |
| - | - | - |
| Prometheus | `prometheus` | `https://prometheus.example.com/api/v1/write` |
| Backend compatible con Prometheus para Grafana | `prometheus` | `https://<stack>.grafana.net/api/prom/push` |
| Colector OTLP | `otlp` | `https://otel.example.com/v1/metrics` o `grpc://otel.example.com:4317` |

No existe un tipo de destino `grafana` separado. Los servicios de métricas compatibles con Grafana siguen usando `type: prometheus`.

## Estructura del destino

```yaml theme={null}
k8s-monitoring:
  extraDestinations:
    <destination-name>:
      type: prometheus|otlp
      url: <endpoint-url>

      # Define la configuración de autenticación del destino,
      # si tu backend la requiere
      auth:
        type: basic|bearer

      # Define el proxy para conectarte al destino,
      # si tu red lo requiere
      proxyURL: http://proxy:port

      # Define la configuración TLS del destino,
      # si el endpoint usa una CA privada o autofirmada
      tls:
        ca: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
```

## Sobrescribir los destinos por defecto de Zylon

Úsalo cuando quieras reemplazar los destinos gestionados por Zylon en lugar de añadir destinos extra.

Esto usa `destinations`, no `extraDestinations`.

Qué tienes que hacer:

* Mantén la entrada `otlp` y pon `url: "-"` para desactivar el destino OTLP por defecto de Zylon.
* Mantén la entrada `loki` y pon `url: "-"` para desactivar el destino Loki por defecto de Zylon.
* Añade tu propio destino como un nuevo elemento dentro de la misma lista `destinations`.
* Cambia el `name`, el `type` y la `url` del destino para que coincidan con tu backend.
* Si tu endpoint usa una CA privada o autofirmada, sustituye el certificado de ejemplo bajo `tls.ca` por tu propia CA.

Ejemplo:

```yaml theme={null}
destinations:
  - name: otlp
    type: otlp
    protocol: grpc
    url: "-"
  - name: loki
    type: loki
    url: "-"
  - name: my-local-prometheus
    type: prometheus
    url: https://prometheus.example.com/api/v1/write
    tls:
      ca: |
        -----BEGIN CERTIFICATE-----
        MIID...
        -----END CERTIFICATE-----
```

## Ejemplos de destinos

**Prometheus**

Usa `type: prometheus` para un servidor Prometheus autoalojado con remote write activado:

```yaml theme={null}
k8s-monitoring:
  extraDestinations:
    prometheus:
      type: prometheus
      url: https://prometheus.example.com/api/v1/write
      auth:
        type: basic
        username: "zylon-metrics"
        password: "${PROMETHEUS_API_KEY}"
```

Prometheus debe tener activado el receptor de remote write, por ejemplo arrancando Prometheus con:

```bash theme={null}
--web.enable-remote-write-receiver
```

Para endpoints de Prometheus con certificado autofirmado, pasa el certificado CA para mantener la verificación TLS activa:

```yaml theme={null}
k8s-monitoring:
  extraDestinations:
    prometheus-selfsigned:
      type: prometheus
      url: https://prometheus.internal:9090/api/v1/write
      auth:
        type: basic
        username: "admin"
        password: "${PROMETHEUS_PASS}"
      tls:
        ca: |
          -----BEGIN CERTIFICATE-----
          MIID...
          -----END CERTIFICATE-----
```

**Grafana-Compatible**

Grafana Cloud y backends similares usan Prometheus remote write, así que siguen usando `type: prometheus`:

```yaml theme={null}
k8s-monitoring:
  extraDestinations:
    grafana-cloud:
      type: prometheus
      url: https://<stack>.grafana.net/api/prom/push
      auth:
        type: basic
        username: "your-access-policy-id"
        password: "${GRAFANA_CLOUD_API_KEY}"
```

Usa la URL de escritura exacta y las credenciales que te dé tu proveedor.

**OTLP**

Usa `type: otlp` cuando vayas a enviar métricas a un colector OpenTelemetry.

OTLP sobre HTTPS:

```yaml theme={null}
k8s-monitoring:
  extraDestinations:
    otlp-https:
      type: otlp
      url: https://otel-collector.company.com/v1/metrics
      auth:
        type: bearer
        token: "${OTLP_BEARER_TOKEN}"
```

OTLP sobre gRPC:

```yaml theme={null}
k8s-monitoring:
  extraDestinations:
    otlp-grpc:
      type: otlp
      url: grpc://otel-collector.company.com:4317
      auth:
        type: bearer
        token: "${OTLP_GRPC_TOKEN}"
```

## Múltiples destinos

Puedes enviar métricas a más de un backend al mismo tiempo:

```yaml theme={null}
k8s-monitoring:
  extraDestinations:
    grafana-primary:
      type: prometheus
      url: https://prometheus-prod-XX.grafana.net/api/prom/push
      auth:
        type: basic
        username: "primary-access-id"
        password: "${GRAFANA_PRIMARY_KEY}"

    internal-prometheus:
      type: prometheus
      url: https://prometheus.internal:9090/api/v1/write
      auth:
        type: basic
        username: "backup"
        password: "${INTERNAL_PROMETHEUS_KEY}"
      tls:
        ca: |
          -----BEGIN CERTIFICATE-----
          MIID...
          -----END CERTIFICATE-----

    compliance-otel:
      type: otlp
      url: https://compliance-otel.company.com/v1/metrics
      auth:
        type: bearer
        token: "${COMPLIANCE_OTEL_TOKEN}"
```

## Secretos

Usa variables de entorno para tokens y contraseñas:

```yaml theme={null}
password: "${ENV_VARIABLE_NAME}"
```


# Dashboard externo de Grafana
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/observability/external-grafana-dashboard



Esta página es para equipos que usan su propia instancia de Grafana.

Zylon proporciona un dashboard de referencia para métricas de plataforma de Triton y vLLM, pero importarlo es una tarea separada en Grafana. No es necesario para activar la observabilidad en Zylon.

Úsalo cuando quieras un dashboard externo de Grafana para:

* salud del servicio
* rendimiento y errores
* análisis de latencia
* cuellos de botella del scheduler y de GPU

## Qué necesitas antes

Antes de que este dashboard sea útil, necesitas:

* métricas de plataforma activadas en Zylon
* un backend de métricas compatible con Prometheus que ya contenga métricas de Zylon
* una instancia de Grafana con un datasource de Prometheus conectado a ese backend

Consulta [Métricas de plataforma](/es/v1.58/operator-manual/configuration/observability/platform-metrics) y [Destinos de métricas](/es/v1.58/operator-manual/configuration/observability/destinations).

## Importar el dashboard

Descarga [grafana-dashboard.json](https://raw.githubusercontent.com/zylon-ai/zylon-docs/main/snippets/grafana-dashboard.json) e impórtalo en tu instancia de Grafana mediante **Dashboards → Nuevo → Importar**.

Para el flujo de importación en Grafana, consulta la [documentación de importación de dashboards de Grafana](https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/import-dashboards/).

## Qué muestra el dashboard

El dashboard está construido a partir de las métricas expuestas en el endpoint `/metrics` de Triton:

* métricas de **Triton Inference Server** como recuento de peticiones, latencia, profundidad de cola y salud de GPU
* métricas de **vLLM** como estado del scheduler, uso de la caché KV, rendimiento de tokens e histogramas de latencia

## Filtros del dashboard

| Variable | Propósito |
| - | - |
| **Datasource** | Datasource de Prometheus a consultar |
| **Environment** | Despliegue o identificador de empresa |
| **Model** | Modelo servido por Triton |
| **GPU** | Filtro `gpu_uuid` para paneles específicos de GPU |

## Cómo leer el dashboard

Sigue este orden cuando investigues un problema:

| Sección | Qué te ayuda a responder |
| - | - |
| Overview | ¿Está sano el servicio ahora mismo? |
| Throughput & Errors | ¿Cuánto tráfico está gestionando y están fallando peticiones? |
| Latency | ¿Dónde se está yendo el tiempo? |
| Capacity & Scheduler | ¿El cuello de botella es cola, presión de caché KV o batching? |
| Workload Analysis | ¿Qué tipo de peticiones envían los clientes? |
| GPU Health | ¿La GPU está saturada o limitada por memoria? |
| Host Resources | ¿El nodo está bajo presión? |

## Paneles por sección

### Overview

Indicadores rápidos de salud para tasa de éxito, peticiones por segundo, peticiones concurrentes y profundidad de cola.

![Secciones Resumen y Rendimiento y errores](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/overview.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=ffa678e150cfba90250149365a22cff7)

### Throughput & Errors

Tasa de peticiones, tasa de fallos, motivos de fallo, comportamiento de batching y profundidad de cola a lo largo del tiempo.

![Paneles de rendimiento y errores](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/throughput-and-errors.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=719ffa5a3370212bca650fe08e285660)

![Desglose de fallos por motivo, recuento de inferencias vs. ejecuciones y profundidad de la cola de peticiones pendientes](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/throughput-and-errors-2.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=77e5c1bcd5ab65429d11b9a916544db3)

### Latency

Latencia extremo a extremo, desglose por fases, TTFT, TPOT y percentiles de latencia de petición.

![Latencia media de extremo a extremo y cascada de latencia](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/latency.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=fc2f8695e420e4b7369d79389d363a24)

![Cola media, cómputo y sobrecarga de E/S; percentiles TTFT de Triton y vLLM](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/latency-2.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=3c932dd61f0712a5da10b35a94a979b7)

![Tiempo por token de salida, latencia extremo a extremo, tiempo de prefill y decode, cuantiles de resumen de Triton](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/latency-3.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=bfc9cfa2639db65870f1f6a7a7dd9af2)

### Capacity & Scheduler

Estado del scheduler, tiempo en cola, utilización de caché KV, preemptions y tamaño de batch.

![Paneles de capacidad y planificador](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/capacity-and-scheduler.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=0d21f88c6f71d23c0a65673a61801f42)

### Workload Analysis

Rendimiento de tokens, longitud de prompts, longitud de generación y comportamiento de la caché de prefijos.

![Rendimiento de tokens, tokens medios por solicitud y distribuciones de longitud de prompt y generación](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/work-analysis.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=830bbb7e486a419c6e88d93b36fa7a02)

![Máximo de tokens de generación, percentiles de máximo de tokens por solicitud y tasa de acierto de la caché de prefijos](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/work-analysis-2.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=c49177ca41a25f0b6313a01154d59bb8)

### GPU Health

Utilización de GPU, presión de memoria, consumo energético y energía acumulada.

![Utilización de GPU, memoria, consumo energético y energía acumulada](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/gpu-health.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=1467cc9f8ded299875e3aa594a6e60b7)

### Host Resources

CPU, RAM y disponibilidad de disco desde `node_exporter`.

![Uso de CPU, uso de RAM y disponibilidad de disco](https://mintcdn.com/zylon/1MC3EkpeIBooYZ9J/images/operator-manual/observability/host-resources.png?fit=max\&auto=format\&n=1MC3EkpeIBooYZ9J\&q=85\&s=23895b1bd0f315a258bbb47049008199)


# Cómo configurar la observabilidad
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/observability/overview



La observabilidad te ayuda a responder tres preguntas:

* ¿Zylon está sano?
* ¿Qué está haciendo?
* ¿A dónde deben ir sus métricas?

La observabilidad de Zylon tiene cinco partes:

* **Crash reporting** avisa a Zylon cuando la plataforma falla para que soporte pueda diagnosticar el problema.
* **Métricas de uso** envía telemetría anónima de uso a Zylon.
* **Monitorización** instala el stack de monitorización local dentro de tu clúster.
* **Métricas de plataforma** son las métricas técnicas reales de Triton, vLLM, GPU y nodos.
* **Destinos** envía esas métricas a tu propio backend de monitorización.

## Primeros pasos

En la mayoría de los casos, piensa en la observabilidad en este orden:

1. Activa `monitoring` si quieres métricas.
2. Activa `platformMetrics` si quieres métricas de Triton, vLLM, GPU y nodos.
3. Añade `destinations` si quieres enviar esas métricas a tu propio backend.
4. Mantén o desactiva `crashReporting` y `usageMetrics` según quieras o no la telemetría de Zylon.

Ejemplo mínimo:

```yaml theme={null}
observability:
  monitoring: true
  platformMetrics:
    enabled: true
```

Esto te da métricas locales en el stack de monitorización del clúster.

### Crash reporting

```yaml theme={null}
observability:
  crashReporting: true
```

`observability.crashReporting` controla si Zylon envía diagnósticos de fallos a Sentry.

Actívalo si quieres que el equipo de soporte de Zylon tenga información cuando la plataforma falle. Desactívalo si no quieres enviar ningún diagnóstico de fallos a Zylon.

### Métricas de uso

```yaml theme={null}
observability:
  usageMetrics: true
```

`observability.usageMetrics` controla si Zylon envía telemetría anónima de uso a los servicios de observabilidad gestionados por Zylon.

Esta es telemetría de producto, no las métricas detalladas de Triton o vLLM que se usan para operar el clúster. Desactívala si no quieres enviar telemetría de uso a Zylon.

### Monitorización

La monitorización debe estar activada si quieres métricas locales o reenvío de métricas a destinos externos.

```yaml theme={null}
observability:
  monitoring: true
```

`observability.monitoring` instala el stack de monitorización dentro del clúster, incluyendo Prometheus, Grafana y `k8s-monitoring`.

Es la base de todo lo relacionado con métricas. Si `monitoring` está desactivado, no podrás inspeccionar métricas de plataforma localmente ni reenviarlas a tus propios destinos.

### Métricas de plataforma

Las métricas de plataforma requieren `monitoring`:

```yaml theme={null}
observability:
  monitoring: true
  platformMetrics:
    enabled: true
```

`observability.platformMetrics.enabled` activa las métricas operativas generadas por el stack de inferencia.

Son las métricas que se usan para entender tasa de peticiones, fallos, latencia, profundidad de cola, presión del scheduler, uso de GPU y salud del host. Vienen de Triton, vLLM, el exportador de GPU y `node_exporter`.

Para la configuración completa de estas métricas, consulta [Métricas de plataforma](/es/v1.58/operator-manual/configuration/observability/platform-metrics).

### Destinos externos

Los destinos externos también requieren `monitoring`:

```yaml theme={null}
observability:
  monitoring: true

k8s-monitoring:
  extraDestinations:
    my-prometheus:
      type: prometheus
      url: https://prometheus.example.com/api/v1/write
```

`k8s-monitoring.extraDestinations` reenvía las métricas recogidas en tu clúster a tu propio backend de monitorización.

Úsalo solo si quieres enviar métricas fuera del stack de monitorización incorporado, por ejemplo a Prometheus, Grafana Cloud o un colector OTLP.

Para la configuración de destinos, consulta [Destinos de métricas](/es/v1.58/operator-manual/configuration/observability/destinations).

> [!WARNING]
>
> Si tu clúster restringe el tráfico saliente, la telemetría y los destinos externos pueden requerir allowlisting de dominios o endpoints. Si desactivas `usageMetrics`, no necesitas los dominios de telemetría de Zylon.

## Siguientes páginas

Para la configuración principal de Zylon:

* [Métricas de plataforma](/es/v1.58/operator-manual/configuration/observability/platform-metrics): habilita métricas de Triton, vLLM, GPU y nodos
* [Destinos de métricas](/es/v1.58/operator-manual/configuration/observability/destinations): envía métricas a Prometheus, backends compatibles con Grafana u OTLP

Si usas tu propia instancia de Grafana, el dashboard es un paso opcional aparte:

* [Dashboard externo de Grafana](/es/v1.58/operator-manual/configuration/observability/external-grafana-dashboard): importa el dashboard de referencia en tu propia instancia de Grafana


# Métricas de plataforma
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/observability/platform-metrics



Las métricas de plataforma son las métricas operativas generadas por el stack de inferencia que se ejecuta en tu clúster.

Incluyen:

* **Métricas de Triton** como tasa de peticiones, fallos, profundidad de cola y latencia
* **Métricas de vLLM** como estado del scheduler, presión sobre la caché KV y rendimiento de tokens
* **Métricas de GPU** del exportador DCGM
* **Métricas de nodo** de `node_exporter`

## Antes de activarlas

Las métricas de plataforma requieren el stack de monitorización:

```yaml theme={null}
observability:
  monitoring: true
```

## Activar métricas de plataforma

```yaml theme={null}
observability:
  monitoring: true
  platformMetrics:
    enabled: true
    generationIntervalMs: 2000
    gpu:
      enabled: true
    inference:
      counterLatencies: true
      histogramLatencies: true
      summaryLatencies: true
      summaryQuantiles: ""
```

## Opciones de configuración

| Clave | Valor por defecto | Qué controla |
| - | - | - |
| `platformMetrics.enabled` | `false` | Activa la recogida de métricas de plataforma |
| `platformMetrics.generationIntervalMs` | `2000` | Intervalo de generación de métricas de Triton |
| `platformMetrics.gpu.enabled` | `true` | Incluye métricas de GPU |
| `platformMetrics.inference.counterLatencies` | `true` | Activa contadores acumulativos de latencia |
| `platformMetrics.inference.histogramLatencies` | `true` | Activa histogramas de latencia |
| `platformMetrics.inference.summaryLatencies` | `true` | Activa resúmenes de latencia con ventana deslizante |
| `platformMetrics.inference.summaryQuantiles` | `""` | Sobrescribe los cuantiles por defecto de Triton |

## Qué obtienes

### Triton

Familia principal de métricas: `nv_*`

Ejemplos:

* `nv_inference_request_success`
* `nv_inference_request_failure`
* `nv_inference_pending_request_count`
* `nv_inference_request_duration_us`
* `nv_inference_compute_infer_duration_us`

### vLLM

Familias principales de métricas:

* `vllm_llms_v1:*`
* `vllm_embeddings_v1:*`

Ejemplos:

* `vllm_llms_v1:num_requests_running`
* `vllm_llms_v1:kv_cache_usage_perc`
* `vllm_llms_v1:time_to_first_token_seconds_bucket`
* `vllm_llms_v1:generation_tokens_total`

### GPU

Ejemplos:

* `nv_gpu_utilization`
* `nv_gpu_memory_used_bytes`
* `nv_gpu_power_usage`

### Nodo

Familia principal de métricas: `node_*`

Ejemplos:

* `node_cpu_seconds_total`
* `node_memory_MemAvailable_bytes`
* `node_filesystem_avail_bytes`

## Siguiente paso

Una vez activadas las métricas de plataforma, puedes:

* inspeccionarlas en el stack de Grafana del clúster
* reenviarlas a tu propio backend mediante [Destinos de métricas](/es/v1.58/operator-manual/configuration/observability/destinations)
* usar el [Dashboard externo de Grafana](/es/v1.58/operator-manual/configuration/observability/external-grafana-dashboard)

Para las listas completas de métricas upstream, consulta la [referencia de métricas de Triton](https://docs.nvidia.com/deeplearning/triton-inference-server/user-guide/docs/user_guide/metrics.html) y la [referencia de métricas de vLLM](https://docs.vllm.ai/en/stable/usage/metrics/).


# Descripción General de la Configuración
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/overview

Guía completa para configurar su instancia de Zylon

Configure su instancia de Zylon para satisfacer los requisitos específicos de su organización. Esta sección cubre modelos de IA, configuración de red, autenticación, funciones y configuraciones avanzadas.

***

## Flujo de Trabajo de Configuración

**1. Editar Configuración**

Modifique `/etc/zylon/zylon-conf.yaml` con la configuración deseada

**2. Validar Cambios**

Revise su configuración para detectar errores de sintaxis y compatibilidad

**3. Aplicar Configuración**

Ejecute `sudo zylon-cli sync` para aplicar los cambios a su instancia en ejecución

**4. Verificar**

Compruebe que los cambios de configuración hayan tenido el efecto esperado

***

## Configuración Principal

> **[Preajustes de IA](/es/v1.58/operator-manual/ai-presets/getting-started)**
>
> Configure modelos de IA basados en la capacidad de GPU y habilite capacidades especializadas

> **[Conectores de Conocimiento](/es/v1.58/operator-manual/knowledge-base/overview)**
>
> Conéctese a fuentes de datos externas como SharePoint, Confluence y sistemas de archivos

> **[Integración n8n](/es/v1.58/operator-manual/configuration/n8n)**
>
> Habilite y configure la automatización de flujos de trabajo n8n dentro de Zylon

> **[Marca Blanca](/es/v1.58/operator-manual/configuration/whitelabel)**
>
> Personalice la marca, logotipos y apariencia para que coincidan con su organización

***

## Red y Conectividad

> **[Puertos y DNS](/es/v1.58/operator-manual/configuration/network/ports-and-dns)**
>
> Configure los puertos de red y la configuración de DNS necesarios

> **[Configuración de Proxy](/es/v1.58/operator-manual/configuration/network/proxy)**
>
> Configure proxy HTTP/HTTPS para entornos de red restringidos

***

## Autenticación y Seguridad

> **[SSO de Google](/es/v1.58/operator-manual/openid/google)**
>
> Habilite el inicio de sesión único de Google para la autenticación de usuarios

> **[SSO de Microsoft Entra](/es/v1.58/operator-manual/openid/microsoft)**
>
> Configure el inicio de sesión único de Microsoft Entra (Azure AD)

***

## Funciones y Capacidades

Habilite o deshabilite funciones específicas para controlar lo que está disponible para sus usuarios.

> **[Registro de Auditoría](/es/v1.58/operator-manual/configuration/features/feat-audit)**
>
> Configure la captura de mensajes de solicitud y respuestas del chat del gateway

> **[Entrega y almacenamiento de logs](/es/v1.58/operator-manual/configuration/features/log-delivery-storage)**
>
> Configure almacenamiento interno, entrega por syslog y entrega por HTTP

> **[Conector de Base de Datos](/es/v1.58/operator-manual/configuration/features/feat-database)**
>
> Habilite consultas directas a bases de datos desde conversaciones de chat

> **[Instrucciones personalizadas de proyecto](/es/v1.58/operator-manual/configuration/features/feat-project-custom-instructions)**
>
> Configure el maximo de instrucciones y entienda los ajustes de comportamiento del chat a nivel de proyecto

> **[Omnisearch](/es/v1.58/operator-manual/configuration/search)**
>
> Configure los idiomas de búsqueda por palabras clave y la longitud máxima de las consultas

> **[Conector MCP](/es/v1.58/operator-manual/configuration/features/feat-mcp)**
>
> Integre herramientas del Protocolo de Contexto de Modelo para capacidades extendidas

> **[Monitor del sistema](/es/v1.58/operator-manual/configuration/features/feat-system-monitor)**
>
> Habilite métricas en vivo de recursos del host y servicio de modelos en Backoffice

> **[Procesamiento de Archivos con Visión](/es/v1.58/operator-manual/configuration/features/feat-file-vision)**
>
> Alpha Configura el procesamiento con visión para archivos PPTX y Docling

> **[Soporte Multimodal](/es/v1.58/operator-manual/configuration/features/feat-multimodal)**
>
> Habilite el procesamiento de imágenes y capacidades de visión en modelos de IA

> **[Extracción Web](/es/v1.58/operator-manual/configuration/features/feat-webextract)**
>
> Extraiga y analice contenido de páginas web en tiempo real

> **[Búsqueda Web](/es/v1.58/operator-manual/configuration/features/feat-websearch)**
>
> Habilite capacidades de búsqueda en internet dentro de conversaciones de chat

***

## Tareas cron

Utilice estas paginas para entender como Zylon programa el trabajo recurrente de backend para sincronizacion y borrado permanente.

> **[Sincronizacion](/es/v1.58/operator-manual/configuration/cron-tasks/sync)**
>
> Configure la tarea de sincronizacion programada de integraciones, incluido el cron y la zona horaria

> **[Borrado permanente](/es/v1.58/operator-manual/configuration/cron-tasks/hard-delete)**
>
> Configure la politica de retencion usada para eliminar definitivamente elementos inactivos o borrados

***

## Configuración Avanzada

> **[Observabilidad](/es/v1.58/operator-manual/configuration/observability/overview)**
>
> Configure telemetría, reportes de fallos y métricas de uso para monitoreo

> **[Ajuste de Rendimiento](/es/v1.58/operator-manual/configuration/performance)**
>
> Optimice la utilización de recursos y el threading para un mejor rendimiento

***


# Ajustes de rendimiento
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/performance



## Docling

### Configuración de rendimiento

Docling utiliza una arquitectura de pool de workers donde los workers se dividen automáticamente en dos grupos para calidad de servicio:

* **Workers de archivos pequeños**: Procesan archivos menores a 1MB y con menos de 100 páginas
* **Workers de archivos grandes**: Procesan archivos mayores o iguales a 1MB o con 100 páginas o más

Esto evita que los archivos grandes bloqueen la cola de procesamiento.

#### Parámetros de configuración

**numWorkers**: Número total de workers (se dividen automáticamente 50/50 entre procesamiento de archivos pequeños y grandes)

**numThreads**: Total de hilos disponibles entre todos los workers. Cada worker recibe `numThreads / numWorkers` hilos.

> **Restricciones y estrategia de configuración**
>
> **Restricciones**
>
> * `numWorkers >= 2` y debe ser par
> * `numThreads >= 2`
> * `numThreads` debe ser divisible por `numWorkers`
> * Recomendado: Dejar al menos 20-30% de los núcleos libres para procesos del sistema
>
> **Estrategia**
>
> **Alta concurrencia, archivos pequeños** → Muchos workers, menos hilos por worker
>
> * Maximiza el procesamiento paralelo de múltiples documentos pequeños
> * Usar cuando se procesan muchos PDFs de menos de 100 páginas
>
> **Baja concurrencia, archivos grandes** → Menos workers, más hilos por worker
>
> * Asigna más poder computacional por documento
> * Usar cuando se procesan libros escaneados o manuales técnicos

### Configuración adicional

**tableMode**: Controla la estrategia de extracción de tablas

* `accurate`: Máxima precisión, mayor tiempo de procesamiento (predeterminado)
* `fast`: Optimizado para velocidad con buena precisión
* `none`: Deshabilita la extracción de tablas

**doCellMatching**: Habilita el matching de celdas de tabla para mejorar el reconocimiento de estructura. Recomendado para tablas complejas (predeterminado: `true`)

**forceFullPageOCR**: Fuerza OCR de página completa en lugar de regiones selectivas. Usar cuando la extracción estándar omite contenido. Incrementa significativamente el tiempo de procesamiento (predeterminado: `false`)

### Configuraciones de ejemplo

Los siguientes ejemplos consideran un sistema con 48 núcleos de CPU. Ajusta `numWorkers` y `numThreads` según el número de CPUs de tu sistema y las características de tu carga de trabajo.

> **Carga de trabajo balanceada**
>
> **Caso de uso**: Carga de trabajo constante con volumen moderado de archivos y tamaños promedio
>
> **Qué hace esto**: Punto medio entre alto rendimiento y procesamiento pesado. Proporciona 2 workers para archivos pequeños y 2 para archivos grandes con 9 hilos cada uno, balanceando concurrencia y poder de procesamiento.
>
> ```yaml theme={null}
> external:
>   docling:
>     # Rendimiento
>     numWorkers: 4   # 2 para archivos pequeños, 2 para archivos grandes
>     numThreads: 36  # 9 hilos por worker, dejando 12 núcleos libres
>
>     # Configuración adicional
>     tableMode: "accurate"
>     doCellMatching: true
>     forceFullPageOCR: false
> ```

> **Muchos documentos pequeños (Alto rendimiento)**
>
> **Caso de uso**: Procesamiento de grandes volúmenes de documentos de menos de 100 páginas y menores a 1MB
>
> **Qué hace esto**: Maximiza el procesamiento concurrente de archivos con 8 workers para archivos pequeños y 8 para archivos grandes. Reduce hilos por worker para incrementar el paralelismo. Usa extracción rápida de tablas para optimizar velocidad sobre precisión.
>
> ```yaml theme={null}
> external:
>   docling:
>     # Rendimiento
>     numWorkers: 16  # 8 para archivos pequeños, 8 para archivos grandes
>     numThreads: 32  # 2 hilos por worker, dejando 16 núcleos libres
>
>     # Configuración adicional
>     tableMode: "fast"        # Priorizar velocidad
>     doCellMatching: false    # Deshabilitar para procesamiento más rápido
>     forceFullPageOCR: false
> ```

> **Documentos pesados (Archivos complejos o grandes)**
>
> **Caso de uso**: Procesamiento de documentos menos numerosos pero más grandes o complejos con tablas detalladas
>
> **Qué hace esto**: Asigna más poder computacional por documento con 8 hilos por worker. Usa solo 2 workers para archivos pequeños y 2 para archivos grandes para enfocar recursos en el procesamiento exhaustivo de contenido complejo.
>
> ```yaml theme={null}
> external:
>   docling:
>     # Rendimiento
>     numWorkers: 4   # 2 para archivos pequeños, 2 para archivos grandes
>     numThreads: 32  # 8 hilos por worker, dejando 16 núcleos libres
>
>     # Configuración adicional
>     tableMode: "accurate"
>     doCellMatching: true
>     forceFullPageOCR: false
> ```

> **Documentos escaneados (Intensivo en OCR)**
>
> **Caso de uso**: Procesamiento principalmente de documentos escaneados o imágenes que requieren extracción OCR completa
>
> **Qué hace esto**: Reduce el número de workers para asignar más hilos por worker para procesamiento OCR intensivo. Habilita OCR de página completa para extraer texto de imágenes escaneadas. Usa menos workers (2 para pequeños, 2 para grandes) con 10 hilos cada uno para maximizar el poder de procesamiento por documento.
>
> ```yaml theme={null}
> external:
>   docling:
>     # Rendimiento
>     numWorkers: 4   # 2 para archivos pequeños, 2 para archivos grandes
>     numThreads: 40  # 10 hilos por worker, dejando 8 núcleos libres
>
>     # Configuración adicional
>     tableMode: "accurate"
>     doCellMatching: true
>     forceFullPageOCR: true  # Requerido para documentos escaneados
> ```


# Omnisearch
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/search

Configura los idiomas y la longitud de consulta de Omnisearch.

Omnisearch combina búsqueda por palabras clave y búsqueda semántica en proyectos, chats, artefactos y contenido de artefactos.

## Configuración

```yaml theme={null}
languages:
  keywordSearch: ["en", "es", "de"]

omnisearch:
  maxQueryCharacters: 80
```

| Clave | Valor predeterminado | Valores | Descripción |
| - | - | - | - |
| `languages.keywordSearch` | `["en"]` | Lista de códigos de idioma compatibles | Selecciona los diccionarios de búsqueda de texto de PostgreSQL usados para indexar y ordenar las coincidencias por palabras clave. |
| `omnisearch.maxQueryCharacters` | `80` | Entero mayor o igual que `3` | Establece la longitud máxima admitida para una consulta después de eliminar los espacios iniciales y finales. |

Después de cambiar la configuración, ejecuta `sudo zylon-cli sync`.

## Cómo funciona la configuración de idiomas

`languages.keywordSearch` solo afecta a la búsqueda por palabras clave. Para cada idioma configurado, Zylon crea y consulta un índice de texto completo de PostgreSQL específico del idioma. Configura todos los idiomas usados en tus proyectos, chats y documentos para que la lematización y el ranking por palabras clave utilicen los diccionarios adecuados.

La búsqueda semántica en el contenido de artefactos sigue una ruta distinta: envía la consulta a PrivateGPT y usa el modelo de embeddings habilitado. Por tanto, la cobertura semántica de idiomas depende de ese modelo de embeddings, no de `languages.keywordSearch` ni del modelo de chat multimodal.

Para la recuperación semántica multilingüe, habilita la capacidad multilingüe en el preset de IA seleccionado:

```yaml theme={null}
ai:
  preset: "baseline-48g,capabilities.multilingual"
```

Esta capacidad selecciona el modelo de embeddings `multilingual-e5-large`. Consulta [capacidades de los presets de IA](/es/v1.58/operator-manual/ai-presets/configuration).

> [!WARNING]
>
> No dejes `languages.keywordSearch` vacío. Omnisearch rechaza las solicitudes cuando no hay ningún idioma de búsqueda por palabras clave configurado. Los códigos de idioma no compatibles también provocan un error.

### Idiomas compatibles con la búsqueda por palabras clave

| Idioma | Código | Idioma | Código |
| - | - | - | - |
| Árabe | `ar` | Armenio | `hy` |
| Vasco | `eu` | Catalán | `ca` |
| Danés | `da` | Neerlandés | `nl` |
| Inglés | `en` | Finlandés | `fi` |
| Francés | `fr` | Alemán | `de` |
| Griego | `el` | Hindi | `hi` |
| Húngaro | `hu` | Indonesio | `id` |
| Irlandés | `ga` | Italiano | `it` |
| Lituano | `lt` | Nepalí | `ne` |
| Noruego | `no` | Portugués | `pt` |
| Rumano | `ro` | Ruso | `ru` |
| Serbio | `sr` | Español | `es` |
| Sueco | `sv` | Tamil | `ta` |
| Turco | `tr` | Yidis | `yi` |

Los códigos de idioma no distinguen mayúsculas de minúsculas. Las entradas duplicadas se eliminan.

## Comportamiento de la longitud de consulta

Las consultas deben contener al menos tres caracteres. `omnisearch.maxQueryCharacters` cambia el límite superior aplicado por el backend, la API de Workspace y el campo de búsqueda de Workspace.

> [!NOTE]
>
> Mantén el valor predeterminado de `80` salvo que los usuarios necesiten consultas más largas. El mismo límite configurado se aplica a las solicitudes de API y al campo de búsqueda de Workspace.


# Whitelabel
Source: https://docs.zylon.ai/es/v1.58/operator-manual/configuration/whitelabel



### Whitelabel del Agente de Zylon

Zylon tiene soporte de whitelabel, por lo que ahora puedes personalizar el nombre del asistente de IA para que coincida con la marca de tu empresa.

Por defecto, el nombre del asistente está establecido como **Zylon**. Para cambiarlo, simplemente actualiza el campo `assistantName` en tu archivo de configuración con tu nombre preferido.

**Pautas de Nomenclatura**

* Mantén el nombre de tu agente bajo 20 caracteres.
* Evita usar mayúsculas y minúsculas mixtas (ej., "MyAIAssistant").
* No incluyas símbolos inusuales, caracteres especiales o puntuación excesiva (por ejemplo, "\$uper\_Bot!").

```
assistantName: "Daisy"
```

![Screenshot 2025-09-05 at 11.05.15.png](https://mintcdn.com/zylon/zp_I0jENZpWrf1N8/images/Screenshot2025-09-05at11.05.15.png?fit=max\&auto=format\&n=zp_I0jENZpWrf1N8\&q=85\&s=53fe0557d2d8d1cfc46ef475955654f0)


# Instalación Full-Airgap
Source: https://docs.zylon.ai/es/v1.58/operator-manual/installation/airgap

Instala Zylon en entornos completamente offline

La instalación airgap permite el despliegue de Zylon en entornos con acceso cero a internet. Este proceso requiere **dos máquinas Linux separadas**: una con conectividad a internet para descargar bundles, y una máquina offline para ejecutar Zylon.

**Lista de Prerrequisitos**:

* [ ] Máquina Linux limpia (Ubuntu 22/24) que cumpla con los [requisitos de hardware](/es/v1.58/operator-manual/installation/hardware-requirements)
* [ ] Acceso root y SSH a la máquina
* [ ] Un nombre de dominio para Zylon (por ejemplo, zylon.company.com)
* [ ] Capacidad para reiniciar la máquina cuando sea necesario
* [ ] La máquina tiene `curl` instalado

- [ ] Máquina online con acceso a internet para descargar bundles de instalación
- [ ] Método para transferir archivos (70-100 GB) a la máquina objetivo aislada (unidad USB, red interna, etc.)
- [ ] La máquina objetivo NO tiene conexión a internet
- [ ] Certificado SSL válido para tu dominio
- [ ] Almacenamiento suficiente en la máquina online y medio de transferencia para bundles grandes

***

## Acceso de Red Requerido

En tu máquina online, asegura acceso de firewall a estos dominios:

**Servicios Esenciales (Obligatorios):**

* `get.zylon.ai` - Instalación de CLI
* `zylon-cli.s3.us-east-1.amazonaws.com` - Binarios de CLI y dependencias
* `zylon-artifacts.s3.us-east-1.amazonaws.com` - Archivos de instalación y actualizaciones de Zylon

> [!WARNING]
>
> Estos dominios deben ser accesibles desde la máquina en línea para descargar bundles y actualizaciones de Zylon.
> Si no hay acceso directo a internet, puede configurar un servidor proxy.
>
> > **Configuración de Ajustes de Proxy**
> >
> > Configure las siguientes variables de entorno antes de ejecutar cualquier comando de Zylon CLI:
> >
> > ```bash theme={null}
> > export HTTP_PROXY="http://proxy.company.com:8080"
> > export HTTPS_PROXY="http://proxy.company.com:8080"
> > ```
> >
> > **Uso de Certificados Autofirmados**
> >
> > Si su proxy usa un certificado autofirmado, también debe configurar el certificado CA:
> >
> > ```bash theme={null}
> > export SSL_CERT_FILE="/path/to/your/ca-cert.pem"
> > export REQUESTS_CA_BUNDLE="/path/to/your/ca-cert.pem"
> > ```
> >
> > **Verificar Configuración de Proxy**
> >
> > Pruebe la conectividad a través del proxy antes de continuar:
> >
> > ```bash theme={null}
> > # Probar conectividad HTTP
> > curl -v -x $HTTP_PROXY http://get.zylon.ai
> >
> > # Probar conectividad HTTPS (si usa certificado autofirmado)
> > curl -v -x $HTTPS_PROXY --cacert $SSL_CERT_FILE https://get.zylon.ai
> > ```
> >
> > **Ejecutar Comandos con sudo**
> >
> > ⚠️ **Importante:** El comando `sudo` no preserva las variables de entorno por defecto. Debe usar la bandera `-E` para pasar la configuración del proxy a comandos que requieren privilegios elevados:
> >
> > ```bash theme={null}
> > sudo -E zylon-cli download <version> --airgap
> > ```

***

## Instalando Zylon

**1. Máquina Online**

Descarga bundles de Zylon y modelos de IA con acceso a internet

**2. Transferir**

Mueve archivos bundle a la máquina offline vía método de transferencia seguro

**3. Máquina Offline**

Importa e instala Zylon sin ninguna conectividad a internet

***

### Parte A: Configuración de Máquina Online

**1. Instalar CLI**

*Tiempo estimado: 2 min*

> [!WARNING]
>
> Antes de comenzar la instalación, valida que tu máquina puede alcanzar `get.zylon.ai`:
>
> ```bash theme={null}
> curl -sLv get.zylon.ai -m 3 | exit 1
> ```
>
> Si la conexión está dando errores, trabaja con tu equipo de red para resolverlos. Una vez que la conectividad esté verificada, puedes proceder.

La CLI de Zylon acelerará el tiempo necesario para tener todo listo, se encargará de instalar controladores, actualizar Zylon y configurar el sistema.
Para instalarla, conéctate por SSH a la máquina donde quieres instalar Zylon y ejecuta:

```bash theme={null}
# ssh <user>@<host-ip>
sudo curl -sL get.zylon.ai | sh
```

Verifica la instalación:

```bash theme={null}
sudo zylon-cli version
```

> [!NOTE]
>
> Se requiere acceso root para las operaciones de la CLI, ya que gestiona dependencias y configuraciones a nivel de sistema.

**2. Configurar Zylon**

*Tiempo estimado: 10min*

Zylon se configura mediante un archivo YAML ubicado en `/etc/zylon/zylon-conf.yaml`.

**Generar Configuración Inicial**

Usa la CLI para generar un archivo de configuración inicial:

```bash theme={null}
sudo zylon-cli config init
```

Esto abre un prompt interactivo que te guía a través de las opciones de configuración.

> [!NOTE]
>
> Si por alguna razón te quedas atascado durante el prompt interactivo, puedes omitirlo añadiendo la bandera `-y` para auto-generar una configuración por defecto:
>
> ```bash theme={null}
> sudo zylon-cli config init -y
> ```
>
> Después necesitarás editar manualmente `/etc/zylon/zylon-conf.yaml` para establecer tu configuración deseada basándote en la sección de [configuración manual](#configuraci%C3%B3n-manual).

**Configuración Automática**

Si ejecutaste `sudo zylon-cli config init`, toda la configuración está establecida.
Revisa `/etc/zylon/zylon-conf.yaml` para confirmar la configuración. Puedes obtener más información sobre qué configuraciones son requeridas en la sección [Configuración Manual](#configuraci%C3%B3n-manual).

> [!NOTE]
>
> Si necesitas volver a ejecutar el asistente de configuración, ejecuta:
>
> ```bash theme={null}
> sudo zylon-cli config init
> ```

**Configuración Manual**

Edita `/etc/zylon/zylon-conf.yaml` para ajustar la configuración según sea necesario.

**Define tu distribución del sistema operativo**

Establece `node.distro` para que coincida con tu versión de Ubuntu:

```yaml theme={null}
node:
  distro: "ubuntu22"  # para Ubuntu 22.04
  # distro: "ubuntu24"  # para Ubuntu 24.04
```

**Define tu arquitectura de CPU**

Establece `node.arch` para que coincida con tu hardware:

```yaml theme={null}
node:
  arch: "amd64"  # para procesadores Intel/AMD
```

**Establece tus controladores de hardware (si aplica)**

Establece `node.drivers` a `generic` (esta es la única opción soportada):

```yaml theme={null}
node:
  drivers: "generic"
```

**Configura el tipo de clúster**

Establece `cluster.type` a `k0s` (esta es la única opción soportada para instalaciones de instancia única):

```yaml theme={null}
cluster:
  type: "k0s"
```

**Selecciona tu canal de lanzamiento**

Establece `channel` a `stable` (recomendado para producción y uso normal) o `unstable` (disponible bajo solicitud para pruebas):

```yaml theme={null}
channel: "stable"
```

**Añade tu información de licencia**

Establece `license.email` a la dirección de correo electrónico asignada a tu licencia (proporcionada durante el registro).

Establece `license.id` al ID de licencia compartido contigo por el equipo de Zylon por correo electrónico:

```yaml theme={null}
license:
  email: "champion@company.com"
  id: "2oq..."
```

**Elige tu preset de IA**

Establece `ai.preset` basándote en tu memoria GPU disponible. Consulta [Presets de IA](/es/v1.58/operator-manual/ai-presets/getting-started) para más detalles.

```yaml theme={null}
ai:
  preset: "baseline-48g"
```

**Establece tu identificador de empresa**

Establece `global.companyIdentifier` a cualquier identificador para el seguimiento anónimo de métricas (por ejemplo, `acme-corp`). Si tienes múltiples instalaciones, usa identificadores diferentes (por ejemplo, `company` y `company-test`):

```yaml theme={null}
global:
  companyIdentifier: "tu-empresa"
```

**Desactiva telemetría e informes de errores**

Para desactivar la telemetría y los informes de errores, añade la siguiente sección:

```yaml theme={null}
observability:
    crashReporting: false
    usageMetrics: false
```

**Configura el ingress de red**

Establece `ingress.host` al dominio que has preparado para Zylon. Debe ser un nombre de dominio completamente cualificado (FQDN) que apunte a la dirección IP de tu servidor.

Ejemplos:

* `zylon.company.com`
* `ai.acme-corp.com`
* `zylon-prod.yourcompany.io`

```yaml theme={null}
ingress:
  host: "zylon.tu-empresa.com"
  enabled: true
  tlsEnabled: true
```

**Configura la generación de certificado SSL**

Si tu servidor es accesible desde internet, Let's Encrypt generará y renovará automáticamente los certificados SSL. Mantén el `certManagerAnnotations` por defecto:

```yaml theme={null}
ingress:
  certManagerAnnotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

Si estás en una red privada o necesitas usar un certificado personalizado, consulta [Desactivar Let's Encrypt](#disable-lets-encrypt) a continuación.

**Desactivar Let's Encrypt**

Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas de la sección `ingress`:

```yaml theme={null}
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

**Ajustes Airgap**

Asegúrate de que estos ajustes estén incluidos para indicar instalación y operación airgap:

```yaml theme={null}
airgap:
  offlineInstall: true
  offlineOperation: true
```

**Licencia Local**

Dado que la máquina offline no puede alcanzar `api.replicated.com`, necesitas una licencia local. Contacta con el soporte de Zylon para obtenerla, luego añade:

```yaml theme={null}
license:
  email: "champion@company.com"
  id: "2xo..."
  type: "Zylon"
  data: |-
    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

> [!WARNING]
>
> Reemplaza el campo `data` con los datos reales de licencia proporcionados por el equipo de Zylon. Por favor, ten cuidado con el formato y la indentación.
> Solo copia el token que comienza con `eyJ...` y termina con `...`.

**Ver Configuración Actual**

```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```

Puedes editar el archivo de configuración directamente usando tu editor de texto preferido (por ejemplo, `nano`, `vim`):

```bash theme={null}
# Elige uno de los siguientes comandos:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml
```

Para información detallada sobre todas las opciones de configuración disponibles, consulta la [Guía de Configuración](/es/v1.58/operator-manual/configuration/overview).

**3. Descargar Modelos de IA**

*Tiempo estimado: 10min a 1h, dependiendo de la velocidad de red y modelos.*

**Antes de descargar Zylon**, debes descargar los modelos de IA en la máquina online. Los modelos están determinados por tu configuración de preset de IA.

Verifica los modelos disponibles y compara con tu preset de IA:

```bash theme={null}
sudo zylon-cli models list
```

Más detalles de preset en la [documentación de Presets de IA](/es/v1.58/operator-manual/ai-presets/presets).

Descarga los modelos basados en tu configuración:

```bash theme={null}
sudo zylon-cli models download --no-install
```

Esto descargará los modelos de IA que has especificado en el Wizard.

Si por alguna razón necesitas descargar modelos específicos, puedes hacerlo con:

```bash theme={null}
sudo zylon-cli models list
sudo zylon-cli models download --no-install model-a model-b model-c
```

Por ejemplo, para el preset `baseline-96g`:

```bash theme={null}
sudo zylon-cli models download --no-install nvidia/Qwen3.8-27B-NVFP4 mixedbread-ai/mxbai-embed-large-v1
```

**4. Exportar Modelos de IA**

*Tiempo estimado: 5 a 30 min, dependiendo del tamaño de los modelos.*

Después de descargar los modelos, expórtalos para transferirlos a la máquina offline:

```bash theme={null}
sudo zylon-cli models export
```

Esto crea un archivo `zylon-models-<timestamp>.tar` en tu directorio actual conteniendo todos los modelos de IA seleccionados.

> [!NOTE]
>
> El archivo de exportación de modelos puede ser de 10-100 GB dependiendo de qué modelos hayas descargado.

**5. Descargar Bundle de Zylon**

*Tiempo estimado: 15min a 2h, dependiendo de la velocidad de red.*

Descarga la versión específica de Zylon que quieres instalar:

```bash theme={null}
sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli download <version> --airgap
```

Reemplaza `<version>` con tu versión objetivo (por ejemplo, `1.50.0`).

> [!NOTE]
>
> Nota que **no usamos** la bandera `--models` aquí ya que los modelos fueron manejados en los pasos anteriores.

**6. Exportar Bundle**

*Tiempo estimado: 15 a 60 min, dependiendo de la versión.*

Exporta la versión descargada en un bundle airgap:

```bash theme={null}
sudo zylon-cli export <version>
```

Esto crea `zylon-<version>-<os>-<arch>.tar` en tu directorio actual. Adicionalmente, generará
los comandos para ejecutar en la máquina offline para la instalación para importar e instalar Zylon. Almacena estos comandos de forma segura.

> [!NOTE]
>
> La exportación puede tomar tiempo significativo. El archivo tar resultante puede ser de 60-80GB.

**7. Preparar Transferencia Inicial (Solo Primera Instalación)**

> [!WARNING]
>
> **¡Solo primera instalación!** Después de la configuración inicial, la CLI se auto-actualiza desde bundles airgap.

Crea un bundle con herramientas CLI y configuración:

```bash theme={null}
sudo tar -czf zylon-initial.tar.gz \
  /usr/local/bin/zylon-cli \
  /usr/local/bin/zylon-forge-cli \
  /etc/zylon/zylon-conf.yaml
```

**8. Preparar Certificados (Opcional)**

*Tiempo estimado: 5 min*

Si tu instancia de Zylon está en una red privada o VPN, necesitas proporcionar manualmente certificados SSL.
Prepáralos para transferencia:

Reúne tus archivos de certificado SSL:

* `crt.pem` (Certificado + Intermedio)
* `key.pem` (Clave Privada)

Crea un tarball para transferencia:

```bash theme={null}
sudo tar -czf zylon-ssl-certs.tar.gz crt.pem key.pem
```

**9. Transferir Archivos**

Transfiere archivos a la máquina offline usando tu método preferido (SCP, USB, unidad externa):

**Primera instalación:**

* `zylon-<version>-<os>-<arch>.tar` (bundle principal)
* `zylon-models-<timestamp>.tar` (exportación de modelos de IA)
* `zylon-initial.tar.gz` (CLI y config)
* `zylon-ssl-certs.tar.gz` (certificados SSL, si aplica)

**Actualizaciones subsecuentes:**

* `zylon-<version>-<os>-<arch>.tar` (bundle principal)
* `zylon-models-<timestamp>.tar` (exportación de modelos de IA, si se agregan nuevos modelos)

**Ejemplo SCP**

```bash theme={null}
scp zylon-<version>-<os>-<arch>.tar user@offline-machine:/tmp/
scp zylon-models-*.tar user@offline-machine:/tmp/
scp zylon-initial.tar.gz user@offline-machine:/tmp/
scp zylon-ssl-certs.tar.gz user@offline-machine:/tmp/
```

***

### Parte B: Instalación de Máquina Offline

**1. Instalar CLI (Solo Primera Vez)**

*Tiempo estimado: 2 min*

> [!WARNING]
>
> **Omite si estás actualizando una instalación existente.** Esto es solo para instalaciones por primera vez.

Extrae herramientas CLI y configuración:

```bash theme={null}
cd /tmp
sudo tar -xzf zylon-initial.tar.gz -C /
sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli
```

Verifica la instalación:

```bash theme={null}
sudo zylon-cli version
cat /etc/zylon/zylon-conf.yaml
```

> [!NOTE]
>
> Las actualizaciones futuras actualizan automáticamente la CLI desde bundles airgap—no se necesita transferencia manual.

**2. Verificar requisitos mínimos de Zylon**

Asegúrate de que tu máquina cumple con los [requisitos de hardware](/es/v1.58/operator-manual/installation/hardware-requirements) para Zylon.

Para validar automáticamente si tu instalación cumple con los requisitos mínimos, ejecuta:

```bash theme={null}
sudo zylon-cli preflight --fresh-system -v
```

Resuelve cualquier problema reportado antes de proceder con la instalación. No podrás continuar hasta que todas las comprobaciones previas pasen.

**3. Importar Modelos de IA**

*Tiempo estimado: 5 a 30 min, dependiendo del tamaño de los modelos.*

**Antes de importar Zylon**, importa los modelos de IA que fueron exportados en la máquina online:

```bash theme={null}
cd /tmp
sudo zylon-cli models import zylon-models-<timestamp>.tar
sudo zylon-cli models download --offline
```

`models import` registra los artefactos del modelo localmente y `models download --offline` los instala en el runtime offline.

Verifica que los modelos fueron instalados exitosamente:

```bash theme={null}
sudo zylon-cli models list --installed
```

**4. Importar Bundle Airgap**

*Tiempo estimado: 10 a 60 min, dependiendo del tamaño del bundle y rendimiento del sistema.*

Importa el bundle de Zylon:

```bash theme={null}
cd /tmp
sudo zylon-cli import zylon-<version>-<os>-<arch>.tar
```

Este proceso:

* Extrae todas las imágenes de contenedores
* Instala dependencias offline
* Prepara el sistema para la instalación

> [!WARNING]
>
> La importación puede tomar 30+ minutos dependiendo del tamaño del bundle y rendimiento del sistema. No interrumpas.

Verifica que la importación se completó exitosamente comprobando las versiones instaladas:

```bash theme={null}
sudo zylon-cli list-versions --offline
```

**5. Instalar Zylon**

*Tiempo estimado: 15min a 1hora, dependiendo del rendimiento del sistema.*

Instala Zylon usando el bundle importado:

```bash theme={null}
sudo zylon-cli install <version> --airgap
```

> [!NOTE]
>
> Los modelos de IA ya fueron importados en un paso anterior, por lo que no se necesita la bandera `--models` aquí.

**6. Crear Organización**

*Tiempo estimado: 5 min*

Después de que Zylon esté instalado y en funcionamiento, crea tu organización y cuenta de administrador root.

**Prepara la Información**

Necesitarás:

* **Nombre de organización**: El nombre de tu empresa o equipo (se puede cambiar más tarde)
* **Regex de correo electrónico**: Patrón para permitir automáticamente que los usuarios se unan
  * Para correos `name@company.com`, usa: `.*@company\.com`
  * Para SSO (Microsoft Entra, Google), puedes usar: `.*`

**Ejecuta el Comando Seed**

```bash theme={null}
sudo zylon-cli seed \
  --org-name "Mi Organización" \
  --email-regex ".*@tuempresa\.com"
```

El comando esperará si Zylon no está completamente listo.

> [!CAUTION]
>
> **Ejecutar el comando seed BORRARÁ TODOS LOS DATOS.** Solo ejecútalo una vez durante la configuración inicial de Zylon.

**Credenciales de Inicio de Sesión**

Después de hacer el seed, obtén la contraseña de un solo uso para la cuenta de administrador:

```bash theme={null}
sudo zylon-cli admin-password
```

Luego inicia sesión con:

```
Usuario: admin@zylon.ai
Contraseña: [la contraseña de un solo uso impresa arriba]
```

El correo electrónico del administrador root siempre es `admin@zylon.ai` y no se puede cambiar.

> [!NOTE]
>
> Después del primer inicio de sesión, puedes crear administradores adicionales y configurar la autenticación SSO.

**7. Configurar Certificados SSL (Si aplica)**

*Tiempo estimado: 10 min*

Si preparaste certificados SSL en la máquina online, extráelos ahora:

```bash theme={null}
cd /tmp
sudo tar -xzf zylon-ssl-certs.tar.gz -C /tmp/
ls /tmp/crt.pem /tmp/key.pem
```

Si ves ambos archivos, procede a instalarlos como sigue:

**Eliminar Generación Automática de Certificado**

Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas:

```yaml theme={null}
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

**Prepara los Archivos de Certificado**

Kubernetes requiere que el certificado se divida en dos archivos:

* `tls.crt` - El archivo de certificado
* `tls.key` - El archivo de clave privada

**Convertir desde PFX (si aplica):**

Si tienes un archivo `.pfx`, conviértelo:

```bash theme={null}
openssl pkcs12 -in <tu-certificado.pfx> -clcerts -nokeys -out tls.crt
openssl pkcs12 -in <tu-certificado.pfx> -nocerts -out tls.key
```

**Importar Certificado en Kubernetes**

```bash theme={null}
# Elimina cualquier certificado existente
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon

# Importa tu certificado
sudo k0s kubectl create secret tls zylon-tls \
  --key tls.key \
  --cert tls.crt \
  -n zylon

# Verifica la creación
sudo k0s kubectl describe secret zylon-tls -n zylon
```

**Aplicar Cambios**

Recarga la configuración de Zylon:

```bash theme={null}
sudo zylon-cli sync
```

**Verificar**

Accede a tu instancia de Zylon en `https://zylon.tu-empresa.com` y confirma:

* La conexión usa HTTPS
* El navegador muestra un certificado válido
* No aparecen advertencias de certificado

> [!TIP]
>
> La renovación del certificado debe hacerse manualmente repitiendo este proceso con archivos de certificado actualizados.

***

## Actualizando Zylon

Las actualizaciones en entornos airgap siguen un flujo de trabajo similar de dos máquinas. El proceso es más rápido que la instalación inicial ya que solo estás transfiriendo cambios, no toda la plataforma.

> [!NOTE]
>
> **Tiempo Estimado**: 45-60 minutos total (15-20 min máquina online, 25-40 min máquina offline)

**1. En Máquina Online: Descargar Nuevos Modelos (Si Se Necesitan)**

*Tiempo estimado: 10 a 60 min (solo si se agregan nuevos modelos)*

**Omite este paso si no estás agregando nuevos modelos de IA.**

Si estás cambiando presets de IA, actualizando requisitos de GPU, o necesitas modelos adicionales:

Primero, verifica tus modelos actuales y disponibles:

```bash theme={null}
sudo zylon-cli models list
```

Descarga los nuevos modelos:

```bash theme={null}
sudo zylon-cli models download --no-install new-model-a new-model-b
```

> [!NOTE]
>
> Compara los modelos disponibles con los requisitos de tu preset de IA para determinar si se necesitan modelos adicionales. Consulta la [documentación de Presets de IA](/es/v1.58/operator-manual/ai-presets/presets).

**2. En Máquina Online: Exportar Nuevos Modelos (Si Aplica)**

*Tiempo estimado: 5 a 30 min (solo si se descargaron nuevos modelos)*

**Omite este paso si no agregaste nuevos modelos de IA.**

Exporta los modelos recién descargados:

```bash theme={null}
sudo zylon-cli models export
```

Esto crea un archivo `zylon-models-<timestamp>.tar` conteniendo todos los modelos descargados actualmente.

**3. En Máquina Online: Descargar Actualización**

*Tiempo estimado: 10 a 60 min*

Descarga el bundle de la nueva versión de Zylon:

```bash theme={null}
sudo zylon-cli download <new-version> --airgap
```

> [!NOTE]
>
> Nota que **ya no usamos** la bandera `--models` durante la descarga, ya que los modelos se manejan por separado.

**4. En Máquina Online: Crear Bundle de Actualización**

*Tiempo estimado: 10 a 60 min*

Exporta un bundle de actualización incremental:

```bash theme={null}
sudo zylon-cli export <new-version> --from <current-version>
```

La bandera `--from` crea un bundle diferencial que contiene solo cambios entre versiones, reduciendo significativamente el tamaño del bundle y tiempo de transferencia.

> [!NOTE]
>
> Los bundles diferenciales típicamente son 5-20 GB vs. 60-80 GB para bundles completos.

**5. Transferir Bundle a Máquina Offline**

Transfiere el/los archivo(s) bundle usando tu método seguro:

**Si actualizaste modelos:**

```bash theme={null}
scp zylon-<new-version>-to-<old-version>-<os>-<arch>.tar user@offline-machine:/tmp/
scp zylon-models-*.tar user@offline-machine:/tmp/
```

**Si no hay nuevos modelos:**

```bash theme={null}
scp zylon-<new-version>-to-<old-version>-<os>-<arch>.tar user@offline-machine:/tmp/
```

**Métodos alternativos:**

* Unidad USB
* Sistema de transferencia de archivos interno
* Compartido de red (si está disponible)

**6. En Máquina Offline: Importar Nuevos Modelos (Si Aplica)**

*Tiempo estimado: 5 a 30 min (solo si se transfirieron nuevos modelos)*

**Omite este paso si no transferiste nuevos modelos de IA.**

Importa los nuevos modelos:

```bash theme={null}
cd /tmp
sudo zylon-cli models import zylon-models-*.tar
sudo zylon-cli models download --offline
```

Verifica que los modelos fueron instalados exitosamente:

```bash theme={null}
sudo zylon-cli models list --installed
```

**7. En Máquina Offline: Importar Actualización**

Importa el bundle de actualización:

```bash theme={null}
cd /tmp
sudo zylon-cli import zylon-<new-version>-to-<old-version>-<os>-<arch>.tar
```

El proceso de importación:

* Extrae imágenes de contenedores para la nueva versión
* Actualiza dependencias del sistema
* Prepara artefactos de actualización

> [!WARNING]
>
> Esto puede tomar 10-30 minutos. No interrumpas el proceso.

Verifica que la importación se completó exitosamente comprobando las versiones instaladas:

```bash theme={null}
sudo zylon-cli list-versions --offline
```

**8. En Máquina Offline: Aplicar Actualización**

*Tiempo estimado: 15 a 60 min*

Aplica la actualización a tu instancia de Zylon en ejecución:

```bash theme={null}
sudo zylon-cli install <new-version> --airgap
```

> [!NOTE]
>
> Los nuevos modelos de IA (si los hay) ya fueron importados en un paso anterior, por lo que no se necesita la bandera `--models` aquí.

***

## Migrando a Airgap

Si tienes una instalación existente de Zylon (online o semi-airgap) y quieres migrarla a un entorno completamente airgap, sigue esta guía. Este proceso preserva tus datos, configuración y certificados SSL mientras realiza la transición a operación offline.

> [!NOTE]
>
> **La migración difiere de la instalación nueva:**
>
> * Tu configuración y datos existentes serán preservados
> * Los certificados SSL serán migrados
> * La organización y usuarios ya existen

**Prerrequisitos de Migración:**

* [ ] Instalación existente de Zylon (online o semi-airgap) con acceso
* [ ] Máquina online con acceso a internet para descargar bundles de migración
* [ ] Método para transferir archivos (70-100 GB) entre máquinas
* [ ] Máquina airgap objetivo sin conexión a internet
* [ ] Acceso root y SSH a todas las máquinas involucradas

***

### Parte A: Extraer de la Máquina Zylon Existente

**1. Extraer Configuración Actual**

*Tiempo estimado: 5 min*

Copia el archivo de configuración actual de Zylon:

```bash theme={null}
# En la máquina Zylon existente
sudo cp /etc/zylon/zylon-conf.yaml /tmp/zylon-conf-backup.yaml
```

**2. Extraer Certificados SSL**

*Tiempo estimado: 5 min*

Extrae los certificados SSL actuales de Kubernetes para evitar regeneración:

```bash theme={null}
# Extraer certificado del secreto de Kubernetes
sudo k0s kubectl get secret zylon-tls -n zylon -o jsonpath='{.data.tls\.crt}' | base64 -d > /tmp/tls.crt
sudo k0s kubectl get secret zylon-tls -n zylon -o jsonpath='{.data.tls\.key}' | base64 -d > /tmp/tls.key

# Verificar que los archivos fueron creados
ls -lh /tmp/tls.crt /tmp/tls.key
```

> [!NOTE]
>
> Si la extracción del certificado falla, significa que estás usando la generación automática de Let's Encrypt. En este caso, necesitarás proporcionar tus propios certificados o continuar usando Let's Encrypt en la máquina airgap (no recomendado para entornos airgap).

**3. Transferir Archivos a Máquina Online**

Transfiere la configuración y certificados a tu máquina online:

**Ejemplo SCP:**

```bash theme={null}
# Desde la máquina Zylon existente a la máquina online
scp /tmp/zylon-conf-backup.yaml user@online-machine:/tmp/
scp /tmp/tls.crt user@online-machine:/tmp/
scp /tmp/tls.key user@online-machine:/tmp/
```

**Métodos alternativos:**

* Unidad USB
* Transferencia de archivos interna segura
* Compartido de red

***

### Parte B: Preparar bundle en Máquina Online

**1. Instalar Zylon CLI**

*Tiempo estimado: 2 min*

La CLI de Zylon acelerará el tiempo necesario para tener todo listo, se encargará de instalar controladores, actualizar Zylon y configurar el sistema.
Para instalarla, conéctate por SSH a la máquina donde quieres instalar Zylon y ejecuta:

```bash theme={null}
# ssh <user>@<host-ip>
sudo curl -sL get.zylon.ai | sh
```

Verifica la instalación:

```bash theme={null}
sudo zylon-cli version
```

> [!NOTE]
>
> Se requiere acceso root para las operaciones de la CLI, ya que gestiona dependencias y configuraciones a nivel de sistema.

**2. Transferir Archivo de Configuración**

*Tiempo estimado: 2 min*

Coloca la configuración respaldada en la ubicación correcta:

```bash theme={null}
sudo mkdir -p /etc/zylon
sudo cp /tmp/zylon-conf-backup.yaml /etc/zylon/zylon-conf.yaml
```

**3. Reconfigurar para Airgap**

*Tiempo estimado: 10 min*

Ejecuta el asistente de configuración para actualizar los ajustes para despliegue airgap:

```bash theme={null}
sudo zylon-cli config init
```

El asistente te guiará a través de la actualización de los siguientes ajustes:

**Cambios Potencialmente Requeridos:**

1. **Tipo de Instalación**: Cambia desde tu tipo actual (online/semi-airgap) a **Airgap**

2. **Certificados SSL**: El asistente solicitará certificados en formato de texto:

* Pega el contenido de `/tmp/tls.crt` cuando se solicite el certificado
* Pega el contenido de `/tmp/tls.key` cuando se solicite la clave privada

> **Cómo ver el Contenido del Certificado:**
>
> ```bash theme={null}
> # Mostrar certificado (copia esta salida)
> cat /tmp/tls.crt
>
> # Mostrar clave privada (copia esta salida)
> cat /tmp/tls.key
> ```

> [!WARNING]
>
> Al pegar certificados en el asistente:
>
> * Incluye el contenido completo incluyendo los encabezados `-----BEGIN CERTIFICATE-----` y `-----END CERTIFICATE-----`
> * Mantén los saltos de línea y formato adecuados
> * No agregues espacios o caracteres extra

3. **Información de Licencia** (si cambias de canal):

   * Email de Licencia: Proporcionado por el equipo de Zylon
   * ID de Licencia: Proporcionado por el equipo de Zylon
   * Datos de Licencia: Token de licencia completo proporcionado por el equipo de Zylon

   > [!WARNING]
   >
   > Asegúrate de que los datos de licencia se copien exactamente como se proporcionan, preservando el formato y los saltos de línea.

4. **Canal** (si aplica):
   * Cambia de `stable` a `X` (o según las instrucciones de Zylon)

5. **Revisar Todos los Otros Ajustes**: El asistente mostrará los valores actuales—confirma o actualiza según sea necesario

**Verificar Configuración Actualizada:**

```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```

Confirma que todo esté configurado correctamente para operación AirGap.

**4. Descargar Bundle de Migración**

*Tiempo estimado: 15 min a 1 hora*

Descarga el bundle de versión de Zylon (sin modelos de IA, ya que ya existen):

```bash theme={null}
sudo zylon-cli list-versions
# Elige tu versión objetivo
sudo zylon-cli download <version> --airgap
```

> [!NOTE]
>
> **No** estamos incluyendo la bandera `--models` porque:
>
> * Los modelos de IA existentes de tu instalación actual serán preservados
> * Si necesitas agregar nuevos modelos, inclúyelos con `--models=model-a,model-b`. Más información en la guía de instalación nueva arriba.

**5. Exportar Bundle de Migración**

*Tiempo estimado: 15 a 60 min*

Exporta el bundle de migración:

```bash theme={null}
sudo zylon-cli export <version>
```

Esto crea `zylon-<version>-<os>-<arch>.tar` en tu directorio actual.

**6. Preparar Paquete de Migración**

*Tiempo estimado: 5 min*

Crea un paquete de migración completo con herramientas CLI y configuración:

```bash theme={null}
sudo tar -czf zylon-migration.tar.gz \
  /usr/local/bin/zylon-cli \
  /usr/local/bin/zylon-forge-cli \
  /etc/zylon/zylon-conf.yaml
```

**7. Transferir Archivos a Máquina Airgap**

Transfiere el paquete de migración a tu máquina airgap:

**Archivos a transferir:**

* `zylon-<version>-<os>-<arch>.tar` (bundle principal)
* `zylon-migration.tar.gz` (CLI y configuración actualizada)

**Ejemplo SCP:**

```bash theme={null}
scp zylon-<version>-<os>-<arch>.tar user@airgap-machine:/tmp/
scp zylon-migration.tar.gz user@airgap-machine:/tmp/
```

***

### Parte C: Migrar a Airgap en Máquina Offline

**1. Extraer Paquete de Migración**

*Tiempo estimado: 2 min*

Extrae las herramientas CLI y configuración:

```bash theme={null}
cd /tmp
sudo tar -xzf zylon-migration.tar.gz -C /
sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli
```

Verificar extracción:

```bash theme={null}
sudo zylon-cli version
cat /etc/zylon/zylon-conf.yaml
```

Debería mostrar:

```yaml theme={null}
airgap:
  offlineInstall: true
  offlineOperation: true
```

**2. Verificar Requisitos del Sistema**

Asegúrate de que la máquina airgap cumple con todos los requisitos:

```bash theme={null}
sudo zylon-cli preflight -v
```

Resuelve cualquier problema antes de proceder.

**3. Importar Bundle de Migración**

*Tiempo estimado: 10 a 60 min*

Importa el bundle de Zylon:

```bash theme={null}
cd /tmp
sudo zylon-cli import zylon-<version>-<os>-<arch>.tar
```

Este proceso:

* Extrae todas las imágenes de contenedores
* Instala dependencias offline
* Prepara el sistema para la instalación

> [!WARNING]
>
> La importación puede tomar 30+ minutos. No interrumpas el proceso.

Verificar finalización de importación:

```bash theme={null}
sudo zylon-cli list-versions --offline
```

**4. Instalar Zylon en Modo Airgap**

*Tiempo estimado: 15 min a 1 hora*

Instala Zylon usando el bundle importado:

```bash theme={null}
sudo zylon-cli install <version> --airgap
```

***

## Próximos Pasos

Después de completar la instalación, considera los siguientes próximos pasos para optimizar tu despliegue de Zylon:

* [Configurar Presets de IA](/es/v1.58/operator-manual/ai-presets) para optimizar según tu hardware
* [Configurar Copias de Seguridad](/es/v1.58/operator-manual/operations/backup) para protección de datos
* [Revisar Manual de Usuario](/es/v1.58/user-manual/quick-start-guide) para comenzar


# Instalar Zylon (Legacy)
Source: https://docs.zylon.ai/es/v1.58/operator-manual/installation/legacy

Una guía para instalar Zylon en una sola instancia

> [!WARNING]
>
> Esta guía solo se aplica a Zylon 1.53.0 o anterior. Para versiones más recientes, el proceso de instalación es diferente y debes referirte a la [guía de instalación principal](/es/v1.58/operator-manual/installation/overview).

## Prerrequisitos

Para una navegación sin problemas, asegúrate de pasar esta lista de verificación antes de comenzar la instalación:

* La máquina objetivo está limpia de cualquier otro software que pueda interferir con ella. Eso significa sin docker, sin kubernetes, servidores http, sin controladores Nvidia, etc.
* Tienes acceso root y SSH a la máquina
* La máquina tiene una conexión a Internet estable y fuerte
* Puedes reiniciar la máquina si es necesario
* Tu firewall no está bloqueando conexiones a ningún sitio web.
  * En caso de que ejecutes en un entorno restringido, consulta las [instrucciones semi-airgap](/es/v1.58/operator-manual/installation/semi-airgap).
* La máquina tiene `curl` instalado
* Tienes un dominio para Zylon listo (ej: zylon.your-company.com)
  * Si tu instancia no está abierta a internet, tienes un certificado SSL válido para ese dominio, será necesario como el último paso de la instalación.

Una vez que hayas cumplido los requisitos de hardware y tengas un dominio listo, ¡es hora de instalar Zylon!

Para configuraciones de instancia única, Zylon se instala usando su CLI `zylon-cli` en la máquina donde quieres ejecutarlo. Para iniciar el proceso de instalación, asegúrate de que:

* En el momento de la instalación, la máquina tiene conexión a internet (Después de que Zylon haya sido instalado, la conexión a internet no es un requisito)
* Tienes acceso ssh a la máquina
* Las reglas del firewall no bloquearán la CLI para descargar imágenes de contenedor de Zylon o la generación de certificados

## Paso 1: Instalar la CLI de Zylon

*Tiempo estimado: 2 min*

La CLI acelerará el tiempo que lleva tener todo listo, se encargará de instalar controladores, actualizar Zylon y generar la configuración de plantilla para ti.

Para instalarla, haz SSH en la máquina donde quieres instalar Zylon y ejecuta

```bash theme={null}
# ssh user@zylon.company.com
sudo curl -sL get.zylon.ai | sh
```

Se requiere acceso root en múltiples pasos de la instalación, si deseas inspeccionar el script simplemente ejecuta

```yaml theme={null}
curl -sL get.zylon.ai
```

¡Ejecuta `sudo zylon-cli help` para obtener una lista de todos los comandos!

## Paso 2: Generar un archivo de configuración para tu instalación de Zylon

*Tiempo estimado: 10min*

Zylon se configura con un archivo YAML ubicado en `/etc/zylon/zylon-conf.yaml`.

Puedes usar la CLI de Zylon para generar una plantilla de configuración:

```bash theme={null}
sudo zylon-cli config
```

Esto genera una plantilla que debes completar con tus valores específicos y guardar en `/etc/zylon/zylon-conf.yaml`.

Ten en cuenta que necesitarás acceso root para editar este archivo.

Un archivo de configuración básico se verá así:

```yaml theme={null}
# Configuración de máquina, esta es la única opción soportada
node:
  distro: "ubuntu22" # o ubuntu24
  arch: "x86_64" 
  drivers: "generic" 

# Tipo de clúster, esta es la única
# opción soportada para instalaciones de instancia única
cluster:
  type: "k0s"

# canal inestable también disponible bajo solicitud
channel: "stable"

license:
  email: "champion@company.com" # El correo asignado a la licencia
  id: "2oq..." # Un id de licencia que un empleado de Zylon compartió contigo por correo

# Configuración de IA, información detallada a continuación.
ai:
  preset: "baseline-96g"

# Usaremos esto para identificar tu empresa en nuestras métricas anónimas
# Puedes establecer cualquier identificador, si tienes múltiples instalaciones
# haz el identificador diferente, por ejemplo, company, y company-test
global:
  companyIdentifier: "your-company"

# Habilitar métricas anónimas y reportes de fallos
observability:
  crashReporting: true
  usageMetrics: true

# Tu configuración de red
ingress:
  host: "zylon.your-company.com" # El dominio que has preparado para Zylon
  enabled: true
  tlsEnabled: true
  certManagerAnnotations:
    # Si planeas abrir la máquina a internet, el certificado SSL
    # se generará automáticamente usando letsencrypt
    # De lo contrario, consulta la documentación SSL para importar un certificado personalizado
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

### Parámetros de Configuración

Completa cada parámetro requerido usando los valores que coincidan con tu entorno:

| Parámetro | Establecer a... | Opciones |
| - | - | - |
| `node.distro` | Tu versión de SO | `ubuntu22`, `ubuntu24` |
| `node.arch` | Tu arquitectura de CPU | `x86_64`, `arm64` |
| `node.drivers` | Tu tipo de hardware | `generic` |
| `cluster.type` | `k0s` | Solo `k0s` soportado |
| `channel` | `stable` | `stable` (recomendado), `unstable` |
| `license.email` | Tu correo registrado | Proporcionado durante el registro |
| `license.id` | Tu clave de licencia | Recibido del equipo de Zylon por correo |
| `ai.preset` | Tu capacidad de hardware | [Ver Presets de IA →](/es/v1.58/operator-manual/ai-presets/presets) |
| `global.companyIdentifier` | Nombre de tu empresa | ej., `acme-corp` |
| `ingress.host` | Tu dominio | ej., `zylon.company.com` |
| `ingress.enabled` | `true` | Debe ser `true` |

> [!TIP]
>
> Para la configuración detallada de la instancia de Zylon, consulta la página de [Configuración](/es/v1.58/operator-manual/configuration/overview).

## Paso 3: Preparar la máquina

*Tiempo estimado: 5min a 45min, dependiendo de la velocidad de red.*

Para instalar Zylon, la máquina necesita estar lista para hacerlo, y durante este paso, se instalarán los controladores, un clúster de kubernetes embebido y otras dependencias se configurarán.

Este proceso tomará entre 5 y 15 minutos, es normal ver que la salida se congela mientras algunos instaladores se ejecutan, simplemente espera hasta que termine.

En condiciones de red lentas, este proceso puede tomar hasta 1 hora.

```bash theme={null}
sudo zylon-cli setup
```

Esto es lo que se instalará:

* Algunos paquetes comunes como gcc y git
* Una distribución de kubernetes embebida, [k0s](https://k0sproject.io/)
* [Controladores Nvidia y CUDA ](https://developer.nvidia.com/cuda-downloads)
* [Nvidia Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html)
* Algunas utilidades de herramientas para gestionar el clúster de kubernetes (kubectl, helm, helmfile...)

Generalmente, solo necesitas ejecutar el setup una vez. Ejecutarlo múltiples veces no tiene efecto a menos que una actualización del equipo de Zylon agregue una nueva dependencia.

> [!TIP]
>
> Es muy recomendable reiniciar la máquina después de que este paso se complete para asegurar que los controladores de GPU se carguen correctamente.

> [!CAUTION]
>
> **¡Las actualizaciones del kernel (como las actualizaciones desatendidas de Ubuntu) romperán los controladores Nvidia en cada cambio!.**
>
> Para probar si los controladores están funcionando, usa la utilidad `nvidia-smi`, mostrará el estado de tu(s) GPU(s) o fallará si los controladores no están funcionando:
>
> Una actualización implícita del kernel también puede ocurrir después de un reinicio de la máquina cuando se ejecuta en proveedores de nube como AWS o Azure.
>
> Consulta la siguiente página para solución de problemas: [Solución de Problemas de Controladores Nvidia](/es/v1.58/operator-manual/troubleshooting/nvidia-drivers)

## Paso 4: Instalar Zylon

*Tiempo estimado: 15min a 1hora, dependiendo de la velocidad de red.*

Este paso (instalar / actualizar) hará que Zylon esté disponible en tu máquina asumiendo que el archivo de configuración en `/etc/zylon/zylon-conf.yaml` es correcto.

```bash theme={null}
sudo zylon-cli update
```

Para actualizar Zylon a una versión más nueva, simplemente ejecuta este comando nuevamente. Puedes hacerlo tan frecuentemente como necesites.

Si modificas tu archivo de configuración de Zylon también necesitarás ejecutar el comando de actualización nuevamente.

> [!NOTE]
>
> La instalación inicial de Zylon tomará alrededor de 15 minutos para completarse después de que el comando de actualización en sí se complete.

Esto es lo que está sucediendo en segundo plano:

* Las imágenes de Zylon se están descargando
* Los modelos de IA se están descargando
* La configuración de GPU se está aplicando, se están ejecutando varias validaciones para asegurar la compatibilidad
* El certificado SSL se está generando

Puedes ver el proceso ejecutándose. Cuando todos los pods estén en estado 1/1 listo, puedes proceder.

```bash theme={null}
watch sudo k0s kubectl get pods -n zylon
# También puedes ver el proceso de validación de GPU nvidia, más propenso a fallos
watch sudo k0s kubectl get pods -n nvidia
```

> [!NOTE]
>
> Si algún servicio se queda atascado en un ContainerCrashLoopBackOff por más de una hora, contáctanos, la instalación ha fallado.

## Paso 5: Preparar tu organización

Para comenzar a usar Zylon necesitarás crear tu organización en él, así como agregar un administrador raíz que servirá como tu punto de entrada para otras tareas de gestión.

Necesitarás:

* Un nombre para tu organización (puede cambiarse más tarde)
* Una expresión regular de correo electrónico para permitir que los usuarios se unan automáticamente. Si tu correo electrónico de trabajo habitual es [`name@company.com`](mailto:name@company.com), tu expresión regular de correo electrónico debe ser `.*@company\.com`. Si tu control de acceso se realiza con SSO (como Microsoft Entra, o Google), puedes usar `.*` como tu expresión regular.

```bash theme={null}
sudo zylon-cli seed --org-name "Mi Org" --email-regex ".*@yourcompany\.com"

# En el momento de seed, si Zylon no está listo,
# este comando esperará hasta que se complete.
```

> [!CAUTION]
>
> **Ejecutar el comando seed BORRARÁ TODOS LOS DATOS. Solo haz esto una vez durante el ciclo de vida de Zylon**

Después de hacer el seed, obtén la contraseña de un solo uso para la cuenta de administrador:

```bash theme={null}
sudo zylon-cli admin-password
```

Las credenciales para iniciar sesión en Zylon serán:

```bash theme={null}
user: admin@zylon.ai
password: la_contraseña_de_un_solo_uso_impresa_arriba
```

El correo electrónico del administrador raíz está fijo y siempre será `admin@zylon.ai`. Necesitarás usar estas credenciales para iniciar sesión por primera vez en el espacio de trabajo.

## Paso 6 (opcional): Instalar certificados SSL manualmente

*Tiempo estimado: 10 minutos*

Si optaste por usar certificados Let's Encrypt puedes omitir esta sección.

En caso de que tu instalación de Zylon esté detrás de una VPN / nube privada y no sea accesible a través de internet, necesitarás configurar SSL tú mismo. Para hacer eso, debes cargar tus propios certificados SSL y hacerlos disponibles al servidor donde está instalado Zylon.

### Archivo de configuración

Primero, **ELIMINA** las siguientes líneas del archivo de configuración `/etc/zylon/zylon-conf.yaml`

```yaml theme={null}
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

Como estamos usando Kubernetes, necesitamos tener la clave privada (`*.key`) y el archivo de certificado en dos archivos (`*.crt`) para almacenarlos como un secreto.

### Para archivo .pfx (ignora si no aplica)

En caso de que tengas un archivo `.pfx` puedes obtener los archivos deseados con los siguientes comandos:

```bash theme={null}
openssl pkcs12 -in <your-certificate.pfx> -clcerts -nokeys -out tls.crt
openssl pkcs12 -in <your-certificate.pfx> -nocerts -out tls.key
```

### Crear un secreto en el clúster de kubernetes

Limpia los certificados anteriores (si los hay) e importa el nuevo. Zylon buscará tu certificado en el clúster con el nombre `zylon-tls`. Ten en cuenta que kubernetes requiere el certificado dividido en dos archivos, el `.crt` con el certificado mismo y `.key` con la clave privada.

```bash theme={null}

# Importar o actualizar los certificados
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon
sudo k0s kubectl create secret tls zylon-tls --key tls.key --cert tls.crt -n zylon

# Verificar si está correctamente creado
sudo k0s kubectl describe secret zylon-tls -n zylon
```

Para recargar los cambios realizados en el archivo de configuración, recarga la configuración.

```bash theme={null}
sudo zylon-cli update
```

Finalmente, ve a tu instancia de Zylon y confirma que la conexión está usando HTTPS.


# Instalación Online
Source: https://docs.zylon.ai/es/v1.58/operator-manual/installation/online

Instala Zylon con acceso completo a internet

Esta guía cubre la instalación estándar de Zylon para entornos con acceso completo a internet. El sistema descargará automáticamente todas las dependencias requeridas, imágenes de contenedores y modelos de IA.

**Lista de Prerrequisitos**:

* [ ] Máquina Linux limpia (Ubuntu 22/24) que cumpla con los [requisitos de hardware](/es/v1.58/operator-manual/installation/hardware-requirements)
* [ ] Acceso root y SSH a la máquina
* [ ] Un nombre de dominio para Zylon (por ejemplo, zylon.company.com)
* [ ] Capacidad para reiniciar la máquina cuando sea necesario
* [ ] La máquina tiene `curl` instalado

- [ ] Acceso completo y sin restricciones a internet en la máquina objetivo
- [ ] El firewall permite conexiones salientes a registros de Docker y repositorios de paquetes
- [ ] Ya sea:
  * [ ] Puertos 80 y 443 abiertos para la generación automática de certificados SSL de Let's Encrypt, O
  * [ ] Certificado SSL válido listo para configuración manual

***

## Instalando Zylon

**1. Instalar Zylon CLI**

*Tiempo estimado: 2 min*

La CLI de Zylon acelerará el tiempo necesario para tener todo listo, se encargará de instalar controladores, actualizar Zylon y configurar el sistema.
Para instalarla, conéctate por SSH a la máquina donde quieres instalar Zylon y ejecuta:

```bash theme={null}
# ssh <user>@<host-ip>
sudo curl -sL get.zylon.ai | sh
```

Verifica la instalación:

```bash theme={null}
sudo zylon-cli version
```

> [!NOTE]
>
> Se requiere acceso root para las operaciones de la CLI, ya que gestiona dependencias y configuraciones a nivel de sistema.

**2. Verificar requisitos mínimos de Zylon**

Asegúrate de que tu máquina cumple con los [requisitos de hardware](/es/v1.58/operator-manual/installation/hardware-requirements) para Zylon.

Para validar automáticamente si tu instalación cumple con los requisitos mínimos, ejecuta:

```bash theme={null}
sudo zylon-cli preflight --network --fresh-system -v
```

Resuelve cualquier problema reportado antes de proceder con la instalación. No podrás continuar hasta que todas las comprobaciones previas pasen.

> [!NOTE]
>
> ¿Tienes problemas con la conectividad de red? Considera cambiar a una [Instalación Semi-Airgap](/es/v1.58/operator-manual/installation/semi-airgap) o [Instalación Airgap](/es/v1.58/operator-manual/installation/airgap).

> [!NOTE]
>
> Zylon requiere que todas las comprobaciones pasen antes de proporcionar soporte de instalación.

**3. Configurar Zylon**

*Tiempo estimado: 10min*

Zylon se configura mediante un archivo YAML ubicado en `/etc/zylon/zylon-conf.yaml`.

**Generar Configuración Inicial**

Usa la CLI para generar un archivo de configuración inicial:

```bash theme={null}
sudo zylon-cli config init
```

Esto abre un prompt interactivo que te guía a través de las opciones de configuración.

> [!NOTE]
>
> Si por alguna razón te quedas atascado durante el prompt interactivo, puedes omitirlo añadiendo la bandera `-y` para auto-generar una configuración por defecto:
>
> ```bash theme={null}
> sudo zylon-cli config init -y
> ```
>
> Después necesitarás editar manualmente `/etc/zylon/zylon-conf.yaml` para establecer tu configuración deseada basándote en la sección de [configuración manual](#configuraci%C3%B3n-manual).

**Configuración Automática**

Si ejecutaste `sudo zylon-cli config init`, toda la configuración está establecida.
Revisa `/etc/zylon/zylon-conf.yaml` para confirmar la configuración. Puedes obtener más información sobre qué configuraciones son requeridas en la sección [Configuración Manual](#configuraci%C3%B3n-manual).

> [!NOTE]
>
> Si necesitas volver a ejecutar el asistente de configuración, ejecuta:
>
> ```bash theme={null}
> sudo zylon-cli config init
> ```

Puedes

**Configuración Manual**

Edita `/etc/zylon/zylon-conf.yaml` para ajustar la configuración según sea necesario.

**Define tu distribución del sistema operativo**

Establece `node.distro` para que coincida con tu versión de Ubuntu:

```yaml theme={null}
node:
  distro: "ubuntu22"  # para Ubuntu 22.04
  # distro: "ubuntu24"  # para Ubuntu 24.04
```

**Define tu arquitectura de CPU**

Establece `node.arch` para que coincida con tu hardware:

```yaml theme={null}
node:
  arch: "amd64"  # para procesadores Intel/AMD
```

**Establece tus controladores de hardware (si aplica)**

Establece `node.drivers` a `generic` (esta es la única opción soportada):

```yaml theme={null}
node:
  drivers: "generic"
```

**Configura el tipo de clúster**

Establece `cluster.type` a `k0s` (esta es la única opción soportada para instalaciones de instancia única):

```yaml theme={null}
cluster:
  type: "k0s"
```

**Selecciona tu canal de lanzamiento**

Establece `channel` a `stable` (recomendado para producción y uso normal) o `unstable` (disponible bajo solicitud para pruebas):

```yaml theme={null}
channel: "stable"
```

**Añade tu información de licencia**

Establece `license.email` a la dirección de correo electrónico asignada a tu licencia (proporcionada durante el registro).

Establece `license.id` al ID de licencia compartido contigo por el equipo de Zylon por correo electrónico:

```yaml theme={null}
license:
  email: "champion@company.com"
  id: "2oq..."
```

**Elige tu preset de IA**

Establece `ai.preset` basándote en tu memoria GPU disponible. Consulta [Presets de IA](/es/v1.58/operator-manual/ai-presets/getting-started) para más detalles.

```yaml theme={null}
ai:
  preset: "baseline-48g"
```

**Establece tu identificador de empresa**

Establece `global.companyIdentifier` a cualquier identificador para el seguimiento anónimo de métricas (por ejemplo, `acme-corp`). Si tienes múltiples instalaciones, usa identificadores diferentes (por ejemplo, `company` y `company-test`):

```yaml theme={null}
global:
  companyIdentifier: "tu-empresa"
```

**Desactiva telemetría e informes de errores**

Para desactivar la telemetría y los informes de errores, añade la siguiente sección:

```yaml theme={null}
observability:
    crashReporting: false
    usageMetrics: false
```

**Configura el ingress de red**

Establece `ingress.host` al dominio que has preparado para Zylon. Debe ser un nombre de dominio completamente cualificado (FQDN) que apunte a la dirección IP de tu servidor.

Ejemplos:

* `zylon.company.com`
* `ai.acme-corp.com`
* `zylon-prod.yourcompany.io`

```yaml theme={null}
ingress:
  host: "zylon.tu-empresa.com"
  enabled: true
  tlsEnabled: true
```

**Configura la generación de certificado SSL**

Si tu servidor es accesible desde internet, Let's Encrypt generará y renovará automáticamente los certificados SSL. Mantén el `certManagerAnnotations` por defecto:

```yaml theme={null}
ingress:
  certManagerAnnotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

Si estás en una red privada o necesitas usar un certificado personalizado, consulta [Desactivar Let's Encrypt](#disable-lets-encrypt) a continuación.

**Desactivar Let's Encrypt**

Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas de la sección `ingress`:

```yaml theme={null}
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

**Ver Configuración Actual**

```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```

Puedes editar el archivo de configuración directamente usando tu editor de texto preferido (por ejemplo, `nano`, `vim`):

```bash theme={null}
# Elige uno de los siguientes comandos:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml
```

Para información detallada sobre todas las opciones de configuración disponibles, consulta la [Guía de Configuración](/es/v1.58/operator-manual/configuration/overview).

**4. Descargar Modelos de IA**

*Tiempo estimado: 10min a 1h, dependiendo de la velocidad de red y modelos.*

**Antes de instalar Zylon**, debes descargar los modelos de IA. Los modelos están determinados por tu configuración de preset de IA.

Verifica los modelos disponibles y compara con tu preset de IA:

```bash theme={null}
sudo zylon-cli models list
```

Más detalles de preset en la [documentación de Presets de IA](/es/v1.58/operator-manual/ai-presets/presets).

Descarga los modelos basados en tu configuración:

```bash theme={null}
sudo zylon-cli models download
```

Esto descargará e instalará los modelos de IA que has especificado en el Wizard.

Si por alguna razón necesitas descargar modelos específicos, puedes hacerlo con:

```bash theme={null}
sudo zylon-cli models list
sudo zylon-cli models download model-a model-b model-c
```

Por ejemplo, para el preset `baseline-96g`:

```bash theme={null}
sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4 mixedbread-ai/mxbai-embed-large-v1
```

**5. Instalar Zylon**

*Tiempo estimado: 15min a 1hora, dependiendo del rendimiento del sistema y velocidad de red.*

Ejecuta el comando de instalación con tu versión deseada:

```bash theme={null}
sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli install <version>
```

Reemplaza `<version>` con tu versión objetivo (por ejemplo, `1.50.0`).

**Qué se Instala**

El proceso de instalación maneja:

* Dependencias del sistema (gcc, git, etc.)
* Distribución de Kubernetes ([k0s](https://k0sproject.io/))
* Controladores NVIDIA y CUDA (si aplica)
* Runtime de contenedores y herramientas (kubectl, helm)
* Imágenes de contenedores de Zylon
* Generación de certificados SSL (si usas Let's Encrypt)

> [!NOTE]
>
> Nota que los modelos de IA **no** están incluidos en este paso—fueron instalados en el paso anterior.

**Monitorear la instalación**

Supervisa el progreso de la instalación:

```bash theme={null}
# Ver pods de Zylon
watch sudo k0s kubectl get pods -n zylon

# Ver validación de GPU (si aplica)
watch sudo k0s kubectl get pods -n nvidia
```

Espera hasta que todos los pods muestren estado listo `1/1`.

> [!TIP]
>
> **Reinicia después de la instalación** para asegurarte de que los drivers de GPU se carguen correctamente.

> [!CAUTION]
>
> **Las actualizaciones del kernel pueden romper los drivers de NVIDIA!**
>
> Verifica los drivers con: `nvidia-smi`
>
> Solución de problemas: [Guía de Drivers de NVIDIA](/es/v1.58/operator-manual/troubleshooting/nvidia-drivers)

> [!WARNING]
>
> Si los servicios permanecen en `ContainerCrashLoopBackOff` durante más de 1 hora, contacta con soporte y comparte los logs.

**6. Crear Organización**

*Tiempo estimado: 5 min*

Después de que Zylon esté instalado y en funcionamiento, crea tu organización y cuenta de administrador root.

**Prepara la Información**

Necesitarás:

* **Nombre de organización**: El nombre de tu empresa o equipo (se puede cambiar más tarde)
* **Regex de correo electrónico**: Patrón para permitir automáticamente que los usuarios se unan
  * Para correos `name@company.com`, usa: `.*@company\.com`
  * Para SSO (Microsoft Entra, Google), puedes usar: `.*`

**Ejecuta el Comando Seed**

```bash theme={null}
sudo zylon-cli seed \
  --org-name "Mi Organización" \
  --email-regex ".*@tuempresa\.com"
```

El comando esperará si Zylon no está completamente listo.

> [!CAUTION]
>
> **Ejecutar el comando seed BORRARÁ TODOS LOS DATOS.** Solo ejecútalo una vez durante la configuración inicial de Zylon.

**Credenciales de Inicio de Sesión**

Después de hacer el seed, obtén la contraseña de un solo uso para la cuenta de administrador:

```bash theme={null}
sudo zylon-cli admin-password
```

Luego inicia sesión con:

```
Usuario: admin@zylon.ai
Contraseña: [la contraseña de un solo uso impresa arriba]
```

El correo electrónico del administrador root siempre es `admin@zylon.ai` y no se puede cambiar.

> [!NOTE]
>
> Después del primer inicio de sesión, puedes crear administradores adicionales y configurar la autenticación SSO.

**7. Configurar SSL (Opcional)**

*Tiempo estimado: 10 min*

> [!NOTE]
>
> **Omite este paso** si usas certificados automáticos de Let's Encrypt (por defecto para instancias públicas).

Para despliegues en VPN o nube privada, necesitas instalar manualmente certificados SSL.

**Eliminar Generación Automática de Certificado**

Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas:

```yaml theme={null}
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

**Prepara los Archivos de Certificado**

Kubernetes requiere que el certificado se divida en dos archivos:

* `tls.crt` - El archivo de certificado
* `tls.key` - El archivo de clave privada

**Convertir desde PFX (si aplica):**

Si tienes un archivo `.pfx`, conviértelo:

```bash theme={null}
openssl pkcs12 -in <tu-certificado.pfx> -clcerts -nokeys -out tls.crt
openssl pkcs12 -in <tu-certificado.pfx> -nocerts -out tls.key
```

**Importar Certificado en Kubernetes**

```bash theme={null}
# Elimina cualquier certificado existente
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon

# Importa tu certificado
sudo k0s kubectl create secret tls zylon-tls \
  --key tls.key \
  --cert tls.crt \
  -n zylon

# Verifica la creación
sudo k0s kubectl describe secret zylon-tls -n zylon
```

**Aplicar Cambios**

Recarga la configuración de Zylon:

```bash theme={null}
sudo zylon-cli sync
```

**Verificar**

Accede a tu instancia de Zylon en `https://zylon.tu-empresa.com` y confirma:

* La conexión usa HTTPS
* El navegador muestra un certificado válido
* No aparecen advertencias de certificado

> [!TIP]
>
> La renovación del certificado debe hacerse manualmente repitiendo este proceso con archivos de certificado actualizados.

***

## Actualizando Zylon

Las actualizaciones siguen el mismo proceso que la instalación:

```bash theme={null}
sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli install <new-version>
```

Alternativamente, puedes actualizar directamente a la última versión usando el comando de actualización:

```bash theme={null}
sudo zylon-cli upgrade
```

***

## Migrando a Online

Si tienes una instalación existente de Zylon (semi-airgap o airgap) y quieres migrarla a un entorno completamente online, sigue esta guía. Este proceso preserva tus datos y configuración, mientras realiza la transición a operación online.

> [!NOTE]
>
> **La migración difiere de la instalación nueva:**
>
> * Tu configuración y datos existentes serán preservados
> * La organización y usuarios ya existen

Para migrar una instalación existente de Zylon (Semi-Airgap, o Airgap) a una instalación Online, sigue estos pasos:

1. **Asegurar conectividad**: Verifica que la máquina objetivo tenga acceso completo a internet.
2. **Actualizar configuración**: Ejecuta `sudo zylon-cli config init` para actualizar la configuración para operación online.
3. **Refrescar configuración**: Ejecuta `sudo zylon-cli sync` para aplicar los nuevos ajustes de configuración.
4. **Verificar operación**: Confirma que todos los servicios funcionan correctamente con acceso a internet.

***

## Próximos Pasos

Después de completar la instalación, considera los siguientes próximos pasos para optimizar tu despliegue de Zylon:

* [Configurar Presets de IA](/es/v1.58/operator-manual/ai-presets) para optimizar según tu hardware
* [Configurar Copias de Seguridad](/es/v1.58/operator-manual/operations/backup) para protección de datos
* [Revisar Manual de Usuario](/es/v1.58/user-manual/quick-start-guide) para comenzar


# Instalación Semi-Airgap
Source: https://docs.zylon.ai/es/v1.58/operator-manual/installation/semi-airgap

Instala Zylon en entornos con acceso restringido a internet

Esta guía cubre la instalación de Zylon para entornos con acceso limitado a internet debido a restricciones de firewall o requisitos de proxy. El sistema requiere conectividad a internet única vez durante la instalación y actualizaciones.

**Lista de Prerrequisitos**:

* [ ] Máquina Linux limpia (Ubuntu 22/24) que cumpla con los [requisitos de hardware](/es/v1.58/operator-manual/installation/hardware-requirements)
* [ ] Acceso root y SSH a la máquina
* [ ] Un nombre de dominio para Zylon (por ejemplo, zylon.company.com)
* [ ] Capacidad para reiniciar la máquina cuando sea necesario
* [ ] La máquina tiene `curl` instalado

- [ ] Servidor proxy configurado con credenciales (si es requerido)
- [ ] El equipo de red ha añadido a lista blanca los dominios y puertos requeridos (ver [Acceso de Red Requerido](/es/v1.58/operator-manual/installation/semi-airgap#acceso-de-red-requerido))
- [ ] Las reglas del firewall permiten conexiones a través del proxy
- [ ] Certificado SSL válido para tu dominio (Let's Encrypt típicamente no funcionará en redes restringidas)

***

## Acceso de Red Requerido

Tu firewall debe permitir acceso a estos dominios:

**Servicios Esenciales (Obligatorios):**

* `get.zylon.ai` - Instalación de CLI
* `zylon-cli.s3.us-east-1.amazonaws.com` - Binarios de CLI y dependencias
* `zylon-artifacts.s3.us-east-1.amazonaws.com` - Archivos de instalación y actualizaciones de Zylon

**Registros de Contenedores Públicos:**

* `quay.io` - Imágenes de contenedores de terceros
* `ghcr.io` - Registro de contenedores de GitHub
* `docker.io` - Imágenes de Docker Hub
* `registry.k8s.io` - Imágenes de Kubernetes
* `reg.kyverno.io` - Motor de políticas Kyverno
* `nvcr.io` - Registro de Contenedores NVIDIA

> [!NOTE]
>
> Dado que Zylon requiere imágenes de código abierto públicas, se requiere acceso de red a los registros originales durante la instalación y actualizaciones.
> Si tus políticas de seguridad restringen el acceso a registros de contenedores públicos, considera cambiar a una instalación airgap usando la [Guía de Instalación Airgap de Zylon](/es/v1.58/operator-manual/installation/airgap).

**Modelos de IA y Dependencias (Solo aplicable si necesitas modelos de IA personalizados):**

* `huggingface.co` - Repositorio de modelos de IA
* `xet.huggingface.co` - Protocolo XET de Hugging Face

**Validación de Licencia (Solo aplicable si se usa licencia Replicated):**

* `replicated.app` - Plataforma de distribución de Zylon
* `api.replicated.com` - Validación de licencia
* `proxy.replicated.com` - Imágenes de contenedores de Zylon

***

## Instalando Zylon

**1. Instalar Zylon CLI**

*Tiempo estimado: 2 min*

> [!WARNING]
>
> Antes de comenzar la instalación, valida que tu máquina puede alcanzar `get.zylon.ai`:
>
> ```bash theme={null}
> curl -sLv get.zylon.ai -m 3 | exit 1
> ```
>
> Si la conexión está dando errores, trabaja con tu equipo de red para resolverlos. Una vez que la conectividad esté verificada, puedes proceder.

La CLI de Zylon acelerará el tiempo necesario para tener todo listo, se encargará de instalar controladores, actualizar Zylon y configurar el sistema.
Para instalarla, conéctate por SSH a la máquina donde quieres instalar Zylon y ejecuta:

```bash theme={null}
# ssh <user>@<host-ip>
sudo curl -sL get.zylon.ai | sh
```

Verifica la instalación:

```bash theme={null}
sudo zylon-cli version
```

> [!NOTE]
>
> Se requiere acceso root para las operaciones de la CLI, ya que gestiona dependencias y configuraciones a nivel de sistema.

**2. Verificar requisitos mínimos de Zylon**

Asegúrate de que tu máquina cumple con los [requisitos de hardware](/es/v1.58/operator-manual/installation/hardware-requirements) para Zylon.

Para validar automáticamente si tu instalación cumple con los requisitos mínimos, ejecuta:

```bash theme={null}
sudo zylon-cli preflight --network --fresh-system -v
```

Resuelve cualquier problema reportado antes de proceder con la instalación. No podrás continuar hasta que todas las comprobaciones previas pasen.

> [!NOTE]
>
> ¿Tienes problemas con la conectividad de red? Considera cambiar a una [Instalación Airgap](/es/v1.58/operator-manual/installation/airgap).

> [!NOTE]
>
> Zylon requiere que todas las comprobaciones pasen antes de proporcionar soporte de instalación.

**3. Configurar Zylon**

*Tiempo estimado: 10min*

Zylon se configura mediante un archivo YAML ubicado en `/etc/zylon/zylon-conf.yaml`.

**Generar Configuración Inicial**

Usa la CLI para generar un archivo de configuración inicial:

```bash theme={null}
sudo zylon-cli config init
```

Esto abre un prompt interactivo que te guía a través de las opciones de configuración.

> [!NOTE]
>
> Si por alguna razón te quedas atascado durante el prompt interactivo, puedes omitirlo añadiendo la bandera `-y` para auto-generar una configuración por defecto:
>
> ```bash theme={null}
> sudo zylon-cli config init -y
> ```
>
> Después necesitarás editar manualmente `/etc/zylon/zylon-conf.yaml` para establecer tu configuración deseada basándote en la sección de [configuración manual](#configuraci%C3%B3n-manual).

**Configuración Automática**

Si ejecutaste `sudo zylon-cli config init`, toda la configuración está establecida.
Revisa `/etc/zylon/zylon-conf.yaml` para confirmar la configuración. Puedes obtener más información sobre qué configuraciones son requeridas en la sección [Configuración Manual](#configuraci%C3%B3n-manual).

> [!NOTE]
>
> Si necesitas volver a ejecutar el asistente de configuración, ejecuta:
>
> ```bash theme={null}
> sudo zylon-cli config init
> ```

Puedes

**Configuración Manual**

Edita `/etc/zylon/zylon-conf.yaml` para ajustar la configuración según sea necesario.

**Define tu distribución del sistema operativo**

Establece `node.distro` para que coincida con tu versión de Ubuntu:

```yaml theme={null}
node:
  distro: "ubuntu22"  # para Ubuntu 22.04
  # distro: "ubuntu24"  # para Ubuntu 24.04
```

**Define tu arquitectura de CPU**

Establece `node.arch` para que coincida con tu hardware:

```yaml theme={null}
node:
  arch: "amd64"  # para procesadores Intel/AMD
```

**Establece tus controladores de hardware (si aplica)**

Establece `node.drivers` a `generic` (esta es la única opción soportada):

```yaml theme={null}
node:
  drivers: "generic"
```

**Configura el tipo de clúster**

Establece `cluster.type` a `k0s` (esta es la única opción soportada para instalaciones de instancia única):

```yaml theme={null}
cluster:
  type: "k0s"
```

**Selecciona tu canal de lanzamiento**

Establece `channel` a `stable` (recomendado para producción y uso normal) o `unstable` (disponible bajo solicitud para pruebas):

```yaml theme={null}
channel: "stable"
```

**Añade tu información de licencia**

Establece `license.email` a la dirección de correo electrónico asignada a tu licencia (proporcionada durante el registro).

Establece `license.id` al ID de licencia compartido contigo por el equipo de Zylon por correo electrónico:

```yaml theme={null}
license:
  email: "champion@company.com"
  id: "2oq..."
```

**Elige tu preset de IA**

Establece `ai.preset` basándote en tu memoria GPU disponible. Consulta [Presets de IA](/es/v1.58/operator-manual/ai-presets/getting-started) para más detalles.

```yaml theme={null}
ai:
  preset: "baseline-48g"
```

**Establece tu identificador de empresa**

Establece `global.companyIdentifier` a cualquier identificador para el seguimiento anónimo de métricas (por ejemplo, `acme-corp`). Si tienes múltiples instalaciones, usa identificadores diferentes (por ejemplo, `company` y `company-test`):

```yaml theme={null}
global:
  companyIdentifier: "tu-empresa"
```

**Desactiva telemetría e informes de errores**

Para desactivar la telemetría y los informes de errores, añade la siguiente sección:

```yaml theme={null}
observability:
    crashReporting: false
    usageMetrics: false
```

**Configura el ingress de red**

Establece `ingress.host` al dominio que has preparado para Zylon. Debe ser un nombre de dominio completamente cualificado (FQDN) que apunte a la dirección IP de tu servidor.

Ejemplos:

* `zylon.company.com`
* `ai.acme-corp.com`
* `zylon-prod.yourcompany.io`

```yaml theme={null}
ingress:
  host: "zylon.tu-empresa.com"
  enabled: true
  tlsEnabled: true
```

**Configura la generación de certificado SSL**

Si tu servidor es accesible desde internet, Let's Encrypt generará y renovará automáticamente los certificados SSL. Mantén el `certManagerAnnotations` por defecto:

```yaml theme={null}
ingress:
  certManagerAnnotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

Si estás en una red privada o necesitas usar un certificado personalizado, consulta [Desactivar Let's Encrypt](#disable-lets-encrypt) a continuación.

**Desactivar Let's Encrypt**

Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas de la sección `ingress`:

```yaml theme={null}
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

**Licencia Local (Si es Necesario)**

Si `api.replicated.com` está bloqueado durante la operación, necesitas una licencia local. Contacta con el soporte de Zylon para obtenerla, luego añade:

```yaml theme={null}
license:
  email: "champion@company.com"
  id: "2xo..."
  type: "Zylon"
  data: |-
    [eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...]
```

> [!WARNING]
>
> Reemplaza el campo `data` con los datos reales de licencia proporcionados por el equipo de Zylon. Por favor, ten cuidado con el formato y la indentación.
> Solo copia el token que comienza con `eyJ...`.

**Configuración de proxy (Si es Necesario)**

Consulta la [Guía de Configuración de Proxy](/es/v1.58/operator-manual/configuration/network/proxy) para configurar los ajustes de proxy en tu configuración.

**Ver Configuración Actual**

```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```

Puedes editar el archivo de configuración directamente usando tu editor de texto preferido (por ejemplo, `nano`, `vim`):

```bash theme={null}
# Elige uno de los siguientes comandos:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml
```

Para información detallada sobre todas las opciones de configuración disponibles, consulta la [Guía de Configuración](/es/v1.58/operator-manual/configuration/overview).

**4. Descargar Modelos de IA**

*Tiempo estimado: 10min a 1h, dependiendo de la velocidad de red y modelos.*

**Antes de instalar Zylon**, debes descargar los modelos de IA. Los modelos están determinados por tu configuración de preset de IA y se descargarán desde los dominios de Hugging Face.

Asegúrate de que tu firewall permita acceso a:

* `huggingface.co`
* `xet.huggingface.co`

Verifica los modelos disponibles y compara con tu preset de IA:

```bash theme={null}
sudo zylon-cli models list
```

Más detalles de preset en la [documentación de Presets de IA](/es/v1.58/operator-manual/ai-presets/presets).

Descarga los modelos basados en tu configuración:

```bash theme={null}
sudo zylon-cli models download
```

Esto descargará e instalará los modelos de IA que has especificado en el Wizard.

Si por alguna razón necesitas descargar modelos específicos, puedes hacerlo con:

```bash theme={null}
sudo zylon-cli models list
sudo zylon-cli models download model-a model-b model-c
```

Por ejemplo, para el preset `baseline-96g`:

```bash theme={null}
sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4 mixedbread-ai/mxbai-embed-large-v1
```

**5. Instalar Zylon**

*Tiempo estimado: 15min a 1hora, dependiendo del rendimiento del sistema y velocidad de red.*

Ejecuta la instalación con tu versión deseada:

```bash theme={null}
sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli install <version>
```

El proceso de instalación maneja:

* Dependencias del sistema (gcc, git, etc.)
* Distribución de Kubernetes ([k0s](https://k0sproject.io/))
* Controladores NVIDIA y CUDA (si aplica)
* Runtime de contenedores y herramientas (kubectl, helm)
* Imágenes de contenedores de Zylon
* Generación de certificados SSL (si usas Let's Encrypt)

> [!NOTE]
>
> Nota que los modelos de IA **no** están incluidos en este paso—fueron instalados en el paso anterior.

**Monitorear la instalación**

Supervisa el progreso de la instalación:

```bash theme={null}
# Ver pods de Zylon
watch sudo k0s kubectl get pods -n zylon

# Ver validación de GPU (si aplica)
watch sudo k0s kubectl get pods -n nvidia
```

Espera hasta que todos los pods muestren estado listo `1/1`.

> [!TIP]
>
> **Reinicia después de la instalación** para asegurarte de que los drivers de GPU se carguen correctamente.

> [!CAUTION]
>
> **Las actualizaciones del kernel pueden romper los drivers de NVIDIA!**
>
> Verifica los drivers con: `nvidia-smi`
>
> Solución de problemas: [Guía de Drivers de NVIDIA](/es/v1.58/operator-manual/troubleshooting/nvidia-drivers)

> [!WARNING]
>
> Si los servicios permanecen en `ContainerCrashLoopBackOff` durante más de 1 hora, contacta con soporte y comparte los logs.

La instalación puede tomar 15-60 minutos dependiendo de la velocidad de red y restricciones del firewall.

**6. Crear Organización**

*Tiempo estimado: 5 min*

Después de que Zylon esté instalado y en funcionamiento, crea tu organización y cuenta de administrador root.

**Prepara la Información**

Necesitarás:

* **Nombre de organización**: El nombre de tu empresa o equipo (se puede cambiar más tarde)
* **Regex de correo electrónico**: Patrón para permitir automáticamente que los usuarios se unan
  * Para correos `name@company.com`, usa: `.*@company\.com`
  * Para SSO (Microsoft Entra, Google), puedes usar: `.*`

**Ejecuta el Comando Seed**

```bash theme={null}
sudo zylon-cli seed \
  --org-name "Mi Organización" \
  --email-regex ".*@tuempresa\.com"
```

El comando esperará si Zylon no está completamente listo.

> [!CAUTION]
>
> **Ejecutar el comando seed BORRARÁ TODOS LOS DATOS.** Solo ejecútalo una vez durante la configuración inicial de Zylon.

**Credenciales de Inicio de Sesión**

Después de hacer el seed, obtén la contraseña de un solo uso para la cuenta de administrador:

```bash theme={null}
sudo zylon-cli admin-password
```

Luego inicia sesión con:

```
Usuario: admin@zylon.ai
Contraseña: [la contraseña de un solo uso impresa arriba]
```

El correo electrónico del administrador root siempre es `admin@zylon.ai` y no se puede cambiar.

> [!NOTE]
>
> Después del primer inicio de sesión, puedes crear administradores adicionales y configurar la autenticación SSO.

**7. Configurar Operación Offline**

*Tiempo estimado: 5 min*

Después de validar que Zylon está funcionando correctamente, puedes habilitar la operación offline. Esto configurará Zylon para funcionar sin acceso a internet.
Edita `/etc/zylon/zylon-conf.yaml` y añade:

```yaml theme={null}
airgap:
  offlineOperation: true
```

Y sincroniza la configuración:

```bash theme={null}
sudo zylon-cli sync
```

Esto desactivará la conectividad en IA, K8s y otros subsistemas.

**8. Configurar SSL (Opcional)**

*Tiempo estimado: 10 min*

Para despliegues en VPN o red privada, necesitas instalar manualmente certificados SSL.

**Eliminar Generación Automática de Certificado**

Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas:

```yaml theme={null}
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
```

**Prepara los Archivos de Certificado**

Kubernetes requiere que el certificado se divida en dos archivos:

* `tls.crt` - El archivo de certificado
* `tls.key` - El archivo de clave privada

**Convertir desde PFX (si aplica):**

Si tienes un archivo `.pfx`, conviértelo:

```bash theme={null}
openssl pkcs12 -in <tu-certificado.pfx> -clcerts -nokeys -out tls.crt
openssl pkcs12 -in <tu-certificado.pfx> -nocerts -out tls.key
```

**Importar Certificado en Kubernetes**

```bash theme={null}
# Elimina cualquier certificado existente
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon

# Importa tu certificado
sudo k0s kubectl create secret tls zylon-tls \
  --key tls.key \
  --cert tls.crt \
  -n zylon

# Verifica la creación
sudo k0s kubectl describe secret zylon-tls -n zylon
```

**Aplicar Cambios**

Recarga la configuración de Zylon:

```bash theme={null}
sudo zylon-cli sync
```

**Verificar**

Accede a tu instancia de Zylon en `https://zylon.tu-empresa.com` y confirma:

* La conexión usa HTTPS
* El navegador muestra un certificado válido
* No aparecen advertencias de certificado

> [!TIP]
>
> La renovación del certificado debe hacerse manualmente repitiendo este proceso con archivos de certificado actualizados.

***

## Actualizando Zylon

Para actualizar la instancia, necesitaremos eliminar temporalmente las restricciones de red en una máquina conectada para descargar paquetes de actualización. Contacta con tu equipo de seguridad de red para añadir a lista blanca los dominios requeridos durante este proceso.
Después de descargar, puedes volver a aplicar las restricciones.

Antes de actualizar, asegúrate de desactivar el modo offline editando `/etc/zylon/zylon-conf.yaml` y estableciendo:

```yaml theme={null}
airgap:
  offlineOperation: false
```

Valida si Zylon tiene conectividad nuevamente ejecutando:

```bash theme={null}
sudo zylon-cli preflight --network -v
```

Si todas las comprobaciones pasan, procede a descargar e instalar la actualización:

```bash theme={null}
sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli install <new-version>
```

Alternativamente, puedes actualizar directamente a la última versión usando el comando de actualización:

```bash theme={null}
sudo zylon-cli upgrade
```

Cuando el proceso esté completo, vuelve a habilitar el modo offline estableciendo:

```yaml theme={null}
airgap:
  offlineOperation: true
```

***

## Migrando a Semi-Airgap

Si tienes una instalación existente de Zylon (online o airgap completo) y quieres migrarla a un entorno semi airgap, sigue esta guía. Este proceso preserva tus datos y configuración, mientras realiza la transición a operación offline.

> [!NOTE]
>
> **La migración difiere de la instalación nueva:**
>
> * Tu configuración y datos existentes serán preservados
> * Los certificados SSL serán migrados
> * La organización y usuarios ya existen

Para migrar una instalación existente de Zylon (Online, o Airgap) a una instalación Semi-Airgap, sigue estos pasos:

1. **Asegurar conectividad**: Verifica que la máquina objetivo tenga conectividad con los dominios mencionados arriba.
2. **Actualizar configuración**: Ejecuta `sudo zylon-cli config init` para actualizar la configuración para operación online. Asegúrate de configurar según describe el paso [Configurar Zylon](#configure-zylon).

* Asegúrate de seleccionar Semi-Airgap cuando ejecutes el asistente de configuración.
* Si no tienes conectividad con los dominios de replicated, asegúrate de solicitar una licencia local al equipo de soporte de Zylon.

4. **Desactivar modo offline**: Edita `/etc/zylon/zylon-conf.yaml` y establece:
   ```yaml theme={null}
   airgap:
     offlineOperation: false
   ```
5. **Refrescar configuración**: Ejecuta `sudo zylon-cli sync` para aplicar los nuevos ajustes de configuración.
6. **Verificar operación**: Confirma que todos los servicios funcionan correctamente.

***

## Próximos Pasos

Después de completar la instalación, considera los siguientes próximos pasos para optimizar tu despliegue de Zylon:

* [Configurar Presets de IA](/es/v1.58/operator-manual/ai-presets) para optimizar según tu hardware
* [Configurar Copias de Seguridad](/es/v1.58/operator-manual/operations/backup) para protección de datos
* [Revisar Manual de Usuario](/es/v1.58/user-manual/quick-start-guide) para comenzar


# Desinstalar Zylon
Source: https://docs.zylon.ai/es/v1.58/operator-manual/installation/uninstall



Si sientes que algo salió mal con tu instalación, puedes desinstalar Zylon fácilmente.

Ten en cuenta que hacerlo **BORRARÁ TODOS TUS DATOS**, incluyendo usuarios, documentos cargados y demás. Este paso no se puede revertir.

Ejecuta el siguiente comando para desinstalar zylon.

```bash theme={null}
helm uninstall -n zylon zylon
```


# Aislar el servidor de la red
Source: https://docs.zylon.ai/es/v1.58/operator-manual/instance-hardening/airgap-your-server



> [!NOTE]
>
> Esta guía asume que instalaste Zylon
> usando Ubuntu 22.04 o Ubuntu 24.04 como sistema operativo base.
> Para otras configuraciones, debes instalar UFW (Uncomplicated Firewall)
> y adaptar los comandos según corresponda.

Si por requisitos de seguridad o cumplimiento normativo tu servidor Zylon debe operar
en un entorno aislado de la red (sin acceso a internet), puedes hacerlo
configurando UFW (Uncomplicated Firewall), que viene preinstalado en tu sistema operativo.

Casi todo el tráfico de red saliente puede bloquearse y la mayoría de las funciones de Zylon
continuarán funcionando con normalidad.

Ejemplos de funciones que *no* estarán disponibles sin acceso a internet (la lista puede crecer en el futuro):

* Búsqueda web con IA
* Conexiones MCP
* Integraciones de bases de datos que requieren acceso a internet (por ejemplo: Google BigQuery, Snowflake, etc.)

Activar el modo aislado implica que a partir de ese momento el proceso de actualización debe
adaptarse mediante dos enfoques:

* Deshabilitar temporalmente el firewall, ejecutar la actualización y volver a habilitarlo
* Pasar a un procedimiento de instalación completamente aislado tal como se describe [aquí](/es/v1.58/operator-manual/installation/airgap)

### Configuración de UFW

¡Después de cualquier cambio no olvides habilitar el firewall!

```bash theme={null}
sudo ufw enable --force
```

### Registro

```md theme={null}
# Habilitar el registro para supervisar el tráfico bloqueado/permitido
sudo ufw logging low
sudo ufw enable --force
```

> **Nota:** El registro de UFW captura la actividad del firewall y es obligatorio para la mayoría de los marcos de cumplimiento de seguridad (SOC 2, ISO 27001, NIS2). El nivel `low` registra todos los paquetes bloqueados y las infracciones de políticas; esto es suficiente para auditoría y respuesta ante incidentes sin generar un volumen excesivo de ruido por el tráfico permitido habitual. Los registros los escribe el kernel y normalmente aparecen en una o varias de las siguientes ubicaciones, según la configuración de su sistema:
>
> * `/var/log/ufw.log` — cuando `rsyslog` está activo (predeterminado en Ubuntu)
> * `/var/log/syslog` — como alternativa o junto con `ufw.log` en algunas configuraciones
> * Accesibles mediante `sudo journalctl -k | grep UFW` en sistemas basados en systemd
>
> Recomendamos verificar qué ubicación está activa en su sistema después de habilitar el registro.

#### Reglas genéricas

Estas son las reglas más restrictivas que deben aplicarse a tu servidor Zylon.
Por lo general, no necesitarás modificarlas, a menos que tengas requisitos de
red específicos.

```bash theme={null}

# Permitir SSH (entrada y salida), ¡de lo contrario podrías bloquearte el acceso!
sudo ufw allow ssh
sudo ufw allow out ssh

# Establecer políticas por defecto: permitir tráfico entrante, denegar tráfico saliente
# Necesario para que el workspace siga funcionando mientras se bloquea
# el acceso a internet
sudo ufw default allow incoming
sudo ufw default deny outgoing

# Permitir tráfico de loopback, para k8s y servicios locales
sudo ufw allow in on lo
sudo ufw allow out on lo

# Comunicación interna de k8s
sudo ufw allow in from 10.0.0.0/8
sudo ufw allow out to 10.0.0.0/8
```

Además, se recomienda encarecidamente permitir la resolución DNS; de lo contrario,
las funciones opcionales listadas a continuación no funcionarán correctamente.

El siguiente script añadirá las reglas necesarias desde
`/etc/resolv.conf`:

```bash theme={null}
for ns in $(awk '/^nameserver/ {print $2}' /etc/resolv.conf); do
    sudo ufw allow out to $ns port 53
done
```

#### Reglas para Google Single Sign-On (SSO)

Si usas Google SSO para la autenticación, debes permitir
el tráfico saliente hacia los servidores OAuth de Google.

El siguiente script obtendrá la lista actual de rangos IP de Google
y añadirá las reglas UFW necesarias:

```bash theme={null}
google_rules=$(
curl -s https://www.gstatic.com/ipranges/goog.json \
| jq -r '.prefixes[]
         | select(.ipv4Prefix)
         | "sudo ufw allow out to \(.ipv4Prefix) port 443"'
)
# Y las aplica
eval "$google_rules"
```

#### Reglas para Microsoft Entra

Si usas Microsoft Entra (Azure AD) para la autenticación, debes permitir
el tráfico saliente hacia los servidores OAuth de Microsoft.

Los pasos para permitir Microsoft Entra son los siguientes:

* Descarga la lista actual de rangos IP de Microsoft desde [aquí](https://www.microsoft.com/en-us/download/details.aspx?id=56519)
* Copia el archivo `ServiceTags_Public_YYYYMMDD.json` a tu servidor
* Ejecuta el siguiente script para generar y aplicar las reglas UFW necesarias:

```bash theme={null}
# Reemplaza ServiceTags_Public_YYYYMMDD.json con el nombre real del archivo
microsoft_rules=$(
jq -r '[.values
| map(select(.id=="AzureActiveDirectory"
or .id=="AzureActiveDirectory.ServiceEndpoint"
or .id=="AzureActiveDirectoryDomainServices"))
| .[].properties.addressPrefixes]
| flatten[]
| "sudo ufw allow out to \(.) port 443"' ServiceTags_Public_20260119.json
)
# Y las aplica
eval "$microsoft_rules"
```

#### Reglas genéricas para otros servicios

Si usas otros servicios que requieren acceso a internet, como servidores MCP,
también deberás permitir el tráfico saliente hacia esos servicios mediante sus direcciones IP.

Para obtener las direcciones IP, puedes usar los comandos `nslookup` o `dig`, por ejemplo:

```bash theme={null}
nslookup mcp.tu-servidor-mcp.com
# o
dig mcp.tu-servidor-mcp.com +short
```


# Cifrado de disco
Source: https://docs.zylon.ai/es/v1.58/operator-manual/instance-hardening/disk-encryption

Cifra el disco de tu servidor Zylon para proteger los datos en reposo en Ubuntu 24.04

> [!NOTE]
>
> Esta guía está escrita para Ubuntu 24.04. Otros sistemas operativos y distribuciones
> pueden requerir herramientas o pasos diferentes — adáptalos según corresponda.

El cifrado de disco garantiza que los datos almacenados en tu servidor sean ilegibles sin
la contraseña correcta, protegiéndolos frente a robos físicos o accesos no autorizados al hardware.

Elige el enfoque que se ajuste a tu situación:

* **Máquina nueva** — sin sistema operativo instalado. El cifrado de disco completo se configura durante la instalación de Ubuntu.
* **Zylon ya instalado** — cifra una partición de datos separada sin necesidad de reinstalar.

***

## Opción 1: Máquina nueva — Cifrado de disco completo durante la instalación

Este es el enfoque recomendado. El instalador de Ubuntu puede cifrar el disco completo
usando LUKS (Linux Unified Key Setup) con una única contraseña.

**1. Arranca desde el instalador de Ubuntu 24.04**

Descarga la ISO de Ubuntu 24.04 Server y arranca tu máquina desde ella.

**2. Avanza en el instalador hasta la configuración de almacenamiento**

En la pantalla de **Configuración de almacenamiento**, selecciona **Disposición de almacenamiento personalizada**
y luego elige la opción **Usar disco completo**.

**3. Activa el cifrado**

Marca **Cifrar el grupo LVM con LUKS**. Se te pedirá que establezcas una contraseña.

Elige una contraseña robusta y guárdala en un lugar seguro — **perderla significa perder el acceso a todos los datos**.

**4. Completa la instalación**

Finaliza el instalador con normalidad. En cada arranque, se te pedirá que introduzcas
la contraseña antes de que el sistema inicie.

**5. Instala Zylon**

Una vez Ubuntu en funcionamiento, sigue la [guía de instalación estándar de Zylon](/es/v1.58/operator-manual/installation/overview).

***

## Opción 2: Zylon ya instalado — Cifrar una partición de datos

Si Zylon ya está en funcionamiento, una reinstalación completa es muy disruptiva. En su lugar, puedes
crear una partición cifrada para el directorio de datos de Zylon (`/var/zylon`)
usando LUKS y mover los datos a ella.

> [!WARNING]
>
> Este proceso mueve datos de una aplicación en producción. **Realiza una copia de seguridad completa antes de continuar.**
> Consulta la [guía de copias de seguridad](/es/v1.58/operator-manual/operations/backup).

### Requisitos previos

* Un disco adicional o espacio sin particionar disponible en el servidor.
* `cryptsetup` y `rsync` instalados:

```bash theme={null}
sudo apt update
sudo apt install -y cryptsetup rsync
```

**1. Identifica el disco o partición objetivo**

Lista los dispositivos de bloque disponibles para encontrar tu disco adicional (p. ej. `/dev/sdb`).
El flag `-e 7` excluye los dispositivos loop (paquetes snap) para reducir el ruido:

```bash theme={null}
lsblk -d -e 7
```

**2. Crea y formatea el contenedor LUKS**

Reemplaza `/dev/sdb` con tu dispositivo real. Esto **borrará todos los datos en él**.

```bash theme={null}
sudo cryptsetup luksFormat /dev/sdb
```

Se te pedirá que confirmes (`YES`) y establezcas una contraseña.

**3. Abre el contenedor cifrado**

```bash theme={null}
sudo cryptsetup open /dev/sdb zylon-data
```

Esto mapea el contenedor a `/dev/mapper/zylon-data`.

**4. Crea un sistema de archivos en el dispositivo mapeado**

```bash theme={null}
sudo mkfs.ext4 /dev/mapper/zylon-data
```

**5. Detén Zylon antes de migrar los datos**

```bash theme={null}
sudo k0s stop
```

**6. Monta la partición cifrada y migra los datos**

```bash theme={null}
sudo mount /dev/mapper/zylon-data /mnt/zylon-data
sudo rsync -aAX /var/zylon/ /mnt/zylon-data/
```

Verifica que la copia se completó correctamente antes de continuar.

**7. Reemplaza el directorio de datos original con el montaje cifrado**

```bash theme={null}
sudo mv /var/zylon /var/zylon.bak
sudo mkdir /var/zylon
sudo umount /mnt/zylon-data
sudo mount /dev/mapper/zylon-data /var/zylon
```

**8. Configura el montaje automático al arranque**

Añade el dispositivo LUKS a `/etc/crypttab`:

```bash theme={null}
# Obtén el UUID del dispositivo LUKS
sudo cryptsetup luksDump /dev/sdb | grep UUID
```

Añade una línea a `/etc/crypttab` (reemplaza `YOUR_UUID` con el valor anterior):

```
zylon-data UUID=YOUR_UUID none luks
```

Luego añade el montaje a `/etc/fstab`:

```
/dev/mapper/zylon-data /var/zylon ext4 defaults 0 2
```

> [!NOTE]
>
> Usar `none` como archivo de clave significa que se pedirá la contraseña en cada arranque.
> Para servidores sin pantalla, consulta la documentación de Ubuntu sobre el desbloqueo remoto de LUKS.

**9. Inicia Zylon y verifica**

```bash theme={null}
sudo k0s start
```

Confirma que todo funciona correctamente y luego elimina la copia de seguridad:

```bash theme={null}
sudo rm -rf /var/zylon.bak
```

### Script automatizado (alternativa)

El script siguiente realiza todos los pasos anteriores de forma interactiva. Solicitará
el disco objetivo y la contraseña LUKS, y se encargará del resto.

> [!WARNING]
>
> Revisa el script antes de ejecutarlo. **Borrará el disco objetivo** y
> detendrá Zylon durante la migración.

Guárdalo como `encrypt-zylon.sh` y ejecútalo con `sudo bash encrypt-zylon.sh`.

```bash theme={null}
#!/usr/bin/env bash
set -eu

log()   { echo "[INFO]  $*"; }
warn()  { echo "[WARN]  $*"; }
abort() { echo "[ERROR] $*" >&2; exit 1; }

[ "$(id -u)" -eq 0 ] || abort "Ejecuta este script con sudo: sudo bash $0"
command -v cryptsetup >/dev/null || abort "cryptsetup no encontrado. Ejecuta: apt install cryptsetup"
command -v rsync      >/dev/null || abort "rsync no encontrado. Ejecuta: apt install rsync"

lsblk -d -e 7
echo

ROOT_DISK=$(lsblk -rno PKNAME,MOUNTPOINT 2>/dev/null | awk '$2=="/" {print $1}')
if [ -n "$ROOT_DISK" ]; then
    warn "Disco raíz (NO usar este): /dev/$ROOT_DISK"
fi

log "Discos sin particiones (candidatos para el cifrado):"
lsblk -d -e 7 -rno NAME | while read -r name; do
    part_count=$(lsblk "/dev/$name" -rno NAME | grep -c ".")
    if [ "$part_count" -eq 1 ] && [ "$name" != "$ROOT_DISK" ]; then
        size=$(lsblk -d "/dev/$name" -rno SIZE)
        echo "    /dev/$name  $size"
    fi
done
echo

read -rp "Introduce el dispositivo de disco objetivo (p. ej. /dev/sdb): " DEVICE

[ -b "$DEVICE" ] || abort "$DEVICE no es un dispositivo de bloque válido."

warn "TODOS LOS DATOS EN $DEVICE SERÁN BORRADOS. Esto no se puede deshacer."
read -rp "Escribe YES para confirmar: " CONFIRM
[ "$CONFIRM" = "YES" ] || abort "Operación cancelada."

MAPPER_NAME="zylon-data"
MOUNT_TMP="/mnt/zylon-data"
DATA_DIR="/var/zylon"
BACKUP_DIR="/var/zylon.bak"

log "Deteniendo Zylon... (si el script se interrumpe a partir de este punto, inícialo manualmente con: sudo k0s start)"
k0s stop || true

log "Formateando $DEVICE con LUKS..."
cryptsetup luksFormat "$DEVICE"

log "Abriendo el contenedor cifrado..."
cryptsetup open "$DEVICE" "$MAPPER_NAME"

log "Creando sistema de archivos ext4..."
mkfs.ext4 "/dev/mapper/$MAPPER_NAME"

mkdir -p "$MOUNT_TMP"
mount "/dev/mapper/$MAPPER_NAME" "$MOUNT_TMP"

log "Copiando datos de $DATA_DIR a la partición cifrada (esto puede tardar un rato)..."
rsync -aAX "$DATA_DIR/" "$MOUNT_TMP/"

log "Reemplazando el directorio de datos..."
mv "$DATA_DIR" "$BACKUP_DIR"
mkdir "$DATA_DIR"
umount "$MOUNT_TMP"
mount "/dev/mapper/$MAPPER_NAME" "$DATA_DIR"

UUID=$(cryptsetup luksDump "$DEVICE" | awk '/^UUID:/ { print $2 }')

log "Actualizando /etc/crypttab..."
echo "$MAPPER_NAME UUID=$UUID none luks" >> /etc/crypttab

log "Actualizando /etc/fstab..."
echo "/dev/mapper/$MAPPER_NAME $DATA_DIR ext4 defaults 0 2" >> /etc/fstab

log "Iniciando Zylon..."
k0s start

echo
log "Listo. Los datos de Zylon están ahora en una partición cifrada."
log "Verificando..."
lsblk -o NAME,FSTYPE,MOUNTPOINT | grep -E "crypto|zylon"
echo
log "Copia de seguridad en $BACKUP_DIR — elimínala cuando todo funcione correctamente:"
echo "  sudo rm -rf $BACKUP_DIR"
```

> [!NOTE]
>
> La contraseña se solicitará en cada arranque. Para servidores sin pantalla, consulta
> la documentación de Ubuntu sobre el desbloqueo remoto de LUKS.


# Seguridad del servidor
Source: https://docs.zylon.ai/es/v1.58/operator-manual/instance-hardening/overview

Guías para proteger y reforzar la seguridad de tu servidor Zylon contra accesos no autorizados y exposición de red

El endurecimiento de la instancia abarca las prácticas y configuraciones que reducen la superficie de ataque de tu despliegue de Zylon.
Aplica estas guías tras la instalación para fortalecer la postura de seguridad de tu servidor.

## Temas

> **[Aislar el servidor de la red](/es/v1.58/operator-manual/instance-hardening/airgap-your-server)**
>
> Restringe el tráfico de red entrante y saliente mediante reglas de firewall UFW para aislar tu instancia de Zylon.

> **[Cifrado de disco](/es/v1.58/operator-manual/instance-hardening/disk-encryption)**
>
> Cifra el disco de tu servidor con LUKS para proteger los datos en reposo, tanto en máquinas nuevas como en instalaciones existentes de Zylon.


# Claromentis
Source: https://docs.zylon.ai/es/v1.58/operator-manual/knowledge-base/claromentis



Para integrar con Claromentis, necesitas una intranet de Claromentis habilitada para tu empresa y tus credenciales de acceso para **configurar Zylon** para usar Claromentis en la aplicación

## Verifica tu dominio de Claromentis

Primero, necesitas verificar que puedes acceder a tu intranet de Claromentis. Tus credenciales se usarán más tarde como el punto de conexión entre Zylon y Claromentis.

* Inicia sesión en tu intranet de Claromentis usando tus credenciales
* Anota tu dominio de Claromentis (ej., `https://your-company.myintranet.net` o tu dominio personalizado de claromentis)
* Verifica que tu cuenta tenga permisos suficientes para acceder a los documentos de tu intranet

## Configurar Zylon para usar la API de Claromentis

Con la información de tu dominio de Claromentis lista del paso 1,
ahora necesitas editar el archivo de configuración de Zylon ubicado en `/etc/zylon/zylon-conf.yaml`

```yaml theme={null}
integration:
  claromentis:
    enabled: true
    domain: "https://your-company.myintranet.net"
```

Y completa las propiedades con los valores generados previamente:

* domain → valor generado en el paso 1.

Guarda y cierra el archivo `/etc/zylon/zylon-conf.yaml`

Finalmente, ejecuta el siguiente comando para reiniciar Zylon y actualizar la configuración

```bash theme={null}
zylon-cli update
```

¡Todo está listo 🎉

## Solución de Problemas

### Intento cargar archivos a la base de conocimiento y el botón de Claromentis está deshabilitado

Limpia la caché del navegador e intenta de nuevo.

### Cuando hago clic en `Upload files -> From Claromentis` el inicio de sesión no funciona

* Verifica que el usuario y contraseña que estás introduciendo sean los mismos que usas para iniciar sesión en Claromentis.

### Actualicé mis credenciales en Claromentis. Mi integración/usuario está atascado y no puedo sincronizar archivos más.

> [!NOTE]
>
> Esta solución es solo para la versión temprana de Zylon que no tiene la pantalla de integraciones. Si tu instancia de Zylon
> tiene una pantalla donde gestionar las integraciones de usuario, por favor usa esa pantalla en lugar de esta guía.

**Lo que necesitamos es el `id` de la integración y la cookie de autenticación `zln_s`.**

1. Ve a tu instancia de zylon e inicia sesión con el usuario que quieres actualizar
2. Abre las herramientas de desarrollador del navegador (clic derecho => inspeccionar)
3. En la nueva barra lateral abierta, ve a la pestaña `Application`,
   selecciona `Cookies` y selecciona el dominio de tu instancia de zylon, luego copia el valor de la cookie `zln_s` y guárdalo para más tarde
4. Ahora, tenemos el token de autenticación, encontremos el `id` de la integración
5. Dentro de la aplicación zylon, abre la pestaña `Network`,
   y selecciona `Fetch/XHR` y filtra por la palabra `integrations`
6. Ahora, dentro de la aplicación zylon, navega al proyecto que
   integraste y ve a la base de conocimiento, verás en la pestaña de red una solicitud, haz clic en ella para ver los detalles, y podrás ver una lista de integraciones, busca `type: "Claromentis"`, ahora puedes ver el `id`
7. A continuación, abre una terminal con cURL instalado
8. Pega el siguiente comando cURL y reemplaza las siguientes variables:

* your-zylon-domain => dominio de la instancia de zylon
* your-zylon-cookie => la cookie `zln_s` que copiaste en el paso 3
* your-integration-id => el `id` que copiaste en el paso 6
* your-user-name => el nombre de usuario de claromentis
* your-new-password-in-raw => la nueva contraseña para ese usuario en texto plano
* your-organization => el slug de la organización,
  si solo tienes 1 organización, es `default` de lo contrario escribiré cómo obtenerlo

```bash theme={null}
curl 'https://{your-zylon-domain}/api/app/integration/claromentis/{your-integration-id}' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  -b 'zln_s={your-zylon-cookie}' \
  -H 'origin: https://{your-zylon-domain}' \
  -H 'x-org: {your-organization}' \
  --data-raw '{"username":"{your-user-name}","password":"{your-new-password-in-raw}"}'
```

## Notas Adicionales

### Los documentos vinculados (symlinks) no están soportados

Algunos archivos en Claromentis pueden aparecer en carpetas pero en realidad son **symlinks**—atajos que apuntan a archivos almacenados en otro lugar. Estos están marcados con un icono 🔗 en la interfaz de Claromentis.

![claromentis\_linked\_files.png](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/operator-manual/knowledge-base/claromentis-images/claromentis_linked_files.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=81a57b4d8c5bda28c956fd7b45e43507)

Zylon **no** ingiere estos documentos symlinked por las siguientes razones:

* La **API de Claromentis no soporta resolver symlinks**, haciendo imposible obtener los archivos objetivo reales.
* Ingerir tanto el archivo original como su symlink crearía **contenido duplicado** en Zylon.
* Si el **archivo original está restringido** o no es accesible para el usuario que realiza la ingesta, la ingesta fallará.
* Podría llevar a **bucles de ingesta infinitos** si los symlinks se referencian entre sí cíclicamente.


# Confluence
Source: https://docs.zylon.ai/es/v1.58/operator-manual/knowledge-base/confluence



Para integrar con Confluence, necesitas **crear una aplicación de Atlassian** que actuará como un puente entre Zylon ↔ Confluence y **configurar Zylon** para usar la nueva aplicación de Atlassian

## Crear una aplicación de Atlassian

Primero necesitas una cuenta de Atlassian que será la propietaria de la aplicación. Recomendamos usar una cuenta no personal. Esta cuenta no necesita tener acceso a ningún Space ya que servirá como un puente entre Zylon y Confluence.

1. Ve a [https://developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/)

   Haz clic en `Create` → `OAuth 2.0 integration`

![image.png](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/operator-manual/knowledge-base/confluence-images/image.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=d8e7bc34830bce4e5a0f525b5521e7dd)

1. Proporciona un nombre significativo para la Aplicación.

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_1.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=71d5a51b6cab6a96ca50c08ea9d43705)

1. En distribución:
   * En el menú izquierdo navega a `Distribution`
   * Haz clic en `Edit`

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_2.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=41d4159241043ba0a1672c72931e11d1)

1. En estado de distribución:

* Selecciona la casilla `Sharing`.
* Ingresa un nombre de proveedor o elige la opción `Use your own name`.
* Si tienes una política de privacidad, proporciona el enlace a ella. Si no, usa el enlace por defecto: [`https://example.com/privacy`](https://example.com/privacy), que está destinado para uso interno.
* Para la pregunta "¿Tu aplicación almacena datos personales?", selecciona `No`

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_3.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=c7b3d0aa17b0c3dbc1a1b174b032537b)

1. En permisos:

* En el menú izquierdo, navega a **`Permissions`**.
* Haz clic en **`Add`** para **`Confluence API`**.
* La página se actualiza automáticamente, y debería aparecer un nuevo botón **`Configure`**. Si no aparece, actualiza la página manualmente.
* Haz clic en **`Configure`**.

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_4.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=fae32262ea8b0f2b591bfa257f64b35a)

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_5.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=e8f5b82b5dd640c7c762ccaa2639685f)

1. Haz clic en `Granual scopes` y luego en `Edit scopes`

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_6.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=b7a2cf2e1027f7921104e79ab05a03a6)

1. Agrega uno por uno los siguientes permisos. Puedes buscarlos pegando los valores en el campo con una lupa.

   Debe haber un total de `10` scopes agregados que puedes revisar antes de guardar.

```bash theme={null}
        read:content:confluence,
        read:content-details:confluence,
        read:space-details:confluence,
        read:page:confluence,
        read:attachment:confluence,
        read:blogpost:confluence,
        read:custom-content:confluence,
        read:space:confluence,
        read:space.permission:confluence,
        read:folder:confluence,

```

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_7.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=74158e3a9247b20f71a9e2a5b2aca41c)

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_8.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=a613d677bc1a9e830d674000414f6dfb)

1. En autorización:

* En el menú izquierdo, navega a **`Authorization`**.
* Haz clic en **`Add`** para **`OAuth 2.0 (3LO)`**.

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/knowledge-base/confluence-images/image_9.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=e3cce66e826c401a3e0064d2bc8aacd6)

1. En autorización:

* En el campo **`Callback URL`**, ingresa:
  `https://zylon.company.com/api/app/integration/confluence/callback`Reemplaza **`zylon.company.com`** con el hostname donde está instalado Zylon en tu servidor.
* Haz clic en **`Save changes`**.

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_10.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=261f42a10455b4d8d83a8ad8775f8bb4)

1. En configuración:

* En el menú izquierdo, navega a `Settings`. Copia los dos valores listados bajo **`Authentication details`**:
  * Client ID
  * Secret

Necesitarás estos valores para el siguiente paso: [Configurar Zylon para usar la Aplicación de Atlassian](#configurar-zylon-para-usar-la-aplicación-de-atlassian)

![image.png](https://mintcdn.com/zylon/F67a_ybxGCNUaYMH/images/operator-manual/knowledge-base/confluence-images/image_11.png?fit=max\&auto=format\&n=F67a_ybxGCNUaYMH\&q=85\&s=e7a5f7d477378aba499344fb0a602936)

## Configurar Zylon para usar la Aplicación de Atlassian

Con los valores que hemos adquirido en el paso 10, necesitas editar el archivo de configuración de Zylon ubicado en `/etc/zylon/zylon-conf.yaml`

> [!TIP]
>
> El archivo de configuración es un archivo `.yaml` ¡ten cuidado con la sangría, espacios, punto y coma, comillas dobles!

Agrega el siguiente fragmento al final del archivo

```bash theme={null}
integration:
  confluence:
    enabled: true
    clientId: ""
    clientSecret: ""
    redirectUri: ""  

```

Y completa las propiedades con los valores generados previamente:

* clientId → valor generado en el paso 10
* clientSecret → valor generado en el paso 10
* redirectUri → mismo valor que en el paso 9

Guarda y cierra el archivo `/etc/zylon/zylon-conf.yaml`

Finalmente, ejecuta el siguiente comando para reiniciar Zylon y actualizar la configuración

```bash theme={null}
zylon-cli update
```

¡Todo está listo 🎉

## Solución de Problemas

### Intento cargar archivos a la base de conocimiento y el botón de Confluence está deshabilitado

Limpia la caché del navegador e intenta de nuevo.

### Cuando hago clic en `Upload files -> From Confluence` el inicio de sesión no funciona

* Verifica que el `clientId` `secretId` estén copiados y pegados correctamente en el archivo de configuración de Zylon
* Verifica que la `Callback URL` sea correcta en el paso 9 y sea la misma que el `redirectUri` en el archivo de configuración.

### No veo ningún espacio para importar

* Asegúrate de haber iniciado sesión en Confluence con una cuenta que tenga acceso a espacios.
* Verifica que los permisos requeridos sean correctos como se muestra en el paso 6


# Confluence Server
Source: https://docs.zylon.ai/es/v1.58/operator-manual/knowledge-base/confluence-server



Zylon se integra directamente con **Confluence Server / Data Center** mediante la **API REST de Confluence**.
No se requiere ninguna aplicación de Atlassian, configuración OAuth ni servicios externos.

***

## Requisitos

* Una instancia de *Confluence Data Server* en ejecución
* Una **cuenta de usuario de Confluence** con acceso a los Espacios que quieras importar
* Acceso de red desde Zylon a la instancia de Confluence

***

## Autenticación

Zylon se autentica mediante **autenticación básica (Basic Authentication)**:

* **Usuario**: nombre de usuario de Confluence
* **Contraseña**: contraseña de Confluence

Los permisos disponibles para Zylon son exactamente los permisos del usuario con el que te autentiques.

***

## Configurar Zylon

Edita el archivo de configuración de Zylon ubicado en:

```bash theme={null}
/etc/zylon/zylon-conf.yaml
```

> [!TIP]
>
> El archivo de configuración es YAML. Ten cuidado con la indentación, los espacios y las comillas.

Añade la siguiente configuración:

```yaml theme={null}
integration:
  confluenceLocal:
    enabled: true
    domain: "http://your-confluence-domain:8090"
```

Campos de configuración

**enabled**
Habilita el conector de Confluence Local.

**domain**
URL base de tu instancia de Confluence Server.

Ejemplos:
[http://confluence.company.local:8090](http://confluence.company.local:8090)
[https://confluence.company.com](https://confluence.company.com)

## Solución de Problemas

### Intento cargar archivos a la base de conocimiento y el botón de Confluence está deshabilitado

Limpia la caché del navegador e intenta de nuevo.

### Cuando hago clic en `Upload files -> From Confluence` el inicio de sesión no funciona

* Verifica que el `domain` este copiado y pegado correctamente en el archivo de configuración de Zylon
* Verifica que el `username` y `password` usados son correctos.

### No veo ningún espacio para importar

* Asegúrate de haber iniciado sesión en Confluence con una cuenta que tenga acceso a espacios.
* Verifica que los permisos requeridos sean correctos como se muestra en el paso 6


# Sistema de Archivos Samba
Source: https://docs.zylon.ai/es/v1.58/operator-manual/knowledge-base/file-system



### 1. Recopila la Información de tu Servidor Samba

Para integrar Zylon con tu servidor de archivos Samba on-premise, necesitas los detalles de conexión del servidor (host, puerto, nombre del recurso compartido) y credenciales válidas. Esta guía explica cómo configurar Zylon para usar Samba para integración de sistema de archivos dentro de tu red local. Necesitarás:

* **Host o dirección IP** del servidor Samba (ej. `files.example.com` o `192.168.1.50`).
* **Puerto** en el que SMB está escuchando (por defecto es `445`; si ejecutas en un puerto no estándar, anótalo).
* **Nombre del recurso compartido (raíz)** (ej. `zylon-samba`).
* **Credenciales** (nombre de usuario y contraseña) que tengan acceso de **lectura** a ese recurso compartido.
* **Soporte de versión de protocolo SMB**:
  * Actualmente soportamos **SMB2 y superiores**.
  * Si requieres **SMB1**, por favor contacta al equipo de Zylon para asistencia.

Para verificar conectividad:

1. **Linux** (usando `smbclient`):

```bash theme={null}
smbclient -L //files.example.com -U yourUser%yourPass
```

Deberías ver un listado de recursos compartidos, incluyendo `zylon-samba`.

2. **macOS** (Finder):

* En Finder, presiona ⌘K → conéctate a `smb://files.example.com/zylon-samba`.
* Ingresa tus credenciales cuando se solicite, y verifica que puedes navegar archivos.

3. Windows

* **Explorador de Archivos (Gráfico)**:
  1. Abre **Explorador de Archivos** (Win + E).
  2. En la barra lateral izquierda, haz clic derecho en **Este equipo** y elige **Conectar unidad de red…**.
  3. En el menú desplegable **Unidad**, selecciona una letra de unidad disponible (ej., `Z:`).
  4. En el campo **Carpeta**, ingresa:
     (o si usas un puerto no estándar, `\\\\files.example.com@445\\zylon-samba`).

```
\\\\files.example.com\\zylon-samba

```

5. Marca **Conectar usando credenciales diferentes**, luego haz clic en **Finalizar**.
6. Cuando se solicite, ingresa tu **Nombre de usuario** y **Contraseña** de Samba, luego haz clic en **Aceptar**.
7. Si la conexión tiene éxito, la nueva unidad mapeada (ej., `Z:`) aparecerá bajo **Este equipo**, y puedes navegar su contenido.

***

### 2. Configurar Zylon para Usar Samba

Con los valores que hemos adquirido en los pasos anteriores, editaremos el archivo de configuración de Zylon ubicado en `/etc/zylon/zylon-conf.yaml`

Agrega el siguiente fragmento al final del archivo

```yaml theme={null}
integration:
  filesystem:
    enabled: true
    protocol: "samba"
    
    
external:
  samba:
    host: "YOUR_HOST_OR_IP"   # ej. "files.example.com" o "192.168.1.50"
    port: 445                 # Cambia tu puerto si no está configurado como defecto
    name: "ROOT_PATH"
```

* **host** → El hostname o dirección IP donde tu servidor Samba es accesible.
* **protocol** → Debe estar establecido en `"samba"`.
* **name** → Nombre de la carpeta compartida (ej. `"Data"`).

Guarda y cierra `zylon-conf.yaml`.

***

### 3. Actualizar Zylon para Aplicar Cambios

Finalmente, ejecuta el siguiente comando para reiniciar Zylon y actualizar la configuración

```bash theme={null}
zylon-cli update
```

¡Todo está listo 🎉

***

### 4. Consideraciones de Acceso de Red (On-Premise)

Dado que este despliegue es on-premise, asegúrate de que el Servidor Ubuntu donde está alojado Zylon pueda alcanzar el servidor Samba. **No** necesitas exponer SMB a internet público—todo permanece dentro de tu red privada.

1. **Configuración DNS / Hosts**

* Verifica que las máquinas cliente puedan resolver el nombre de host de Samba (ej., `files.internal.company`).
* Si DNS no está disponible o es inconsistente, actualiza `/etc/hosts` (Linux/macOS) o `C:\Windows\System32\drivers\etc\hosts` (Windows) para mapear el hostname a su IP.

2. **Firewall y Acceso de Puerto**

* Asegúrate de que el **puerto TCP 445** (o tu puerto SMB personalizado) esté abierto entre las estaciones de trabajo cliente y el servidor Samba.
* En el servidor Samba, confirma que el firewall del SO (iptables, firewalld, Windows Firewall, etc.) permite conexiones entrantes en ese puerto.
* Si los usuarios remotos se conectan vía VPN, asegúrate de que la subred VPN pueda enrutar a la IP:445 del host de Samba.

***

### 5. Credenciales

Cuando un usuario habilita la integración de Samba por primera vez a través del frontend de Zylon, se le solicitará ingresar:

* **Nombre de usuario**
* **Contraseña**

Zylon verifica estas credenciales inmediatamente. Si son inválidas, el frontend muestra un mensaje de error, y el usuario debe volver a ingresar credenciales correctas. Una vez válidas, Zylon almacena las credenciales de forma segura para acceso posterior al recurso compartido; no se requiere configuración manual de variables de entorno.

> Nota: Las credenciales están limitadas por cuenta de usuario. Si múltiples usuarios necesitan conectarse al mismo recurso compartido, cada uno debe ingresar credenciales válidas con acceso apropiado.---

### 6. Solución de Problemas

### 6.1 "No se puede resolver el host" o "Nombre o servicio desconocido"

* **DNS/Hosts:** Verifica que el hostname de Samba pueda resolverse:

  ```bash theme={null}
  ping files.internal.company
  ```

* Si DNS falla, actualiza el archivo hosts de cada cliente con:

  ```
  192.168.1.50   files.internal.company
  ```

### 6.2 "No se puede conectar al host"

* **Alcance del Puerto:**

  ```bash theme={null}
  nc -vz files.internal.company 445
  ```

(o reemplaza `445` con tu puerto personalizado).

* Si la prueba falla, confirma las reglas de firewall tanto en el segmento de red del cliente como en el servidor Samba.

### 6.3 Autenticación Fallida / Credenciales Incorrectas

* Si un usuario ingresa credenciales de Samba incorrectas en el frontend de Zylon, verá un error inmediato como "Autenticación fallida: nombre de usuario o contraseña inválidos."
* Para corregir, el usuario debe volver a ingresar su nombre de usuario y contraseña válidos de Samba a través de la interfaz de integración.
* En el lado del servidor Samba, verifica que la cuenta exista y tenga permisos en `/etc/samba/smb.conf`:

  ```bash theme={null}
  sudo smbpasswd -a yourUser
  testparm -s
  sudo tail -f /var/log/samba/log.smbd
  ```

### 6.4 "Versión de protocolo inválida"

* Asegúrate de que tu servidor y Zylon ambos soporten **SMB2 o superior**.
* Para forzar SMB2+ en el servidor, agrega bajo `[global]` en `/etc/samba/smb.conf`:

  ```
  server min protocol = SMB2
  ```

Luego reinicia Samba:

```bash theme={null}
sudo systemctl restart smbd
```

* Si debes usar SMB1, contacta al equipo de Zylon para una compilación de cliente personalizada.

***

### 8. Notas Adicionales

* **Solo Samba (SMB) Está Soportado para Integraciones de Sistema de Archivos**

En este momento, el framework de integración de Zylon soporta **solo montajes de sistema de archivos SMB2+**. Si requieres un protocolo diferente (ej., NFS, FTP, WebDAV), contacta al equipo de Zylon.

* **Soporte SMB1**

SMB1 está deprecado e inseguro. Si tu entorno aún requiere SMB1, contáctanos. Podemos proporcionar orientación o construir un cliente compatible.

* **Consejos de Rendimiento**
  * Para repositorios grandes, asegúrate de que tu servidor Samba tenga suficiente I/O y ancho de banda de red.
  * En Linux, montar con `cache=none` puede reducir problemas de archivos obsoletos si los usuarios modifican archivos frecuentemente fuera de Zylon.

Ahora estás listo para integrar Zylon con tu sistema de archivos Samba. Una vez conectado, los usuarios podrán navegar y gestionar archivos compartidos directamente desde la interfaz de Zylon.


# Google Drive
Source: https://docs.zylon.ai/es/v1.58/operator-manual/knowledge-base/google-drive



Para integrar Google Drive, crea una aplicación OAuth en Google Cloud y configura Zylon con sus credenciales. Esto permite que los usuarios inicien sesión con Google, seleccionen archivos o carpetas con Google Picker y los importen a una base de conocimiento.

## Antes de empezar

* Usa una cuenta de Google que pueda administrar el proyecto de Google Cloud. No necesita acceso al contenido de Drive que importarán los usuarios.
* Conoce la URL pública de tu instancia de Zylon, por ejemplo `https://zylon.company.com`.
* Guarda el secreto del cliente OAuth en un gestor de secretos seguro. No lo incluyas en el control de versiones. La clave de API de Picker se usa en el navegador, así que restríngela a las APIs requeridas y, cuando corresponda, al origen de Zylon.

## Crear o seleccionar un proyecto de Google Cloud

1. Abre la [consola de Google Cloud](https://console.cloud.google.com/).
2. Selecciona un proyecto existente o crea uno nuevo para la integración.
3. Anota el **número de proyecto** en el panel del proyecto. Zylon lo usa como **App ID** de Picker.

\[Placeholder: Añadir una captura que muestre el número de proyecto de Google Cloud.]

## Habilitar las APIs de Google

1. En la consola de Google Cloud, ve a **APIs y servicios** → **Biblioteca**.
2. Busca y habilita **Google Drive API**.
3. Busca y habilita **Google Picker API**.

![Resultados de búsqueda de la biblioteca de APIs de Google Cloud](https://mintcdn.com/zylon/jk3rCZ-wO976NtRI/images/operator-manual/knowledge-base/google-drive-images/api-list.png?fit=max\&auto=format\&n=jk3rCZ-wO976NtRI\&q=85\&s=bc7596c87d16eb3b60194d37af22f094)

## Crear y restringir una clave de API

Google Picker requiere una clave de API además de las credenciales del cliente OAuth.

1. Ve a **APIs y servicios** → **Credenciales**.
2. Selecciona **Crear credenciales** → **Clave de API**.
3. Copia la clave; será el valor de `apiKey` en Zylon.
4. Abre la nueva clave y, en **Restricciones de API**, selecciona **Restringir clave**.
5. Selecciona **Google Drive API** y **Google Picker API** y guarda la clave.

Si la política de Google Cloud exige restricciones de aplicación, restringe la clave al origen público de Zylon Workspace, por ejemplo `https://zylon.company.com`.

![Clave de API restringida a Google Drive API y Google Picker API](https://mintcdn.com/zylon/jk3rCZ-wO976NtRI/images/operator-manual/knowledge-base/google-drive-images/credentials-permissions.png?fit=max\&auto=format\&n=jk3rCZ-wO976NtRI\&q=85\&s=b5b87c965de36f66cd89cf04f853aac6)

## Configurar la pantalla de consentimiento OAuth y el acceso a datos

1. En la consola de Google Cloud, abre **Google Auth platform**. Completa la configuración obligatoria de **Branding** y **Audience** de tu organización.
2. Abre **Data Access** y selecciona **Add or remove scopes**.
3. Añade los siguientes scopes y guarda los cambios.

| Scope | Descripción para el usuario |
| - | - |
| `https://www.googleapis.com/auth/drive.metadata.readonly` | Ver metadatos de archivos en Google Drive. |
| `https://www.googleapis.com/auth/drive.readonly` | Ver y descargar archivos de Google Drive. |
| `https://www.googleapis.com/auth/userinfo.email` | Ver tu dirección de correo principal de Google Account. |
| `https://www.googleapis.com/auth/userinfo.profile` | Ver tu información personal, incluida la información que has hecho pública. |
| `openid` | Asociarte con tu información personal en Google. |
| `https://www.googleapis.com/auth/drive.file` | Ver, editar, crear y eliminar solo los archivos específicos de Google Drive que usas con esta aplicación. |

Zylon solicita todos estos scopes al iniciar sesión. El scope de metadatos de Drive también es necesario para la implementación del conector.

![Scopes de Data Access en Google Auth platform](https://mintcdn.com/zylon/jk3rCZ-wO976NtRI/images/operator-manual/knowledge-base/google-drive-images/data-access.png?fit=max\&auto=format\&n=jk3rCZ-wO976NtRI\&q=85\&s=527685e606d564785f2472ea20f203fb)

## Crear un cliente OAuth

1. En **Google Auth platform**, abre **Clients**.
2. Selecciona **Create client** y elige **Web application** como tipo de aplicación.
3. Asigna un nombre significativo al cliente, por ejemplo `Zylon Google Drive`.
4. En **Authorized redirect URIs**, añade la siguiente URL; sustituye el dominio por la URL de tu instancia de Zylon:

```text theme={null}
https://{your-zylon-domain}/api/app/integration/googledrive/callback
```

5. Crea el cliente.
6. Copia el **Client ID** y el **Client secret**. Los usarás como `clientId` y `clientSecret` en la configuración de Zylon.

> [!WARNING]
>
> La URI de redirección de Google Cloud y Zylon debe coincidir exactamente, incluidos `https`, el dominio, la ruta y las barras finales.

![Configuración del cliente OAuth de Google](https://mintcdn.com/zylon/jk3rCZ-wO976NtRI/images/operator-manual/knowledge-base/google-drive-images/client-config.png?fit=max\&auto=format\&n=jk3rCZ-wO976NtRI\&q=85\&s=434a8f493bc265d8d717764ab9d99215)

## Configurar Zylon

Añade los siguientes valores a la configuración de Zylon. Los valores `apiKey` y `appId` también se proporcionan al frontend de Workspace para Google Picker.

```yaml theme={null}
integration:
  googleDrive:
    enabled: true
    clientId: "{Google OAuth client ID}"
    clientSecret: "{Google OAuth client secret}"
    redirectUri: "https://{your-zylon-domain}/api/app/integration/googledrive/callback"
    apiKey: "{Google API key}"
    appId: "{Google Cloud project number}"
```

Para instalaciones con Helm, configura los valores equivalentes en tu archivo de valores bajo `integration.googleDrive`.

Aplica la configuración mediante tu proceso habitual de despliegue de Zylon. En instalaciones gestionadas con Zylon CLI, ejecuta:

```bash theme={null}
sudo zylon-cli sync
```

Ya puedes conectar Google Drive desde una base de conocimiento de un proyecto.

## Solución de problemas

### La opción de Google Drive no está disponible o el selector se cierra inmediatamente

* Confirma que `integration.googleDrive.enabled` es `true`.
* Confirma que `apiKey` y `appId` están configurados. Google Picker necesita ambos valores.
* Confirma que Google Drive API y Google Picker API están habilitadas en el mismo proyecto de Google Cloud.

### Google muestra un error de URI de redirección

* Comprueba que la **Authorized redirect URI** sea exactamente igual a `redirectUri` en la configuración de Zylon.
* Confirma que el dominio sea el dominio HTTPS público con el que se accede a Zylon.

### Un usuario no puede ver o importar un elemento de Drive

* Confirma que el usuario inicia sesión con la cuenta de Google que puede acceder al elemento.
* Confirma que la pantalla de consentimiento incluya todos los scopes de [Configurar la pantalla de consentimiento OAuth y el acceso a datos](#configurar-la-pantalla-de-consentimiento-oauth-y-el-acceso-a-datos).


# Conectores de Conocimiento
Source: https://docs.zylon.ai/es/v1.58/operator-manual/knowledge-base/overview



> **[Google Drive](/es/v1.58/operator-manual/knowledge-base/google-drive)**
>
> Configura el acceso a Google Drive para que los usuarios puedan seleccionar e indexar archivos y carpetas de sus cuentas de Google

> **[Confluence](/es/v1.58/operator-manual/knowledge-base/confluence)**
>
> Conecta con espacios de Atlassian Confluence para indexar páginas wiki, documentación y contenido colaborativo

> **[SharePoint](/es/v1.58/operator-manual/knowledge-base/sharepoint)**
>
> Integra con sitios de Microsoft SharePoint para acceder a documentos, listas y contenido de colaboración en equipo

> **[Claromentis](/es/v1.58/operator-manual/knowledge-base/claromentis)**
>
> Configura el conector de intranet Claromentis para indexar conocimiento interno de la empresa y contenido del lugar de trabajo digital

> **[Sistema de archivos](/es/v1.58/operator-manual/knowledge-base/file-system)**
>
> Configura la integración de recursos compartidos de archivos para indexar unidades de red y contenido del sistema de archivos compartido. Ej. Samba


# SharePoint
Source: https://docs.zylon.ai/es/v1.58/operator-manual/knowledge-base/sharepoint



Para integrar con SharePoint, necesitas **crear una aplicación de Microsof Entra** que actúa como un puente entre Zylon ↔ SharePoint y **configurar Zylon** para usar esta aplicación de Microsoft.

Esta guía te guía a través de la integración de SharePoint con Zylon usando el flujo OAuth 2.0 de Microsoft. Esto permite a Zylon acceder de forma segura a tus recursos de SharePoint usando permisos delegados.

## Crear una aplicación de Microsoft Entra

Primero necesitas una aplicación de Microsoft Entra. Recomendamos usar una cuenta no personal para crear esto desde el panel de Microsoft Entra. Esta cuenta no necesita tener acceso a ningún elemento en SharePoint pero tiene los permisos correctos para configurar la aplicación que servirá como un puente entre Zylon y SharePoint.

1. Ve a [https://entra.microsoft.com](https://entra.microsoft.com/).

En la barra lateral izquierda haz clic en `Applications` → `App Registrations` → `New Registration`

![imagen.png](https://mintcdn.com/zylon/fjTiqvTg5eiWUGXr/images/operator-manual/knowledge-base/sharepoint-images/imagen.png?fit=max\&auto=format\&n=fjTiqvTg5eiWUGXr\&q=85\&s=886f48ef78891c43a0789e743b671d65)

2. Proporciona un nombre significativo para la Aplicación.
3. En Tipos de cuenta admitidos elige `Accounts in this organizational directory only`
4. Bajo `Redirect URI` → Selecciona `Web` y agrega la siguiente URL de redirección

```
https://{your-zylon-instance}.com/api/app/integration/sharepoint/callback
```

1. Haz clic en `Register`

![Screenshot 2025-04-07 at 11.23.17.png](https://mintcdn.com/zylon/AAEt1MHLqi0nuOjf/images/operator-manual/knowledge-base/sharepoint-images/Screenshot_2025-04-07_at_11.23.17.png?fit=max\&auto=format\&n=AAEt1MHLqi0nuOjf\&q=85\&s=7593f512ac814cc4ed5e6ac753ddff0d)

2. Haz clic en `Redirect URIs`

![image.png](https://mintcdn.com/zylon/fjTiqvTg5eiWUGXr/images/operator-manual/knowledge-base/sharepoint-images/image.png?fit=max\&auto=format\&n=fjTiqvTg5eiWUGXr\&q=85\&s=2c9a5ac2f25081a237305363a0d4298b)

3. Haz clic en `Add a platform`

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/knowledge-base/sharepoint-images/image_1.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=f4980275df71017fe156503b60421179)

4. Haz clic en `Single-Page application`

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/knowledge-base/sharepoint-images/image_2.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=2502cd19f344baf3d5da86deebaae091)

5. Agrega la siguiente URL y haz clic en `Configure`:

```
https://{your-zylon-instance}.com
```

6. Ahora que la aplicación está creada, anota el `Application (client) Id` y `Directory (tenant) id` de la página `Overview`.

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/knowledge-base/sharepoint-images/image_3.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=041b8705687b10a18580592c7769b9ed)

7. Creemos un secreto de aplicación

Navega a `Certificates & secrets` → Haz clic en `+ New client secret` → Agrega una descripción y fecha de expiración (si agregas una fecha que viene pronto, debes ser consciente de que tu integración dejará de funcionar cuando el secreto expire)

Copia el `value` del Client Secret. El valor del secreto no será accesible más tarde.

![imagen.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/knowledge-base/sharepoint-images/imagen_1.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=57483ffd893fa152d919126d4c6f0a42)

Ahora tenemos que configurar los permisos de API que tendrá nuestra aplicación cliente.

Navega a `API Permissions` → `+ Add a permission` → `Microsoft Graph` → `Delegated permissions` e incluye los permisos a continuación y luego haz clic en `Add permissions`

* `Files.Read.All`
* `OpenId permissions.offline_access`
* `SharePointTenantSettings.Read.All`
* `Sites.Read.All`
* `User.Read`

Navega a `API Permissions` → `+ Add a permission` → `SharePoint` → `Delegated permissions` e incluye los permisos a continuación y luego haz clic en `Add permissions`

* `AllSites.Read`
* `EnterpriseResource.Read`
* `MyFiles.Read`
* `Project.Read`
* `Sites.Search.All`
* `User.Read.All`

Después de agregar ambas listas de permisos, haz clic en `Grant admin consent for [Your Org]` y confirma haciendo clic en `Yes`

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/knowledge-base/sharepoint-images/image_4.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=e57ffd10d306ef13e02e7cbbec8a0a62)

## Configurar Zylon con tu aplicación de Azure AD

Con los valores que hemos adquirido en los pasos anteriores, editaremos el archivo de configuración de Zylon ubicado en `/etc/zylon/zylon-conf.yaml`

Agrega el siguiente fragmento al final del archivo

```bash theme={null}
integration:
  sharepoint:
    enabled: true
    clientId: "" //Del paso 10 - Application client Id
    clientSecret: "" //Del paso 11 - Secret value
    redirectUri: "" //Del paso 4
    domain: "" //Tu dominio de sharepoint. ej: https://zylonai.sharepoint.com
    tenantId: "" //Del paso 10 - Directory tenant Id
    entrySite: "" //Opcional: URL del sitio de SharePoint por defecto
    entryList: "" //Opcional: Nombre de la lista por defecto (ej: "Documents")
    entryFolder: "" //Opcional: Nombre de la carpeta por defecto
```

Y completa las propiedades con los valores generados previamente:

* clientId → valor generado en el paso 10
* clientSecret → valor generado en el paso 11
* redirectUri → mismo valor que en el paso 4
* domain → Tu URL de SharePoint
* tenantId → mismo valor que en el paso 10
* entrySite → (Opcional) URL del sitio de SharePoint por defecto. Ver sección [Configurar Carpeta de Apertura por Defecto](#configurar-carpeta-de-apertura-por-defecto) más abajo
* entryList → (Opcional) Nombre de la lista por defecto, ej: "Documents". Ver sección [Configurar Carpeta de Apertura por Defecto](#configurar-carpeta-de-apertura-por-defecto) más abajo
* entryFolder → (Opcional) Nombre de la carpeta por defecto. Ver sección [Configurar Carpeta de Apertura por Defecto](#configurar-carpeta-de-apertura-por-defecto) más abajo

Guarda y cierra el archivo `/etc/zylon/zylon-conf.yaml`

Finalmente, ejecuta el siguiente comando para reiniciar Zylon y actualizar la configuración

```bash theme={null}
sudo zylon-cli sync
```

¡Todo está listo 🎉

## Configurar Carpeta de Apertura por Defecto

Puedes configurar una carpeta de apertura por defecto para la integración de SharePoint. Esto permite que la integración se abra directamente en una carpeta específica cuando los usuarios acceden a SharePoint a través de Zylon, mejorando la experiencia del usuario al omitir pasos de navegación.

Los tres campos opcionales controlan el punto de entrada para la integración:

* `entrySite`: La URL absoluta del sitio de SharePoint (funciona tanto para SharePoint como para OneDrive)
* `entryList`: El nombre de la lista dentro del sitio (ej: "Documents" es el predeterminado para SharePoint)
* `entryFolder`: El nombre de la carpeta dentro de la lista

**Importante:** Debes usar rutas absolutas de SharePoint para el campo `entrySite`, incluso para OneDrive. El formato de la ruta debe ser como:

```
https://example-my.sharepoint.com/personal/user_example_onmicrosoft_com
```

### Ejemplo de Configuración

Si deseas que la integración se abra por defecto en la carpeta "Defense and Security" en la lista Documents para el usuario `user_example_onmicrosoft_com`, configurarías:

```bash theme={null}
entrySite: "https://example-my.sharepoint.com/personal/user_example_onmicrosoft_com"
entryList: "Documents" //Predeterminado en SharePoint
entryFolder: "Defense and Security"
```

Esta configuración hará que la integración se abra directamente en la carpeta "Defense and Security" cuando los usuarios accedan a SharePoint a través de Zylon.

**Nota:** Los tres campos son opcionales. Si no se configuran o se dejan vacíos, serán ignorados y la integración usará el comportamiento predeterminado (abriendo en el nivel raíz).

## Solución de Problemas

### Intenté cargar archivos a la base de conocimiento pero el botón de SharePoint está deshabilitado

Limpia la caché del navegador e intenta de nuevo.

### Cuando hago clic en `Upload files -> From SharePoint` el inicio de sesión no funciona

* Verifica que el `clientId` `secretId` estén copiados y pegados correctamente en el archivo de configuración de Zylon
* Verifica que `redirectUri` sea el mismo que en el paso 4 y que tu dominio de sharepoint sea correcto
* Verifica que el `tenantId` que se está usando coincida con el de la página `Overview` de tu aplicación en Azure AD


# Integración con Google (SSO)
Source: https://docs.zylon.ai/es/v1.58/operator-manual/openid/google



### Crear una nueva aplicación OAuth para Zylon

Para habilitar el inicio de sesión único (SSO) de Google en Zylon, necesitas crear una aplicación OAuth 2.0 en la Consola de Google Cloud.

Accede a la [Consola de Google Cloud](https://console.cloud.google.com/).

> [!NOTE]
>
> Es posible que necesites crear un nuevo proyecto de Google para Zylon si aún no tienes uno.
>
> ![create-project](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/1-create-project.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=b8349c3a49d3772c22489faffbc20c3e)

Ve a la [sección de Autenticación de Google](https://console.cloud.google.com/auth/) para crear la aplicación.

![create-oauth-app](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/2-create-app.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=d8d06ceb592e7785c1a38e1daf22497e)

![oauth-config](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/3-configure-audience.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=02b51e86cd7852250426b92dbb70edb1)

En la configuración de audiencia, establécela como **interna** para que solo los usuarios de tu organización puedan iniciar sesión; de lo contrario, tendrás que pasar por el proceso de verificación de Google.

### Configurar el cliente OAuth

A continuación, configura el cliente OAuth.

![oauth-client-id](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/4-create-oauth-client.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=257cd8f21779047a3abeb6beac5ee2df)

Asegúrate de que se:

* El tipo de aplicación está configurado como **Aplicación web**.
* Los orígenes de JavaScript permitidos están configurados como `https://zylon.company.com`, sustituyendo `zylon.company.com` por el dominio donde está alojado Zylon (es el mismo dominio que el host en el archivo de configuración ubicado en `/etc/zylon/zylon-conf.yaml`).
* El URI de redirección autorizado está configurado como `https://zylon.company.com/api/v1/auth/google/callback`; al igual que antes, sustituye `zylon.company.com` por el dominio donde está alojado Zylon.
* Aplica los cambios y guarda el `Client ID` y el `Client Secret`, que se utilizarán más adelante en el archivo de configuración de Zylon.

Selecciona **Aplicación web** como tipo de aplicación:

![oauth-web-app](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/5-select-web-app-as-type.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=09a8be586c3cda8cdbcf86123e6331c7)

Configura el URI de redirección autorizado como se ha mencionado anteriormente; comprueba que el dominio es correcto
y que el sufijo es `/api/v1/auth/google/callback`:

![oauth-redirect-uri](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/6-configure-origin-and-callback.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=d6d3f71045ea79ffde86aaa514f4e0fa)

Crea el cliente OAuth y guarda el `Client ID` y el `Client Secret`:

![oauth-client-created](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/7-copy-oauth-data.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=ae02e6bff9184eedfb9fb0e86ddea25b)

### Scopes de openid

Ve a la [sección de acceso a datos/scopes](https://console.cloud.google.com/auth/scopes) y añade los siguientes scopes a tu aplicación:

* auth/userinfo.email (para obtener el correo electrónico del usuario)
* auth/userinfo.profile (para obtener el nombre del usuario y su foto de perfil)
* openid (para autenticar a los usuarios con OpenID Connect)

![oauth-scopes](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/8-add-scopes.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=63ffd81dd2ce8bcd9ed5746f977649b6)

![oauth-scopes-added](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/google/9-add-scopes-output.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=0728e2b6f483cfb2927ed476b2c4b076)

### Actualiza la configuración a Zylon

Añade la siguiente configuración a `/etc/zylon/zylon-conf.yaml`,
sustituyendo los valores de `clientId` y `clientSecret` por los obtenidos en los pasos anteriores
y `redirectUri` por el dominio correcto donde está alojado Zylon.

El archivo de configuración es un archivo `.yaml`, por lo que la indentación, los espacios, los puntos y coma y las
comillas dobles son relevantes.

```yaml theme={null}
auth:
  google:
    enabled: true
    clientId: "1234567890-abcde.apps.googleusercontent.com"
    clientSecret: "GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx"
    redirectUri: "https://zylon.company.com/api/v1/auth/google/callback"
```

Ejecuta el siguiente comando para actualizar la configuración:

```yaml theme={null}
sudo zylon-cli sync
```

Ahora deberías ver la opción de Google SSO al iniciar sesión.

> [!TIP]
>
> En caso de que no veas el botón de Google para iniciar sesión, borra la caché del navegador.


# Integración con Microsoft Entra (SSO)
Source: https://docs.zylon.ai/es/v1.58/operator-manual/openid/microsoft



### Agregar una nueva aplicación para Zylon

El objetivo es obtener 3 valores que se utilizarán para configurar Zylon para poder iniciar sesión con una cuenta de Microsoft.

* `Application (client) ID`
* `Client Secret`

1. Primero necesitas iniciar sesión en el panel de consola [https://portal.azure.com/#home](https://portal.azure.com/#home)
2. Haz clic en `Microsoft Entra Id`

![image.png](https://mintcdn.com/zylon/BXrLYrh44RWGgEbL/images/operator-manual/openid-images/microsoft/image.png?fit=max\&auto=format\&n=BXrLYrh44RWGgEbL\&q=85\&s=cd5a3a168800539d6a172d12b9a639c2)

3. Registra una nueva aplicación. Haz clic en `App registrations` en el menú izquierdo.

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_1.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=b39240470fa532c148d5a2d7044d4e00)

4. Haz clic en `New Registration`.

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_2.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=c0802132759a745e16d35c368d473837)

1. Se abrirá una nueva ventana y necesitarás agregar la siguiente información

* ⚠️ El tipo de Redirect URI es **web**⚠️
* Dominio: `https://zylon.company.com/api/v1/auth/microsoft/callback`. Reemplaza `zylon.company.com` con el dominio donde está alojado Zylon (Es el mismo dominio que en el archivo de configuración ubicado en `/etc/zylon/zylon-conf.yaml`).
* Tipos de cuenta admitidos: Se admiten todos los tipos de cuenta. Elige según tus necesidades específicas.

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_3.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=c05fc3ea6500ec894aa29bba0c1f39bb)

* En caso de que quieras cambiarlo más tarde, puedes hacerlo en `Application Overview`

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_4.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=8a45683409d3da704563900f8487e601)

5. Guarda el siguiente valor que se usará más tarde en el archivo de configuración para Zylon.

* Application (client) ID

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_5.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=22e6f6ee68858bca69404fb6e365b52c)

6. Ahora necesitamos generar el `ClientSecret`. Ve al menú izquierdo y haz clic en `Manage > Certificates & secrets`

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_6.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=c171e6123e85978a76430a13ea32a6a9)

7. Haz clic en `New client secret` y agrega la información requerida

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_7.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=ede6d89d5c968411e21a1eecd09635cd)

8. Copia el `Value` del secreto del cliente.

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_8.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=8a216df83330c7711de9f9dd0a1e164f)

9. Verifica que el permiso `User.read` esté concedido. Haz clic en `API Permissions` en el menú izquierdo. Deberías verlo allí por defecto. En caso de que falte, concédelo.

![image.png](https://mintcdn.com/zylon/bIRZmoPdFWuTOEQj/images/operator-manual/openid-images/microsoft/image_9.png?fit=max\&auto=format\&n=bIRZmoPdFWuTOEQj\&q=85\&s=d59e4c567215bb167d30d6bc5ce888d0)

10. Agrega la siguiente configuración a `/etc/zylon/zylon-conf.yaml`

El archivo de configuración es un archivo `.yaml` por lo que la sangría, espacios, punto y coma, comillas dobles son muy importantes

```yaml theme={null}
auth:
  microsoft:
    enabled: true
    redirectUri: "https://zylon.company.com/api/v1/auth/microsoft/callback"
    tenantId: "common"
    clientId: "8c7d......"
    clientSecret: ".RS8Q~....."
```

Ejecuta el siguiente comando para actualizar la configuración

```yaml theme={null}
sudo zylon-cli update
```

Ahora deberías ver el SSO de Microsoft Account

> [!TIP]
>
> En caso de que no veas el botón de Microsoft Account para iniciar sesión, limpia la caché del navegador.

### Cómo gestionar usuarios

Para limitar el número de usuarios que pueden iniciar sesión en Zylon, consulta el siguiente enlace, por defecto todos en el Directorio pueden acceder a Zylon y se les otorgará el rol `member`

[https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/what-is-access-management](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/what-is-access-management)


# Copias de seguridad y recuperación ante desastres
Source: https://docs.zylon.ai/es/v1.58/operator-manual/operations/backup



Zylon está preparado para ser completamente respaldado y restaurado en caso de fallo de hardware o situaciones de recuperación ante desastres.

Hay múltiples formas de abordar el problema: una copia completa del disco y una solución basada en Velero.

## Copia de seguridad completa del disco

Dado que la mayoría de las instalaciones de Zylon se ejecutan en un solo nodo, es perfectamente válido hacer una copia de seguridad completa tradicional del disco con una herramienta como Clonezilla o similar.

Almacena la imagen en un almacenamiento en frío y en caso de recuperación simplemente reemplaza el contenido del disco. Zylon debería volver al momento en el tiempo en que se tomó la instantánea.

Ten en cuenta que esto solo es posible si Zylon se está ejecutando en un solo nodo de kubernetes; las configuraciones de múltiples nodos DEBEN usar Velero como estrategia de respaldo.

## Copia de seguridad de datos usando zylon-cli

### Comando de copia de seguridad:

`sudo zylon-cli backup [--keep-last N]`

Tomará una instantánea de los datos de Zylon y la guardará en la máquina local.

### Comando de restauración:

`sudo zylon-cli restore [--backup-file path-to-backup]`

Restaurará el estado de Zylon al momento en el tiempo en que se tomó la instantánea. Por defecto, se usará la última copia de seguridad, pero también se puede especificar una instantánea determinada.

Estas copias de seguridad básicas tomarán una instantánea del estado de Zylon y guardarán el contenido como un .tar.gz en la carpeta `/var/backups/zylon` con la fecha de la copia de seguridad como nombre de archivo.

Deberías considerar copiar los archivos de copia de seguridad a una máquina diferente en caso de fallo del disco.

Por defecto, solo se conservan las últimas 10 copias de seguridad.

**Durante el proceso de copia de seguridad, Zylon estará fuera de línea.** Dependiendo de la cantidad de documentos que hayas cargado, este proceso puede tomar varios minutos.

### Cómo se detiene Zylon durante la copia de seguridad y la restauración

Antes de copiar o reemplazar datos, `zylon-cli backup` y `zylon-cli restore` acordonan (cordon) y drenan (drain) el nodo para que todos los pods de Zylon se detengan de forma ordenada. Solo entonces se detiene k0s. Cuando termina la copia o la restauración de los datos, k0s se vuelve a iniciar y se quita el acordonamiento del nodo (uncordon), de modo que los pods se vuelven a programar automáticamente.

* El drenado suele tardar entre uno y dos minutos.
* Cuando el comando termina, Zylon todavía necesita unos minutos más para estar completamente disponible, sobre todo mientras se cargan los modelos de IA. Puedes comprobar el progreso con `sudo k0s kubectl get pods -n zylon`.

> [!WARNING]
>
> Si una copia de seguridad o una restauración se interrumpe (por ejemplo, si se mata el proceso o se cae la sesión SSH), el nodo puede quedar acordonado. En ese caso los pods de Zylon permanecen en `Pending` y Zylon sigue fuera de línea, incluso después de reiniciar. Para recuperar Zylon, quita el acordonamiento del nodo:
>
> ```bash theme={null}
> sudo k0s kubectl uncordon $(sudo k0s kubectl get nodes -o name)
> ```

### Poner las copias de seguridad en programación

Puedes agregar estas copias de seguridad en una programación automáticamente, ejecuta `sudo crontab -e` para abrir el editor de cron y agrega la copia de seguridad como

Por ejemplo, esta copia de seguridad se realizará todos los sábados a las 4am

```jsx theme={null}

0 4 * * 6 sudo zylon-cli backup --keep-last 5 -y >> /var/log/zylon-backup.log 2>&1
```

## Velero

[Velero](https://velero.io/) es la forma estándar de hacer copias de seguridad de clústeres de kubernetes. Permite automatización y solo respalda la información requerida del clúster y la aplicación.

> Ten en cuenta que en caso de fallo del disco, una copia de seguridad de Velero no restaurará el clúster, los controladores Nvidia y otras herramientas requeridas para ejecutar Zylon. Para recuperarse de ese escenario, realiza una configuración regular de Zylon seguida del proceso de restauración de la copia de seguridad.Para habilitar las copias de seguridad de Velero **debes:**

### 1. Instalar Velero CLI

```bash theme={null}
https://velero.io/docs/v1.3.0/velero-install/
```

Después de que el comando tenga éxito, el binario `velero` debería estar disponible en tu ruta.

### 2. Proporcionar una solución de almacenamiento de objetos válida.

Este es el almacenamiento donde se almacenarán las copias de seguridad y idealmente debería ser una máquina completamente separada.

Una lista de proveedores comunes son:

* AWS s3
* Google Cloud Storage
* Azure Blob storage
* Un servidor minio autohospedado
* Lista completa de proveedores aquí: [https://velero.io/docs/v1.15/supported-providers/](https://velero.io/docs/v1.15/supported-providers/)

Una copia de seguridad inicial de Zylon tomará un mínimo de 20GB de almacenamiento y crecerá a medida que cargues documentos y generes más datos.

Consulta las `instrucciones de configuración` para tu proveedor elegido en la tabla [https://velero.io/docs/v1.15/supported-providers/](https://velero.io/docs/v1.15/supported-providers/).

Es posible que necesites seguir varios pasos como crear un usuario de AWS en caso de s3, configurar algunos permisos y así sucesivamente. Si necesitas orientación durante el proceso, contacta al equipo de Zylon.

### 3. Instalar Velero en el clúster de kubernetes de Zylon

Velero CLI se encargará de *la mayor parte* del trabajo para habilitar las copias de seguridad dentro del clúster. Sin embargo, para hacer una copia de seguridad adecuada de Zylon usando Velero, se DEBEN pasar varias banderas durante la instalación, en particular estas banderas son obligatorias:

```bash theme={null}
--features=EnableCSI
--use-node-agent
```

Por ejemplo, una instalación de Velero que usa AWS S3 como almacenamiento tendrá un archivo de configuración ubicado en `/etc/zylon/velero.txt` con el contenido:

```bash theme={null}
[default]
aws_access_key_id = AKIA5...
aws_secret_access_key = kuBsP9dc0...
```

Entonces Velero se instalará con el siguiente comando:

```bash theme={null}
velero install --provider aws \
		--bucket backup \
		--secret-file /etc/zylon/velero.txt \
		--plugins velero/velero-plugin-for-aws:v1.10.0 \
		--backup-location-config region=us-east-1 \
		--use-volume-snapshots=true \
		--features=EnableCSI \
    --use-node-agent \
		--snapshot-location-config region=us-east-1,s3ForcePathStyle="true"
```

El proceso es ligeramente diferente para cada proveedor, asegúrate de estar seleccionando el plugin de velero correcto, las credenciales adecuadas y que se pasen las banderas obligatorias requeridas por Zylon.

### 4. Parchear Velero para k0s

Zylon usa k0s internamente como un clúster de kubernetes. Velero necesita un pequeño parche para habilitar las copias de seguridad. Ejecuta el siguiente comando para que Velero pueda descubrir todos los pods que necesitan ser respaldados:

```bash theme={null}
kubectl patch daemonset node-agent \
		--namespace velero --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/volumes/0/hostPath/path", "value": "/var/lib/k0s/kubelet/pods"}]'
```

### 5. Crear una copia de seguridad del namespace de Zylon

La creación del proceso de copia de seguridad también requiere banderas obligatorias, en este caso, se DEBEN pasar las siguientes banderas

```bash theme={null}
--include-namespaces zylon 
--default-volumes-to-fs-backup
```

Por ejemplo, configurar una copia de seguridad inicial podría hacerse ejecutando:

```bash theme={null}
velero backup create my-first-backup --include-namespaces zylon --default-volumes-to-fs-backup
```

Hay muchas estrategias de copia de seguridad y restauración que van más allá del alcance de este manual, para más información sobre ellas consulta la documentación oficial: [https://velero.io/docs/v1.15/](https://velero.io/docs/v1.15/)


# Almacenar los datos de Zylon en un disco separado
Source: https://docs.zylon.ai/es/v1.58/operator-manual/operations/data-disk

Mueve el directorio de datos de Zylon a un disco o partición dedicada para obtener capacidad de almacenamiento adicional.

Zylon almacena sus datos de aplicación en `/var/zylon`. Por defecto, este directorio reside en el mismo disco que el sistema operativo. A medida que tu despliegue crece, puede que necesites mover esos datos a un disco más grande o dedicado.

Esta guía explica cómo reubicar los datos de Zylon en un disco o partición separada sin reinstalar la plataforma.

## Cuándo usar esta guía

Usa este procedimiento cuando:

* El disco del sistema operativo se está quedando sin espacio pero tienes un disco adicional disponible.
* Quieres aislar los datos de Zylon en almacenamiento dedicado por razones de rendimiento u operativas.
* Estás preparando el servidor para un cambio en la disposición del almacenamiento (por ejemplo, antes de activar el [cifrado de disco](/es/v1.58/operator-manual/instance-hardening/disk-encryption)).

## Qué se mueve

El estado persistente de Zylon se almacena en `/var/zylon`, incluyendo:

* Documentos cargados y contenido de la base de conocimiento
* Bases de datos
* Dependencias (controladores, binarios), almacenadas en `artifacts`
* Modelos de IA
* Volúmenes persistentes de Kubernetes gestionados por Zylon

Puedes elegir qué directorios bajo `/var/zylon` mover según lo que esté consumiendo más espacio en tu servidor. El mismo enfoque de bind mount funciona para cualquier ruta de la lista anterior.

> [!WARNING]
>
> **Haz una copia de seguridad antes de empezar.** Esta es una operación de alto riesgo; es posible perder datos si algo sale mal.
>
> Crea una copia de seguridad y verifica que puedes restaurarla antes de continuar:
>
> ```bash theme={null}
> sudo zylon-cli backup
> ```
>
> Copia el archivo de copia de seguridad resultante a una ubicación externa segura y confirma que puedes acceder a él.
> Consulta la [guía de copias de seguridad](/es/v1.58/operator-manual/operations/backup) para más detalles.

***

## Resumen

Este procedimiento mueve directorios de datos seleccionados a un disco dedicado mientras el resto de `/var/zylon` permanece en el volumen del sistema operativo. Zylon sigue usando las mismas rutas (por ejemplo, `/var/zylon/artifacts` y `/var/zylon/ai-models`). Los **bind mounts** en `/etc/fstab` redirigen esas rutas al nuevo disco, por lo que no se requieren cambios en la configuración de la aplicación.

A alto nivel, harás lo siguiente:

1. **Identificar el disco objetivo**: encontrar un disco o partición sin usar con espacio suficiente para los datos actuales y futuros.
2. **Preparar el disco**: particionarlo (si es necesario), formatearlo con ext4 y montarlo en `/mnt/data`.
3. **Detener Zylon**: apagar el clúster de Kubernetes con `sudo k0s stop` para que ningún proceso esté usando los archivos durante la copia.
4. **Migrar los datos**: copiar los directorios elegidos desde `/var/zylon` al nuevo disco.
5. **Configurar los bind mounts**: añadir entradas en `/etc/fstab` para que las rutas del nuevo disco se monten de vuelta en sus ubicaciones originales bajo `/var/zylon` en cada arranque.
6. **Iniciar Zylon y verificar**: levantar el clúster de nuevo y confirmar que Zylon funciona correctamente.
7. **Eliminar los datos antiguos**: una vez verificado, borrar las copias originales del disco del sistema operativo y volver a montar los bind mounts.

> [!NOTE]
>
> **Habrá tiempo de inactividad durante la migración.** Zylon debe estar detenido mientras se copian los datos y se reconfiguran los montajes. La duración depende de la cantidad de datos que estés moviendo.

***

## Paso 1: Identificar el disco objetivo

Ejecuta `lsblk` para ver qué discos están conectados al servidor. Necesitas un dispositivo que no esté en uso (sin puntos de montaje listados) y con espacio suficiente para tus datos de Zylon:

```bash theme={null}
lsblk
```

En nuestro ejemplo, la salida se ve así:

```
NAME         MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
loop0          7:0    0  27.6M  1 loop /snap/amazon-ssm-agent/11797
loop1          7:1    0  28.2M  1 loop /snap/amazon-ssm-agent/13009
loop2          7:2    0  73.9M  1 loop /snap/core22/2045
loop3          7:3    0    74M  1 loop /snap/core22/2411
loop4          7:4    0  49.3M  1 loop /snap/snapd/24792
loop5          7:5    0  49.3M  1 loop /snap/snapd/26865
nvme1n1      259:0    0   300G  0 disk /
nvme0n1      259:1    0   300G  0 disk 
```

En este ejemplo, usamos `nvme0n1` como objetivo. Reemplaza `/dev/nvme0n1` con tu dispositivo real en todos los comandos siguientes.

***

## Paso 2: Preparar el disco objetivo

Crea un punto de montaje y configura el disco objetivo para que se monte automáticamente al arrancar. Si el disco ya está particionado y formateado, omite los comandos de particionado y formateo siguientes y pasa directamente a crear el punto de montaje.

> [!WARNING]
>
> Particionar y formatear **borran todos los datos** del disco objetivo. Solo ejecuta estos comandos en un disco vacío, o cuando estés seguro de que el dispositivo no contiene datos que necesites conservar. Verifica que has seleccionado el dispositivo correcto antes de continuar.

Si el disco aún no está particionado y formateado, ejecuta lo siguiente para configurarlo con ext4:

```bash theme={null}
sudo parted /dev/nvme0n1 mklabel gpt
sudo parted /dev/nvme0n1 mkpart primary 0% 100%
sudo mkfs.ext4 /dev/nvme0n1
```

Crea el punto de montaje en el nuevo disco:

```bash theme={null}
sudo mkdir -p /mnt/data
```

Obtén el UUID del disco para que el montaje persista tras los reinicios:

```bash theme={null}
sudo blkid /dev/nvme0n1
```

La salida será similar a:

```
/dev/nvme0n1: UUID="2c2f893d-6ce5-4eb5-8e0a-3b85b4894814" BLOCK_SIZE="4096" TYPE="ext4"
```

Añade una entrada en `/etc/fstab` usando tu UUID (reemplaza el valor siguiente con el de tu salida):

```bash theme={null}
echo 'UUID=2c2f893d-6ce5-4eb5-8e0a-3b85b4894814  /mnt/data  ext4  defaults  0  2' | sudo tee -a /etc/fstab
```

Recarga systemd y monta el disco:

```bash theme={null}
sudo systemctl daemon-reload
sudo mount -a
```

Confirma que el disco está montado:

```bash theme={null}
df -h /mnt/data
```

***

## Paso 3: Detener Zylon

Detén el clúster de Kubernetes para que ningún proceso esté leyendo o escribiendo en los directorios que vas a migrar:

```bash theme={null}
sudo k0s stop
```

Espera a que el comando termine antes de continuar.

***

## Paso 4: Migrar los datos al nuevo disco

Puedes decidir qué directorios bajo `/var/zylon` mover al nuevo disco. Elige las rutas que estén usando más espacio o que quieras mantener separadas del volumen del sistema operativo. En este ejemplo, movemos las dependencias de Zylon y los modelos de IA. Las dependencias se almacenan en el directorio `artifacts`.

```bash theme={null}
sudo cp -a /var/zylon/artifacts/. /mnt/data/zylon/artifacts/
sudo cp -a /var/zylon/ai-models/. /mnt/data/zylon/ai-models/
```

Verifica que la copia se completó y que los tamaños son razonables:

```bash theme={null}
du -sh /var/zylon/artifacts /mnt/data/zylon/artifacts
du -sh /var/zylon/ai-models /mnt/data/zylon/ai-models
```

Los tamaños en el origen y el destino deben coincidir.

***

## Paso 5: Apuntar Zylon a la nueva ubicación

Añade entradas de bind mount en `/etc/fstab`. Esto hace que Linux presente los datos del nuevo disco en las rutas originales que Zylon espera:

```bash theme={null}
echo '/mnt/data/zylon/artifacts /var/zylon/artifacts none bind 0 0' | sudo tee -a /etc/fstab
echo '/mnt/data/zylon/ai-models  /var/zylon/ai-models none bind 0 0' | sudo tee -a /etc/fstab
sudo systemctl daemon-reload
sudo mount -a
```

Confirma que ambos bind mounts están activos:

```bash theme={null}
sudo findmnt /var/zylon/artifacts
sudo findmnt /var/zylon/ai-models
```

Cada comando debe mostrar que el origen del montaje apunta a `/mnt/data/zylon/...`.

***

## Paso 6: Iniciar Zylon y verificar

Inicia el clúster y confirma que Zylon funciona con normalidad:

```bash theme={null}
sudo k0s start
```

Inicia sesión en el workspace y ejecuta una consulta que use modelos de IA para confirmar que ambos directorios se sirven desde el nuevo disco.

***

## Paso 7: Eliminar los datos antiguos

Una vez verificado que Zylon funciona correctamente, elimina las copias originales del disco del sistema operativo para recuperar espacio. Este paso requiere detener Zylon de nuevo y desmontar temporalmente los bind mounts.

Detén Zylon:

```bash theme={null}
sudo k0s stop
```

Desmonta los bind mounts (esto no afecta los datos en `/mnt/data`):

```bash theme={null}
sudo umount /var/zylon/ai-models
sudo umount /var/zylon/artifacts
```

Confirma que ya no están montados:

```bash theme={null}
sudo findmnt /var/zylon/ai-models
sudo findmnt /var/zylon/artifacts
```

Ambos comandos no deben devolver resultados.

Elimina los datos antiguos y recrea los directorios vacíos que servirán como puntos de montaje:

```bash theme={null}
sudo rm -rf /var/zylon/ai-models
sudo rm -rf /var/zylon/artifacts
sudo mkdir /var/zylon/ai-models
sudo mkdir /var/zylon/artifacts
```

Vuelve a aplicar los bind mounts desde `/etc/fstab`:

```bash theme={null}
sudo mount -a
```

Confirma que los bind mounts están de vuelta:

```bash theme={null}
sudo findmnt /var/zylon/ai-models
sudo findmnt /var/zylon/artifacts
```

Inicia Zylon:

```bash theme={null}
sudo k0s start
```


# Panel de Administración del Sistema
Source: https://docs.zylon.ai/es/v1.58/operator-manual/operations/sys-admin-dashboard

Monitorea y gestiona la salud del sistema, el rendimiento y las actividades de los usuarios con el Panel de Administración del Sistema.

Zylon viene con un [Kubernetes Dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/) integrado,
que te ayudará a monitorear y diagnosticar problemas con tu instalación.

Para habilitarlo, necesitarás editar tu archivo de configuración en `/etc/zylon/zylon-conf.yaml` y agregar la siguiente sección:

```yaml theme={null}
adminDashboard:
  enabled: true
  exposeIngress: true
```

A continuación, actualiza tu sistema Zylon ejecutando:

```bash theme={null}
sudo zylon-cli sync
```

Una vez que se complete la actualización, accede al panel en:
`https://<zylon.company.com>/kube-dashboard`

Para iniciar sesión, puedes generar un token de corta duración:

```bash theme={null}
kubectl -n zylon create token zylon
```

O un token permanente:

```bash theme={null}
kubectl get secret zylon-token -n zylon -o jsonpath='{.data.token}' | base64 -d
```

> [!WARNING]
>
> El token permanente proporcionará acceso completo de administrador a tu clúster de Kubernetes.
> Manténlo secreto y seguro.

> [!TIP]
>
> Zylon usa múltiples namespaces, puedes verificar el estado de cada uno.
> Selecciona el namespace correcto del menú desplegable en la esquina superior izquierda.
>
> * zylon: Componentes del sistema Zylon
> * openebs: Sistema de almacenamiento OpenEBS
> * nvidia: Controlador NVIDIA y plugin de dispositivo

Después de iniciar sesión, podrás ver el estado de tu instalación de Zylon, incluyendo:

* Pods
* Logs
* Métricas básicas sobre el uso de CPU y memoria

## Preguntas frecuentes

### ❓ ¿Por dónde empiezo cuando algo no funciona?

Cuando abres el panel de Kubernetes por primera vez, verás una vista general del estado de tus cargas de trabajo y del clúster.
Esta vista muestra el estado actual de los recursos en ejecución, como Pods, Deployments y el uso básico de CPU y memoria.

![image](https://mintcdn.com/zylon/J25J8IDOgVs0UO0R/images/operator-manual/k8s-1.png?fit=max\&auto=format\&n=J25J8IDOgVs0UO0R\&q=85\&s=8543483645ef100b8e69e3a81ad4d43f)

***

### ❓ ¿Qué namespace debo seleccionar?

Zylon utiliza varios namespaces, pero la mayoría de los problemas relacionados con workspaces y la plataforma estarán en el namespace `zylon`.

1. Abre el desplegable de namespaces en la **esquina superior izquierda** del dashboard
2. Selecciona el namespace que quieras revisar
3. El dashboard se actualizará y mostrará únicamente los componentes del sistema de ese namespace

Esto ayuda a reducir el ruido y asegura que estás inspeccionando los recursos correctos.

## ![image](https://mintcdn.com/zylon/J25J8IDOgVs0UO0R/images/operator-manual/k8s-2.png?fit=max\&auto=format\&n=J25J8IDOgVs0UO0R\&q=85\&s=be279a6ee4b3e58abc6735327f8c4fa1)

### ❓ ¿Cómo puedo ver los logs de un Pod?

Para inspeccionar los logs de un Pod concreto:

1. Haz clic en el **nombre del Pod** que quieres investigar
2. Esto abrirá la página de detalles del Pod, donde podrás ver:

* Estado
* Eventos
* Uso de recursos
* Contenedores

3. En la **esquina superior derecha**, haz clic en **Logs**

![image](https://mintcdn.com/zylon/J25J8IDOgVs0UO0R/images/operator-manual/k8s-3.png?fit=max\&auto=format\&n=J25J8IDOgVs0UO0R\&q=85\&s=35af643efe3276c2b83cc95a86268766)

Desde aquí puedes:

* Ver los logs en tiempo real
* Descargar los logs para analizarlos offline si tu instancia está en modo *airgap*

Los logs suelen ser la forma más rápida de identificar errores de configuración, fallos durante el arranque o problemas en tiempo de ejecución.


# Autenticación para acciones sensibles
Source: https://docs.zylon.ai/es/v1.58/operator-manual/security/authentication-for-sensitive-actions

Referencia de compliance para las acciones protegidas por la vigencia de autenticación.

Zylon puede exigir una autenticación reciente antes de que un principal realice una acción sensible del espacio de trabajo o del backoffice. Este control añade un requisito de reautenticación limitado en el tiempo a las comprobaciones existentes de permisos y autorización.

> [!WARNING]
>
> La vigencia de autenticación no se aplica a las peticiones a la API autenticadas con tokens. Las integraciones basadas en tokens no necesitan pasos adicionales de reautenticación ni cambios en sus flujos actuales.

La función puede [activarse y configurarse por nivel de riesgo](/es/v1.58/operator-manual/configuration/features/authentication-freshness). Cuando está activada, la comprobación específica de cada acción solo es válida durante el periodo de vigencia configurado. Los periodos bajo, medio y alto son independientes.

## Acciones protegidas

La siguiente tabla refleja los puntos actuales del backend que llaman a `assertPrincipalAuthChallengeIsValid`. Es una referencia basada en el código y debe revisarse después de cualquier cambio en las rutas de autorización sensibles.

| Área | Acción protegida | Método backend | Nivel de riesgo |
| - | - | - | - |
| Organización | Crear una organización | `createOrganization` | Medio |
| Organización | Eliminar una organización, incluido su contenido | `deleteOrganization` | Alto |
| Organización | Actualizar la configuración de una organización | `updateOrganization` | Bajo |
| Gateway | Crear un gateway | `createGateway` | Alto |
| Gateway | Eliminar un gateway | `deleteGateway` | Alto |
| Usuarios de gateway | Añadir un usuario a un gateway | `addUserToGateway` | Medio |
| Usuarios de gateway | Cambiar el rol de un usuario de gateway | `updateUserRole` | Medio |
| Usuarios de gateway | Activar un usuario de gateway | `setGatewayUserState` | Bajo |
| Usuarios de gateway | Desactivar un usuario de gateway | `setGatewayUserState` | Alto |
| Usuarios de gateway | Eliminar un usuario de un gateway | `removeGatewayUser` | Medio |
| Proyecto | Transferir la propiedad de un proyecto | `transferProjectOwnership` | Medio |
| Proyecto | Actualizar la configuración de un proyecto | `updateProject` | Bajo |
| Proyecto | Añadir miembros a un proyecto | `addMembersToProject` | Medio |
| Proyecto | Actualizar los roles de miembros de un proyecto | `updateMemberRoles` | Medio |
| Proyecto | Eliminar un miembro de un proyecto | `removeMemberFromProject` | Medio |
| Proyecto | Borrado lógico de un proyecto | `deleteProject` | Alto |
| Proyecto | Borrado permanente de un proyecto | `hardDeleteProject` | Alto |
| Tokens de API | Crear un token de API | `createApiToken` | Alto |
| Tokens de API | Eliminar un token de API | `deleteTokenByHash` | Alto |
| Artefactos | Crear artefactos de tipo conector | `createArtifact` | Bajo |
| Artefactos | Eliminar artefactos | `deleteArtifactsById` | Alto |
| Artefactos | Eliminar un documento ingerido y su entidad | `scheduleDeleteVectorsAndEntity` | Alto |
| Usuarios | Cambiar el rol de un usuario | `updateUser` | Medio al mantener o reducir privilegios; alto al conceder un rol superior |
| Usuarios | Añadir un usuario a una organización | `addUserToOrganization` | Alto |
| Usuarios | Activar un usuario | `setUserState` | Alto |
| Usuarios | Desactivar un usuario | `setUserState` | Medio |
| Cuentas | Activar una cuenta | `updateAccount` | Alto |
| Cuentas | Desactivar una cuenta | `updateAccount` | Bajo |

Los principales autenticados con tokens están exentos de esta comprobación por diseño. Esto no omite las comprobaciones normales de permisos, ámbitos u ownership del endpoint.

## Métodos de autenticación y gestión de fallos

Para los usuarios interactivos, el frontend puede responder al desafío de autenticación mediante la contraseña configurada o el flujo SSO disponible. Si no existe un desafío válido o este ha caducado, la acción protegida no continúa hasta que el usuario vuelve a autenticarse. Google y Microsoft SSO pueden redirigir el navegador fuera de la petición original; los operadores deben contemplar que el usuario tenga que repetir la acción al volver.

Para conocer la configuración y los periodos de vigencia exactos, consulta [Vigencia de autenticación](/es/v1.58/operator-manual/configuration/features/authentication-freshness).


# Rendimiento de Inferencia de IA
Source: https://docs.zylon.ai/es/v1.58/operator-manual/troubleshooting/ai

Guía de resolución de problemas para diagnosticar y mejorar el rendimiento de inferencia de IA en Zylon.

## Rendimiento Lento de Inferencia

Cuando experimentes tiempos de inferencia lentos, primero establece una línea base de rendimiento.
Utiliza la [Calculadora de VRAM](https://apxml.com/tools/vram-calculator) para determinar el throughput esperado de tu GPU y compáralo con las [especificaciones de tu modelo](/es/v1.58/operator-manual/ai-presets/presets).

Zylon proporciona un script de benchmarking que simula solicitudes de inferencia concurrentes para medir el Time To First Token (TTFT), latencia y throughput. Esto puede ayudar a identificar si el rendimiento está por debajo de las expectativas y si se degrada bajo carga.

> [!NOTE]
>
> Zylon asigna recursos de cómputo para mantener tiempos de respuesta consistentes bajo carga concurrente (8-10 usuarios simultáneos). Esto significa que los benchmarks de inferencia única pueden mostrar tokens/s más bajos que el máximo teórico del hardware, pero el rendimiento en el mundo real con múltiples usuarios cumplirá o superará las expectativas.

```python theme={null}
import asyncio
import json
import random
import time
from dataclasses import dataclass
from typing import Optional

BASE_URL = "https://<host>/api/gpt"
BEARER_TOKEN = "your_token_here"
MODEL = "qwen-3-5-35b-a3b"
MAX_TOKENS = 4096
PROMPT = "Write a paragraph about artificial intelligence."
CONCURRENCY_LEVELS = [1, 4, 8, 16, 32]
DEBUG = False
JITTER_MAX_MS = 200


@dataclass
class RequestResult:
    success: bool
    ttft: Optional[float] = None
    latency: float = 0.0
    generation_time: float = 0.0
    tokens: int = 0
    throughput: float = 0.0
    error: Optional[str] = None


@dataclass
class BenchmarkStatistics:
    success_rate: float
    avg_ttft: float
    avg_latency: float
    avg_generation_time: float
    avg_throughput: float
    p50_ttft: float
    p95_ttft: float
    p99_ttft: float


@dataclass
class ConnectionConfig:
    host: str
    port: int
    use_ssl: bool
    path: str


def debug_log(message: str, force: bool = False) -> None:
    if DEBUG or force:
        timestamp = time.strftime("%H:%M:%S", time.localtime())
        print(f"[DEBUG {timestamp}] {message}")


def parse_url(url: str) -> ConnectionConfig:
    use_ssl = url.startswith("https")
    host_and_path = url.split("//")[1]
    parts = host_and_path.split("/", 1)
    host = parts[0]
    path = "/" + parts[1] if len(parts) > 1 else "/"
    port = 443 if use_ssl else 80

    return ConnectionConfig(host=host, port=port, use_ssl=use_ssl, path=path)


def build_http_request(
    config: ConnectionConfig, payload: dict[str, object], bearer_token: str
) -> bytes:
    path = config.path + "/v1/messages"
    body = json.dumps(payload)

    request_lines = [
        f"POST {path} HTTP/1.1",
        f"Host: {config.host}",
        "Content-Type: application/json",
        f"Authorization: Bearer {bearer_token}",
        f"Content-Length: {len(body)}",
        "Connection: close",
        "",
        body,
    ]

    return "\r\n".join(request_lines).encode()


async def read_stream_response(
    reader: asyncio.StreamReader, session_id: int, start_time: float
) -> tuple[Optional[float], Optional[float], int, int]:
    ttft: Optional[float] = None
    content_block_stop_time: Optional[float] = None
    output_tokens = 0
    event_count = 0
    headers_done = False
    buffer = b""

    while True:
        chunk = await reader.read(8192)
        if not chunk:
            break

        buffer += chunk

        if not headers_done:
            if b"\r\n\r\n" in buffer:
                headers_done = True
                buffer = buffer.split(b"\r\n\r\n", 1)[1]

        if headers_done:
            lines = buffer.split(b"\n")
            buffer = lines[-1]

            for line in lines[:-1]:
                line_str = line.decode("utf-8").strip()

                if not line_str or not line_str.startswith("data: "):
                    continue

                data_str = line_str[6:]
                if data_str == "[DONE]":
                    debug_log(f"Session {session_id}: Stream complete")
                    continue

                try:
                    event = json.loads(data_str)
                    event_count += 1

                    if ttft is None and event.get("type") == "content_block_delta":
                        ttft = time.perf_counter() - start_time
                        debug_log(f"Session {session_id}: TTFT = {ttft:.3f}s")

                    if event.get("type") == "content_block_stop":
                        content_block_stop_time = time.perf_counter()
                        debug_log(
                            f"Session {session_id}: Content block stopped at {content_block_stop_time - start_time:.3f}s"
                        )

                    if event.get("type") == "message_delta":
                        usage = event.get("usage", {})
                        output_tokens = usage.get("output_tokens", 0)
                        debug_log(
                            f"Session {session_id}: Received usage data - {output_tokens} tokens"
                        )

                except json.JSONDecodeError as e:
                    debug_log(f"Session {session_id}: JSON decode error - {e}")
                    continue

    return ttft, content_block_stop_time, output_tokens, event_count


async def make_request(session_id: int) -> RequestResult:
    jitter = random.randint(0, JITTER_MAX_MS) / 1000.0
    debug_log(f"Session {session_id}: Waiting {jitter:.3f}s before starting")
    await asyncio.sleep(jitter)

    debug_log(f"Session {session_id}: Starting request")

    payload: dict[str, object] = {
        "model": MODEL,
        "max_tokens": MAX_TOKENS,
        "messages": [{"role": "user", "content": PROMPT}],
        "stream": True,
        "correlation_id": f"session-{session_id}",
    }

    start_time = time.perf_counter()

    try:
        debug_log(f"Session {session_id}: Opening connection")

        config = parse_url(BASE_URL)
        reader, writer = await asyncio.open_connection(
            config.host, config.port, ssl=config.use_ssl
        )

        request_bytes = build_http_request(config, payload, BEARER_TOKEN)
        writer.write(request_bytes)
        await writer.drain()

        debug_log(f"Session {session_id}: Connection established")

        ttft, content_block_stop_time, output_tokens, event_count = (
            await read_stream_response(reader, session_id, start_time)
        )

        writer.close()
        await writer.wait_closed()

        end_time = time.perf_counter()
        total_latency = end_time - start_time

        generation_time = 0.0
        throughput = 0.0
        if ttft is not None and content_block_stop_time is not None:
            generation_time = content_block_stop_time - (start_time + ttft)
            if generation_time > 0:
                throughput = output_tokens / generation_time

        debug_log(
            f"Session {session_id}: Completed - "
            f"Latency: {total_latency:.3f}s, "
            f"Generation: {generation_time:.3f}s, "
            f"Tokens: {output_tokens}, "
            f"Events: {event_count}, "
            f"Throughput: {throughput:.2f} tok/s"
        )

        return RequestResult(
            success=True,
            ttft=ttft,
            latency=total_latency,
            generation_time=generation_time,
            tokens=output_tokens,
            throughput=throughput,
        )

    except Exception as e:
        debug_log(f"Session {session_id}: Error - {type(e).__name__}: {e}")
        return RequestResult(success=False, error=str(e))


async def run_concurrent_requests(num_users: int) -> list[RequestResult]:
    debug_log(f"Starting {num_users} concurrent requests")
    tasks = [make_request(i) for i in range(num_users)]
    results = await asyncio.gather(*tasks)
    debug_log(f"All {num_users} requests completed")
    return list(results)


def calculate_percentile(data: list[float], p: float) -> float:
    if not data:
        return 0.0
    k = (len(data) - 1) * p
    f = int(k)
    c = f + 1
    if c >= len(data):
        return data[f]
    return data[f] + (k - f) * (data[c] - data[f])


def calculate_statistics(results: list[RequestResult]) -> BenchmarkStatistics:
    successful = [r for r in results if r.success]
    debug_log(
        f"Calculating statistics for {len(successful)}/{len(results)} successful requests"
    )

    if not successful:
        debug_log("No successful requests to calculate statistics")
        return BenchmarkStatistics(
            success_rate=0.0,
            avg_ttft=0.0,
            avg_latency=0.0,
            avg_generation_time=0.0,
            avg_throughput=0.0,
            p50_ttft=0.0,
            p95_ttft=0.0,
            p99_ttft=0.0,
        )

    ttfts = sorted([r.ttft for r in successful if r.ttft is not None])
    latencies = [r.latency for r in successful]
    generation_times = [r.generation_time for r in successful]
    throughputs = [r.throughput for r in successful if r.throughput > 0]

    return BenchmarkStatistics(
        success_rate=len(successful) / len(results),
        avg_ttft=sum(ttfts) / len(ttfts) if ttfts else 0.0,
        avg_latency=sum(latencies) / len(latencies),
        avg_generation_time=sum(generation_times) / len(generation_times)
        if generation_times
        else 0.0,
        avg_throughput=sum(throughputs) / len(throughputs) if throughputs else 0.0,
        p50_ttft=calculate_percentile(ttfts, 0.5) if ttfts else 0.0,
        p95_ttft=calculate_percentile(ttfts, 0.95) if ttfts else 0.0,
        p99_ttft=calculate_percentile(ttfts, 0.99) if ttfts else 0.0,
    )


def print_statistics(concurrency: int, stats: BenchmarkStatistics) -> None:
    print(f"\nTesting with {concurrency} concurrent inferences...")
    print(f"  Success Rate: {stats.success_rate:.2%}")
    print(f"  Avg TTFT: {stats.avg_ttft:.3f}s")
    print(f"  P50 TTFT: {stats.p50_ttft:.3f}s")
    print(f"  P95 TTFT: {stats.p95_ttft:.3f}s")
    print(f"  P99 TTFT: {stats.p99_ttft:.3f}s")
    print(f"  Avg Latency: {stats.avg_latency:.3f}s")
    print(f"  Avg Generation Time: {stats.avg_generation_time:.3f}s")
    print(f"  Avg Throughput: {stats.avg_throughput:.2f} tok/s")


async def benchmark() -> None:
    print(f"Benchmarking API: {BASE_URL}")
    print(f"Model: {MODEL}")
    print(f"Prompt: {PROMPT[:50]}...")
    print("-" * 80)

    for concurrency in CONCURRENCY_LEVELS:
        debug_log(f"Starting concurrency level: {concurrency}")

        results = await run_concurrent_requests(concurrency)
        stats = calculate_statistics(results)
        print_statistics(concurrency, stats)


if __name__ == "__main__":
    asyncio.run(benchmark())
```

Actualiza `BASE_URL`, `BEARER_TOKEN`, y `MODEL` en el script, luego ejecútalo para medir TTFT, throughput y latencia bajo diferentes niveles de concurrencia. Compara tus resultados con el máximo teórico de la calculadora de VRAM para identificar si el rendimiento está por debajo de las expectativas.


# Exportar logs
Source: https://docs.zylon.ai/es/v1.58/operator-manual/troubleshooting/exporting-logs



Esta guía te ayuda a exportar logs precisos para que el equipo de soporte resuelva incidentes más rápido y con menos idas y vueltas. Como Zylon se ejecuta localmente en tu infraestructura y muchas veces en entornos totalmente air‑gap, estos logs son la forma más segura y confiable de entender lo que ocurrió sin acceder directamente a tus datos.

> [!NOTE]
>
> Para enviar continuamente eventos de auditoría y seguridad a tu SIEM, usa [Enviar logs a tu SIEM](/es/v1.58/operator-manual/configuration/features/log-delivery-storage#enviar-logs-a-tu-siem). Esta guía recoge diagnósticos del navegador y servicios para soporte.

## Antes de empezar

1. Abre la app de Zylon en tu navegador.
2. Ve a la pantalla donde ocurre el problema.
3. Mantén esta pestaña abierta mientras sigues los pasos.

## Logs del frontend (respuestas del navegador)

Hay dos formas de compartir los logs del frontend. Puedes enviar un archivo HAR completo o compartir una sola respuesta desde la lista de solicitudes.
Un HAR (HTTP Archive) es un archivo que contiene todas las solicitudes y respuestas de red de una página. Esto puede acelerar la investigación. Si quieres compartir solo una respuesta específica, sigue los pasos de log individual debajo.

### Google Chrome

1. Abre las herramientas de desarrollador.
2. Presiona `F12` en Windows o `Cmd + Option + I` en Mac.
3. Haz clic en la pestaña `Network`.
4. Marca `Preserve log` para que las solicitudes no se borren al recargar.
5. Repite el problema (haz los mismos clics o la misma acción).
6. Para exportar un HAR: haz clic derecho en la lista de solicitudes y elige `Save all as HAR with content`, luego comparte el archivo con soporte.
7. En la lista de solicitudes, haz clic en la que corresponda a la acción que acabas de hacer.
8. En el panel derecho, abre la pestaña `Response`.
9. Haz clic derecho dentro de la respuesta y elige `Copy`.
10. Pega la respuesta en un archivo de texto y compártelo con soporte.

[Zylon Workspace - Exporting web logs on Chrome](https://www.youtube.com/embed/LOiqjMdOCNw)

### Microsoft Edge

1. Abre las herramientas de desarrollador.
2. Presiona `F12` en Windows o `Cmd + Option + I` en Mac.
3. Haz clic en la pestaña `Network`.
4. Marca `Preserve log` para que las solicitudes no se borren al recargar.
5. Repite el problema (haz los mismos clics o la misma acción).
6. Para exportar un HAR: haz clic derecho en la lista de solicitudes y elige `Save all as HAR with content`, luego comparte el archivo con soporte.
7. En la lista de solicitudes, haz clic en la que corresponda a la acción que acabas de hacer.
8. En el panel derecho, abre la pestaña `Response`.
9. Haz clic derecho dentro de la respuesta y elige `Copy`.
10. Pega la respuesta en un archivo de texto y compártelo con soporte.

[Zylon Workspace - Exporting web logs on Edge](https://www.youtube.com/embed/nMErrL50zHQ)

### Mozilla Firefox

1. Abre las herramientas de desarrollador.
2. Presiona `F12` en Windows o `Cmd + Option + I` en Mac.
3. Haz clic en la pestaña `Network`.
4. Repite el problema (haz los mismos clics o la misma acción).
5. Para exportar un HAR: haz clic derecho en la lista de solicitudes y elige `Save All As HAR`, luego comparte el archivo con soporte.
6. En la lista de solicitudes, haz clic en la que corresponda a la acción que acabas de hacer.
7. En el panel derecho, abre la pestaña `Response`.
8. Haz clic derecho dentro de la respuesta y elige `Copy`.
9. Pega la respuesta en un archivo de texto y compártelo con soporte.

[Zylon Workspace - Exporting web logs on Firefox](https://www.youtube.com/embed/notcVPpYBpM)

Si no encuentras la solicitud, prueba estos pasos rápidos.

1. Asegúrate de estar en la pestaña `Network`.
2. Recarga la página y repite la acción.
3. Busca filtros como `Fetch/XHR` y selecciónalos.

## Logs que no son del frontend (backend, servicios de AI y otros pods)

Los logs de problemas que no son del frontend deben obtenerse desde el pod correspondiente (backend, servicios de AI u otros componentes). Puedes revisar tus pods para ubicar el servicio correcto antes de recolectarlos.
Consulta la guía del panel de administración del sistema para ver el estado de pods y servicios: [Guía del panel de administración del sistema](/es/v1.58/operator-manual/operations/sys-admin-dashboard)


# Solución de Problemas de Controladores Nvidia
Source: https://docs.zylon.ai/es/v1.58/operator-manual/troubleshooting/nvidia-drivers



Esta sección de solución de problemas proporciona soluciones a problemas comunes encontrados con los controladores Nvidia en instalaciones de Zylon.

### Por qué podrías encontrar problemas con los controladores Nvidia

Para proporcionar las últimas capacidades de GPU para Zylon generalmente requerimos las últimas versiones de los controladores Nvidia instalados, lo que significa que deben compilarse bajo demanda para tu versión específica del kernel que tu hardware está ejecutando.

Al mismo tiempo, los controladores Nvidia de código abierto todavía están en desarrollo activo y a veces pueden surgir problemas durante la instalación o el tiempo de ejecución.

En particular, durante las actualizaciones del kernel o cambios en la configuración del sistema, los controladores Nvidia pueden dejar de funcionar correctamente, fallando al detectar la GPU o causando que los servicios de IA funcionen mal debido a discrepancias en el uso de memoria.

Aquí hay algunas formas comunes de diagnosticar si ese es el caso y cómo solucionarlo.

### 1 - Verificar la página de Estado de Zylon

Navega a la página de Estado de Zylon en `https://<your_zylon_domain>/status`. Verifica si hay algún error en la sección de Servicio de IA y en particular `zylon-triton`.

Si el servicio no está en línea, continúa con los siguientes pasos para diagnosticar el problema.

Si el sistema está en línea pero Zylon sigue fallando, la fuente es muy probablemente un problema a nivel de aplicación, por favor contacta al soporte de Zylon.

Si no puedes acceder a la página de estado, salta al paso 2.

### 2 - Verificar el Estado del Controlador Nvidia

Verifica la salida de `nvidia-smi`:

```bash theme={null}
nvidia-smi

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 575.51.03              Driver Version: 575.51.03      CUDA Version: 12.9     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA L40S                    Off |   00000000:30:00.0 Off |                    0 |
| N/A   38C    P0            104W /  350W |   40673MiB /  46068MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|    0   N/A  N/A           18592      C   tritonserver                            490MiB |
|    0   N/A  N/A           23968      C   VLLM::EngineCore                      38968MiB |
|    0   N/A  N/A           26834      C   VLLM::EngineCore                       1196MiB |
+-----------------------------------------------------------------------------------------+
```

Debería reportar el estado de la GPU, junto con el proceso que la está usando.

#### 2.1 - Controladores no funcionando: nvidia-smi no puede comunicarse con el controlador NVIDIA

Este es el error más común, generalmente causado por una actualización del kernel durante una actualización desatendida. La solución requiere

Ejecuta los siguientes comandos:

```bash theme={null}
sudo zylon-cli install-drivers --force # Reinstalar controladores Nvidia
helm uninstall gpu-operator -n nvidia # Desinstalar operador GPU
sudo reboot # Reiniciar el sistema para limpiar cualquier información de GPU en caché
sudo zylon-cli sync # Reinstalar operador GPU cuando el sistema vuelva a estar en línea
```

Espera unos minutos y verifica la página de estado nuevamente, el problema debería estar resuelto. La instalación del controlador tomará de 10 a 15 minutos, y 3\~5 minutos adicionales hasta que Triton vuelva a estar en línea.

#### 2.2 - Controladores funcionando: nvidia-smi está funcionando correctamente pero el servicio Triton sigue fallando

Si `nvidia-smi` está funcionando correctamente pero el servicio Triton está fallando (confirma esto en la página de estado), esto generalmente es causado por problemas de caché con respecto a la autodetección de GPU, para solucionarlo ejecuta:

```bash theme={null}
helm uninstall gpu-operator -n nvidia
sudo reboot # Reiniciar para limpiar cualquier información de GPU en caché
sudo zylon-cli sync # Reinstalar operador GPU
```

Espera unos minutos y verifica la página de estado nuevamente, el problema debería estar resuelto. Ten en cuenta que en este caso Triton podría tomar 3\~5 minutos para volver a estar en línea.

#### 2.3 - Controladores funcionando, pero las soluciones para 2.1 y 2.2 no funcionaron

Si `nvidia-smi` está funcionando pero las soluciones anteriores no funcionaron, el problema podría estar ubicado en la instalación de Nvidia Container Toolkit.

Verifica que el archivo ubicado aquí: `/etc/k0s/containerd.d/nvidia.toml` existe, y tiene el siguiente contenido:

```toml theme={null}
# Permitir que k0s containerd use nvidia-container-runtime
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]
privileged_without_host_devices = false
runtime_engine = ""
runtime_root = ""
runtime_type = "io.containerd.runc.v2"

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]
BinaryName = "/usr/bin/nvidia-container-runtime"
```

Si el archivo falta, puedes recrearlo automáticamente ejecutando:

```bash theme={null}
sudo zylon-cli setup
sudo reboot # Reiniciar el sistema
```

Espera unos minutos y verifica la página de estado nuevamente, el problema debería estar resuelto.


# Solución de Problemas Generales
Source: https://docs.zylon.ai/es/v1.58/operator-manual/troubleshooting/troubleshoot



La solución de problemas de Zylon se realiza principalmente a través de la herramienta de línea de comandos `zylon-cli`.

## Zylon Doctor

`zylon-cli` viene con una herramienta de diagnóstico integrada.

Ejecuta:

```bash theme={null}
sudo zylon-cli doctor
```

para obtener toda la información relevante para depurar. La salida del comando te guiará más adelante en caso de que necesites información más detallada si alguna parte del sistema está fallando.

## Cambiar la IP del servidor después de que Zylon ha sido instalado

En caso de que necesites mover el servidor donde está instalado Zylon a una dirección IP diferente, hay un cambio que debe hacerse.

1. Detén el clúster K0s: `sudo k0s stop`
2. Edita el archivo `/var/lib/k0s/kubelet.conf` y reemplaza la IP antigua por la nueva IP
3. Reinicia la máquina
4. Ejecuta `sudo zylon-cli sync-kube-config`

## Herramientas de depuración

Además del comando doctor, se pueden habilitar herramientas de depuración adicionales en `zylon-conf.yaml`.

Ten en cuenta que estas herramientas acceden directamente a los internos de Zylon y puedes romper el sistema si modificas cualquier recurso crítico.

### Depuración de tareas en segundo plano

Habilita la herramienta de depuración de tareas en segundo plano agregando estas líneas a la configuración:

```yaml theme={null}
zylonGPTWorker:
  exposeIngress: true
  # flowerPassword: "zylon-flower"
  # puedes personalizar la contraseña si quieres exponerla permanentemente
```

Después de la actualización, un nuevo endpoint estará disponible bajo `/gpt-worker/tasks` que contiene información sobre las operaciones en ejecución. La tecnología que impulsa el panel es [flower](https://flower.readthedocs.io/en/latest/).

El nombre de usuario es `flower` y la contraseña por defecto es `zylon-flower`

### Panel de Kubernetes

Habilita el panel de administración de Kubernetes para control avanzado de Zylon agregando estas líneas a la configuración:

```yaml theme={null}
adminDashboard:
  enabled: true
  exposeIngress: true 
```

Después de la actualización, un nuevo endpoint estará disponible bajo `/kube-dashboard`. La tecnología que impulsa el panel es [kubernetes dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/).

Para conectarte al panel debes generar un token ejecutando el siguiente comando en tu instancia

```yaml theme={null}
kubectl create token -n zylon zylon
```

Este token da ACCESO COMPLETO a todos los recursos de Zylon, configuración, secretos, y así sucesivamente.

> Como regla general, una vez que termines de usar el panel, debes deshabilitarlo debido a los riesgos de seguridad.

## Mejorar la indexación para versiones anteriores a 1.13.0

Si estás instalando una versión de Zylon mayor que 1.13.0 (Lanzada el 27 de enero de 2025) omite esta sección, solo se aplica a versiones anteriores.

Con el lanzamiento v1.13.0 y el soporte para archivos más grandes, la indexación es necesaria para un mejor rendimiento. Esta es una operación única que creará el índice en la base de datos vectorial para tus documentos existentes y nuevos.

Simplemente ejecuta el script en la máquina donde está instalado Zylon. Ejecutar el script múltiples veces no tiene efecto negativo. El tiempo de indexación puede variar dependiendo del número de documentos, pero debería ser más rápido que un minuto.

* Script de indexación

  ```bash theme={null}
  #!/bin/bash

  # Configuración
  QDRANT_HOST="localhost"
  QDRANT_PORT="6333"
  MAX_RETRIES=30
  RETRY_INTERVAL=2
  QDRANT_RELEASE_NAME="zylon"
  NAMESPACE="$QDRANT_RELEASE_NAME"

  # Función de limpieza
  cleanup() {
      echo "Limpiando..."
      if [ ! -z "$PORT_FORWARD_PID" ]; then
          echo "Deteniendo proceso de port-forward..."
          kill $PORT_FORWARD_PID 2>/dev/null
          wait $PORT_FORWARD_PID 2>/dev/null
      fi
      exit 0
  }

  # Configurar trap para limpieza
  trap cleanup SIGINT SIGTERM EXIT

  # Iniciar port-forwarding
  echo "Iniciando port-forwarding..."
  kubectl port-forward "svc/${QDRANT_RELEASE_NAME}-qdrant" -n "$NAMESPACE" "${QDRANT_PORT}:6333" &
  PORT_FORWARD_PID=$!

  # Verificar que el proceso de port-forward se inició correctamente
  if ! ps -p $PORT_FORWARD_PID > /dev/null; then
      echo "Error: Falló al iniciar port-forwarding"
      exit 1
  fi

  echo "Port-forwarding iniciado con PID $PORT_FORWARD_PID"

  # Función para verificar si Qdrant está listo
  check_qdrant_health() {
      curl --silent --fail "http://${QDRANT_HOST}:${QDRANT_PORT}/healthz" > /dev/null
      return $?
  }

  # Esperar a que Qdrant esté listo
  echo "Esperando a que Qdrant esté listo..."
  retries=0
  until check_qdrant_health; do
      # Verificar si el port-forward sigue ejecutándose
      if ! ps -p $PORT_FORWARD_PID > /dev/null; then
          echo "Error: El proceso de port-forward murió"
          exit 1
      fi
      
      retries=$((retries + 1))
      if [ $retries -eq $MAX_RETRIES ]; then
          echo "Error: El servicio Qdrant no estuvo listo a tiempo"
          exit 1
      fi
      echo "Qdrant aún no está listo. Reintento $retries/$MAX_RETRIES..."
      sleep $RETRY_INTERVAL
  done

  echo "¡Qdrant está listo! Creando índices..."

  # Crear índice artifact_id
  echo "Creando índice artifact_id..."
  curl -X PUT "http://${QDRANT_HOST}:${QDRANT_PORT}/collections/zgptvector/index" \
      -H 'Content-Type: application/json' \
      -d '{
          "field_name": "artifact_id",
          "field_schema": {
              "type": "keyword",
              "on_disk": true
          }
      }' || exit 1

  # Verificar si la primera solicitud fue exitosa
  if [ $? -ne 0 ]; then
      echo "Error: Falló al crear índice artifact_id"
      exit 1
  fi

  # Crear índice project_id
  echo "Creando índice project_id..."
  curl -X PUT "http://${QDRANT_HOST}:${QDRANT_PORT}/collections/zgptvector/index" \
      -H 'Content-Type: application/json' \
      -d '{
          "field_name": "project_id",
          "field_schema": {
              "type": "keyword",
              "on_disk": true
          }
      }' || exit 1

  # Verificar si la segunda solicitud fue exitosa
  if [ $? -ne 0 ]; then
      echo "Error: Falló al crear índice project_id"
      exit 1
  fi

  echo "¡Índices creados exitosamente!"
  ```

## OpenEBS no está funcionando, haciendo que los PODs estén Pendientes

En ciertas situaciones, mientras Zylon se está instalando, puede causar que OpenEBS no se instale correctamente. Para remediar esto, puedes hacer lo siguiente:

```bash theme={null}
kubectl delete pods,deployments,statefulsets,daemonsets,pv,pvc,sc --all -n zylon
kubectl delete namespace openebs
helm uninstall openebs -n openebs
sudo zylon-cli sync
```