Build safe and maintainable agents

After you have defined your problem and quality bar, your goal is to build an agent that is easy to test, safe to operate, and straightforward for others to maintain.

Start small and focused

The most successful agents start with the narrowest possible version of a workflow. A small, well-scoped agent is easier to validate and faster for users to trust.

• Solve one high-value scenario first: Do not try to build an all-in-one assistant immediately.
• Limit tools and branches: Minimize the number of external calls and decision points.
• Use explicit steps: Where predictability is critical, use structured steps rather than relying entirely on open-ended reasoning.

Design for safe write behavior

Actions that modify data like updating a CRM or sending an email require much stronger safeguards than read-only workflows.

Before adding a write action, you must be able to answer:

• Preconditions: What must be true before this action runs?
• Review: How does the user confirm the action? The agent should propose; the user should approve.
• Failure: What happens if the action fails halfway through?
• Rollback: How would we undo the result if needed?

For interactive workflows, follow the Glean model: The agent proposes the work, and the user reviews it before the action executes.

Respect data boundaries

While Glean Agents inherently respect the permissions of the invoking user, you must still build with least privilege in mind.

• Scoped sources: Prefer specific data sources over broad, company-wide access.
• Graceful declines: Design the agent to handle Permission Denied errors clearly, rather than failing silently.
• Clear documentation: Explicitly state which permissions a user needs to get the most out of the agent.

Build for maintainability

The logic of an agent must be understandable to someone other than the original builder. If the design is too opaque, it becomes difficult to update.

• Clear naming: Use descriptive names for the agent, its tools, and its instructions.
• Modularize: If an agent becomes too complex, break major responsibilities into smaller, discrete steps or specialized sub-agents.
• Change logs: Keep a lightweight record of meaningful changes to instructions or data sources so others can follow the evolution of the agent.

Document dependencies

Make it clear exactly what the agent needs to function. Your build notes must specify:

• Read/Write systems: Which apps the agent interacts with, for example, Jira, Slack, Salesforce.
• Action packs: Which specific Glean action packs are required.
• Fallback behavior: What the agent should do if a specific system is offline or unreachable.

Example: The Renewal-Risk Agent

Instead of building a fully autonomous renewal assistant, follow an incremental path:

• Version 1 (Read-Only): The agent reads account notes and support tickets, then generates a risk recommendation for the user to read.
• Version 2 (Interactive Write): Once V1 is reliable, add an action where the agent drafts a renewal plan and asks the user: "Would you like me to save this draft to the CRM?"