Skip to main content

​
User Profiles Database

The User Profiles Database defines how MOOD MNKY agents store, access, and utilize information about users to deliver personalized experiences. It provides a structured approach for maintaining user preferences, behavior patterns, and interaction history in a privacy-respecting manner.

​
Purpose and Role

The User Profiles Database defines “who” agents interact with, enabling them to tailor their responses, recommendations, and behaviors to individual users.
This database documents:
  • User preference information
  • Demographic and psychographic data
  • Interaction history and patterns
  • Product preferences and purchase history
  • Privacy settings and consent records
  • Personalization parameters and vectors

​
Schema and Structure

{
  "user_id": "string",
  "created_at": "timestamp",
  "updated_at": "timestamp",
  "basic_info": "object",
  "preferences": "object",
  "product_affinities": "object",
  "interaction_patterns": "object",
  "privacy_settings": "object",
  "segments": "array",
  "personalization_vectors": "object",
  "connected_accounts": "array",
  "status": "string"
}

​
Field Descriptions

A unique identifier for the user.
When the user profile was first created.
When the user profile was last modified.
Essential user information like name, email, and timezone.
User-specified preferences across various domains.
Computed affinities for product categories and collections.
Observed patterns in user behavior and interaction.
User-controlled privacy and data usage preferences.
User segments or personas for targeted experiences.
Vector representations of user preferences for similarity matching.
External accounts linked to this user profile.
Current status of the user account.

​
Profile Components

The MOOD MNKY user profile system consists of several interconnected components:

Explicit Preferences

Directly stated user preferences, collected through:
  • Initial onboarding questionnaires
  • Preference settings in account
  • Direct feedback on recommendations
  • Feature opt-ins and settings
  • Survey responses

Behavioral Insights

Observed patterns derived from user activity:
  • Product browsing and purchase history
  • Content engagement patterns
  • Search query analysis
  • Feature usage frequency
  • Time and duration patterns

Preference Vectors

Computed embeddings that represent user preferences for:
  • Product affinity matching
  • Content recommendation
  • Tone and style preferences
  • Similar user clustering
  • Cold-start inference

Segmentation

Groupings that place users in meaningful categories:
  • Lifestyle segments
  • Purchase behavior clusters
  • Engagement level categories
  • Value alignment groups
  • Product affinity segments

​
Integration with OpenAI Agents SDK

​
User Profile Access

from agents import Agent, Tool, Runner
from user_profile import UserProfileSystem

# Initialize profile system
profiles = UserProfileSystem()

# Define profile access tool
def get_user_preferences(user_id: str, preference_type: str = None) -> dict:
    """Retrieve user preferences of a specific type."""
    return profiles.get_preferences(
        user_id=user_id,
        preference_type=preference_type
    )

# Create tool for the agent
profile_tool = Tool(
    name="get_user_preferences",
    description="Retrieve information about user preferences",
    function=get_user_preferences
)

# Create agent with the tool
agent = Agent(
    name="MOOD MNKY",
    instructions="You are MOOD MNKY, the brand assistant. Use profile information to personalize recommendations.",
    tools=[profile_tool]
)

# Run the agent
runner = Runner()
result = await runner.run(agent, "What products would you recommend for me?")

​
Profile-Aware Instructions

from agents import Agent, Runner
from user_profile import UserProfileSystem

# Initialize profile system
profiles = UserProfileSystem()

async def create_profile_aware_agent(user_id: str) -> Agent:
    # Retrieve user profile summary
    profile_summary = profiles.get_summary(user_id)
    
    # Create agent with profile-infused instructions
    agent = Agent(
        name="MOOD MNKY",
        instructions=f"""You are MOOD MNKY, the brand assistant.
        
        User profile information:
        {profile_summary}
        
        Use this information to provide personalized assistance.
        
        Important preferences to consider:
        - Scent preferences: {profile_summary.get('preferences', {}).get('scent', {})}
        - Product preferences: {profile_summary.get('preferences', {}).get('products', {})}
        - Communication style: {profile_summary.get('preferences', {}).get('communication', {}).get('tone', 'neutral')}
        
        Ensure your tone and recommendations align with these preferences."""
    )
    
    return agent

# Create and run agent for a specific user
agent = await create_profile_aware_agent("usr_425b3c")
runner = Runner()
result = await runner.run(agent, "I'm looking for something to help me relax")

​
Profile MCP Server Integration

from agents import Agent, Runner
from agents.mcp.server import MCPServerSse, MCPServerSseParams

# Set up MCP server for user profiles
async with MCPServerSse(
    params=MCPServerSseParams(
        url="http://localhost:3000/profile-mcp",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ),
    name="profile_mcp",
    cache_tools_list=True
) as profile_server:
    
    # Create agent with profile MCP server
    agent = Agent(
        name="MOOD MNKY",
        instructions="You are MOOD MNKY, the brand assistant. Use profile information to personalize recommendations.",
        mcp_servers=[profile_server]
    )
    
    # Run the agent
    runner = Runner()
    result = await runner.run(agent, "What scents would I like?")
The User Profiles Database implements a comprehensive privacy and consent framework:

​
Preference Collection and Update

​
Initial Collection

from agents import Agent, Tool, Runner
from user_profile import UserProfileSystem

# Initialize profile system
profiles = UserProfileSystem()

