Best Practices for Custom Agents
A well-designed Custom Agent uses fewer resources and delivers better results. The difference between an Agent that works flawlessly and one that produces inconsistent output usually comes down to a handful of design decisions made upfront. This guide walks through how to make each of them well.
Start with the Custom Agents article to understand what they are, how triggers work, and what you can connect them to before diving into optimization.
Foundational Best Practices
Before writing a single line of instructions, a few principles will save you significant iteration time:
- Reserve Custom Agents for recurring work. For one-off questions or tasks, use Closot Agent instead — it's purpose-built for that. Custom Agents run autonomously in the background, which is where their value comes from.
- Use specific triggers. Trigger on a particular
@mentionor a specific property change — not on every message or every database update. The narrower your trigger, the fewer unnecessary runs you'll have. - Keep context tight. Point your Agent at the exact pages or databases it needs. The less it has to read, the faster and more focused each run will be.
- Define "done" in the instructions. Tell your Agent precisely what a completed run looks like. A clear finish line leads to cleaner, faster execution.
- Batch independent tasks. If your Agent needs to read from multiple sources, let it do so in parallel rather than sequentially.
Example — batching vs. sequential:
✅ Do this: "Read the Launches database and the #product-feedback Slack channel, then write the weekly digest."
🚫 Not this: "Read the Launches database, then write the weekly digest. Then read the #product-feedback Slack channel and add to the digest."
The first version reads both sources simultaneously. The second forces the Agent to wait and re-run unnecessarily.
Choose a Workflow That's Repeatable
The best starting point for a Custom Agent is a workflow your team repeats regularly and can easily evaluate. The easier it is to judge whether the output is correct, the faster you'll be able to iterate.
Look for workflows that are:
- Repeatable — Compiling weekly reports, triaging incoming Slack messages, generating release notes from a sprint database
- Frequent — Tasks that happen daily or weekly benefit most from automation
- Easy to evaluate — If you can glance at the output and immediately tell whether it's right, you'll iterate quickly
Once you've chosen a workflow, build the simplest possible version first. Get it running reliably before adding more complexity. Once it feels stable, add triggers or schedules to fully automate it.
Write Clear, Goal-Focused Instructions
When instructions are vague, outputs are inconsistent. When instructions are specific and outcome-focused, the Agent can deliver reliably every time.
Start with the Outcome You Want
Describe what the final output should look like rather than listing every micro-step along the way. Let the Agent figure out the path.
Example: "Generate a weekly digest that includes completed deliverables, open blockers, and three priority items for next week."
Include a Real Example
Paste a previous report, a formatted summary, or an example of a correctly triaged request. Concrete examples outperform abstract descriptions every time.
Be Specific About Format and Destination
Tell the Agent exactly where the output should go and how it should be structured.
Example: "Post the digest to #team-updates in Slack and add a copy to the Weekly Reports database under the current week's entry."
Set Simple Boundaries
Clarify what the Agent should do and what it should avoid.
Example: "Update the existing weekly report page — don't create a new one." or "Only respond to messages in #support, not in any other channel."
Handle Edge Cases Explicitly
Don't leave the Agent to guess what to do when there's no data. Tell it.
Example: "If there are no updates to report this week, post 'No updates this week' rather than skipping the post entirely."
Keep Instructions Concise
Shorter instructions tend to produce more consistent results. If your instructions are getting long, it's usually a sign that the workflow should be split into multiple focused Agents rather than one sprawling one.
Decide How Your Agent Should Run
Before configuring triggers, ask yourself: should this Agent run on a fixed schedule, in response to something happening, or both?
Use Schedules for Predictable Work
Choose a schedule when the task should run at a set cadence regardless of what's happening in the workspace. Weekly reports, daily briefings, and monthly summaries are natural fits.
Use Triggers for Responsive Work
Choose a trigger when the task should respond to a specific event — a new bug filed via Slack, a page added to a database, a property value changed. Triggers make your Agent reactive rather than periodic.
Combine Both When Needed
Some workflows have two distinct patterns. For example: a trigger-based Agent that processes new support requests as they come in, paired with a scheduled Agent that compiles a weekly summary of everything that was processed.
Start Small and Scale Up
Begin with a weekly schedule instead of daily. Start with one Slack channel instead of five. Once the output is consistent and the Agent is behaving as expected, increase frequency and scope gradually.
Test and Troubleshoot Your Agent
Skipping testing before activating triggers is the most common mistake in Custom Agent setup. A few minutes of manual testing saves hours of debugging.
Test Before Activating
- Click Run to execute the Agent manually
- Review the output against what you expected
- Only turn on triggers and schedules once the result looks right
Test with a Small Group First
Share the Agent with two or three teammates before rolling it out broadly. Early feedback catches misconfigurations before they affect the whole team.
Expect Multiple Iterations
Most Agents need several test runs to dial in. Refine the instructions based on what the output actually shows, not what you intended the instructions to say. Those are often different things.
Check the Activity Log First
When something goes wrong, the Activity log is your first stop:
- Click the clock icon (or go to the Activity tab) to see what triggered the run
- Review each step the Agent took
- Look for the point where behavior diverged from what you expected
Common Fixes
| Symptom | Likely Cause | Fix |
|---|---|---|
| Incorrect output | Instructions too vague | Add more specificity, examples, and clear output format |
| Missing data | Agent lacks access | Add the relevant pages or databases under Tools and access |
| Failed runs | Permissions gap or unclear instructions | Review access settings and simplify instructions |
Improve Reliability and Performance
Three factors drive most Custom Agent inefficiency: how often it runs, how much it reads, and how many steps it takes to complete a task.
1. Reduce How Often Your Agent Runs
The easiest performance win is eliminating unnecessary runs. Design triggers so the Agent only runs when there's likely something to act on.
Start small, scale gradually:
- Begin with weekly runs before moving to daily
- Cover one channel or workflow before expanding
- Increase frequency only after results are consistently reliable
Use high-signal triggers:
- For Slack: trigger on
@mentionsor a specific emoji reaction, not every message in a channel - For Closot: trigger on a specific property change, not every database update
"No action needed" runs are normal. When the Agent checks the trigger, evaluates the instructions, and determines there's nothing to do — that's efficient behavior, not a problem.
2. Be Intentional About What Your Agent References
The more content an Agent reads, the heavier each run becomes. Keep the scope minimal.
- Point the Agent at the smallest possible set of pages — ideally a single source of truth that links to sub-pages the Agent can pull only if needed
- Avoid broad searches when you know which database or page holds the answer
3. Keep the Number of Steps Low
Each additional step in a run adds work, especially when the Agent needs to execute multiple lookups or searches.
- Write a clear definition of "done" so the Agent stops when it should
- Encourage parallel tool use in your instructions when the sources are independent
Example — parallel vs. sequential reads:
✅ Parallel (faster): "Read the Sprint database, the #eng-updates Slack channel, and the current roadmap page at the same time — these are independent sources."
🚫 Sequential (slower): "Read the Sprint database, then read the #eng-updates Slack channel, then read the roadmap page."
When one step's output is needed as input for the next step — like creating a page and then posting its URL to Slack — sequential ordering is correct. For truly independent reads, always run them in parallel.
4. Watch for Loops and Retries
If your Agent frequently asks multiple follow-up questions, retries the same action, re-reads the same pages, or errors in predictable ways — the instructions or access settings need attention.
- Frequent permission errors (can't respond in a Slack channel, can't access a URL): adjust the Agent's access under Tools and access, or update the instructions to avoid those actions
- Repetitive re-reads: add a clearer stopping condition to the instructions
- Unexpected loops: split the workflow into two separate Agents with distinct, focused jobs