> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Use o SDK oficial de Python com predefinições, saídas estruturadas e depuração por requisição sem recorrer a chamadas HTTP brutas.

Use esta receita quando um serviço em Python precisar usar padrões gerenciados pelo painel, em vez de repetir a configuração de prompts, roteamento e parâmetros em cada requisição.

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

```python theme={null}
import os

from phaseo import Phaseo

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

Compartilhe o cliente, em vez de criar um para cada requisição.

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

Crie uma predefinição em **Painel -> Configurações -> Predefinições** quando estes valores precisarem permanecer estáveis entre vários chamadores:

* 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

Depois que a predefinição existir, o código Python que faz a chamada pode continuar enxuto.

## 3. Solicite um formato JSON estrito

```python theme={null}
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,
    }
)
```

Por que esse formato funciona bem:

* `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

```python theme={null}
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)
```

Para workers em Python, isso geralmente basta para relacionar uma linha de log do aplicativo a:

* 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

Se uma requisição for roteada de forma diferente do esperado:

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

Evite tentar corrigir uma requisição problemática adicionando muitas substituições inline. Isso geralmente anula a vantagem de usar predefinições.

## 6. Mantenha a compatibilidade do cache quando quiser reutilizar resultados

Se a predefinição habilitar o cache de respostas:

* 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

Se um chamador realmente precisar de outro comportamento, use uma predefinição separada em vez de reduzir a reutilização do cache no fluxo compartilhado.

## Guias relacionados

* [Implante predefinições e depure o roteamento](./preset-rollout-and-routing-debug.mdx)
* [Use cache de respostas com predefinições](./response-caching-with-presets.mdx)
* [Recupere respostas JSON estruturadas](./response-healing-for-structured-json.mdx)
* [Visão geral do SDK de Python](../sdk-reference/python/overview.mdx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.