hermes - 💡(How to fix) Fix fix(api_server): _handle_responses drops text.format JSON schema — structured output constraints silently ignored [1 pull requests]

Summary

POST /v1/responses with a text.format.type = json_schema body is handled by _handle_responses in gateway/platforms/api_server.py. The handler parses input, instructions, previous_response_id, stream, and store from the request body, but never reads body.get("text") — so the structured-output schema is silently discarded before the AIAgent call.

Reproduction

import os, json, urllib.request

payload = json.dumps({
    "model": "hermes-agent",
    "input": "Reply with PONG",
    "text": {
        "format": {
            "type": "json_schema",
            "name": "Probe",
            "schema": {
                "type": "object",
                "properties": {"word": {"type": "string"}},
                "required": ["word"],
                "additionalProperties": False
            }
        }
    }
}).encode()

req = urllib.request.Request(
    "http://127.0.0.1:8642/v1/responses",
    data=payload,
    headers={"Content-Type": "application/json", "Authorization": "Bearer <key>"}
)
with urllib.request.urlopen(req) as r:
    body = json.loads(r.read())
    print(body["output"][0]["content"][0]["text"])
# Prints: "PONG"   ← plain text, not {"word":"PONG"}

Using the OpenAI Agents SDK the failure surfaces as:

ModelBehaviorError: Invalid JSON when parsing PONG for TypeAdapter(Probe)

Expected behaviour

The gateway should forward the text.format constraint to the backend model when the model and provider support it (i.e. pass response_format / json_schema in the underlying LLM call). If the backend model does not support structured output, return an appropriate error rather than silently returning plain text.

Affected code

gateway/platforms/api_server.py — _handle_responses(), around the section that builds user_message / calls AIAgent. The text key is never extracted from body.

Impact

Any client using /v1/responses with output_type=<PydanticModel> (OpenAI Agents SDK pattern) receives a plain-text response that fails Pydantic validation, making schema-enforced agent workflows unusable on the _handle_responses path.

Suggested fix

Extract body.get("text") → if text["format"]["type"] == "json_schema", pass the schema as response_format (or equivalent) in the kwargs forwarded to the underlying LLM call, conditional on the configured provider supporting it.