Skip to main content

Getting Started

This guide will walk you through the setup of the OpenAI Agents Manager plugin step by step.

Overview: What to Expect​

You'll be ready in 5 simple steps:

  1. ✅ Install and activate plugin
  2. ✅ Create OpenAI API key
  3. ✅ Enter API key in Shopware
  4. ✅ Create first agent
  5. ✅ Test agent

Time required: Approx. 15-20 minutes

Step 1: Install Plugin​

Installation via Shopware Store​

  1. Log in to the Shopware backend
  2. Navigate to Extensions → My extensions
  3. Search for "OpenAI Agents Manager" or "5 Elements"
  4. Click Install
  5. After installation, click Activate

Installation via Console​

Alternatively, you can install the plugin via command line:

# Install plugin
bin/console plugin:install FelOAIAssistantsManager --activate

# Clear cache
bin/console cache:clear
Plugin successfully installed

After activation, a new menu item "5E OAI Agent Manager" appears in the left navigation of your Shopware backend.

Step 2: Create OpenAI API Key​

To use the plugin, you need an API key from OpenAI.

2.1 Create OpenAI Account (if not already done)​

  1. Visit platform.openai.com
  2. Click Sign Up
  3. Create an account or sign in with Google/Microsoft
  4. Verify your email address

2.2 Add Payment Method​

OpenAI works on a pay-as-you-go basis. You only pay for what you use.

  1. Go to platform.openai.com/settings/organization/billing
  2. Click Add payment method
  3. Add a credit card
  4. (Optional) Set a monthly budget (e.g., €20)
Cost Tip

For a small to medium shop, €10-20 per month is often sufficient. Thanks to token caching (50-90% savings), costs are very manageable!

2.3 Create API Key​

  1. Navigate to platform.openai.com/api-keys
  2. Click + Create new secret key
  3. Enter a name (e.g., "Shopware Production")
  4. Select permissions: All
  5. Click Create secret key
Important: Keep key secure!

The API key is only displayed once! Copy it immediately and store it securely. If you lose it, you'll need to create a new one.

The key looks like this:

sk-proj-aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890...

Copy the complete key to your clipboard.

Step 3: Enter API Key in Shopware​

Now we connect Shopware with your OpenAI account.

3.1 Open Plugin Configuration​

  1. Go to Settings → System → Plugins in the Shopware backend
  2. Search for the plugin OpenAI Agents Manager
  3. Click the three dots (⋮) on the right
  4. Select Configure

3.2 Enter API Key​

In the configuration window:

  1. Find the field "API Key for the Agent Manager"
  2. Paste your copied API key
  3. Click "Test API Key" (if available)
  4. Click Save
API connection established

If everything worked, you'll see a success message. Your Shopware system can now communicate with OpenAI!

3.3 Additional Settings (Optional)​

In the plugin configuration, you'll find additional options:

SettingRecommendationDescription
Enable thread logging✅ OnSaves all chat histories for tracking
Enable usage counter✅ OnCounts tool calls per agent
Search query logging✅ OnLogs agent search queries
Maximum attempts75Number of attempts before abort
Wait time between attempts2 secondsWait time in loop

For the beginning, you can keep the default settings.

Step 4: Create First Agent​

Now we'll create your first agent! We'll start with a simple Product Advisor.

4.1 Open Agent Overview​

  1. Click 5E OAI Agent Manager in the left navigation
  2. You'll see the agent overview (still empty)
  3. Click + Create Agent

Agent Overview

4.2 Enter Agent Name​

Enter an internal name for your agent:

Agent Name (for internal management):

Product Advisor Shop

This name is only displayed in the backend and serves to distinguish multiple agents.

4.3 Instructions - The MCP Interface for Shopware​

What are Instructions?

The Instructions are pre-optimized system prompts that tell the agent how to use the available tools. Together with the tools, you get essentially an MCP (Model Context Protocol) - a structured interface to control your Shopware shop!

The plugin comes with optimized instructions that:

  • ✅ Generate HTML-formatted responses (instead of Markdown)
  • ✅ Intelligent product search with exact matching of categories and properties
  • ✅ Use log system as knowledge database
  • ✅ Handle multilingualism automatically
  • ✅ Implement security protocol (Protocol 712 - no user URLs fetched)

Available Tools (activatable in the next step):

  • get_product_properties() - Retrieve categories, properties, manufacturers
  • product_search() - Search products with filters (price, category, properties)
  • get_meta_information() - Shop metadata
  • search_logs() - Search knowledge database
  • fetch_url() - Secure URL queries
  • More tools for cart, orders, CMS pages, etc.

Workflow Example (from instructions):

User: "I'm looking for a jacket in blue between €50-100"

