Skip to main content

Best Practices - Tips for Optimal Agents

This guide shows you proven methods to optimally configure your agents, save costs, and achieve the best results.

🎯 Writing Instructions​

1. Be Specific, Not Vague​

❌ Bad:

Be helpful and answer questions.

✅ Good:

You are a product advisor.
Ask 2-3 targeted questions (budget, size, color).
Present maximum 4 products with reasoning.
Respond in 3-5 sentences.

2. Use Structure & Lists​

❌ Bad:

You should help customers and recommend products and contact support for problems and be polite.

✅ Good:

TASK:
- Help customers with product selection
- Give suitable recommendations

BEHAVIOR:
- Polite and friendly
- Maximum 3 questions per response

FOR PROBLEMS:
- Refer to support: support@shop.com

3. Give Concrete Examples​

✅ Very good:

EXAMPLE DIALOGUE:
Customer: "I'm looking for a jacket"
You: "Great! For what occasion? [BUTTON:Everyday] [BUTTON:Sports] [BUTTON:Business]
And what price range? [BUTTON:Up to $50] [BUTTON:Up to $100]"

Examples help the AI tremendously in understanding the desired behavior!

4. Mention Tools Explicitly​

✅ Recommended:

TOOL USAGE:
- At beginning: Call get_product_properties() ONCE
- For searches: Use product_search(query, filters)
- For details: Use get_product_details(productId)
- NEVER guess tools - only use activated tools

5. Define Do's & Don'ts Clearly​

✅ Very helpful:

MUST:
- Always ask about budget
- Show maximum 4 products at once
- Ask when unsure

MUST NOT:
- Promise discounts
- Invent prices
- Store personal data

🛠️ Tool Selection​

1. Less is More​

Rule of thumb: Only activate tools you really need!

Why?

  • Each tool increases complexity
  • Longer response times
  • Higher token costs
  • More error sources

Example: Product Advisor

✅ Needed:
- get_product_properties (load filters)
- product_search (search)
- get_product_details (details)
- get_chatbot_name (name)

