Agent Best Practices

Follow these best practices to build agents that work reliably and efficiently.

Writing Good Instructions

Be Specific and Clear

Check my emails and do something with them.

1. Check Gmail for unread emails from the last 24 hours
2. Filter for emails from addresses ending in @company.com
3. For each email, extract:
   - Sender name
   - Subject line
   - Key action items (if any)
4. Create a numbered list sorted by sender
5. Post the list to Slack channel #company-emails

Use Numbered Steps

Structure instructions as numbered steps:

1. [First action]
2. [Second action]
3. [Third action]
4. [Output/notification]

This helps the AI follow a clear sequence.

Handle Edge Cases

Anticipate unusual situations:

If there are no unread emails, post "No new emails" to Slack.

If there are more than 50 emails, process only the 20 most recent
and note "Showing 20 of X total emails."

If an email has no subject line, use "[No Subject]" as the title.

Include Format Examples

Show what output should look like:

Format each email like this:

**From:** John Smith
**Subject:** Q4 Budget Review
**Summary:** Requesting review of the Q4 budget proposal
**Action:** Review and respond by Friday

---

Choosing the Right Model

When to Use Cheaper Models

• Simple data extraction
• Straightforward formatting
• Basic notifications
• High-frequency tasks

When to Use Premium Models

• Complex analysis
• Important customer communications
• Nuanced writing
• Multi-step reasoning

Reliability Tips

Keep Agents Focused

Build in Error Handling

Add fallback instructions:

If Gmail is unavailable, wait 5 minutes and retry once.

If the Slack post fails, send an email notification instead.

If any step fails, log the error and continue with remaining steps.

Use Appropriate Timeouts

Consider how long your agent needs:

• Simple tasks: 1-2 minutes
• Medium tasks: 3-4 minutes
• Complex tasks: Push toward the 5-minute limit

If consistently hitting timeouts, break into smaller agents.

Test Before Deploying

Always test thoroughly:

1. Test with sample data - Use test mode first
2. Test edge cases - Empty inbox, many items, unusual data
3. Test error scenarios - Disconnect integration, check behavior
4. Monitor initial runs - Watch the first few real executions

Security Best Practices

Principle of Least Privilege

Only enable integrations the agent actually needs:

Email Digest Agent needs: Gmail (read only)
Email Digest Agent doesn't need: Google Drive, GitHub, Slack

Protect Sensitive Data

• Never hardcode credentials in instructions
• Don't log sensitive information
• Be careful with customer data in notifications

Review Agent Actions

Periodically audit:

• What data agents are accessing
• What actions they're taking
• Who has access to agent output

Performance Optimization

Minimize API Calls

Bad: Check Gmail 10 times looking for different things
Good: Fetch all emails once, then filter locally

Process Incrementally

For large datasets:

Instead of: Process all 1000 items at once
Do: Process 100 items per run, track progress

Use Efficient Models

For simple tasks, faster models save time and credits:

• GPT-4o Mini responds in ~1-2 seconds
• GPT-5 may take 10-15 seconds

Cache When Possible

If data doesn't change often:

• Store results for reuse
• Only fetch changed items
• Use incremental sync

Organizing Agents

Naming Conventions

Use clear, descriptive names:

• ✓ "Daily Email Digest"
• ✓ "GitHub PR Reviewer - Main Repo"
• ✓ "Weekly Sales Report"
• ✗ "Agent 1"
• ✗ "test"
• ✗ "email thing"

Use Folders

Group related agents:

• Email agents
• Development agents
• Marketing agents
• Personal agents

Document Purpose

Add descriptions:

• What the agent does
• Why it exists
• Who relies on it
• When it was last updated

Maintenance

Regular Reviews

Monthly, check:

• Are all agents still needed?
• Any consistent failures?
• Any that could be improved?
• Any running too frequently?

Update Instructions

When things change:

• Team member leaves → Update @mentions
• Slack channel renamed → Update channel names
• New requirements → Modify instructions

Archive Unused Agents

Don't delete, archive:

• Preserves history
• Can reactivate later
• Keeps things organized

Common Mistakes to Avoid

1. Overly Complex Agents

Problem: One agent doing too many things Solution: Split into focused, single-purpose agents

2. Missing Error Handling

Problem: Agent fails silently on errors Solution: Add explicit error handling and notifications

3. Too Frequent Schedules

Problem: Running every minute when hourly is fine Solution: Use the minimum frequency needed

4. No Testing

Problem: Deploying without testing Solution: Always test with sample data first

5. Ignoring Failures

Problem: Not investigating failed runs Solution: Set up alerts and review failures promptly

6. Hardcoded Values

Problem: "Post to #sales-team" when channel might change Solution: Use variables and update centrally

Checklist for New Agents

Before activating any agent:

• Instructions are clear and specific
• Edge cases are handled
• Only necessary integrations enabled
• Appropriate model selected
• Schedule/trigger is correct
• Notifications configured
• Tested with sample data
• Tested edge cases
• Name is descriptive
• Description added

Common Questions

Next Steps

• Review monitoring agents
• Explore templates
• Set up triggers