Agent Configuration - All Settings in Detail
This guide explains every single setting in the agent configuration and how it affects your agent's behavior.
Overview of Configuration Areas
The agent configuration is divided into several areas:
- Basic Information - Names, description
- AI Model - Which OpenAI model to use
- Instructions - Define behavior
- Tools - Activate functions
- Advanced Parameters - Temperature, Reasoning, etc.
- Resources - Vector Stores, files
- Status & Assignment - Activation, sales channel
1. Basic Information
Technical Name
What is it? A unique identifier for the agent – used in code and APIs.
Format:
- Only lowercase letters (a-z)
- Only numbers (0-9)
- Only underscores (_)
- No spaces, umlauts or special characters
Examples:
✅ product_advisor
✅ customer_service_bot
✅ faq_assistant_2024
✅ order_status_checker
❌ ProductAdvisor (capitals)
❌ FAQ-Bot (hyphen)
❌ Agent #1 (space, special character)
Important: The Technical Name CANNOT be changed after creation!
Display Name
What is it? The name that users see.
Format: All characters allowed – Unicode, emojis, special characters.
Examples:
✅ Product Advisor Max
✅ FAQ Assistant
✅ Customer Service 🤖
✅ Order Status Checker 24/7
Best Practice:
- Choose a friendly, understandable name
- Avoid overly technical names
- Emojis optional (can lighten the perception)
Can be changed anytime: ✅ Yes
Description
What is it? Internal documentation – only visible to administrators.
Maximum length: 500 characters
What to use it for?
- Document agent's purpose
- What tasks does it handle
- Note special features
- For team communication
Example:
Product advisor for the "Clothing" category.
Can:
- Search and filter products by color, size, material
- Give recommendations based on budget
- Explain product details
- Link to product pages
Created: 2025-01-15
Last modified: 2025-01-20
Responsible: Marketing Team
2. AI Model
Model
What is it? The OpenAI model the agent uses.
Available Models in Detail
gpt-4o-mini
Cost: $0.15 / 1M Input Tokens, $0.60 / 1M Output Tokens Speed: ⚡⚡⚡ Very fast (1-3 seconds) Context Window: 128k Tokens
Strengths:
- ✅ Very affordable (10x cheaper than gpt-4o)
- ✅ Fast responses
- ✅ Excellent price-performance ratio
- ✅ Reliable tool calls
Weaknesses:
- ❌ Somewhat less "intelligent" than gpt-4o
- ❌ Can have limitations with very complex tasks
Recommended for:
- Product advisors
- Customer service
- FAQ bots
- Order status checkers
- 90% of all use cases
gpt-4o
Cost: $2.50 / 1M Input Tokens, $10.00 / 1M Output Tokens Speed: ⚡⚡ Fast (2-5 seconds) Context Window: 128k Tokens
Strengths:
- ✅ Very intelligent
- ✅ Better understanding of complex queries
- ✅ More creative and nuanced responses
- ✅ Multimodal (can understand images)
Weaknesses:
- ❌ Significantly more expensive (approx. 17x more than mini)
Recommended for:
- Content creation
- Complex consulting
- Creative tasks
- When gpt-4o-mini isn't sufficient
gpt-5
Cost: ~$5.00 / 1M Input Tokens (experimental) Speed: ⚡ Slow (5-15 seconds) Context Window: 128k Tokens
Strengths:
- ✅ Highest intelligence
- ✅ Excellent reasoning
- ✅ Best quality
Weaknesses:
- ❌ Very expensive
- ❌ Slow
- ❌ Still in beta
Recommended for:
- Only for special applications
- When maximum quality is required
o4-mini
Cost: ~$1.00 / 1M Input Tokens Speed: ⚡⚡ Fast Context Window: 128k Tokens
Strengths:
- ✅ Good reasoning
- ✅ Cheaper than gpt-4o
- ✅ Fast
Recommended for:
- Alternative to gpt-4o
- When more intelligence than mini needed, but cheaper than 4o
Model Selection: Decision Tree
Do you need maximum quality?
├─ Yes → Is budget unlimited?
│ ├─ Yes → gpt-5
│ └─ No → gpt-4o
└─ No → Is fast response important?
├─ Yes → gpt-4o-mini ✅ (RECOMMENDED)
└─ No → o4-mini
Rule of thumb: Start with gpt-4o-mini. Only if you notice the quality isn't sufficient should you switch to a more expensive model.
3. Instructions
General About Instructions
Instructions are the "brain" of your agent. They define:
- How it behaves
- What tone it uses
- How it uses tools
- How it handles problems
Important: The more precise your instructions, the better the results!
System Instructions
What is it? The main instructions that define basic behavior.
When is it loaded? In every conversation – always active.
Structure Recommendation:
# ROLE & TASK
[Who is the agent? What is its purpose?]
# BEHAVIOR
[How should it behave? Tone?]
# TOOL USAGE
[Which tools to use? When?]
# RULES & PROHIBITIONS
[What MUST it do? What can it NOT do?]
# WORKFLOW/PROCESS
[Step-by-step how to proceed?]
# EXAMPLES
[Concrete example dialogues]
Example: Product Advisor
# ROLE & TASK
You are a professional product advisor for our online store "Fashion House Miller".
Your task is to help customers select suitable clothing.
# BEHAVIOR
- Be polite, helpful and patient
- Ask targeted questions instead of just suggesting products
- Respond precisely (max. 4-5 sentences per response)
- Do NOT use emojis
# TOOL USAGE
1. Call get_product_properties() ONCE at the beginning
2. For product searches: Use product_search() with appropriate filters
3. For details about a product: Use get_product_details()
4. For navigation: Use go_to_url()
# RULES & PROHIBITIONS
MUST:
- Always ask about budget ("What price range are you looking at?")
- For clothing, ask about size
- Maximum 2-3 follow-up questions per response (don't overwhelm!)
MUST NOT:
- Promise discounts or negotiate prices
- Invent product features
- Show more than 5 products at once
# WORKFLOW
1. Friendly greeting
2. Ask about need ("What are you looking for today?")
3. Targeted follow-up questions (budget, size, color, occasion)
4. Product search with appropriate filters
5. Present 2-4 options with reasoning
6. Ask if further assistance is desired
# EXAMPLE
Customer: "I'm looking for a jacket"
You: "I'd be happy to help! What occasion do you need the jacket for?
[BUTTON:Everyday] [BUTTON:Sports] [BUTTON:Business]
And what price range? [BUTTON:Up to $50] [BUTTON:$50-100] [BUTTON:Over $100]"
Best Practices:
✅ Be specific ("2-3 questions" instead of "some questions")
✅ Use lists and structure (easier for AI to parse)
✅ Give concrete examples
✅ Mention tools explicitly
✅ Define clear do's & don'ts
❌ Too vague formulations
❌ Contradictions
❌ Too long (> 3000 characters)
❌ Unnecessary details
Init Instructions
What is it? Optional instructions loaded at the beginning of a conversation.
Typical use:
- Define greeting message
- Set context for new conversation
Example: Simple
Hello! I'm Max, your product advisor.
How can I help you today?
Example: With Context
Hello and welcome to Fashion House Miller!
I'm Max, your personal shopping assistant.
I can help you with:
- Product search and recommendations
- Questions about sizes and materials
- Navigation through our categories
What are you looking for today?
Example: With Buttons
Hello! I'm your product advisor.
What are you looking for today?
[BUTTON:Clothing] [BUTTON:Shoes] [BUTTON:Accessories]
Tip: Keep it short! The greeting should be max. 2-3 sentences.
Fallback Instructions
What is it? Optional instructions for error/exception cases.
When is it used?
- Agent cannot answer question
- Tool call fails
- No matching products found
- Unexpected situation
Example: Customer Service
WHEN you cannot answer a question:
1. Apologize politely
2. Explain that you don't have this information
3. Offer to contact a human employee
4. Provide support contact: support@fashionhouse-miller.com
EXAMPLE RESPONSE:
"Sorry, I cannot answer this specific question.
Our support team will be happy to help you: support@fashionhouse-miller.com
Alternatively, you can reach us by phone: 0800-1234567"
Example: Product Advisor
WHEN no matching products are found:
1. Explain friendly that nothing suitable is currently available
2. Offer alternative search criteria
3. Suggest adding to wishlist or checking again later
EXAMPLE:
"Unfortunately, I currently found no black winter jackets in size XXL under $80.
Would you like to:
- View another price range? [BUTTON:Up to $100] [BUTTON:Up to $150]
- View other colors? [BUTTON:Dark blue] [BUTTON:Gray]
- Add to wishlist and be notified?"
4. Advanced Parameters
Temperature
What is it? Controls the randomness/creativity of responses.
Value range: 0.0 - 2.0
Effect:
| Temperature | Behavior | Example Response to "How are you?" |
|---|---|---|
| 0.1 | Very consistent, almost always the same | "I'm good, thanks. How can I help?" |
| 0.5 | Slightly variable, but predictable | "Good, thanks! What can I do for you?" |
| 0.7 | Balanced - slight variation | "Great! How can I help you today?" |
| 1.0 | Noticeably creative | "I'm doing super! Nice that you're here. What are you looking for?" |
| 1.5 | Very creative, surprising | "Fantastic! 😊 Ready for shopping? What would you like?" |
| 2.0 | Maximum creativity, unpredictable | "Hey! I'm doing great! Let's shop! What do you need?" |
Recommendations by Use Case:
| Use Case | Temperature | Reasoning |
|---|---|---|
| FAQ bot | 0.2-0.4 | Consistent, exact answers |
| Customer service | 0.5-0.7 | Slightly variable, but reliable |
| Product advisor | 0.6-0.8 | Friendly and natural |
| Content creation | 0.8-1.2 | Creative and varied |
| Brainstorming | 1.3-1.8 | Very creative, new ideas |
Default: 0.7 (good middle ground)
Important: Temperature and Top P should NOT be used together – choose one!
Top P (Nucleus Sampling)
What is it? Alternative method to Temperature for controlling predictability.
Value range: 0.0 - 1.0
Difference from Temperature:
- Temperature: Influences probability distribution globally
- Top P: Limits selection to most likely tokens
Recommendation: Leave this field EMPTY if you use Temperature!
Only relevant for advanced users.
Max Output Tokens
What is it? Limits the maximum length of agent responses.
Important: 1 Token ≈ 0.75 words (English)
Conversion:
| Tokens | Approx. Words | Approx. Characters | Example |
|---|---|---|---|
| 100 | ~75 | ~500 | Short paragraph |
| 500 | ~375 | ~2,500 | Medium answer |
| 1000 | ~750 | ~5,000 | Long answer |
| 2000 | ~1,500 | ~10,000 | Very detailed |
Recommendations:
| Agent Type | Max Tokens | Reasoning |
|---|---|---|
| FAQ bot | 300-500 | Short, precise answers |
| Customer service | 500-800 | Medium answers with details |
| Product advisor | 600-1000 | Product descriptions + recommendations |
| Content creator | 1500-2500 | Detailed texts |
Advantages of a limit:
- ✅ Saves costs (output tokens are more expensive than input!)
- ✅ Prevents rambling answers
- ✅ Faster responses
Default: Empty (= no limit)
Reasoning Effort
What is it? Controls how much time/resources the model uses for "thinking".
Available values: low, medium, high
Comparison:
| Effort | Think Time | Speed | Quality | Cost | When to Use |
|---|---|---|---|---|---|
| low | Minimal | ⚡⚡⚡ 1-2 sec. | ⭐⭐ Ok | $ | Simple questions, FAQ |
| medium | Normal | ⚡⚡ 2-5 sec. | ⭐⭐⭐⭐ Good | $$ | Standard (RECOMMENDED) |
| high | Intensive | ⚡ 10-30 sec. | ⭐⭐⭐⭐⭐ Excellent | $$$ | Complex analyses |
Examples:
Low Reasoning:
Customer: "Show me red jackets"
Agent: [Quick search, direct answer]
Medium Reasoning:
Customer: "I'm looking for a jacket for winter in the mountains"
Agent: [Considers: Winter = warm, mountains = weatherproof]
Agent: "I recommend waterproof winter jackets..."
High Reasoning:
Customer: "I need outdoor clothing for a 3-week trekking tour in Patagonia"
Agent: [Deep analysis: Climate, season, layering system, materials]
Agent: [Detailed, thoughtful recommendation with reasoning]
Default: medium (recommended)
Verbosity
What is it? Controls the detail level of responses.
Available values:
- low: Short and concise
- medium: Balanced (default)
- high: Very detailed
Example - Question: "What is a softshell jacket?"
Low Verbosity:
A softshell jacket is a lightweight, breathable jacket for sports and outdoors.
Water-resistant, but not waterproof.
Medium Verbosity:
A softshell jacket is a flexible outdoor jacket that provides protection from wind and light rain.
It's made of elastic material, is breathable and suitable for sports and active movement.
Ideal for moderate temperatures and as a mid-layer in the layering principle.
High Verbosity:
A softshell jacket is a versatile outdoor garment made of multi-layered, elastic material.
It combines wind protection, water resistance and breathability in one piece of clothing.
FEATURES:
- Material: Usually polyester with elastane content
- Water-resistant (DWR coating), but NOT waterproof
- Very breathable through membranes
- Stretch properties for freedom of movement
USAGE:
Ideal for active outdoor activities like hiking, climbing, cycling in moderate weather.
Can serve as outer layer in mild conditions or as mid-layer under a hardshell jacket.
DISTINCTION:
Unlike hardshell jackets, softshell jackets offer less weather protection, but more comfort and breathability.
Recommendations:
| Agent Type | Verbosity | Reasoning |
|---|---|---|
| FAQ bot | Low | Quick, precise answers |
| Customer service | Medium | Sufficient detail without overwhelming |
| Product advisor | Medium-High | Details important for purchase decision |
| Content creator | High | Thoroughness desired |
Default: medium
Response Format
What is it? Defines the format of agent responses.
Available options:
Auto (Default)
- Responses in HTML/text format
- For normal chats
- RECOMMENDED for 95% of cases
JSON Object
- Agent tries to format responses as JSON
- Not guaranteed
- For structured data
Example response:
{
"greeting": "Hello!",
"question": "What are you looking for?",
"options": ["Jackets", "Pants", "Shoes"]
}
JSON Schema
- Enforces a specific JSON structure
- Guarantees structured output
- For API integration
Example schema:
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"}
}
}
}
}
}
When to use which format?
| Format | When to Use | Example |
|---|---|---|
| Auto | Normal chats | Customer service, product advisor |
| JSON Object | Semi-structured data | When flexible structure desired |
| JSON Schema | API integration | Backend-to-backend communication |
5. Resources
Vector Store ID
What is it? The ID of a Vector Store (knowledge database) on OpenAI.
Format: vs_abc123...
What for? Linking uploaded documents (PDFs, text files) with the agent.
Example: You uploaded a PDF with product information → Created vector store → Enter ID here.
More details: See Vector Stores
File Bundle ID
What is it? ID of a File Bundle for additional files.
Rarely used - Vector Stores are the preferred method.
6. Status & Assignment
Is Active
What is it? Turns the agent on/off.
Values:
- ✅ On: Agent is ready to use
- ❌ Off: Agent is deactivated
Important: An agent with "Is Active" = Off will NOT work, even if everything else is correctly configured!
When to deactivate?
- Agent is being revised
- Temporarily out of service
- Test agent that shouldn't go live
Is Default
What is it? Defines whether this is the default agent.
Values:
- ✅ On: This agent is used when no specific agent is requested
- ❌ Off: Normal agent
Only ONE agent should have "Is Default" = On!
Default Sales Channel
What is it? Assigns the agent to a specific sales channel.
When to use?
- Multi-shop setup (e.g., DE, AT, CH)
- Different agents per language
- Different product catalogs
Example:
- Agent "Product Advisor DE" → Sales Channel: Germany
- Agent "Product Advisor EN" → Sales Channel: United Kingdom
Optional: Leave empty = Agent for all sales channels
7. Metadata & Versioning
Config Version
What is it? Version number of the configuration.
Automatically managed - no manual input needed.
Toolchain Version
What is it? Version of the tool implementation.
Automatically managed - no manual input needed.
Created By / Created At
What is it? Who created the agent and when.
Automatically set - no manual input.
Updated At
What is it? Time of last change.
Automatically updated with each save.
Best Practices for Agent Configuration
1. Start Simple, Then Expand
Phase 1: Minimal Configuration
- Basic info
- One model (gpt-4o-mini)
- Few tools (3-5)
- Simple instructions
Phase 2: Test
- Try out in backend chat
- Identify problems
Phase 3: Optimize
- Refine instructions
- Adjust tools
- Tune parameters
Phase 4: Expand
- Add more tools
- Integrate vector store
- More complex instructions
2. Document Changes
Use the "Description" field:
Version 1.0 (2025-01-15):
- Initially created
- Tools: product_search, get_product_details
Version 1.1 (2025-01-20):
- Temperature lowered from 0.7 to 0.5 (too creative)
- Tool "get_order_status" added
- Instructions extended for order status handling
Version 1.2 (2025-01-25):
- Model switched from gpt-4o-mini to gpt-4o
- Reason: Better product recommendations needed
3. A/B Testing
Create two versions of an agent:
- Agent A: Temperature 0.5
- Agent B: Temperature 0.9
Test both and compare quality.
4. Use Templates
Create a "Template Agent" with good basic configuration. For new agents: Copy the instructions manually.
Checklist: Optimal Configuration
Use this checklist for verification:
Basics:
- Technical Name is unique and descriptive
- Display Name is user-friendly
- Description documents purpose and changes
Model:
- Appropriate model chosen (start: gpt-4o-mini)
- Model costs within budget
Instructions:
- System Instructions are specific and clear
- Tools are explicitly mentioned
- Tone defined
- Do's & don'ts established
- Examples included
- Init Instructions present (optional)
- Fallback Instructions present (recommended)
Tools:
- Only needed tools activated
- No redundant tools
Parameters:
- Temperature sensibly chosen (default: 0.7)
- Reasoning Effort appropriate (default: medium)
- Max Output Tokens set (optional, saves costs)
- Verbosity appropriate (default: medium)
Status:
- Is Active = On
- Is Default correctly set
- Sales Channel assigned (if necessary)
Test:
- Tested in backend chat
- Various scenarios played through
- Tool calls verified
- Response quality assessed
Next Steps
You now understand all configuration options!
➡️ Tools & Functions - Detailed tool reference
➡️ Vector Stores - Upload your own documents
➡️ Best Practices - Optimization tips
➡️ Troubleshooting - When something doesn't work