Creating Your First Agent - Detailed Guide
This guide will walk you through creating your first AI agent step by step.
- How to create a new agent
- Which settings are important
- How to choose tools wisely
- How to write instructions
- How to test your agent
Preparation
Make sure you have already completed the following steps:
- ✅ Plugin is installed and activated
- ✅ OpenAI API key is configured
- ✅ OpenAI account has credits
If not, please follow the Getting Started guide.
Step 1: Start Agent Creation
1.1 Navigate to Agent Manager
- Log in to the Shopware backend
- Click "5E OAI Agent Manager" in the left navigation
- You'll see the agent overview (list of all agents)
1.2 Create New Agent
- Click "+ Create Agent" in the top right corner
- An empty form will open
- You are now in agent creation mode
Step 2: Basic Information
2.1 Technical Name
The technical name is a unique identifier for your agent.
Rules:
- Only lowercase letters (a-z)
- Only numbers (0-9)
- Only underscores (_)
- No spaces
- No umlauts (ä, ö, ü)
- No special characters
Good Examples:
product_advisor
customer_service
content_checker
faq_bot
order_assistant
Bad Examples:
❌ Product Advisor (spaces, capitals)
❌ FAQ-Bot (hyphens not allowed)
❌ Agent#1 (special characters not allowed)
Recommendation: Choose a name that describes the function. This name will be used later in code/APIs.
2.2 Display Name
The display name is the name that users will see.
All characters are allowed here:
Product Advisor Max
FAQ Assistant
Customer Service Bot 🤖
Order Status Checker
Recommendation: Choose a friendly, understandable name.
2.3 Description
An internal description for documentation (max. 500 characters).
Example:
This agent helps customers with product selection.
It can:
- Search and filter products
- Explain product details
- Give recommendations
- Browse categories
Step 3: Choose AI Model
3.1 Available Models
| Model | Cost* | Speed | Intelligence | Recommendation |
|---|---|---|---|---|
| gpt-4o-mini | $ | ⚡⚡⚡ Very fast | ⭐⭐⭐ Good | ✅ Start here! |
| gpt-4o | $$$ | ⚡⚡ Fast | ⭐⭐⭐⭐⭐ Very good | For complex tasks |
| gpt-5 | $$$$$ | ⚡ Slow | ⭐⭐⭐⭐⭐⭐ Excellent | Only when needed |
| o4-mini | $$ | ⚡⚡ Fast | ⭐⭐⭐⭐ Very good | Alternative to 4o |
*Cost: $ = cheap, $$$$$ = very expensive
3.2 Which Model for Which Purpose?
Product Advisor / Customer Service:
→ gpt-4o-mini (perfect!)
- Cheap, fast, sufficiently intelligent
- Understands customer questions very well
- Can reliably call tools
Content Creation / Review:
→ gpt-4o or gpt-5
- Better text quality
- Deeper understanding
- More creative phrasing
FAQ / Order Status:
→ gpt-4o-mini (more than sufficient!)
- Simple tasks
- Fast responses
- Very cheap
3.3 Select Model in Form
- Find the "Model" field
- Click on the dropdown list
- Select your model (e.g.,
gpt-4o-mini)
Always start with gpt-4o-mini! Only if you notice the answers aren't good enough should you switch to a more expensive model.
Step 4: Activate Tools
Tools are the functions your agent can use. Activate only what you really need!
4.1 Tool Selection Interface
In the form, you'll find the section "Customize Capabilities: Enable Tools as needed".
Here you see all available tools as checkboxes.
4.2 Recommended Tool Sets by Agent Type
🛍️ Product Advisor Agent
Must-have:
- ✅
get_product_properties- Load product filters - ✅
product_search- Search products - ✅
get_product_details- Display product details - ✅
get_chatbot_name- Name for greeting - ✅
go_to_url- Links to products
Optional:
- ⚪
get_delivery_times- Delivery time info - ⚪
get_payment_methods- Payment methods
Not necessary:
- ❌
get_categories(redundant with product_properties) - ❌
get_manufacturer(redundant with product_properties) - ❌
get_order_status(product advisor doesn't need this)
🎧 Customer Service Agent
Must-have:
- ✅
get_meta_information- Shop info (contact, hours, etc.) - ✅
get_chatbot_name- Name - ✅
get_order_status- Check order status - ✅
get_date_time- Current time - ✅
search_logs- Search knowledge base - ✅
log- Save new entries
Optional:
- ⚪
get_faqs- FAQ content - ⚪
get_delivery_times- Delivery times - ⚪
get_payment_methods- Payment methods - ⚪
get_countries- Delivery countries
Not necessary:
- ❌ Product tools (except for product questions)
📝 Content Checker (Backend)
Must-have:
- ✅
fetch_url- Fetch websites - ✅
get_chatbot_name- Name
Optional:
- ⚪
log- Document improvements
Not necessary:
- ❌ All shop/product tools
4.3 Activate Tools
- Scroll through the tool list
- Check the boxes for the tools you need
- Leave unnecessary tools deactivated
Each activated tool:
- Increases complexity
- Extends response times
- Increases token costs
Activate only what's really necessary!
Step 5: Write Instructions
Instructions are the "brain" of your agent. Here you define its behavior.
5.1 Three Types of Instructions
The system offers three separate fields:
- System Instructions - Basic behavior (IMPORTANT!)
- Init Instructions - Greeting at the beginning (Optional)
- Fallback Instructions - For problems (Optional)
5.2 Write System Instructions
The most important field! Here you define the agent's personality and task.
Template for Product Advisor:
You are a friendly and competent product advisor for our online store.
YOUR TASK:
- Help customers with product selection
- Ask targeted questions to understand needs (budget, size, color, purpose)
- Use available tools to find suitable products
- Never give false information - be honest when you don't know something
YOUR BEHAVIOR:
- Be polite, helpful and patient
- Ask maximum 2-3 questions per response (don't overwhelm!)
- Respond precisely, not too long (max. 4-5 sentences)
- Don't use emojis
IMPORTANT RULES:
- ALWAYS use get_product_properties() at the beginning of the conversation
- Use product_search() to search for products
- Use get_product_details() for details about a product
- Never offer discounts or special conditions
- Refer to support for technical problems
EXAMPLE WORKFLOW:
1. Greet friendly
2. Ask about the need ("What are you looking for?")
3. Ask targeted follow-up questions (budget, color, size)
4. Search for suitable products
5. Present 2-4 options with reasoning
6. Offer further assistance
Template for Customer Service:
You are the customer service assistant for our online store.
YOUR TASK:
- Answer questions about orders, shipping, returns, payment
- Check order status on request
- Use the knowledge database (search_logs) BEFORE every answer
- Save new insights in the knowledge database (log)
YOUR BEHAVIOR:
- Be professional, friendly and empathetic
- For problems: Apologize and offer solutions
- Respond clearly and structured
IMPORTANT RULES:
- ALWAYS use search_logs() before answering (avoid hallucinations!)
- For unknown questions: Use log() to save the answer
- For order status: Ask for order number AND ZIP code
- Use get_meta_information() for shop info
- For complex problems: Refer to human support
PROHIBITIONS:
- No promises of discounts
- No commitments for refunds
- No disclosure of personal data
5.3 Init Instructions (Optional)
The first message the agent sends.
Examples:
Product Advisor:
Hello! I'm Max, your product advisor.
How can I help you with product search today?
Customer Service:
Good day! I'm your customer service assistant.
How can I help you?
Short & simple:
Hello! How can I help you?
5.4 Fallback Instructions (Optional)
What to do when the agent can't proceed?
Example:
If you cannot answer the question:
1. Apologize politely
2. Offer to contact a human employee
3. Provide our support email: support@myshop.com
Example response:
"Sorry, I cannot answer this question.
You're welcome to contact our support at support@myshop.com.
Our team will help you quickly!"
5.5 Tips for Good Instructions
DO's:
- ✅ Be specific ("Ask 2-3 questions" instead of "Ask questions")
- ✅ Name tools explicitly ("Use product_search()")
- ✅ Give examples
- ✅ Define clear rules
- ✅ Describe the tone
DON'Ts:
- ❌ Too vague ("Be helpful")
- ❌ Too long (> 3000 characters becomes expensive and confusing)
- ❌ Contradictions ("Be creative" vs. "Always answer the same")
- ❌ Unnecessary details
Step 6: Advanced Settings
6.1 Temperature (Creativity)
Controls the randomness/creativity of responses.
| Value | Behavior | Recommended for |
|---|---|---|
| 0.1-0.3 | Very consistent, little variation | FAQ bots, exact answers |
| 0.4-0.7 | Balanced | Product advisor, customer service ✅ |
| 0.8-1.2 | Creative, variable | Content creation |
| 1.3-2.0 | Very creative, unpredictable | Brainstorming, storytelling |
Default value: 0.7 (recommended for most cases)
6.2 Top P (Alternative to Temperature)
Nucleus Sampling - alternative method to control predictability.
Recommendation: Leave this field empty! If you use Temperature, you don't need Top P.
6.3 Max Output Tokens
Limits the maximum length of responses.
Recommended values:
- Short answers: 500 Tokens (approx. 375 words)
- Medium answers: 1000 Tokens (approx. 750 words)
- Long answers: 2000 Tokens (approx. 1500 words)
Default value: Leave empty (= no limit)
A limit saves costs and prevents overly long, rambling answers!
6.4 Reasoning Effort
How much time should the model "think"?
| Value | Speed | Quality | Cost | Recommendation |
|---|---|---|---|---|
| low | ⚡⚡⚡ Very fast | ⭐⭐ Ok | $ Cheap | Simple questions |
| medium | ⚡⚡ Fast | ⭐⭐⭐⭐ Good | $$ Medium | Standard ✅ |
| high | ⚡ Slow (10-30s) | ⭐⭐⭐⭐⭐ Excellent | $$$ Expensive | Complex tasks |
Default value: medium (recommended)
6.5 Verbosity (Detail Level)
How detailed should answers be?
- Low: Short and concise
- Medium: Balanced (default)
- High: Very detailed
Recommendation: Medium
6.6 Response Format
How should the response be formatted?
| Format | Description | Recommendation |
|---|---|---|
| Auto | HTML (default) | ✅ For chats |
| JSON Object | Attempts to generate JSON | For structured data |
| JSON Schema | Enforces JSON structure | For API integration |
Default value: Auto (recommended for most cases)
Step 7: Sales Channel & Status
7.1 Assign Sales Channel (Optional)
If you have multiple sales channels (e.g., DE, AT, CH):
- Find the "Default Sales Channel" field
- Select a sales channel
- Or leave it empty for "All channels"
7.2 Activate Agent
Important! Set these options:
- Is Active: ✅ On (otherwise the agent won't work!)
- Is Default: ✅ On (if this should be your main agent)
An agent with "Is Active" = Off will not work, even if everything else is configured correctly!
Step 8: Save
- Scroll up or down
- Find the "Save" button
- Click Save
Your agent has been successfully saved and is now ready to use!
Step 9: Test Agent
9.1 Open Backend Chat
- Click "5E OAI Agent Manager" in the navigation
- Select "Chat" in the menu
- The backend chat will open
9.2 Select Agent
If you have multiple agents:
- There's an agent selection dropdown in the chat
- Select your new agent
- Or: Default agent will be loaded automatically
9.3 Perform Test Scenarios
Test 1: Greeting
Input: "Hello!"
Expected: Friendly greeting
Test 2: Simple Question
Input: "What do you sell?"
Expected: Overview of product categories
Test 3: Product Search
Input: "I'm looking for a red jacket"
Expected: Agent asks for details (size, budget)
Test 4: Specific Request
Input: "Show me black winter jackets under €100 in size L"
Expected: Agent searches and shows matching products
Test 5: Tool Test
Input: "What's your name?"
Expected: Agent calls get_chatbot_name() and responds correctly
9.4 Check Quality
Pay attention to:
- ✅ Response time: Should be 1-10 seconds (depending on model)
- ✅ Relevance: Are the answers appropriate?
- ✅ Tone: Is the address correct?
- ✅ Tool usage: Are tools called correctly?
- ✅ Product recommendations: Are they relevant?
9.5 Review Logs (Optional)
- Go to 5E OAI Agent Manager → Logs
- Here you see all conversations
- Check:
- Which tools were called?
- How many tokens were consumed?
- Were there errors?
Step 10: Optimize & Adjust
After the first tests, you'll probably want to make adjustments.
10.1 Edit Agent
- Go to 5E OAI Agent Manager
- Click on your agent in the list
- The edit form will open
- Change instructions, tools, settings
- Save
10.2 Common Adjustments
Answers are too long:
- → Lower temperature (from 0.7 to 0.5)
- → Limit max output tokens (e.g., 500)
- → In instructions: "Keep answers short (max. 3 sentences)"
Answers are too generic:
- → Increase temperature (from 0.7 to 0.9)
- → Choose better model (from mini to 4o)
Agent doesn't call tools:
- → Explicitly mention in instructions: "Use product_search() for..."
- → Increase reasoning effort (from low to medium)
Too expensive:
- → Cheaper model (4o → 4o-mini)
- → Reduce tools
- → Limit max output tokens
Summary: Agent Creation Checklist
Use this checklist for every new agent:
- Technical Name chosen (lowercase_with_underscores)
- Display Name set (friendly name)
- Description written (internal documentation)
- Model selected (start: gpt-4o-mini)
- Tools activated (only needed ones!)
- System Instructions written (behavior defined)
- Init Instructions written (greeting)
- Fallback Instructions written (error handling)
- Temperature set (default: 0.7)
- Reasoning Effort set (default: medium)
- Is Active = ✅ On
- Is Default = ✅ On (if main agent)
- Saved
- Tested in backend chat
- Optimized based on tests
Next Steps
Congratulations! You have successfully created your first agent! 🎉
Now continue with:
➡️ Agent Configuration - All settings in detail
➡️ Tools & Functions - Tool reference
➡️ Vector Stores - Upload your own documents
➡️ Best Practices - Optimization tips