Skip to main content

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:
Enabling too many toolkits can cause:
  • Slower responses
  • Confusion about which tool to use
  • Unnecessary tool calls
  • Higher costs

Explicit Tool Instructions

When agents should use specific tools, say so explicitly:

Reasoning Level Optimization

When to Use Each Level

Signs of Wrong Reasoning Level

Too Low:
  • Answers are superficial
  • Missing important context
  • Not connecting related information
Too High:
  • 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:
  1. Reduce toolkits - Only enable what’s necessary
  2. Lower reasoning - Use Low or Medium for simple tasks
  3. Use Flash models - Gemini Flash is faster than Pro
  4. Simplify instructions - Shorter, clearer instructions process faster

Quality Optimization

To improve output quality:
  1. Use Pro models - Better reasoning capability
  2. Increase reasoning level - More thorough analysis
  3. Add examples - Show exactly what you want
  4. Be specific - Detailed instructions get better results

Cost Optimization

To reduce costs:
  1. Use Auto model selection - System optimizes automatically
  2. Match reasoning to task - Don’t over-reason simple tasks
  3. Minimize tool calls - Explicit instructions reduce unnecessary calls
  4. 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:

A/B Testing Instructions

When optimizing, test variations:
Compare results to see which produces better outcomes.

Troubleshooting Guide

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
Symptoms: Responses take too long, feel sluggish.Solutions:
  • Reduce enabled toolkits
  • Lower reasoning level
  • Switch to Flash model
  • Simplify instructions
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)
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
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

  1. Deploy - Release initial version
  2. Observe - Monitor how users interact
  3. Identify - Find common issues or gaps
  4. Adjust - Modify instructions/configuration
  5. Test - Verify improvement
  6. Deploy - Release updated version
  7. Repeat

Feedback Collection

Gather feedback on:
  • Response accuracy
  • Response usefulness
  • Missing capabilities
  • Confusing outputs
  • Speed/performance
Use this feedback to guide iterations.

Next Steps

Creating Agents

Step-by-step agent creation guide

AI Components

Use agents in automation flows