Agent thinks:
1. get_product_properties() → Fetches available categories & colors
2. product_search(
     query: "Jacket",
     categories: ["Clothing", "Outerwear"],
     properties: ["Color:Blue"],
     price_min: 50,
     price_max: 100
   )
3. Formats results as HTML list with links
Customizable

The instructions are optimized but can be adjusted at any time if you want specific behavior. For starters, we recommend the standard version!

4.4 Select Model​

Choose an AI model:

Recommended for beginners: gpt-4o-mini

  • ✅ Very affordable (approx. 10x cheaper than GPT-4o)
  • ✅ Fast responses (1-3 seconds)
  • ✅ Sufficient for most applications

You can switch to a more powerful model later at any time.

GPT-4o vs. GPT-5 Instructions

The plugin contains optimized instructions for both model generations. GPT-5 models (gpt-5-mini, gpt-5) use advanced reasoning capabilities and more structured tool calls.

4.5 Activate Tools - The MCP Interface​

Tools are the real power of the system! They give the agent structured access to Shopware functions.

Recommended for a Product Advisor agent:

Basic Tools (must activate):

  • ✅ get_product_properties() - Required! Fetches categories, properties, manufacturers
  • ✅ product_search() - Product search with filters
  • ✅ get_chatbot_name() - Bot name for greetings

Extended Product Tools:

  • ✅ get_product_details() - Detailed product info
  • ✅ get_categories() - Category tree
  • ✅ get_manufacturer() - Manufacturer information

Knowledge Database:

  • ✅ search_logs() - Searches your FAQ/knowledge database
  • ✅ tags_for_logs() - Available tags for log search
  • ✅ get_meta_information() - Shop metadata

Optional Tools (depending on use case):

  • fetch_url() - Secure URL queries (only for trusted sources)
  • add_to_cart() - Add products to cart
  • get_cart() - Display cart
  • More CMS & content tools
Important: Tool Order

The instructions are optimized to call get_product_properties() first before a product search. This way, the agent knows which categories and properties exist and can match exactly!

MCP Concept

Model Context Protocol: The combination of Instructions + Tools gives the AI a structured, secure interface to the shop. It can:

  • Retrieve data (get_product_properties, search_logs)
  • Filter data (product_search with exact parameters)
  • Process data (HTML-formatted responses)

But it cannot perform harmful actions (e.g., no arbitrary URL fetching - Protocol 712).

4.6 Adjust Settings​

Temperature (Creativity): 0.7

  • 0.1 = very predictable and consistent
  • 1.5 = creative and variable

Reasoning Effort: medium

  • Low = fast, simple
  • Medium = balanced (recommended)
  • High = thorough, slow

Leave the other settings on default.

4.7 Activate and Save Agent​

  1. Set "Is Active" to ✅ On
  2. (Optional) Set "Is Default" to ✅ On (if this should be your main agent)
  3. Click Save
First agent created! 🎉

Your "Product Advisor" agent is now ready for use!

Step 5: Test Agent​

Now let's test if everything works.

5.1 Open Backend Chat​

  1. Click 5E OAI Agent Manager in the left navigation
  2. Click Chat in the menu
  3. The backend chat opens

5.2 Perform First Test​

Try these test messages:

Test 1: Greeting

Hello!

Expectation: The agent greets you friendly

Test 2: Product Search

I'm looking for a jacket

Expectation: The agent asks for more details (color, size, budget)

Test 3: Specific Search (if you have jackets in the shop)

Show me black winter jackets under €100

Expectation: The agent searches and presents matching products

5.3 Analyze Conversation​

Pay attention to:

  • ✅ Does the agent respond quickly? (should take 1-5 seconds)
  • ✅ Is the response friendly and helpful?
  • ✅ Are tools called correctly?
  • ✅ Are product recommendations relevant?

Troubleshooting: Common Problems​

Problem: "Missing OpenAI API Key"​

Solution:

  1. Go to Settings → System → Plugins
  2. Configure the plugin again
  3. Check if the API key was copied completely

Problem: Agent doesn't respond​

Possible causes:

  • ❌ Invalid API key → Create new key
  • ❌ No OpenAI credits → Add credits
  • ❌ Agent not activated → Set "Is Active" in agent settings

Problem: "Rate limit exceeded"​

Solution: OpenAI has a request limit. Wait 1 minute and try again.

Problem: High costs​

Solution:

  • Use gpt-4o-mini instead of more expensive models
  • Deactivate unneeded tools
  • Shorten instructions (but not too much!)

Next Steps​

Congratulations! You have successfully:

  • ✅ Installed the plugin
  • ✅ Established the OpenAI connection
  • ✅ Created your first agent
  • ✅ Tested the agent

Now continue with:

➡️ Understanding Agent Configuration - Detailed explanation of all settings

➡️ Tools & Functions - Which tool for what?

➡️ Using Vector Stores - Upload your own documents

➡️ Best Practices - Tips for optimal agents