Agent Best Practices
This guide covers advanced techniques for optimizing your AI agents, common patterns, and troubleshooting approaches.Instruction Design Patterns
The Role-Task-Format Pattern
Structure your instructions with three clear sections:The Guardrails Pattern
Add explicit constraints to prevent unwanted behavior:The Example Pattern
Include examples for complex outputs:Tool Usage Optimization
Minimal Toolkits
Start with the minimum tools needed:| Agent Purpose | Recommended Toolkits |
|---|---|
| Account analysis | Account Data, Activity Data |
| Task management | Account Data, Task Management |
| Outreach drafting | Account Data, Contact Data |
| Full CS workflow | Account Data, Activity Data, Task Management, Communication |
Explicit Tool Instructions
When agents should use specific tools, say so explicitly:Reasoning Level Optimization
When to Use Each Level
| Reasoning Level | Use When | Examples |
|---|---|---|
| Low | Simple lookups, formatting | ”Get Acme Corp’s health score” |
| Medium | Standard analysis, most tasks | ”Summarize Acme Corp’s recent activity” |
| High | Complex reasoning, multi-step | ”Identify churn risk patterns across accounts” |
Signs of Wrong Reasoning Level
Too Low:- Answers are superficial
- Missing important context
- Not connecting related information
- Responses are slow
- Over-analysis for simple questions
- Unnecessary complexity
Common Agent Patterns
The Research Agent
Focused on gathering and synthesizing information.The Action Agent
Focused on executing tasks efficiently.The Advisory Agent
Focused on providing recommendations.Performance Tuning
Speed Optimization
To make agents faster:- Reduce toolkits - Only enable what’s necessary
- Lower reasoning - Use Low or Medium for simple tasks
- Use Flash models - Gemini Flash is faster than Pro
- Simplify instructions - Shorter, clearer instructions process faster
Quality Optimization
To improve output quality:- Use Pro models - Better reasoning capability
- Increase reasoning level - More thorough analysis
- Add examples - Show exactly what you want
- Be specific - Detailed instructions get better results
Cost Optimization
To reduce costs:- Use Auto model selection - System optimizes automatically
- Match reasoning to task - Don’t over-reason simple tasks
- Minimize tool calls - Explicit instructions reduce unnecessary calls
- Review usage patterns - Identify where lower settings work
Error Handling
Graceful Degradation
Add instructions for handling incomplete data:Scope Boundaries
Help the agent know when to redirect:Testing Strategies
Systematic Testing
Test each capability systematically:| Test Category | Example Prompts |
|---|---|
| Happy path | ”Analyze Acme Corp’s account health” |
| Edge cases | ”Analyze an account I just created with no activity” |
| Ambiguity | ”Acme” (multiple possible meanings) |
| Out of scope | ”What’s the weather?” |
| Error conditions | Reference a non-existent account |
A/B Testing Instructions
When optimizing, test variations:Troubleshooting Guide
Agent gives generic responses
Agent gives generic responses
Symptoms: Responses could apply to any account, lack specific data.Solutions:
- Add explicit instructions to cite specific data
- Ensure toolkits are enabled and working
- Add examples showing data-rich responses
- Increase reasoning level
Agent is too slow
Agent is too slow
Symptoms: Responses take too long, feel sluggish.Solutions:
- Reduce enabled toolkits
- Lower reasoning level
- Switch to Flash model
- Simplify instructions
Agent makes things up
Agent makes things up
Symptoms: Includes data or statistics that don’t exist.Solutions:
- Add explicit constraints against fabrication
- Require citation of sources
- Add instruction to say “I don’t have that data”
- Use lower temperature (if configurable)
Agent doesn't use tools
Agent doesn't use tools
Symptoms: Gives generic answers instead of fetching data.Solutions:
- Verify toolkits are enabled
- Add explicit “ALWAYS use [toolkit] to…” instructions
- Reduce the number of toolkits (less confusion)
- Test tools individually
Agent goes off-topic
Agent goes off-topic
Symptoms: Answers questions it shouldn’t, wanders from purpose.Solutions:
- Add clear scope constraints
- Add explicit redirect instructions
- Narrow the agent’s defined role
- Add examples of out-of-scope handling
Iteration Workflow
The Improvement Cycle
- Deploy - Release initial version
- Observe - Monitor how users interact
- Identify - Find common issues or gaps
- Adjust - Modify instructions/configuration
- Test - Verify improvement
- Deploy - Release updated version
- Repeat
Feedback Collection
Gather feedback on:- Response accuracy
- Response usefulness
- Missing capabilities
- Confusing outputs
- Speed/performance
Next Steps
Creating Agents
Step-by-step agent creation guide
AI Components
Use agents in automation flows