❌ Unnecessary:
- get_order_status (product advisor doesn't do this)
- fetch_url (not needed)
- get_unresolved_logs (only for backend)

2. Avoid Redundancy​

Example: If you have get_product_properties active, you DON'T need:

  • get_categories (already included in product_properties)
  • get_manufacturer (already included in product_properties)

3. Document Tool Usage​

Note in instructions:

You have access to:
1. get_product_properties - Call once at beginning
2. product_search - For every product search
3. get_product_details - For details about 1 product

💰 Optimize Costs​

1. Choose the Right Model​

Cost comparison (per 1M input tokens):

gpt-4o-mini:  $0.15  (CHEAP) ✅
o4-mini:      $1.00
gpt-4o:       $2.50  (EXPENSIVE)
gpt-5:        $5.00  (VERY EXPENSIVE)

Recommendation: Start with gpt-4o-mini. Only upgrade when necessary!

2. Use Token Caching​

The system caches automatically! But you can optimize:

✅ Cache-friendly:

- Stable instructions (don't change constantly)
- Reuse same system prompts
- get_product_properties() only 1x per session

Savings: 50-90% of costs on repeated requests!

3. Limit Max Output Tokens​

Without limit: Agent can respond with 2000+ tokens
With limit (500): Max 500 tokens
→ Cost savings: Up to 75%!

Set in agent config:

Max Output Tokens: 500 (for FAQ/Service)
Max Output Tokens: 800 (for product advisor)
Max Output Tokens: 1500 (for content)

4. Shorten Instructions (But Not Too Much!)​

Find balance:

❌ Too short (100 characters):
"Be helpful"
→ Poor results

✅ Optimal (800-1500 characters):
Clear, structured, with examples
→ Good results, acceptable costs

❌ Too long (5000+ characters):
Novels with many details
→ High costs, AI loses focus

5. Adjust Reasoning Effort​

low:    Fast + cheap, but simpler
medium: Balanced ✅ (RECOMMENDED)
high:   Slow + expensive, but best quality

When to use high?

  • Only for complex analyses
  • Content creation
  • Critical decisions

When to use low?

  • Simple FAQ
  • Order status checks
  • Simple product searches

⚡ Optimize Performance​

1. Low Temperature for Consistency​

FAQ bot:          0.3 (very consistent)
Customer service: 0.5 (some variation)
Product advisor:  0.7 (natural)
Content:          1.0 (creative)

Less variation = Faster decision = Faster response

2. Use Tools in Order​

Define in instructions:

WORKFLOW:
1. FIRST: get_product_properties() (only 1x!)
2. THEN: product_search() with filters
3. OPTIONAL: get_product_details() for 1-2 products

3. Avoid Too Many Tool Calls​

❌ Inefficient:

Agent calls:
1. get_product_properties()
2. product_search(query="jacket")
3. get_product_details(id=1)
4. get_product_details(id=2)
5. get_product_details(id=3)
→ 5 tool calls!

✅ Better:

Agent calls:
1. get_product_properties()
2. product_search(query="jacket", limit=3)
→ 2 tool calls!

In instructions:

Use get_product_details() only for SINGLE products when explicitly asked.
Use product_search() for lists - it already provides basic info!

🎨 User Experience​

1. Keep Responses Short​

✅ Good (3-5 sentences):

I found 3 winter jackets that fit your budget.
The "Arctic Pro" is waterproof and very warm.
The "City Parka" is stylish and suitable for everyday use.
Which one interests you?

❌ Too long (>10 sentences):

I have conducted an extensive search in our inventory...
[5 more sentences]
The first jacket I would like to recommend is the Arctic Pro...
[10 more sentences with all details]

Solution:

In instructions:
"Keep responses short (max. 5 sentences)"

In config:
Max Output Tokens: 500

2. Use Buttons (When Possible)​

In instructions:

Use buttons for frequent options:
[BUTTON:Yes] [BUTTON:No]
[BUTTON:Show more] [BUTTON:Other category]

3. Structure in Responses​

✅ Structured:

I recommend 3 jackets:

1. Arctic Pro ($89)
   - Waterproof
   - Very warm
   - Sporty style

2. City Parka ($79)
   - Water-resistant
   - Everyday suitable
   - Elegant look

Which appeals to you?

❌ Unstructured:

The Arctic Pro costs $89 and is waterproof, very warm and has a sporty style, the City Parka costs $79...

🧠 Knowledge Management​

1. Use search_logs BEFORE Answering​

In instructions:

IMPORTANT: Before answering, ALWAYS call search_logs()!

PROCESS:
1. Customer asks question
2. You call search_logs(query="question")
3. If match found: Use this answer
4. If no match: Answer yourself and save with log()

Advantage:

  • Consistent answers
  • No hallucinations
  • Knowledge DB grows automatically

2. Use Tags Meaningfully​

Good tags:

shipping
returns
payment
product_details
technical
general

Bad tags:

tag1
misc
other

3. Only Public Logs for Customers​

Public (isPublic=true):
- FAQ answers
- General shop info
- Product information

Private (isPublic=false):
- Internal notes
- Problems/bugs
- Improvement suggestions

🔒 Security & Privacy​

1. No Sensitive Data in Instructions​

❌ NEVER:

For problems: Database password is "abc123"
Support credentials: admin/password

✅ Instead:

For problems: Refer to support@shop.com

2. Prohibit Data Disclosure​

In instructions:

PROHIBITED:
- NEVER disclose customer data (email, address, phone)
- NEVER mention complete order details
- NEVER reveal payment information

FOR order status:
- Only status and tracking code
- NO address, NO name, NO products

3. Verification for Sensitive Actions​

For get_order_status:

ALWAYS ask for order number AND ZIP code!

Example:
Customer: "Where is my order?"
You: "Gladly! Please provide your order number and ZIP code for verification."

📊 Testing & Iteration​

1. Define Standard Test Scenarios​

Example: Product Advisor

Test 1: "Hello"
→ Expected: Friendly greeting

Test 2: "I'm looking for a jacket"
→ Expected: 2-3 follow-up questions (budget, size, occasion)

Test 3: "Black winter jacket, size L, up to $100"
→ Expected: Product search, 2-4 results

Test 4: "What does shipping cost?"
→ Expected: Correct info (from get_meta_information)

Test 5: "Will you give me 20% discount?"
→ Expected: Polite decline

After each change: Run all tests!

2. A/B Testing​

Create 2 versions:

Agent A: Temperature 0.5, gpt-4o-mini
Agent B: Temperature 0.8, gpt-4o-mini

→ Test both
→ Compare quality
→ Choose the better one

3. Analyze Logs​

Regularly check:

- Which questions come frequently?
- Which tools are often used?
- Where does the agent make mistakes?
- How many tokens are consumed?

Basis for optimization!

🚀 Scaling​

1. Multiple Specialized Agents​

❌ One agent for everything:

"Universal Agent"
- 20 tools active
- 3000 character instructions
- Slow, complex, expensive

✅ Multiple specialized agents:

"Product Advisor"
- 5 tools
- 1000 character instructions
- Fast, focused

"Customer Service"
- 6 tools
- 1200 character instructions
- Specific for support

"Order Status"
- 2 tools
- 500 character instructions
- Very fast, cheap

2. Sales Channel-Specific Agents​

Agent "Product Advisor DE"
- German
- Sales Channel: Germany
- Euro prices

Agent "Product Advisor EN"
- English
- Sales Channel: United Kingdom
- Pound prices

3. Create Template Agent​

1. Create a "Template Agent" with good base config
2. For new agents: Copy instructions manually
3. Adapt for specific purpose
4. Saves time and ensures quality

📝 Documentation​

1. Use Description Field​

In each agent:

Product advisor for winter clothing

CREATED: 2025-01-15
RESPONSIBLE: Marketing Team
LAST UPDATE: 2025-01-20

VERSION 1.0:
- Base setup

VERSION 1.1:
- Temperature from 0.7 to 0.5 (more consistent)
- Tool "get_delivery_times" added

VERSION 1.2:
- Instructions extended: Button usage

2. Version Changes​

Instructions v1.2 (2025-01-20)

CHANGES from v1.1:
- Added: Explicit tool mentions
- Removed: Emoji usage
- Optimized: Shorter answers (max 5 sentences)

3. Measure Success​

Track KPIs:
- Average response time
- Tokens per conversation
- Cost per conversation
- Success rate (leads to sale/solution?)
- User satisfaction

✅ Checklist: Optimal Agent​

Use this checklist for quality control:

Instructions:

  • Specific, not vague
  • Structured (lists, headings)
  • With concrete examples
  • Tools explicitly mentioned
  • Do's & don'ts defined
  • Length: 800-2000 characters

Tools:

  • Only needed tools active
  • No redundancies
  • Documented in instructions

Parameters:

  • Appropriate model (start: gpt-4o-mini)
  • Temperature sensible (0.5-0.8)
  • Max output tokens set (optional)
  • Reasoning effort: medium

Performance:

  • Response time < 10 seconds
  • Cost per conversation < $0.05
  • Token caching active (visible in logs)

Quality:

  • Test scenarios defined
  • All tests passed
  • Logs analyzed
  • No hallucinations

Security:

  • No sensitive data in config
  • Verification for critical actions
  • Privacy rules defined

Documentation:

  • Description filled out
  • Changes versioned
  • KPIs measured

Summary: Top 10 Tips​

  1. Start with gpt-4o-mini - Upgrade only when needed
  2. Instructions: Specific & structured - With examples!
  3. Only activate necessary tools - Less is more
  4. Set max output tokens - Saves costs
  5. Use search_logs - Prevents hallucinations
  6. Specialized agents - Not one agent for everything
  7. Test, test, test - With standard scenarios
  8. Analyze logs - Basis for optimization
  9. Document - Description & versioning
  10. Iterate - Continuously improve

Next Steps​

➡️ Troubleshooting - When problems occur

➡️ Use Cases - Concrete practical examples

➡️ Cost Management - Costs in detail