UCP Agent Example with Upsonic

Production-ready implementation demonstrating Upsonic Agent Framework for intelligent multi-store product search using UCP (Universal Commerce Protocol).

Architecture

This demo showcases Upsonic's Agent Framework with:

• 4 Specialized Agents working in coordination
• Clean separation of concerns (agents, tools, config)
• Type-safe models with Pydantic
• Async parallel operations across 24 Shopify stores

Upsonic Agents

1. IntentAnalyzerAgent

Role: Shopping intent analysis Model: GPT-4o Purpose: Extracts keywords, gender, and scenario from natural language

from agents.intent_analyzer import IntentAnalyzerAgent

analyzer = IntentAnalyzerAgent()
intent = analyzer.analyze("I need workout clothes for the gym")
# Returns: {"keywords": ["shirt", "joggers"], "gender": "men", "scenario": "athletic"}

2. ProductFetcherAgent

Role: Product discovery from multiple stores Model: GPT-4o-mini Purpose: Fetches products from 24 Shopify stores in parallel

3. RelevanceFilterAgent

Role: Product relevance and gender filtering Model: GPT-4o-mini Purpose: AI-powered filtering with gender awareness

4. OrchestratorAgent

Role: Multi-agent coordination Purpose: Manages workflow, deduplication, and result aggregation

Installation

# Clone the repository
git clone https://github.com/Upsonic/ucp-upsonic-shopify-demo.git
cd ucp-upsonic-shopify-demo

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

Usage

python main.py

Programmatic Usage

from agents.orchestrator import OrchestratorAgent
from config.stores import SHOPIFY_STORES

orchestrator = OrchestratorAgent(SHOPIFY_STORES)
result = orchestrator.execute("Find me a keyboard and mouse")

print(f"Found {len(result['products'])} products")
for product in result['products']:
    print(f"{product['title']} - ${product['price']}")

Project Structure

ucp-upsonic-shopify-demo/
├── agents/                   # Upsonic Agent implementations
│   ├── __init__.py
│   ├── base.py              # Base agent interface
│   ├── intent_analyzer.py   # GPT-4o: Intent analysis
│   ├── product_fetcher.py   # Product discovery agent
│   ├── relevance_filter.py  # GPT-4o-mini: AI filtering
│   └── orchestrator.py      # Multi-agent coordination
├── tools/                    # Custom Upsonic Tools
│   ├── __init__.py
│   └── shopify_fetcher.py   # Parallel Shopify API fetcher
├── config/                   # Configuration
│   ├── stores.py            # 24 Shopify store domains
│   └── constants.py         # Global constants
├── models/                   # Pydantic data models
│   ├── __init__.py
│   └── product.py           # Product, SearchIntent, SearchResult
├── services/                 # External services
│   ├── __init__.py
│   └── shopify_service.py   # Shopify API service layer
├── main.py                   # CLI entry point
├── requirements.txt          # Python dependencies
├── .env.example             # Environment template
└── .gitignore               # Git ignore rules

Upsonic Features Used

• ✅ Agent: Role-based agent creation with goals and instructions
• ✅ Task: Contextual task definition with descriptions
• ✅ Tool: Custom tool for Shopify product fetching
• ✅ Output Format: JSON-structured responses
• ✅ Model Selection: GPT-4o for intent, GPT-4o-mini for filtering

Example Output

🎯 Query: I need a mechanical keyboard and wireless mouse
📋 Execution Steps:
  🔍 Analyzing shopping intent...
  ✓ Detected: keyboard, mouse | Gender: unisex | Scenario: tech
  🛍️  Searching for 'keyboard' across 24 stores...
  📦 Found 47 raw products
  🤖 Filtering with AI for relevance and gender...
  ✓ Added: Keychron K2 Wireless Mechanical Keyboard... | $79.0
  ...

🎁 Found 8 Products

Design Principles

• SOLID: Single responsibility per agent
• DRY: Reusable agent configurations
• Clean Code: Self-documenting, no comments needed
• Type Safety: Pydantic models throughout
• Async First: Parallel operations for performance

Performance

• 24 stores queried in parallel (~8 seconds)
• Smart filtering reduces LLM token usage
• Max 12 products for optimal response time
• Fallback logic ensures reliability

Configuration

All constants are centralized in config/constants.py:

MAX_PRODUCTS_PER_KEYWORD = 4  # Products per category
MAX_TOTAL_PRODUCTS = 12        # Total result limit
MAX_KEYWORDS = 3               # Maximum keywords to process
SHOPIFY_FETCH_TIMEOUT = 8.0    # Request timeout (seconds)
INTENT_MODEL = "openai/gpt-4o" # Intent analysis model
FILTER_MODEL = "openai/gpt-4o-mini" # Filtering model

Powered By

• Upsonic Agent Framework v0.69.3
• OpenAI GPT-4o / GPT-4o-mini
• Shopify Products API (24 stores)
• UCP Universal Commerce Protocol principles
• Python 3.10+ with async/await