Visión general

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

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

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

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`

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

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
Ingesta de contenido: Artefactos

Primeros pasos

Construye con Zylon

Coding Agents

Visión general

Requisitos previos

Solicitud y respuesta básicas

Herramientas integradas

Cómo se devuelven los resultados de las herramientas integradas

Herramientas personalizadas

Errores comunes

Próximos pasos

​Requisitos previos

​Solicitud y respuesta básicas

​Herramientas integradas

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

​Herramientas personalizadas

​Errores comunes

​Próximos pasos

Requisitos previos

Solicitud y respuesta básicas

Herramientas integradas

Cómo se devuelven los resultados de las herramientas integradas

Herramientas personalizadas

Errores comunes

Próximos pasos