LangChain Sub-Agent Errors: Which Boundary to Check

When a LangChain sub-agent fails, the first boundary to check is the data contract between the parent agent and the sub-agent: the exact structure and content of the input you pass and the output you expect. Most errors trace back to a mismatch here—missing keys, wrong types, or unexpected values—rather than to the sub-agent’s internal logic. This article explains the boundaries you should inspect, how to diagnose failures systematically, and what to fix first.

Background: How Sub-Agents Fit in LangChain

LangChain lets you build agents that can call tools, and one of those tools can be another agent—a sub-agent. The parent agent decides when to delegate, passes a task to the sub-agent, and receives a result. This pattern is common for breaking complex tasks into smaller, focused steps, like researching a topic and then writing a summary.

The key thing to understand is that a sub-agent is just a tool from the parent’s perspective. It has a name, a description, and an input schema. When the parent calls it, it passes a string (usually a JSON object) and expects a string back. Any error in that exchange breaks the chain.

How the Boundaries Work

There are four main boundaries where errors originate:

• Input boundary: What the parent sends to the sub-agent. This must match the sub-agent’s expected input format (e.g., a JSON with specific keys).
• Output boundary: What the sub-agent returns. It must be a string that the parent can parse or use directly.
• Execution boundary: The sub-agent’s internal run—its own LLM calls, tool usage, and loops. Errors here are usually due to bad prompts or tool failures inside the sub-agent.
• State boundary: How the sub-agent’s result is stored and passed along. If the parent expects a specific variable name or type, a mismatch causes downstream errors.

Each boundary has its own failure modes. The input boundary fails when the parent sends the wrong structure (e.g., a plain string instead of a JSON object). The output boundary fails when the sub-agent returns something the parent can’t parse (e.g., a list instead of a string). Execution errors are trickier because they happen inside the sub-agent and may not be visible unless you enable verbose logging.

How to Choose Which Boundary to Check First

Start by reading the error message. LangChain errors often include the sub-agent’s name and the tool call that failed. If the error says something like “Invalid input to tool” or “Expected JSON object but got string,” it’s an input boundary issue. If it says “Could not parse output” or “Output did not match schema,” it’s an output boundary issue.

If the error is vague, check the execution boundary by running the sub-agent in isolation with a test input. This tells you whether the sub-agent itself works. If it works alone but fails when called by the parent, the problem is likely in the input or output boundary.

Finally, check the state boundary by inspecting the parent’s memory or context after the call. Sometimes the sub-agent returns a valid result, but the parent tries to use it in a way that doesn’t match (e.g., expecting a number but getting text).

Common Problems and Misconceptions

A frequent misconception is that sub-agent errors are always due to the LLM’s reasoning. In reality, most are structural. For example, a parent might send a task like “Summarize the report” without including the report content—the sub-agent then fails because it has nothing to work with. This is an input boundary issue, not a reasoning problem.

Another common issue is output parsing. Sub-agents often return a JSON string, but if the parent expects a plain string, it may try to parse it and fail. This is an output boundary mismatch.

Also, beware of silent failures: the sub-agent might return a string like “I couldn’t find the data” instead of a structured error. The parent might treat that as a successful result and continue, leading to downstream errors that are hard to trace.

Comparing Sub-Agent vs. Tool Errors

Sub-agents are more complex than regular tools. A regular tool has a fixed input schema and returns a fixed output. A sub-agent is an LLM-driven agent, so its behavior is probabilistic. This means errors are less predictable and often require more debugging.

When you use a regular tool, you know exactly what it will return. With a sub-agent, you must validate the output more carefully. Some developers prefer to wrap sub-agents in a function that enforces a strict output schema, converting any unexpected result into a clear error message.

Cost is another difference—sub-agents use more tokens because they involve multiple LLM calls. If you have a tight budget, consider whether a regular tool could do the job instead.

Safety and Best Practices

To minimize errors, follow these practices:

• Always define a clear input schema for the sub-agent and ensure the parent sends exactly that.
• Use a structured output parser (like Pydantic) to validate the sub-agent’s result.
• Enable verbose logging to see the sub-agent’s internal steps.
• Set a timeout and max iterations to prevent infinite loops.
• Test the sub-agent in isolation before integrating it.

Also, be careful with sensitive data. Sub-agents may pass data to external LLM providers, so avoid sending personal or confidential information unless you have appropriate safeguards.

Frequently Asked Questions

Why does my sub-agent fail only when called by the parent, not alone?

This usually indicates an input or output boundary issue. The parent might be sending the wrong format, or the sub-agent’s output doesn’t match what the parent expects. Run the sub-agent alone with the exact input the parent sends, and inspect the output format.

How do I get the sub-agent to return a specific structure?

Use a structured output parser. Define a Pydantic model for the expected output and pass it to the sub-agent’s output parser. This forces the sub-agent to return a valid structure or raise a clear error.

What does “Could not parse tool input” mean?

It means the parent agent tried to call the sub-agent tool, but the arguments it generated didn’t match the tool’s input schema. Check the parent’s prompt and the tool’s description to ensure the agent knows the correct format.

Can a sub-agent call another sub-agent?

Yes, but this adds more boundaries and potential failure points. Each level needs its own input/output validation. It’s often better to flatten the hierarchy unless absolutely necessary.

How do I debug a sub-agent that returns an empty string?

Check the sub-agent’s execution boundary first. It might be failing silently due to a tool error or an empty LLM response. Enable verbose logging and run the sub-agent with a simple test input to see what’s happening.

Is it better to use a sub-agent or a regular tool?

Use a regular tool when the task is deterministic and has a fixed input/output. Use a sub-agent when the task requires reasoning or multiple steps. Sub-agents are more flexible but cost more and are harder to debug.

Related

• Older Flagship vs Newer Midrange Chip: Which to Choose?
• Word AI Summarize: What It Does and How to Use It
• Deezer AI Music Filtering: What It Blocks and What It Doesn’t

in in_msg | Input message | text | "Summarize the attached report" | 0 | 10000
in sub_tool | Sub-agent tool name | text | "research_tool" | 0 | 100
in max_retries | Max retries | - | 2 | 0 | 10
out boundary | Boundary to check | - | "Data contract" | 0