Design Principles

Good agent design is mostly about constraint. The most reliable agents are not the most flexible ones. They are the ones with a clear goal, explicit boundaries, and predictable recovery behavior.

Principles

Keep the task narrow

One agent should own one coherent business responsibility. If you cannot explain the job in a short sentence, the scope is probably too broad.

Prefer deterministic boundaries

Make side effects happen in explicit steps. Keep data gathering, reasoning, and acting separate so you can observe and recover each phase cleanly.

Design for retries and replay

Assume a step may be resumed. Avoid hidden mutable state and make repeat execution safe or clearly detectable.

Limit access on purpose

Grant only the tools, triggers, and data scopes the agent actually needs. Smaller surfaces are easier to reason about and safer to operate.

Escalate when uncertainty matters

If the cost of a wrong action is high, the agent should prepare a recommendation or request approval, not silently execute.

Make outputs easy to inspect

Return structured, reviewable outputs instead of dense free-form text whenever downstream systems or people need to trust the result.