Skip to content

Agent Zero AI framework

Handle reasoning-only and plain-text fallback responses

linkliti0bd5f34848fc
diff --git a/extensions/python/_functions/agent/Agent/hist_add_warning/end/_90_stop_unusable_response_loop.py b/extensions/python/_functions/agent/Agent/hist_add_warning/end/_90_stop_unusable_response_loop.py
index 87670a273..e28abfcf9 100644
--- a/extensions/python/_functions/agent/Agent/hist_add_warning/end/_90_stop_unusable_response_loop.py
+++ b/extensions/python/_functions/agent/Agent/hist_add_warning/end/_90_stop_unusable_response_loop.py
@@ -23,6 +23,8 @@ class StopUnusableResponseLoop(Extension):
self.agent.read_prompt("fw.msg_misformat.md"),
self.agent.read_prompt("fw.msg_repeat.md"),
self.agent.read_prompt("fw.msg_empty_response.md"),
+ self.agent.read_prompt("fw.msg_reasoning_only.md"),
+ self.agent.read_prompt("fw.msg_thoughts_fallback.md"),
}:
return
diff --git a/extensions/python/message_loop_result/AGENTS.md b/extensions/python/message_loop_result/AGENTS.md
index c1395c5fb..59ff7d054 100644
--- a/extensions/python/message_loop_result/AGENTS.md
+++ b/extensions/python/message_loop_result/AGENTS.md
@@ -7,7 +7,7 @@
## Ownership
- Extensions receive mutable `result_data` with `llm_result` and may set `skip_default_processing` after fully handling the turn.
-- `_20_empty_response.py` retries turns with neither response nor reasoning, counts them toward the unusable-response limit without adding a warning to model history, and uses `fw.msg_empty_response.md` for agent-prefixed UI warning text only.
+- `_20_empty_response.py` retries turns with no response content: fully empty turns count toward the unusable-response limit without adding a warning to model history and use `fw.msg_empty_response.md` for agent-prefixed UI warning text only; reasoning-only turns add an agent-facing `fw.msg_reasoning_only.md` history warning with a separate `fw.msg_reasoning_only_response.md` user notice and are counted by the stop-unusable-response-loop extension.
- `_30_repeat_response.py` retries response content that exactly matches `loop_data.last_response`, regardless of reasoning, using `fw.msg_repeat.md` for history and `fw.msg_repeat_response.md` for the agent-prefixed UI warning text.
## Local Contracts
diff --git a/extensions/python/message_loop_result/_20_empty_response.py b/extensions/python/message_loop_result/_20_empty_response.py
index aa79bf8c8..4f1b26d6d 100644
--- a/extensions/python/message_loop_result/_20_empty_response.py
+++ b/extensions/python/message_loop_result/_20_empty_response.py
@@ -25,7 +25,19 @@ class EmptyResponse(Extension):
reasoning = getattr(llm_result, "reasoning", "")
if not isinstance(response, str) or not isinstance(reasoning, str):
return
- if response.strip() or reasoning.strip():
+ if response.strip():
+ return
+
+ if reasoning.strip():
+ warning = self.agent.read_prompt("fw.msg_reasoning_only.md")
+ warning_message = self.agent.hist_add_warning(message=warning)
+ PrintStyle(font_color="orange", padding=True).print(warning)
+ self.agent.context.log.log(
+ type="warning",
+ content=f"{self.agent.agent_name}: {self.agent.read_prompt('fw.msg_reasoning_only_response.md')}",
+ id=warning_message.id,
+ )
+ result_data["skip_default_processing"] = True
return
warning = self.agent.read_prompt("fw.msg_empty_response.md")
diff --git a/plugins/_context_doctor/AGENTS.md b/plugins/_context_doctor/AGENTS.md
index 65429146e..d3f5393eb 100644
--- a/plugins/_context_doctor/AGENTS.md
+++ b/plugins/_context_doctor/AGENTS.md
@@ -10,12 +10,14 @@
- `hooks.py` installs the exact root-pinned repair dependency in the framework runtime.
- `extensions/python/startup_migration/` prepares that dependency after startup and self-update.
- `extensions/python/message_loop_result/` normalizes completed model output before default processing.
+- `prompts/` owns fallback warning texts.
- `webui/config.html` exposes XML suppression and log-detail settings.
## Local Contracts
- Repaired and fallback JSON is always minified.
- Nonempty non-tool output becomes `{"thoughts":[raw]}`; XML-like output becomes `{}` only when suppression is enabled.
+- A raw-text fallback conversion owns the turn: `fw.msg_thoughts_fallback.md` history warning, separate `fw.msg_thoughts_fallback_response.md` user notice, one unusable-response failure counted by the stop-unusable-response-loop extension, and `skip_default_processing` set.
- Log kvps retain streamed `reasoning` and add transformed output; `update_log` controls only View Details content.
- A repaired `response` tool call refreshes the response log item when streaming did not create it.
- Runtime setup reads the `json_repair` pin from root `requirements.txt`; do not duplicate its version in plugin code.
@@ -31,4 +33,4 @@
## Child DOX Index
-No child DOX files.
+No child DOX files.
\ No newline at end of file
diff --git a/plugins/_context_doctor/extensions/python/message_loop_result/_10_context_doctor.py b/plugins/_context_doctor/extensions/python/message_loop_result/_10_context_doctor.py
index fb04dd935..d323993d6 100644
--- a/plugins/_context_doctor/extensions/python/message_loop_result/_10_context_doctor.py
+++ b/plugins/_context_doctor/extensions/python/message_loop_result/_10_context_doctor.py
@@ -7,7 +7,9 @@ from typing import Any, override
from helpers.extension import Extension
from helpers.plugins import get_plugin_config
+from helpers.print_style import PrintStyle
from plugins._context_doctor.helpers.context_doctor import (
+ is_thoughts_fallback,
transform_response,
update_log_item,
)
@@ -32,6 +34,19 @@ class ContextDoctor(Extension):
)
llm_result.response = transformed
+ # Claim raw-text fallback turns with clear warnings before log refresh
+ if is_thoughts_fallback(response, transformed):
+ warning = self.agent.read_prompt("fw.msg_thoughts_fallback.md")
+ warning_message = self.agent.hist_add_warning(message=warning)
+ PrintStyle(font_color="orange", padding=True).print(warning)
+ self.agent.context.log.log(
+ type="warning",
+ content=f"{self.agent.agent_name}: {self.agent.read_prompt('fw.msg_thoughts_fallback_response.md')}",
+ id=warning_message.id,
+ )
+ result_data["skip_default_processing"] = True
+ return
+
# Suppressed XML does not update the generating log
params = getattr(
getattr(self.agent, "loop_data", None), "params_temporary", None
diff --git a/plugins/_context_doctor/helpers/context_doctor.py b/plugins/_context_doctor/helpers/context_doctor.py
index 30c85bff4..443459f72 100644
--- a/plugins/_context_doctor/helpers/context_doctor.py
+++ b/plugins/_context_doctor/helpers/context_doctor.py
@@ -110,6 +110,24 @@ def transform_response(response: str, *, suppress_xml: bool) -> str:
return _compact_json({"thoughts": [response]})
+def is_thoughts_fallback(response: str, transformed: str) -> bool:
+ """Check whether transform wrapped raw output as its only thoughts entry."""
+ if not response:
+ return False
+ try:
+ parsed = json.loads(transformed)
+ except ValueError:
+ return False
+ if (
+ not isinstance(parsed, dict)
+ or set(parsed.keys()) != {"thoughts"}
+ or not isinstance(parsed.get("thoughts"), list)
+ or len(parsed["thoughts"]) != 1
+ ):
+ return False
+ return parsed["thoughts"][0] == response
+
+
def update_log_item(
agent: Any,
log_item: Any,
diff --git a/plugins/_context_doctor/prompts/fw.msg_thoughts_fallback.md b/plugins/_context_doctor/prompts/fw.msg_thoughts_fallback.md
new file mode 100644
index 000000000..e98aa0b77
--- /dev/null
+++ b/plugins/_context_doctor/prompts/fw.msg_thoughts_fallback.md
@@ -0,0 +1 @@
+Your reply was plain text instead of a tool call. Respond with a single valid JSON tool call; use the `response` tool with `text` to reply to the user.
\ No newline at end of file
diff --git a/plugins/_context_doctor/prompts/fw.msg_thoughts_fallback_response.md b/plugins/_context_doctor/prompts/fw.msg_thoughts_fallback_response.md
new file mode 100644
index 000000000..bd86ec8c5
--- /dev/null
+++ b/plugins/_context_doctor/prompts/fw.msg_thoughts_fallback_response.md
@@ -0,0 +1 @@
+Plain-text reply was kept as thoughts. Retrying with a tool-call reminder.
\ No newline at end of file
diff --git a/plugins/_context_doctor/tests/test_context_doctor.py b/plugins/_context_doctor/tests/test_context_doctor.py
index 9d680a6a6..4da1220db 100644
--- a/plugins/_context_doctor/tests/test_context_doctor.py
+++ b/plugins/_context_doctor/tests/test_context_doctor.py
@@ -4,6 +4,7 @@ from plugins._context_doctor.extensions.python.message_loop_result._10_context_d
ContextDoctor,
)
from plugins._context_doctor.helpers.context_doctor import (
+ is_thoughts_fallback,
transform_response,
update_log_item,
)
@@ -81,6 +82,23 @@ def test_updates_log_kvps_and_heading_while_preserving_raw_content():
assert log_item.data["heading"] == "A0: Done"
+def test_converted_to_thoughts_detects_plain_text_wrap():
+ assert is_thoughts_fallback("plain text", '{"thoughts":["plain text"]}')
+ assert not is_thoughts_fallback("plain text", "{}")
+
+
+def test_converted_to_thoughts_ignores_native_thoughts_json():
+ response = '{"thoughts":["only thoughts"]}'
+
+ assert not is_thoughts_fallback(response, response)
+
+
+def test_converted_to_thoughts_ignores_tool_calls():
+ response = '{"tool_name":"response","tool_args":{"text":"ok"}}'
+
+ assert not is_thoughts_fallback(response, response)
+
+
def test_extension_replaces_result_refreshes_log_and_response_item(monkeypatch):
monkeypatch.setattr(
"plugins._context_doctor.extensions.python.message_loop_result._10_context_doctor.get_plugin_config",
diff --git a/prompts/fw.msg_reasoning_only.md b/prompts/fw.msg_reasoning_only.md
new file mode 100644
index 000000000..289bfa50f
--- /dev/null
+++ b/prompts/fw.msg_reasoning_only.md
@@ -0,0 +1 @@
+You produced reasoning but no response content. Respond now with a single valid tool-call JSON object exactly as the system prompt requires; do not end a turn without one.
\ No newline at end of file
diff --git a/prompts/fw.msg_reasoning_only_response.md b/prompts/fw.msg_reasoning_only_response.md
new file mode 100644
index 000000000..cf3096e33
--- /dev/null
+++ b/prompts/fw.msg_reasoning_only_response.md
@@ -0,0 +1 @@
+Reasoning-only response detected. Retrying.
\ No newline at end of file
diff --git a/tests/test_message_loop_result.py b/tests/test_message_loop_result.py
index 46cdd1c55..ac1c418e8 100644
--- a/tests/test_message_loop_result.py
+++ b/tests/test_message_loop_result.py
@@ -34,6 +34,8 @@ class FakeAgent:
"fw.msg_empty_response.md": "empty",
"fw.msg_repeat.md": "repeat",
"fw.msg_repeat_response.md": "Repeated response detected. Retrying.",
+ "fw.msg_reasoning_only.md": "reasoning only",
+ "fw.msg_reasoning_only_response.md": "Reasoning-only response detected. Retrying.",
}[name]
def hist_add_ai_response(self, response, **kwargs):
@@ -124,8 +126,17 @@ def test_repeat_ignores_reasoning():
assert agent.warnings == ["repeat"]
-def test_result_with_reasoning_uses_default_processing():
+def test_reasoning_only_retries_with_agent_warning():
agent = FakeAgent("", reasoning="thinking", last_response="previous")
- assert "skip_default_processing" not in _run(agent)
- assert agent.history == []
+ result = _run(agent)
+
+ assert result["skip_default_processing"] is True
+ assert agent.warnings == ["reasoning only"]
+ assert agent.logs == [
+ {
+ "type": "warning",
+ "content": "A0: Reasoning-only response detected. Retrying.",
+ "id": "warning",
+ }
+ ]
diff --git a/tests/test_unusable_response_loop.py b/tests/test_unusable_response_loop.py
index 6c0343387..51c46d26f 100644
--- a/tests/test_unusable_response_loop.py
+++ b/tests/test_unusable_response_loop.py
@@ -22,6 +22,8 @@ def _agent():
"fw.msg_misformat.md": "misformatted",
"fw.msg_repeat.md": "repeated",
"fw.msg_empty_response.md": "empty response",
+ "fw.msg_reasoning_only.md": "reasoning only",
+ "fw.msg_thoughts_fallback.md": "thoughts fallback",
}
def read_prompt(name, **kwargs):
@@ -84,6 +86,36 @@ def test_nonconsecutive_failure_starts_a_new_recovery_window(monkeypatch):
assert agent.loop_data.params_persistent[response_loop.STATE_KEY]["count"] == 1
+def test_reasoning_only_warning_counts_toward_the_limit(monkeypatch):
+ monkeypatch.setattr(
+ response_loop,
+ "get_settings",
+ lambda: {"max_consecutive_unusable_responses": 1},
+ )
+ agent = _agent()
+ extension = response_loop.StopUnusableResponseLoop(agent=agent)
+
+ data = _run(extension, agent, "reasoning only")
+
+ assert isinstance(data["exception"], HandledException)
+ assert agent.loop_data.params_persistent[response_loop.STATE_KEY]["count"] == 1
+
+
+def test_thoughts_fallback_warning_counts_toward_the_limit(monkeypatch):
+ monkeypatch.setattr(
+ response_loop,
+ "get_settings",
+ lambda: {"max_consecutive_unusable_responses": 1},
+ )
+ agent = _agent()
+ extension = response_loop.StopUnusableResponseLoop(agent=agent)
+
+ data = _run(extension, agent, "thoughts fallback")
+
+ assert isinstance(data["exception"], HandledException)
+ assert agent.loop_data.params_persistent[response_loop.STATE_KEY]["count"] == 1
+
+
def test_general_settings_expose_the_default_failure_limit():
settings = get_default_settings()
assert settings["max_consecutive_unusable_responses"] == 5