Tool Call Error Handling and Validation

Hello! Welcome to the next lesson in our journey to build capable AI agents.

In our last session, we built a multi-step tool chain, enabling our agent to tackle complex queries by sequencing tool calls. We focused on the "happy path," where every tool works perfectly, and every LLM output is exactly as expected. But as any experienced software engineer knows, the real world is rarely that clean.

Today, we'll address the "unhappy path." What happens when a tool fails because an external API is down? What if the LLM hallucinates non-existent arguments for a function call? Our goal is to make our agent resilient to these inevitable issues.

This lesson directly addresses the learning outcome: Implement error handling and validation for tool call results. You'll find that many of the principles here are direct applications of robust software engineering practices you already use, adapted for the unique challenges of working with probabilistic LLMs.

Why Error Handling is Crucial for Agents

LLM-based agents are inherently non-deterministic. Unlike a traditional program that produces the same output for the same input, an LLM's response can vary. This non-determinism, combined with reliance on external tools and APIs, creates multiple potential points of failure.

Let's start by watching a short video that frames this problem. While it discusses non-determinism broadly, it correctly identifies that the real concerns are response quality and debugging—both of which are addressed by robust error handling and validation.

Categorizing Failure Modes

To handle errors effectively, we first need to understand where they come from. In an agentic system, failures can occur at multiple levels.

The article below provides an excellent breakdown of common error sources.

As the article outlines, errors generally fall into these buckets:

1. Input Issues: The LLM provides malformed arguments to a tool (e.g., a string instead of an integer, an invalid format). This is a very common failure mode due to the creative nature of LLMs.
2. Execution & External Service Issues: The tool itself fails during execution. This could be due to a network timeout, a 404 error from an API, failed authentication, or a rate limit being exceeded.
3. Internal Logic/Resource Errors: Classic software bugs within your tool's code or an inability to access a local resource (like a file not found).

Now, let's explore the strategies to handle these, starting with the most proactive approach: validation.

Proactive Defense: Validating LLM Outputs with Pydantic

Many errors can be caught before a tool even executes by validating the inputs the LLM provides. Forcing the LLM's output to conform to a strict schema is one of the most powerful techniques for building reliable agents. In the Python ecosystem, Pydantic is the go-to library for this.

The following image provides a high-level overview of how Pydantic acts as a validation layer between the often-messy output of an LLM and your structured application code.

Now, let's see this in action. The instructor library, paired with Pydantic, provides a powerful and elegant way to not only validate LLM outputs but also to automatically guide the LLM to correct its mistakes.

This approach of defining a schema with Pydantic and using a library like instructor is a best practice for handling input issues. It prevents your tools from ever being called with malformed data.

Reactive Defense: Robust In-Tool Error Handling

Validation is great, but it can't prevent all errors. A perfectly valid API call can still fail due to network issues or server-side problems. This is where reactive error handling—writing your tool code defensively—comes in.

The core principle is to catch exceptions within your tool and return a descriptive error message to the LLM agent. Crashing the agent is unhelpful. Providing it with information about the failure allows it to potentially retry, try an alternative tool, or inform the user.

This next article provides a comprehensive guide with a clear pseudocode example that should be very familiar from a general software engineering perspective.

To summarize the key takeaways for your tool's implementation:

• Wrap critical code in try...except blocks. Catch specific exceptions like NetworkTimeout or generic ones.
• Return structured error messages. Instead of just {"error": "Something went wrong"}, return something the LLM can parse, like: {"success": False, "error": {"type": "APIFailure", "message": "The weather service returned a 503 Service Unavailable error. You could try again in a few minutes."}}.
• Implement retries for transient errors. For network glitches or temporary service overloads, a simple retry loop with exponential backoff can make your agent much more resilient. The tenacity library in Python is excellent for this.
• Log detailed technical errors for yourself. While the LLM gets a user-friendly error, your logs should contain the full stack trace for debugging.

A Holistic Approach to Reliability

Effective error handling isn't about a single technique; it's a layered strategy that combines proactive validation, reactive error handling, and good software engineering discipline.

The video from Google Cloud Tech connects these ideas back to fundamental development practices.

Finally, as a developer, you know that reliability is also a function of good testing. Building agents requires a shift in testing mindset, away from purely deterministic unit tests and towards testing for behavioral properties, including how the agent handles failure.

Conclusion

In this lesson, you've learned how to move beyond the "happy path" and build resilient, robust AI agents that can handle real-world failures.

Key Takeaways:

• Categorize Errors: Agent failures can stem from invalid LLM inputs, tool execution errors, or external service problems.
• Validate Proactively: Use schema validation libraries like Pydantic to enforce structure on LLM outputs, catching malformed data before it causes problems.
• Handle Reactively: Write defensive tool code using try...except blocks to catch runtime errors.
• Inform the Agent: When a tool fails, it should return a structured, descriptive error message to the LLM, not crash. This allows the agent to reason about the failure and decide on a next step (e.g., retry or inform the user).
• Embrace Engineering Principles: Building reliable agents relies on familiar software engineering practices like logging, retries with exponential backoff, timeouts, and comprehensive testing for failure modes.

You are now equipped to build agents that are not only capable but also dependable.

In the next module, we'll shift our focus slightly. Having built a strong conceptual and practical foundation for how LLMs work and how agents reason, we will begin exploring how to interact with them programmatically through APIs and master the art of prompt engineering.