Migración de API 1.57 -> 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 que devuelven los mensajes de chat, tanto en la API de Workspace como en la de ZylonGPT.

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

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
Petición 1.58

POST /app/project/{projectID}/artifact

{
  "type": "SmartDoc",
  "name": "Draft",
  "raw_content": "Hello",
  "props": {}
}

POST /app/artifact

{
  "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.

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
Petición 1.58

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

{
  "content": "{BASE64_EDITOR_STATE}",
  "plain_text_content": "Hello"
}

{BASE64_EDITOR_STATE} representa tu documento del editor ya codificado.

PUT /app/artifact/{artifactID}

{
  "content": "Hello"
}

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.

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)

{
  "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. 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.

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.

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.

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.

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)

{
  "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.

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.
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, transferencia de propiedad y filtros de incidencias 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.

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.
Body	`artifacts`	No	Objeto de selección por ámbito descrito abajo.

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:

{
  "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.

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

{
  "organization_id": "{orgId}",
  "project_id": "{projectID}",
  "credentials": {
    "username": "***",
    "password": "***"
  }
}

Esta operación devuelve un booleano. Consulta validar credenciales de filesystem 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, 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
1.58
1.58 con extensión de Zylon

[
  { "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:

{
  "type": "tool_result",
  "tool_use_id": "tool_1a2b",
  "content": "Web search provider timed out",
  "is_error": true
}

[
  { "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):

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_1a2b",
  "content": { "type": "web_search_tool_result_error", "error_code": "unavailable" }
}

[
  { "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:

{
  "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
1.58
1.58 con extensión de Zylon

[
  { "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:

{
  "type": "tool_result",
  "tool_use_id": "tool_3c4d",
  "content": "403 Forbidden",
  "is_error": true
}

[
  { "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:

{
  "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.

[
  { "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:

{
  "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
1.58
1.58 con extensión de Zylon

[
  { "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:

{
  "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):

{
  "type": "tool_result",
  "tool_use_id": "tool_5e6f",
  "content": "code_execution provider is not configured.",
  "is_error": true
}

[
  { "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:

{
  "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):

{
  "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.

Los resultados correctos son iguales que sin la extensión. Los objetos de error incluyen además detail, con el error original:

{
  "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
1.58
1.58 con extensión de Zylon

view:

[
  { "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:

[
  { "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:

[
  { "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:

[
  { "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::

{
  "type": "tool_result",
  "tool_use_id": "tool_7a8b",
  "content": [{ "type": "text", "text": "Error: File not found: /tmp/outputs/missing.py" }],
  "is_error": false
}

view:

[
  { "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:

[
  { "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:

[
  { "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):

[
  { "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:

{
  "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.

Los resultados correctos son iguales que sin la extensión. Los objetos de error incluyen además detail, con el error original:

{
  "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
1.58

[
  { "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:

{ "type": "tool_result", "tool_use_id": "tool_9c0d", "content": "context_filter is required", "is_error": true }

[
  { "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:

{ "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
1.58

[
  { "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:

{ "type": "tool_result", "tool_use_id": "tool_1e2f", "content": "context_filter is required", "is_error": true }

[
  { "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:

{ "type": "server_tool_result", "tool_use_id": "srvtoolu_1e2f", "content": "context_filter is required", "is_error": true }

tabular_analysis

1.57
1.58

[
  { "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:

{ "type": "tool_result", "tool_use_id": "tool_3a4b", "content": "context_filter is required", "is_error": true }

[
  { "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:

{ "type": "server_tool_result", "tool_use_id": "srvtoolu_3a4b", "content": "context_filter is required", "is_error": true }

database_query

1.57
1.58

[
  { "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:

{ "type": "tool_result", "tool_use_id": "tool_5c6d", "content": "At least one SQL database artifact is required.", "is_error": true }

[
  { "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:

{ "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
1.58

[
  { "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:

{ "type": "tool_result", "tool_use_id": "tool_7e8f", "content": "code_execution provider is not configured.", "is_error": true }

[
  { "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:

{ "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
1.58

[
  { "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:

{ "type": "tool_result", "tool_use_id": "tool_9a0b", "content": "code_execution provider is not configured.", "is_error": true }

[
  { "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:

{ "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
1.58

[
  { "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:

{
  "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
}

[
  { "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:

{
  "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
1.58

[
  { "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:

{ "type": "tool_result", "tool_use_id": "tool_3e4f", "content": "MCP server returned 401 Unauthorized", "is_error": true }

[
  { "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:

{ "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.

[
  { "type": "tool_use", "id": "tool_5a6b", "name": "get_weather", "input": { "city": "Madrid" } }
]

{ "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

Sustituye las URLs obsoletas y mueve el selector de proyecto a la consulta o al cuerpo correspondiente.
Usa bytes Base64 para crear artefactos con JSON, texto para actualizarlos y file_data para archivos multipart.
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.
Usa IDs de cuenta en los filtros de creador y los nombres canónicos de campos e inclusiones.
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.
Adapta los cuerpos de chat, selectores de artefactos por ámbito, SSE, archivos de hilo y sondeo del estado de lectura.
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.

Primeros pasos

Construye con Zylon

Coding Agents

Migración de API 1.57 -> 1.58

Requisitos previos

Rutas de artefactos

Cuerpos de creación

Cuerpos de actualización

Qué peticiones antiguas siguen siendo compatibles

Respuestas y selección de artefactos

Miembros del espacio de trabajo

IDs de cuenta y campos renombrados

Migrar IDs de usuario guardados

Qué conservan los alias antiguos

Usar nombres de campo canónicos

Chats e hilos

Mover el chat de proyecto a la ruta unificada

Archivos de hilo y estado de lectura

Peticiones de filesystem

Bloques de herramientas de servidor

Reglas de migración

Ejemplos de migración por herramienta

Peticiones con la extensión de Zylon activada

Envío del historial de conversación

Antes de actualizar tu cliente

​Requisitos previos

​Rutas de artefactos

​Cuerpos de creación

​Cuerpos de actualización

​Qué peticiones antiguas siguen siendo compatibles

​Respuestas y selección de artefactos

​Miembros del espacio de trabajo

​IDs de cuenta y campos renombrados

​Migrar IDs de usuario guardados

​Qué conservan los alias antiguos

​Usar nombres de campo canónicos

​Chats e hilos

​Mover el chat de proyecto a la ruta unificada

​Archivos de hilo y estado de lectura

​Peticiones de filesystem

​Bloques de herramientas de servidor

​Reglas de migración

​Ejemplos de migración por herramienta

​Peticiones con la extensión de Zylon activada

​Envío del historial de conversación

​Antes de actualizar tu cliente

Requisitos previos

Rutas de artefactos

Cuerpos de creación

Cuerpos de actualización

Qué peticiones antiguas siguen siendo compatibles

Respuestas y selección de artefactos

Miembros del espacio de trabajo

IDs de cuenta y campos renombrados

Migrar IDs de usuario guardados

Qué conservan los alias antiguos

Usar nombres de campo canónicos

Chats e hilos

Mover el chat de proyecto a la ruta unificada

Archivos de hilo y estado de lectura

Peticiones de filesystem

Bloques de herramientas de servidor

Reglas de migración

Ejemplos de migración por herramienta

Peticiones con la extensión de Zylon activada

Envío del historial de conversación

Antes de actualizar tu cliente