Skip to main content

Common Mistakes and Troubleshooting

A lot of the frustration people run into while building their first agents in Agent Builder traces back to a small set of recurring issues. Here's what to watch for, and how to fix each one.

A system prompt that's really a wish list​

It's common to write a system prompt that lists everything you'd like the agent to be capable of, without being specific about how it should handle any single case. The result is an agent that seems capable in a demo but behaves inconsistently once you throw real cases at it. A good system prompt reads more like a policy document for one narrow decision than a job description for an entire role. If you find yourself writing "and also" more than once or twice, that's usually a sign the prompt is trying to cover too much ground.

Adding tools the agent doesn't actually need yet​

It's tempting to connect every tool that might eventually be useful when you're first setting up an agent. The problem is that every tool is something the agent has to reason about at run time, deciding whether it's relevant to the case in front of it. An agent with too many marginal tools tends to pick the wrong one more often, not because the tools are badly built, but because the agent has more room to make the wrong call. Start with only the tools the agent's specific goal actually requires, and add more only once you've confirmed the basics work.

Skipping context grounding, then blaming the model​

If an agent's answers feel generic or disconnected from your actual policies, the first thing to check isn't the prompt. It's whether the agent has a Context Grounding index connected at all. An ungrounded agent can only reason from the case details you give it directly plus the model's general knowledge, which is rarely enough for anything domain-specific. Connecting a real index of your actual policy documents usually fixes this faster than any amount of prompt tweaking.

Vague tool descriptions​

Agent Builder relies on each tool's description to decide when that tool is relevant. A tool described only as "check payment history" gives the agent very little to go on if there are multiple tools that touch payment data. Be specific: what does this tool actually return, and in what situations should it be called versus a similar-sounding tool. Vague tool descriptions are one of the most common causes of an agent calling the wrong tool, or failing to call the right one.

No escalation until something goes wrong in production​

It's easy to treat escalations as a nice-to-have you'll add once the agent is "basically working." In practice, this means the first time an agent encounters a case it genuinely shouldn't decide alone, there's no safety net in place. Add at least one escalation for your highest-stakes action before you test with anything beyond a handful of hand-picked examples, not after.

Testing only in Debug chat with cases you already know the answer to​

Debug chat is great for quick iteration, but if every test case is one you designed the prompt around, you're really just confirming the agent agrees with you, not that it handles the range of cases it'll actually see. Deliberately include ambiguous, incomplete, or unusual cases in your testing, the kind a real user would actually submit, before you trust an agent enough to publish it.

Publishing without a rollback plan​

Once an agent is published to Orchestrator and wired into a Maestro process, changing it isn't as low-stakes as editing a prompt in Studio Web. Before publishing a change to a live agent, know how you'd roll back if the new version performs worse than the old one, and keep your test case set up to date so you can quickly verify a new version against the same cases the old version handled correctly.

Blaming the agent for a process design problem​

Sometimes an agent's decisions look wrong because the process around it is asking it to make a call it doesn't have enough information to make well, not because the agent's reasoning is faulty. If you keep tweaking a prompt without the agent's behavior meaningfully improving, step back and check whether the real fix is adding a tool, connecting better context, or restructuring where in the Maestro process this decision actually belongs.

Where to go from here​

If a specific agent keeps misbehaving in ways this list doesn't cover, it's often worth re-reading Core Concepts with that specific failure in mind. Most persistent issues trace back to one of the five building blocks (prompt, tools, context, escalations, memory) not being set up the way you assumed it was.