Skip to content

Agent Zero AI framework

Prevent Responses metadata history bloat

Alessandro7b216c634379
diff --git a/helpers/history.py b/helpers/history.py
index 1ff802d87..f0ee4c0df 100644
--- a/helpers/history.py
+++ b/helpers/history.py
@@ -150,11 +150,19 @@ class Message(Record):
@staticmethod
def from_dict(data: dict, history: "History"):
content = data.get("content", "Content lost")
+ metadata = data.get("metadata", {})
+ metadata = metadata if isinstance(metadata, dict) else {}
+ if data["ai"]:
+ from helpers.llm_result import result_from_metadata
+
+ result = result_from_metadata(metadata)
+ if result:
+ metadata = {**metadata, **result.metadata()}
msg = Message(
ai=data["ai"],
content=content,
id=data.get("id", ""),
- metadata=data.get("metadata", {}) if isinstance(data.get("metadata"), dict) else {},
+ metadata=metadata,
sequence=int(data.get("sequence", 0) or 0),
)
msg.summary = data.get("summary", "")
diff --git a/helpers/history.py.dox.md b/helpers/history.py.dox.md
index 53a7149e0..7f00f5075 100644
--- a/helpers/history.py.dox.md
+++ b/helpers/history.py.dox.md
@@ -79,6 +79,7 @@
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- `clear_responses_provider_state(agent)` removes the active provider continuation IDs after local history rewrites while preserving stored response ID lists for later cleanup.
+- `Message.from_dict()` normalizes legacy AI Responses metadata through `LLMResult.metadata()` so loaded chats shed transient payloads while unrelated metadata and non-AI tool-result inputs remain intact.
- Observed side-effect areas: filesystem writes, filesystem deletion, model calls, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `abc`, `asyncio`, `collections`, `collections.abc`, `enum`, `helpers`, `json`, `langchain_core.messages`, `math`, `plugins._model_config.helpers.model_config`, `typing`, `uuid`.
diff --git a/helpers/llm_result.py b/helpers/llm_result.py
index 874edec9b..a39234eab 100644
--- a/helpers/llm_result.py
+++ b/helpers/llm_result.py
@@ -216,7 +216,18 @@ class LLMResult:
}
def metadata(self) -> dict[str, Any]:
- return {RESPONSE_METADATA_KEY: self.to_dict()}
+ return {
+ RESPONSE_METADATA_KEY: {
+ "response_id": self.response_id,
+ "previous_response_id": self.previous_response_id,
+ "output_items": [item.to_dict() for item in self.output_items],
+ "provider_model_key": self.provider_model_key,
+ "mode": self.mode,
+ "state": self.state,
+ "usage": self.usage,
+ "capability": self.capability,
+ }
+ }
def function_call_output_item(
diff --git a/helpers/llm_result.py.dox.md b/helpers/llm_result.py.dox.md
index 78b472885..4d98b9a23 100644
--- a/helpers/llm_result.py.dox.md
+++ b/helpers/llm_result.py.dox.md
@@ -17,7 +17,7 @@
## Runtime Contracts
-- `LLMResult.metadata()` stores data under `RESPONSE_METADATA_KEY` so history can round-trip provider state.
+- `LLMResult.metadata()` stores only durable provider state under `RESPONSE_METADATA_KEY`: response IDs, structured output items, provider/mode/state, usage, and capability data. Runtime prompt inputs, raw responses, and duplicated response/reasoning text are not persisted in history.
- `from_response(...)` must preserve provider `response_id`, `previous_response_id`, raw output items, usage, and capability metadata.
- `from_chat(...)` must produce an equivalent chat-completions result with `mode="chat_completions"` and `state="off"`, preserving optional function-call output items when the chat transport supplies them.
- Function-call output items must preserve `call_id` and optional acknowledged safety checks.
diff --git a/tests/test_responses_architecture.py b/tests/test_responses_architecture.py
index 056e912a6..c893f29e9 100644
--- a/tests/test_responses_architecture.py
+++ b/tests/test_responses_architecture.py
@@ -43,7 +43,7 @@ class _AsyncEventStream:
self.closed = True
-def test_llm_result_round_trips_responses_metadata():
+def test_llm_result_persists_only_durable_responses_metadata():
result = LLMResult.from_response(
{
"id": "resp_123",
@@ -69,7 +69,14 @@ def test_llm_result_round_trips_responses_metadata():
provider_model_key="openai/gpt-5.4",
)
- loaded = result_from_metadata(result.metadata())
+ metadata = result.metadata()
+ persisted = metadata["responses"]
+ assert "response" not in persisted
+ assert "reasoning" not in persisted
+ assert "input_items" not in persisted
+ assert "raw" not in persisted
+
+ loaded = result_from_metadata(metadata)
assert loaded is not None
assert loaded.response_id == "resp_123"
@@ -79,22 +86,42 @@ def test_llm_result_round_trips_responses_metadata():
assert loaded.builtin_items[0].type == "web_search_call"
-def test_history_serializes_metadata_and_migrates_old_messages():
+def test_history_migrates_legacy_ai_metadata_and_preserves_tool_inputs():
class DummyAgent:
pass
hist = history.History(DummyAgent())
result = LLMResult.from_response(
{"id": "resp_1", "output": [{"type": "message", "content": [{"type": "output_text", "text": "ok"}]}]},
+ input_items=[{"role": "user", "content": "question"}],
provider_model_key="openai/gpt-5.4",
)
message = hist.add_message(True, "ok", metadata=result.metadata())
+ tool_item = {"type": "function_call_output", "call_id": "call_1", "output": "done"}
+ hist.add_message(
+ False,
+ "done",
+ metadata={"responses": {"input_items": [tool_item]}},
+ )
restored = history.deserialize_history(hist.serialize(), DummyAgent())
restored_message = restored.all_messages()[0]
assert restored_message.sequence == message.sequence
assert result_from_metadata(restored_message.metadata).response_id == "resp_1"
+ assert restored.all_messages()[1].metadata["responses"]["input_items"] == [tool_item]
+
+ migrated = history.Message.from_dict(
+ {
+ "_cls": "Message",
+ "ai": True,
+ "content": "old",
+ "metadata": {"custom": "keep", "responses": result.to_dict()},
+ },
+ restored,
+ )
+ assert "input_items" not in migrated.metadata["responses"]
+ assert migrated.metadata["custom"] == "keep"
old = history.Message.from_dict({"_cls": "Message", "ai": False, "content": "old"}, restored)
assert old.metadata == {}