Building a Gift Registry Agent: Registry Creation, Search, and Purchase Assistance

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.

flowchart LR
    CALLER(["Shopper"])
    subgraph TEL["Telephony"]
        SIP["Twilio SIP and PSTN"]
    end
    subgraph BRAIN["E-commerce AI Agent"]
        STT["Streaming STT<br/>Deepgram or Whisper"]
        NLU{"Intent and<br/>Entity Extraction"}
        TOOLS["Tool Calls"]
        TTS["Streaming TTS<br/>ElevenLabs or Rime"]
    end
    subgraph DATA["Live Data Plane"]
        CRM[("CRM and Notes")]
        CAL[("Calendar and<br/>Schedule")]
        KB[("Knowledge Base<br/>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

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.

@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 and not show_purchased:
            continue
        status = f"{remaining} still needed" 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 <= 0:
        return (
            f"{item.product_name} has already been fully purchased. "
            f"Consider choosing another item from the registry."
        )

    actual_qty = min(quantity, remaining)
    item.quantity_purchased += actual_qty
    item.purchased_by.append({
        "buyer": buyer_name,
        "quantity": actual_qty,
        "date": datetime.now().isoformat(),
    })

    return (
        f"{buyer_name} purchased {actual_qty}x {item.product_name} "
        f"from {registry.owner_name}'s registry. "
        f"{'Item fulfilled!' if item.quantity_purchased >= item.quantity_requested else f'{remaining - actual_qty} more needed.'}"
    )

Thank-You Tracking

@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

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