--- title: "Building a Gift Registry Agent: Registry Creation, Search, and Purchase Assistance" description: "Build an AI agent that manages gift registries end-to-end — from creating registries and managing items to tracking purchases and coordinating between gift givers to prevent duplicates." canonical: https://callsphere.ai/blog/building-gift-registry-agent-creation-search-purchase-assistance category: "Learn Agentic AI" tags: ["Gift Registry", "E-Commerce AI", "Wedding Registry", "Retail Automation", "Purchase Tracking"] author: "CallSphere Team" published: 2026-03-17T00:00:00.000Z updated: 2026-05-06T19:57:48.627Z --- # Building a Gift Registry Agent: Registry Creation, Search, and Purchase Assistance > Build an AI agent that manages gift registries end-to-end — from creating registries and managing items to tracking purchases and coordinating between gift givers to prevent duplicates. ## The Gift Registry Use Case Gift registries — for weddings, baby showers, housewarmings, and birthdays — involve coordination between the registry owner and multiple gift givers. Traditional registries are static lists that require manual updates. An AI agent can create registries from natural language descriptions, help gift givers find and purchase items, prevent duplicate gifts, and send thank-you reminders. ## Data Model A registry needs to track owners, items, purchasers, and gift statuses. ```mermaid flowchart LR CALLER(["Shopper"]) subgraph TEL["Telephony"] SIP["Twilio SIP and PSTN"] end subgraph BRAIN["E-commerce AI Agent"] STT["Streaming STT Deepgram or Whisper"] NLU{"Intent and Entity Extraction"} TOOLS["Tool Calls"] TTS["Streaming TTS ElevenLabs or Rime"] end subgraph DATA["Live Data Plane"] CRM[("CRM and Notes")] CAL[("Calendar and Schedule")] KB[("Knowledge Base and Policies")] end subgraph OUT["Outcomes"] O1(["Order status answered"]) O2(["Return RMA created"]) O3(["Specialist handoff"]) end CALLER --> SIP --> STT --> NLU NLU -->|Lookup| TOOLS TOOLS CRM TOOLS CAL TOOLS KB NLU --> TTS --> SIP --> CALLER NLU -->|Resolved| O1 NLU -->|Schedule| O2 NLU -->|Escalate| O3 style CALLER fill:#f1f5f9,stroke:#64748b,color:#0f172a style NLU fill:#4f46e5,stroke:#4338ca,color:#fff style O1 fill:#059669,stroke:#047857,color:#fff style O2 fill:#0ea5e9,stroke:#0369a1,color:#fff style O3 fill:#f59e0b,stroke:#d97706,color:#1f2937 ``` ```python from agents import Agent, Runner, function_tool from dataclasses import dataclass, field from typing import Optional from datetime import datetime import uuid @dataclass class RegistryItem: item_id: str product_name: str price: float quantity_requested: int quantity_purchased: int = 0 purchased_by: list = field(default_factory=list) priority: str = "normal" # high, normal, low @dataclass class Registry: registry_id: str owner_name: str event_type: str event_date: str items: list = field(default_factory=list) is_public: bool = True thank_you_sent: list = field(default_factory=list) # In-memory store (use database in production) REGISTRIES = {} @function_tool def create_registry(owner_name: str, event_type: str, event_date: str) -> str: """Create a new gift registry.""" registry_id = f"REG-{uuid.uuid4().hex[:8].upper()}" registry = Registry( registry_id=registry_id, owner_name=owner_name, event_type=event_type, event_date=event_date, ) REGISTRIES[registry_id] = registry return ( f"Registry {registry_id} created for {owner_name}'s {event_type} " f"on {event_date}. Share this ID with your guests so they can " f"find your registry." ) @function_tool def add_item_to_registry(registry_id: str, product_name: str, price: float, quantity: int = 1, priority: str = "normal") -> str: """Add an item to an existing registry.""" registry = REGISTRIES.get(registry_id) if not registry: return "Registry not found." item_id = f"ITEM-{uuid.uuid4().hex[:6].upper()}" item = RegistryItem( item_id=item_id, product_name=product_name, price=price, quantity_requested=quantity, priority=priority, ) registry.items.append(item) return ( f"Added {product_name} (${price:.2f} x{quantity}) to registry " f"{registry_id}. Priority: {priority}." ) ``` ## Gift Giver Tools Gift givers need to search registries, see what has already been purchased, and mark items as bought. ```python @function_tool def search_registries(owner_name: str) -> str: """Search for a registry by the owner's name.""" matches = [ r for r in REGISTRIES.values() if owner_name.lower() in r.owner_name.lower() and r.is_public ] if not matches: return f"No public registries found for '{owner_name}'." results = [] for r in matches: total_items = len(r.items) purchased = sum(1 for i in r.items if i.quantity_purchased >= i.quantity_requested) results.append( f" {r.registry_id}: {r.owner_name}'s {r.event_type} " f"({r.event_date}) - {total_items} items, " f"{purchased} fulfilled" ) return "Found registries:\n" + "\n".join(results) @function_tool def view_registry_items(registry_id: str, show_purchased: bool = False) -> str: """View items in a registry. By default hides fully purchased items.""" registry = REGISTRIES.get(registry_id) if not registry: return "Registry not found." lines = [f"{registry.owner_name}'s {registry.event_type} Registry:"] for item in registry.items: remaining = item.quantity_requested - item.quantity_purchased if remaining 0 else "Fulfilled" priority_marker = " [HIGH PRIORITY]" if item.priority == "high" else "" lines.append( f" {item.item_id}: {item.product_name} - " f"${item.price:.2f} - {status}{priority_marker}" ) if len(lines) == 1: lines.append(" All items have been fulfilled!") return "\n".join(lines) @function_tool def purchase_registry_item(registry_id: str, item_id: str, buyer_name: str, quantity: int = 1) -> str: """Mark a registry item as purchased by a gift giver.""" registry = REGISTRIES.get(registry_id) if not registry: return "Registry not found." item = next((i for i in registry.items if i.item_id == item_id), None) if not item: return "Item not found in this registry." remaining = item.quantity_requested - item.quantity_purchased if remaining = item.quantity_requested else f'{remaining - actual_qty} more needed.'}" ) ``` ## Thank-You Tracking ```python @function_tool def get_thank_you_status(registry_id: str) -> str: """Check which gift givers still need thank-you notes.""" registry = REGISTRIES.get(registry_id) if not registry: return "Registry not found." all_buyers = set() for item in registry.items: for purchase in item.purchased_by: all_buyers.add(purchase["buyer"]) thanked = set(registry.thank_you_sent) pending = all_buyers - thanked if not pending: return "All thank-you notes have been sent!" return f"Pending thank-you notes for: {', '.join(sorted(pending))}" ``` ## Assembling the Registry Agent ```python registry_agent = Agent( name="Gift Registry Assistant", instructions="""You manage gift registries for all occasions. For registry owners: - Help create registries with event details - Add, remove, or update items and priorities - Track purchase progress and thank-you note status For gift givers: - Help find registries by owner name - Show available (unpurchased) items sorted by priority - Process gift purchases and prevent duplicates - Suggest items within a stated budget Always prevent duplicate purchases by checking remaining quantity before confirming a purchase.""", tools=[create_registry, add_item_to_registry, search_registries, view_registry_items, purchase_registry_item, get_thank_you_status], ) ``` ## FAQ ### How do I prevent two gift givers from purchasing the same item simultaneously? Implement optimistic locking at the database level. When a gift giver starts the purchase flow, place a temporary hold on the item with a short expiration (5 minutes). Use database transactions with row-level locks to ensure only one purchase succeeds if two givers attempt the same item. Display real-time availability counts that update on page focus. ### Can the agent suggest items for a registry based on the event type? Yes. Build a recommendation tool that maps event types to popular gift categories. For weddings, suggest kitchen appliances, bedding, and dinnerware. For baby showers, suggest essentials by trimester. Pull suggestions from your product catalog ranked by popularity within that event category and the stated budget range. ### How should the agent handle group gifts for expensive items? Support partial contributions by allowing multiple givers to contribute toward a single high-value item. Track each contribution amount and contributor name. Display progress as a percentage funded. Once fully funded, notify the registry owner. This works well for items like furniture, electronics, or experience gifts that exceed a typical individual gift budget. --- #GiftRegistry #ECommerceAI #WeddingRegistry #RetailAutomation #PurchaseTracking #AgenticAI #LearnAI #AIEngineering --- Source: https://callsphere.ai/blog/building-gift-registry-agent-creation-search-purchase-assistance