Publicar JSON estructurado con el SDK de Python y ajustes predefinidos

​

Objetivo

• mantener pequeño el código de Python que hace la llamada
• usar el identificador de un ajuste predefinido para enrutar, en vez de fijar un modelo en el código
• solicitar una salida estructurada estricta
• conservar suficientes metadatos de respuesta para depurar el enrutamiento o el comportamiento de los plugins

​

1. Empieza con un cliente compartido

import os

from phaseo import Phaseo

gateway = Phaseo(api_key=os.environ["PHASEO_API_KEY"])

​

2. Traslada los valores predeterminados estables a un ajuste predefinido

• el prompt del sistema
• el modelo o la lista de modelos permitidos
• las preferencias de proveedores
• la configuración de razonamiento
• la temperatura y otros parámetros de generación relacionados
• la política de caché de respuestas cuando sea importante repetir resultados deterministas

​

3. Solicita una forma JSON estricta

response = gateway.generate_response(
    {
        "preset": "release-summary",
        "input": "Summarize the last 24 hours of deployment activity.",
        "response_format": {
            "type": "json_schema",
            "name": "release_summary",
            "schema": {
                "type": "object",
                "required": ["summary", "risk_level"],
                "properties": {
                    "summary": {"type": "string"},
                    "risk_level": {
                        "type": "string",
                        "enum": ["low", "medium", "high"],
                    },
                },
                "additionalProperties": False,
            },
        },
        "plugins": [{"id": "response-healing"}],
        "meta": True,
    }
)

• preset mantiene el enrutamiento y los prompts predeterminados fuera del código de la aplicación
• response_format hace explícito el contrato
• plugins puede recuperar JSON mal formado pero casi válido si el flujo de trabajo lo permite
• meta conserva detalles de enrutamiento y ejecución de plugins para depurar

​

4. Analiza el JSON y registra los identificadores operativos

import json

message_text = ""
for item in response.get("output", []):
    if item.get("type") != "message":
        continue
    for part in item.get("content", []):
        if part.get("type") == "output_text":
            message_text = part.get("text", "")
            break

payload = json.loads(message_text)

print("response_id:", response.get("id"))
print("selected_provider:", response.get("meta", {}).get("routing", {}).get("selected_provider"))
print("plugin_executions:", response.get("meta", {}).get("plugin_executions"))
print(payload)

• el diálogo de detalles de la solicitud en el panel
• los diagnósticos de enrutamiento
• los metadatos de ejecución de plugins

​

5. Depura antes de añadir excepciones

1. abre la solicitud en Gateway -> Uso
2. revisa los diagnósticos de enrutamiento y los proveedores candidatos
3. revisa los metadatos de ejecución de plugins si la solicitud incluía JSON estructurado
4. modifica el ajuste predefinido solo después de que los registros muestren lo que ocurrió

​

6. Mantén la compatibilidad con la caché si quieres reutilizar resultados

• mantén estable la redacción del prompt
• mantén estable el esquema de respuesta
• evita excepciones innecesarias de proveedores en cada solicitud
• evita listas de herramientas que cambien constantemente

​

Guías relacionadas

• Desplegar ajustes predefinidos y depurar el enrutamiento
• Usar caché de respuestas con ajustes predefinidos
• Usar la reparación de respuestas para JSON estructurado
• Descripción general del SDK de Python