Multi-Step Agents and Error Handling
- Check call_result.isError in the agent loop and log tool errors without crashing the loop
- Handle json.JSONDecodeError from a malformed tool_call and inject a correction message so Hermes retries
- Persist and reload conversation history across sessions by saving only user and assistant turns to a JSON file
- Connect to a remote HTTP MCP server by substituting streamable_http_client for stdio_client in the server connection code
How Hermes Handles Tool Errors
When a tool raises an exception, FastMCP returns the error message as a tool result with isError: true. The agent code from Lesson 10 injects this back into the conversation the same way it injects a successful result. Hermes reads the error message and can recover — if the error message is actionable, the model will often correct its arguments and retry.
Example of a recoverable error sequence:
- Hermes calls
get_notewithnote_id: 99 - The notes server raises
ValueError("Note 99 does not exist. Call list_notes to see available IDs.") - The agent injects:
<tool_response>{"name": "get_note", "content": "Note 99 does not exist. Call list_notes to see available IDs."}</tool_response> - Hermes reads the error, calls
list_notes, sees that ID 3 exists, then callsget_notewithnote_id: 3
This works because the error message is a recovery instruction. Write your tool error messages this way — tell the model what went wrong and what to do next, not just what failed.
To detect and log tool errors in the agent loop, check call_result.isError:
call_result = await session.call_tool(tool_name, arguments=tool_args)
if call_result.isError:
print(f"[tool error] {tool_name}: {call_result.content[0].text if call_result.content else 'unknown'}")
tool_result = call_result.content[0].text if call_result.content else "No output."
Log the error but continue — inject the error message as the tool response and let Hermes decide what to do.
Handling Malformed Tool Calls
Hermes occasionally produces a malformed <tool_call> block — JSON with a syntax error, a missing field, or extra text mixed into the JSON. The parse_tool_call function from Lesson 10 will raise a json.JSONDecodeError in these cases.
Catch it and inject an error message that guides the model to retry:
def parse_tool_call(text: str) -> dict | None:
match = re.search(r"<tool_call>s*({.*?})s*</tool_call>", text, re.DOTALL)
if not match:
return None
try:
return json.loads(match.group(1))
except json.JSONDecodeError as e:
return {"_parse_error": str(e), "_raw": match.group(1)}
Then in the agent loop, check for _parse_error and inject a correction message:
tool_call = parse_tool_call(response)
if tool_call and "_parse_error" in tool_call:
# Inject a correction so Hermes retries with valid JSON
messages.append({
"role": "user",
"content": (
"The tool call you generated contained a JSON syntax error. "
"Please retry with valid JSON inside the tool_call tags."
),
})
continue
Malformed calls are uncommon with temperature 0.1 and a clear system prompt, but they happen. This handling prevents a parse error from crashing the agent.
Conversation Memory Across Sessions
The agent in Lesson 10 starts fresh every run — it has no memory of previous conversations. For a research assistant, this means the agent cannot answer "summarise what I found last week" without re-reading files.
The simplest memory approach is to persist the conversation history to a JSON file and reload it on startup:
HISTORY_FILE = "conversation_history.json"
def load_history() -> list:
try:
return json.loads(Path(HISTORY_FILE).read_text())
except (FileNotFoundError, json.JSONDecodeError):
return []
def save_history(messages: list) -> None:
# Save only user and assistant turns (not system or tool messages)
persistent = [m for m in messages if m["role"] in ("user", "assistant")]
Path(HISTORY_FILE).write_text(json.dumps(persistent[-50:], indent=2))
Load the history at the start of run_agent and insert it between the system message and the new user message:
history = load_history()
messages = [
{"role": "system", "content": system_prompt},
*history,
{"role": "user", "content": user_query},
]
At the end of the run, save the updated history. The [-50:] slice keeps only the last 50 turns to prevent the context window from filling up over time.
Important: do not persist tool messages in the history file. They reference tool calls and results from a specific session; replaying them in a new session confuses the model. Only user and assistant messages carry useful context across sessions.
Connecting to Remote MCP Servers Over HTTP
Some MCP servers run remotely over Streamable HTTP rather than stdio. The connection pattern is different but the rest of the agent code stays the same.
Using the MCP Python SDK's HTTP client:
from mcp.client.streamable_http import streamable_http_client
async with streamable_http_client(
url="https://mcp.example.com/mcp",
headers={"Authorization": "Bearer your-api-key"},
) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools_result = await session.list_tools()
To add a remote server to the agent's SERVERS list, change the entry format:
SERVERS = [
# ... existing local servers ...
{
"name": "github",
"transport": "http",
"url": "https://api.githubcopilot.com/mcp",
"headers": {"Authorization": "Bearer ghp_xxxx"},
},
]
Update connect_servers in the agent to check the transport key and use streamable_http_client instead of stdio_client when it is set to "http". The session and tool discovery code is identical — only the transport differs.
Debugging Slow or Stuck Agents
If the agent hangs without output, the likely causes are:
- Ollama not running: the
requests.postcall hangs on connection. Checkollama listand restart Ollama if needed. - Server not starting:
stdio_clientspawns the server process, but if the process exits immediately (a Python error in your server), the client hangs waiting for a response. Add a startup check: run the server in a terminal separately to see if it starts cleanly. - Infinite tool loop: Hermes keeps calling tools without a final answer. Add debug prints to the loop to see what it is calling. Usually caused by a tool that always returns an error, or tools with names so similar the model keeps trying them in a loop. Check the tool descriptions for ambiguity.
- Context exhaustion: the conversation history is too long and Ollama is truncating earlier turns. Increase
num_ctxin the Modelfile or trim the history.
Add a --debug flag to the agent that prints the full conversation history at each turn. This shows exactly what Hermes sees and is the most direct way to understand unexpected behaviour.
- Tool error messages should be recovery instructions — tell the model what went wrong and what to call next, not just the exception text
- Only persist user and assistant messages in the history file — tool messages reference session-specific tool calls and confuse the model when replayed in a new session
- The [-50:] slice on saved history prevents context exhaustion over long-running conversation files — adjust based on your context window size
- A stuck agent is almost always one of four things: Ollama down, server failing to start, infinite tool loop, or exhausted context — add debug prints to the loop to distinguish them quickly
Progress is saved in this browser only — clear your cache or switch device and it's gone. Create a free account and it follows you everywhere.