Skip to content

The agent that grows with you

fix(api_server): a budget-exhausted chat turn reports "length", not "cancelled"

Teknium8397dafbcc85
diff --git a/gateway/platforms/api_server_openai_routes.py b/gateway/platforms/api_server_openai_routes.py
index 9b6c1bfad69..05e2d7b6482 100644
--- a/gateway/platforms/api_server_openai_routes.py
+++ b/gateway/platforms/api_server_openai_routes.py
@@ -68,7 +68,13 @@ def _result_flags(result: Any) -> tuple:
bool(result.get("failed")), result.get("error"))
-def _finish_reason(completed, is_partial, is_failed, err_msg, agent_error=None) -> str:
+def _budget_exhausted(result: Any) -> bool:
+ """The turn ran out of its iteration budget; its final text is the agent's own wrap-up."""
+ reason = str(result.get("turn_exit_reason") or "") if isinstance(result, dict) else ""
+ return reason.startswith(("budget_exhausted", "max_iterations_reached("))
+
+
+def _finish_reason(completed, is_partial, is_failed, err_msg, agent_error=None, *, budget_exhausted=False) -> str:
"""OpenAI ``finish_reason``: "length" for truncation, "error" for failure, else "stop"."""
# OpenAI uses "length" for truncation, "stop" for normal completion, and downstream SDKs accept "error"
# / custom codes. See issue #22496.
@@ -76,6 +82,10 @@ def _finish_reason(completed, is_partial, is_failed, err_msg, agent_error=None)
return "length"
if agent_error is not None or is_failed or (not completed and err_msg):
return "error"
+ # "cancelled" means the user interrupted; a budget-capped turn stopped short of the task instead,
+ # and a broker reading "cancelled" discards a usable wrap-up answer.
+ if budget_exhausted:
+ return "length"
return 'cancelled' if not completed else 'stop'
@@ -114,10 +124,12 @@ def _response_status(result):
return 'completed'
-def _hermes_extras(completed, is_partial, is_failed, err_msg, finish_reason: str) -> dict[str, Any]:
- return {
- "completed": completed, "partial": is_partial, "failed": is_failed, "error": err_msg,
- "error_code": "output_truncated" if finish_reason == "length" else "agent_error"}
+def _hermes_extras(completed, is_partial, is_failed, err_msg, finish_reason: str, *,
+ budget_exhausted: bool = False) -> dict[str, Any]:
+ error_code = ("iteration_budget_exhausted" if budget_exhausted and finish_reason == "length"
+ else "output_truncated" if finish_reason == "length" else "agent_error")
+ return {"completed": completed, "partial": is_partial, "failed": is_failed, "error": err_msg,
+ "error_code": error_code}
def _transformed_notice() -> str:
@@ -969,7 +981,8 @@ class OpenAICompatRoutesMixin:
completed, is_partial, is_failed, err_msg = _result_flags(result)
if err_msg:
err_msg = _redact_api_error_text(err_msg)
- finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg)
+ budget_exhausted = _budget_exhausted(result)
+ finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg, budget_exhausted=budget_exhausted)
# Same #13437 identity contract as the SSE path: an explicit-header client is echoed
# the stable id it sent; a fingerprint-derived (header-less) turn keeps reporting the
# id the agent actually resolved, so headerless clients still learn where the turn went.
@@ -1000,7 +1013,8 @@ class OpenAICompatRoutesMixin:
response_data["choices"][0]["message"]["reasoning_content"] = reasoning_text
if is_partial or is_failed or not completed:
response_data["hermes"] = _hermes_extras(
- completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason)
+ completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason,
+ budget_exhausted=budget_exhausted)
response_headers["X-Hermes-Completed"] = "false"
response_headers["X-Hermes-Partial"] = "true" if is_partial else "false"
if err_msg and not presentation_muted:
@@ -1149,7 +1163,9 @@ class OpenAICompatRoutesMixin:
if agent_error is not None:
is_failed = True
err_msg = err_msg or str(agent_error)
- finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg, agent_error)
+ budget_exhausted = _budget_exhausted(result)
+ finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg, agent_error,
+ budget_exhausted=budget_exhausted)
finish_chunk = _chunk({}, finish_reason, usage=_chat_usage_payload(usage))
presentation_muted = (
(isinstance(result, dict) and result.get("_notification_presentation_suppressed") is True)
@@ -1174,7 +1190,8 @@ class OpenAICompatRoutesMixin:
"message": err_msg,
"type": type(agent_error).__name__ if agent_error else "agent_error"}
finish_chunk["hermes"] = _hermes_extras(
- completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason)
+ completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason,
+ budget_exhausted=budget_exhausted)
await response.write(_sse_frame(finish_chunk))
await response.write(b"data: [DONE]\n\n")
except (ConnectionResetError, ConnectionAbortedError, BrokenPipeError, OSError):
diff --git a/tests/gateway/test_api_terminal_http.py b/tests/gateway/test_api_terminal_http.py
index 8500fa5bb35..1fd17665786 100644
--- a/tests/gateway/test_api_terminal_http.py
+++ b/tests/gateway/test_api_terminal_http.py
@@ -1,4 +1,5 @@
"""Transport projections never report a non-successful result as completion."""
+import json
from unittest.mock import AsyncMock
import pytest
@@ -36,6 +37,41 @@ def test_chat_interruption_is_not_stop():
from gateway.platforms.api_server_openai_routes import _result_flags, _finish_reason
assert _finish_reason(*_result_flags({'completed': False, 'interrupted': True})) != 'stop'
+
[email protected]('stream', [False, True])
[email protected]('result,finish,code', [
+ ({'turn_exit_reason': 'max_iterations_reached(2/2)'}, 'length', 'iteration_budget_exhausted'),
+ ({'interrupted': True}, 'cancelled', 'agent_error'),
+])
+async def test_chat_budget_exhausted_turn_is_length_not_cancelled(stream, result, finish, code):
+ """A turn that ran out of iterations delivers its wrap-up as ``length`` with a distinct code; a
+ broker reading "cancelled" (reserved for user interrupts) would discard a usable answer."""
+ adapter = APIServerAdapter(PlatformConfig(enabled=True))
+ adapter._run_agent = AsyncMock(return_value=(
+ {'final_response': 'wrap-up', 'completed': False, 'messages': [], **result}, {}))
+ app = web.Application()
+ app.router.add_post('/v1/chat/completions', adapter._handle_chat_completions)
+ try:
+ async with TestClient(TestServer(app)) as client:
+ response = await client.post('/v1/chat/completions', json={
+ 'model': 'hermes', 'stream': stream, 'messages': [{'role': 'user', 'content': 'hi'}]})
+ assert response.status == 200
+ if stream:
+ chunks = [json.loads(line[6:]) for line in (await response.text()).splitlines()
+ if line.startswith('data: {')]
+ final = chunks[-1]
+ content = ''.join(c['choices'][0]['delta'].get('content') or '' for c in chunks)
+ else:
+ final = await response.json()
+ content = final['choices'][0]['message']['content']
+ assert content == 'wrap-up'
+ assert final['choices'][0]['finish_reason'] == finish
+ assert final['hermes']['error_code'] == code
+ finally:
+ adapter._response_store.close()
+ adapter._run_idempotency_store.close()
+
@pytest.mark.asyncio
@pytest.mark.parametrize('flag,status', [('failed', 'failed'), ('interrupted', 'cancelled')])
async def test_session_chat_terminal_result_is_not_success(flag, status):
diff --git a/website/docs/user-guide/features/api-server.md b/website/docs/user-guide/features/api-server.md
index 7e890da60a4..2d920eb64d9 100644
--- a/website/docs/user-guide/features/api-server.md
+++ b/website/docs/user-guide/features/api-server.md
@@ -68,6 +68,11 @@ structured through execution; it is not interpreted as a gateway slash command.
terminal status and `response.cancelled` / `response.failed` events, including when
diagnostic text is present. Chat Completions reports `finish_reason: "cancelled"`
for interrupted turns and `"error"` for failures, not a successful `"stop"`.
+- A turn that runs out of its iteration budget (`agent.max_turns`) still answers with the
+ agent's wrap-up of what it found. Chat Completions delivers that text with
+ `finish_reason: "length"` and `hermes.error_code: "iteration_budget_exhausted"`;
+ Responses reports `status: "incomplete"`. Treat the content as a usable answer to a task
+ that stopped short, not as a cancellation.
- Session-chat replies include `status`; their streams report matching terminal run
events. An assistant finalization frame is not itself proof of successful execution.