Designing reliable agents

Reliable agents are designed around what the platform actually guarantees — per-step retries, one active run at a time, approvals with a one-hour clock — rather than around hope. This page is the accumulated judgment; the mechanics each link out.

Task Agent or Convo Agent?

Choose by trigger. A time or an event — every morning, when a webhook fires, after standup — wants a Task Agent: repeatable plan, recorded runs, no one present. A person with a question wants a Convo Agent: judgment in the loop, the asker’s own credentials, no schedule.

The tell for a wrong choice: a Task Agent whose plan is full of “ask the user” steps should be a Convo Agent — there is nobody there to ask. A Convo Agent whose every chat is the same request verbatim should be a Task Agent — you’ve built a button and are pressing it by hand.

Write the brief like a handoff

The planning agent is a colleague who has never seen your team’s context. The briefs that plan well say four things:

• The goal, with the output named. “Post a summary of yesterday’s new Jira bugs to #triage” beats “keep an eye on Jira.”
• The boundaries. Which projects, which channels, which date ranges — anything you’d correct a new hire on, say now.
• What done looks like. An expected output per step is what makes failure detectable; without it, a wrong answer completes successfully.
• The edge behavior. What should happen when there’s nothing to report? Empty-input behavior is the difference between a quiet agent and a noisy one.

Be equally deliberate about reasoning effort: planning benefits from higher effort; a mechanical fetch-and-post step doesn’t need Max.

Design for the run you’ll actually get

• Small steps with real dependencies. One tool call per step gives retries something precise to retry and the execution log something legible to show. A step that “does three things” fails as one blob.
• Let reads run, gate writes. Agents whose reads are on Allow and writes on Approve run fast and accountable. If every read pauses for approval, the agent will mostly be waiting — and its approvals will be rubber-stamped.
• Respect the approval clock. A pending approval expires in one hour and fails the run. Schedule agents for hours their owner works; don’t fire a write-heavy agent at 2 a.m. and expect the 9 a.m. approval to count.
• Match schedule to duration. One run at a time means a 20-minute plan on a 15-minute schedule is a skip generator. When in doubt, widen the interval — catch-up covers downtime.
• Attachments are reference, not workspace. An attached file is read-only context for every run; agents cannot edit it or return a modified copy. Plans that need to produce a document should produce it through a tool.
• Webhook plans should consume run input explicitly. Mark the steps that use the delivered payload; a run-input plan fired from cron does empty work.

Earn autonomy gradually

The loop that works: run it manually and watch the execution log; schedule it with writes on Approve and live with the approvals for a week; then move the writes that have earned it to Allow — deliberately, one at a time, while someone reads the audit trail. Autonomy is the reward for a legible track record, not the default.