# Define preference update tool
def update_user_preferences(user_id: str, preference_type: str, 
                             preferences: dict) -> dict:
    """Update user preferences of a specific type."""
    return profiles.update_preferences(
        user_id=user_id,
        preference_type=preference_type,
        preferences=preferences
    )

# Create tool for the agent
update_tool = Tool(
    name="update_user_preferences",
    description="Update information about user preferences",
    function=update_user_preferences
)

# Create onboarding agent with the tool
onboarding_agent = Agent(
    name="MOOD MNKY",
    instructions="""You are MOOD MNKY, the brand assistant. 
    Guide new users through setting up their preferences.
    Ask about scent preferences, product types, and sensitivity.
    Update their profile with the information collected.""",
    tools=[update_tool]
)

# Run the onboarding agent
runner = Runner()
result = await runner.run(onboarding_agent, "I'm new here, can you help me get started?")

​
Preference Learning

from agents import Agent, Tool, Runner
from user_profile import UserProfileSystem

# Initialize profile system
profiles = UserProfileSystem()

# Define preference learning tool
def infer_preference(user_id: str, interaction: str, 
                     confidence: float) -> dict:
    """Infer a user preference from an interaction."""
    return profiles.infer_preference(
        user_id=user_id,
        interaction=interaction,
        confidence=confidence
    )

# Create tool for the agent
learning_tool = Tool(
    name="infer_preference",
    description="Infer user preferences from interactions",
    function=infer_preference
)

# Create agent with the tool
agent = Agent(
    name="MOOD MNKY",
    instructions="""You are MOOD MNKY, the brand assistant.
    During conversations, identify stated preferences and update the user profile.
    Look for mentions of likes, dislikes, sensitivities, and goals.""",
    tools=[learning_tool]
)

# Run the agent
runner = Runner()
result = await runner.run(agent, "I really enjoy lavender scents, but citrus gives me a headache.")

​
Personalization Vectors

The system uses vector embeddings to represent different aspects of user preferences:

Product Vectors

Represent product preferences in embedding space to enable similarity-based recommendations and affinity matching.

Content Vectors

Capture content consumption patterns and preferences for personalizing education materials and marketing messages.

Communication Vectors

Model preferred communication styles, tone, detail level, and formality for adapting agent interactions.

Experience Vectors

Encode overall experience preferences like design aesthetics, complexity level, and engagement patterns.

​
Vector Creation

from agents import Agent, Tool, Runner
from user_profile import UserProfileSystem
import numpy as np

# Initialize profile system
profiles = UserProfileSystem()

# Define vector update tool
def update_preference_vector(user_id: str, vector_type: str, 
                              vector_data: list) -> dict:
    """Update a user's preference vector."""
    return profiles.update_vector(
        user_id=user_id,
        vector_type=vector_type,
        vector_data=vector_data
    )

# Create tool for the agent
vector_tool = Tool(
    name="update_preference_vector",
    description="Update a user's preference vector representation",
    function=update_preference_vector
)

# Function to generate embedding
def generate_product_embedding(preferences: dict) -> list:
    """Convert product preferences to vector representation."""
    # In a real system, this would use a machine learning model
    # This is a simplified example
    embedding = np.random.normal(size=128).tolist()
    return embedding

# Create agent with the tool
agent = Agent(
    name="MOOD MNKY",
    instructions="""You are MOOD MNKY, the brand assistant.
    Analyze user interactions to update their preference vectors.""",
    tools=[vector_tool]
)

# Example of updating vectors
preferences = {
    "scent": ["lavender", "bergamot"],
    "product_types": ["candles", "diffusers"],
    "occasions": ["relaxation", "sleep"]
}
embedding = generate_product_embedding(preferences)
await vector_tool.function(
    user_id="usr_425b3c",
    vector_type="product",
    vector_data=embedding
)

​
Best Practices for User Profile Management

​
Privacy and Ethics

  • Transparent Collection: Clearly communicate what data is collected and why
  • Minimization Principle: Collect only what’s necessary for personalization
  • Control Mechanisms: Provide user-accessible controls for preferences and data
  • Sensitivity Awareness: Apply special handling for sensitive preference data
  • Right to be Forgotten: Implement comprehensive data deletion capabilities

​
Profile Quality

  • Confidence Scoring: Track confidence levels for inferred preferences
  • Verification Loops: Confirm inferred preferences through interaction
  • Recency Weighting: Give higher weight to more recent preference signals
  • Contradiction Resolution: Implement strategies for handling conflicting preferences
  • Profile Health Metrics: Monitor completeness and consistency of profiles

​
Implementation Strategies

  • Progressive Profiling: Build profiles gradually through natural interactions
  • Multi-source Integration: Combine explicit, implicit, and inferred data
  • Vector Maintenance: Regularly update and re-compute personalization vectors
  • Segmentation Automation: Dynamically assign and update user segments
  • Cross-validation: Compare signals across different interaction channels

​
Personalization Delivery

  • Appropriate Adaptation: Match personalization level to user expectations
  • Transparency: Make personalization visible when appropriate
  • Overrides: Allow users to easily override personalized settings
  • A/B Testing: Continuously evaluate personalization effectiveness
  • Fallback Mechanisms: Handle new users and sparse profiles gracefully

​
Additional Resources