Skip to content

Tool result serialization: handle_tool_call should return JSON string, not dict #254

Closed

Description

@KyoMio

Describe the bug

The agentmemory plugin's handle_tool_call returns raw Python dicts instead of JSON strings. When Hermes is configured with an Anthropic-protocol backend, these dicts get stored as-is in the tool result message content field within the session history. On the next LLM request, the Anthropic API's message validation rejects them:

Failed to deserialize the JSON body into the target type:
messages[N]: content should be a string or a list at line 1 column XXXXX

Once triggered, every subsequent request in that session fails until the session JSON is manually cleaned.

To Reproduce

  1. Connect Hermes Agent to agentmemory via the plugin
  2. Use an Anthropic-protocol LLM provider (provider: anthropic, proxies included)
  3. Call memory_recall / memory_save / memory_search during a conversation
  4. The tool result is stored as a raw dict in session messages
  5. Continue the conversation → 400 bombs

Expected behavior

handle_tool_call should return a JSON string, matching the behavior of native MCP tool handlers. The tool result's content field must be a valid string type.

Root cause

All 4 return statements in plugins/agentmemory/__init__.py → handle_tool_call are raw dicts:

# Before
return {"results": []}
return {"results": items}
return result or {"success": False}
return {"error": f"Unknown tool: {name}"}

# After
return json.dumps({"results": []})
return json.dumps({"results": items})
return json.dumps(result or {"success": False})
return json.dumps({"error": f"Unknown tool: {name}"})

Additional issues

The following method signatures in the same file are incompatible with the Hermes MemoryProvider base class (missing session_id parameter), causing TypeError in gateway multi-session contexts:

  • prefetch(self, query) -> str → missing *, session_id: str = ""
  • queue_prefetch(self, query) -> None → same
  • sync_turn(self, user, assistant) -> None → same

Fix: add *, session_id: str = "" to both the ABC and the implementation.

Environment

  • Hermes Agent gateway (latest)
  • agentmemory v0.9.4 (LaunchAgent via npx)
  • macOS 26.2
  • Python 3.11

Activity

  1. rohitg00 commented on May 9, 2026

    @rohitg00
    Owner

    Confirmed and fixed — PR #255.

    Verified the root cause matches your analysis exactly:

    • All four return paths in handle_tool_call return raw Python dicts.
    • Hermes' tool-result handling stores the return value as the message content field verbatim — when the LLM provider is Anthropic-protocol (or any Anthropic-compatible proxy), the API enforces content is str | list, so a dict 400s on the next request.
    • This is invisible on OpenAI-protocol backends because they coerce more loosely, which is why this only surfaces under your specific stack. Good repro — that's the kind of bug that hides for a while.

    The fix wraps every return in json.dumps(...) and tightens the return-type annotation Any → str on both the abstract base and the concrete class so mypy / type checkers will catch a future regression.

    Cross-checked against agentmemory's own MCP server contract in src/mcp/standalone.ts:

    { type: "text", text: JSON.stringify(payload, null, pretty ? 2 : 0) }

    The Hermes plugin was the outlier — every other agentmemory tool surface (REST, MCP, OpenClaw plugin) already returns JSON strings. After #255 the Hermes plugin matches.

    Re: your secondary note about session_id in hook signatures

    prefetch / queue_prefetch / sync_turn missing the kwarg parameter is already fixed by #252 (merged earlier today). That one went broader — added **kwargs: Any to all seven hooks (prefetch, queue_prefetch, sync_turn, on_session_end, on_pre_compress, on_memory_write, shutdown). **kwargs is a strict superset of *, session_id: str = "" — accepts that exact key plus any future Hermes-passed context kwargs without further patches. Where Hermes passes session_id, the patch also prefers it over the cached self._session_id so multi-session gateway contexts route to the right session.

    Closing this on #255 merge.

  2. added a commit that references this issue on May 9, 2026
    eaecc65
  3. added a commit that references this issue on Jul 20, 2026
    cac8869
  4. added a commit that references this issue on Jul 27, 2026
    4b250ec
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions