Envie JSON estruturado com predefinições e o SDK de Python

​

Objetivo

• manter pequeno o código Python que faz a chamada
• rotear por um slug de predefinição, em vez de fixar um modelo no código
• solicitar uma saída estruturada estrita
• manter metadados de resposta suficientes para depurar o roteamento ou o comportamento dos plugins

​

1. Comece com um cliente compartilhado

import os

from phaseo import Phaseo

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

​

2. Mova os padrões estáveis para uma predefinição

• prompt do sistema
• modelo ou lista de modelos permitidos
• preferências de provedores
• configuração de raciocínio
• temperatura e outros parâmetros de geração relacionados
• política de cache de respostas quando a repetição determinística for importante

​

3. Solicite um formato JSON estrito

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 mantém os padrões de roteamento e de prompt fora do código do aplicativo
• response_format deixa o contrato explícito
• plugins pode recuperar JSON malformado quase válido quando o fluxo permitir
• meta preserva detalhes do roteamento e da execução do plugin para depuração

​

4. Analise o JSON e registre os identificadores operacionais

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)

• a janela de detalhes da requisição no painel
• os diagnósticos de roteamento
• os metadados de execução do plugin

​

5. Depure antes de substituir configurações

1. abra a requisição em Gateway -> Uso
2. confira os diagnósticos de roteamento e os provedores candidatos
3. inspecione os metadados de execução dos plugins se houver JSON estruturado
4. altere a predefinição somente depois que os logs mostrarem o que aconteceu

​

6. Mantenha a compatibilidade do cache quando quiser reutilizar resultados

• mantenha estável o texto do prompt
• mantenha estável o esquema da resposta
• evite substituições desnecessárias de provedor em cada requisição
• evite listas de ferramentas que mudem com frequência

​

Guias relacionados

• Implante predefinições e depure o roteamento
• Use cache de respostas com predefinições
• Recupere respostas JSON estruturadas
• Visão geral do SDK de Python