Chat Completions: contexto, herramientas y errores#

Para integrar un modelo mediante Sherpa AI Server, se debe utilizar POST /api/v1/threads/chat/completions. Ejecuta una solicitud sin crear un chat ni una ejecución. El cliente envía el historial de mensajes.

Autenticación y selección del modelo#

Se requiere un token de API válido con permiso de creación en Chat. POST /api/v1/threads/chat/preflight requiere permiso de lectura. La autenticación determina la cuenta. No es necesario enviar account_guid.

En model se debe indicar el nombre de una ficha de modelo de la cuenta actual. El servidor selecciona una instancia activa de esa ficha. También se admite la selección anterior por nombre de instancia activa de la misma cuenta. Un nombre desconocido o de otra cuenta devuelve 404 model_not_found. Una ficha sin instancias activas devuelve 503 model_unavailable.

Un parámetro explícito tiene prioridad sobre la ficha y el entorno del servidor. Los parámetros ausentes usan la ficha y después el entorno. El objeto chat_template_kwargs se reemplaza por completo. null, {} y un campo ausente son distintos. Se debe enviar solo un campo de presupuesto de salida: max_tokens o max_completion_tokens.

Comprobación del contexto antes de generar#

Se debe enviar la solicitud completa prevista a /api/v1/threads/chat/preflight con Authorization: Bearer <API_TOKEN> y Content-Type: application/json. En el ejemplo se debe sustituir Support model por el nombre de una ficha disponible:

{
  "model": "Support model",
  "messages": [{"role": "user", "content": "Read the test file"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "read_file",
      "parameters": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"],
        "additionalProperties": false
      }
    }
  }],
  "max_tokens": 512,
  "chat_template_kwargs": {"enable_thinking": false}
}

Preflight no genera respuestas, ejecuta herramientas ni crea historial. El resultado está en data:

Campo Significado
prompt_tokens Tamaño de entrada con mensajes, esquemas de herramientas y reservas para imágenes y formato de respuesta.
output_tokens Presupuesto de salida. null si se desconoce.
context_limit Ventana de contexto conocida. null si no hay un límite configurado.
fits Indica si caben la solicitud y la salida. null si faltan datos.
exact, count_method Recuento exacto del tokenizer o estimación. Las imágenes y el formato pueden añadir reservas estimadas.
would_reject Indica si un límite fiable rechaza la solicitud. Una estimación por sí sola no bloquea la generación.
fallback_reason Motivo de la estimación, como tokenizer no disponible o proveedor en la nube sin tokenizer.
allowed_max_output Contexto restante tras la entrada calculada. Si es estimado, es orientativo.

Si would_reject=true, se debe reducir el historial, los esquemas o la salida y comprobar de nuevo. Después se envía la misma solicitud a /api/v1/threads/chat/completions. El servidor comprueba el presupuesto para la instancia real, también tras cambiar de instancia. Los límites pueden variar. Preflight no reserva una instancia para la siguiente solicitud.

Llamadas a herramientas#

El cliente externo de API ejecuta las llamadas recibidas. tools declara funciones y JSON Schema para sus argumentos. Los campos de entrada adicionales deben incluirse en el esquema y en function.arguments.

En la siguiente solicitud se debe conservar el mensaje del asistente con tool_calls y añadir resultados role=tool. function.arguments y tool.content son cadenas. tool_call_id vincula cada resultado con su llamada. Los estados, errores, artefactos y metadatos de la aplicación son JSON dentro de la cadena content:

[
  {"role":"assistant","content":null,"tool_calls":[{"id":"call_1","type":"function","function":{"name":"read_file","arguments":"{\"path\":\"sample.txt\"}"}}]},
  {"role":"tool","tool_call_id":"call_1","content":"{\"status\":\"ok\",\"data\":\"Example text\",\"artifacts\":[]}"}
]

Cada nuevo ID de llamada debe ser único en el historial. Los resultados deben seguir a su mensaje del asistente antes de otro mensaje de distinto rol. Se deben conservar los argumentos incorrectos junto con el resultado de error para que el modelo corrija la llamada. No se deben repetir acciones exitosas con efectos secundarios.

En el modo Agente interno, los argumentos corregibles se devuelven al modelo. El número de estos errores por sí solo no termina la tarea. Repetir una llamada incorrecta idéntica deja la ejecución en waiting con continuation.required=true. Tras corregir la causa, se debe reanudar explícitamente mediante el método normal de ejecución. Se conservan el contexto y los resultados completados. La cancelación y las restricciones reales de acceso siguen vigentes.

/api/v1/threads/responses utiliza el formato Responses separado. No se deben mezclar sus elementos con mensajes Chat Completions.

Errores y reintentos#

Un error contiene error.code, repairable, retryable, request_id y details seguros. Con repairable=true se debe corregir la solicitud según los detalles. Con retryable=true se permite reintentar con demora, respetando Retry-After. Estas marcas no autorizan repetir acciones de herramientas ya completadas.

Código Acción
invalid_arguments, invalid_tool_history Corregir parámetros, esquema o pares de llamadas y resultados.
context_limit Reducir la entrada o la salida. Revisar los datos numéricos en details.
model_not_found, model_unavailable Comprobar nombre, cuenta e instancias activas.
access_denied Comprobar token, permisos y acceso del servidor al proveedor.
upstream_rate_limited Respetar Retry-After.
upstream_timeout, upstream_unavailable, invalid_upstream_response Comprobar retryable y reintentar más tarde si procede.

Para SSE se requiere stream=true. Se debe leer hasta finalizar y procesar event: error. HTTP 200 indica el inicio del flujo y no garantiza que termine correctamente. Los errores de lectura o interrupciones producen un error con el mismo request_id.

Diagnóstico de solicitudes#

Se recomienda enviar X-Request-ID: de 1 a 128 caracteres A-Z, a-z, 0-9, ., _, :, -. Si falta o no es válido, el servidor crea un ID nuevo.

Las respuestas JSON y SSE incluyen X-Request-ID y X-Sherpa-Attempt-Count. Si se selecciona una ficha, están disponibles X-Sherpa-Model-Guid, X-Sherpa-Model-Instance-Guid y X-Sherpa-Configuration-Revision. La revisión distingue cambios en la configuración efectiva. JSON también incluye request_meta.request_id. Los errores anteriores a la selección no incluyen información de instancia.

Para contactar con el administrador, se deben conservar ID, hora, código de error y cabeceras de diagnóstico. El registro existente del servidor relaciona intentos, causas, latencia, usage y finalización del flujo por ID. Las ejecuciones en segundo plano se vinculan mediante GUID de ejecución e ID run:<GUID>. El evento de programación relaciona el ID externo con el GUID. Solo los administradores de infraestructura acceden al registro. Los mensajes, argumentos de herramientas y claves no se incluyen en el nuevo registro de diagnóstico.

Los tiempos de espera de cada llamada al modelo dependen de la conexión. La comprobación del contexto y el diagnóstico no limitan la duración de un robot externo.