Error Handling

~22 min · tool-errors, recovery

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Robust tool execution requires handling several failure modes: malformed arguments, unknown tools, execution failures, and timeouts.

Key principle: Always return errors as JSON in the tool result — never raise exceptions that terminate the loop. The model can read error messages and adjust its approach, ask the user for clarification, or try a different tool.

Tools fail; the agent recovers

Network blip during get_weather? Don't crash the whole agent — return {"error": "network", "detail": "timeout after 5s"} as the tool result. The model is good at recovery: it might retry, fall back to a different tool, or tell the user what failed. Crashing means none of those options are available.

Security note: a Python traceback can carry API keys, internal hostnames, file paths, even partial query strings. Strip or summarize before returning to the model — the model output is shown to the user. Same hygiene as any user-facing log.

Code

Returning a structured tool error·python

for tc in tool_calls:
    try:
        func = TOOLS_MAP[tc.name]
        result = func(**json.loads(tc.arguments))
        output = json.dumps(result)
    except KeyError:
        output = json.dumps({"error": f"Unknown tool: {tc.name}"})
    except json.JSONDecodeError:
        output = json.dumps({"error": "Invalid JSON in tool arguments"})
    except TimeoutError:
        output = json.dumps({"error": f"Tool {tc.name} timed out"})
    except Exception as e:
        output = json.dumps({"error": str(e), "success": False})

    input_items.append({
        "type": "function_call_output",
        "call_id": tc.call_id,
        "output": output,  # always return JSON, even for errors
    })

External links

Tool error patterns

Exercise

In your tool loop, deliberately raise an exception inside one tool handler. Implement two strategies: (a) crash, (b) catch + return {error,...}. Compare the assistant's downstream behavior in each.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousParallel Function Calling Next →Designing Effective Tool Descriptions

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.