Conversations

shopping.agent supports multi-turn shopping: follow-up questions, refining a search, and comparing or asking about products already shown. The server is stateless over HTTP, so your client keeps two values and sends them back.

Value	Where it comes from	Send it back as	Lifetime
conversation_id	Every completed response that searched the catalog	conversation_id	48 hours after the last call in the conversation, and at most 30 days after it started
item_id	Each item in answer_items	selected_item_ids	48 hours after it was returned, and only in the conversation it came from

Both values work only for the account whose API key received them. Any of your account's keys can continue the conversation.

Start and continue a conversation

1. First call: send query only. The response contains a new conversation_id.
2. Next calls: send the new query with the same conversation_id. The agent remembers earlier turns: budget, preferences, and products it showed.

first = await session.call_tool("shopping.agent", {"query": "a standing desk for a small room"})
cid = first.structuredContent["conversation_id"]

follow = await session.call_tool(
    "shopping.agent",
    {"query": "only ones under $250 with a memory keypad", "conversation_id": cid},
)

Refer to products already shown

To compare products or ask about one, pass their item_id values in selected_item_ids, together with the conversation_id they came from.

items = first.structuredContent["answer_items"]
ids = [items[0]["item_id"], items[1]["item_id"]]

compare = await session.call_tool(
    "shopping.agent",
    {
        "query": "compare these two on stability and max height",
        "conversation_id": cid,
        "selected_item_ids": ids,
    },
)
tables = compare.structuredContent.get("item_comparison_table") or {}

Rules for selected_item_ids:

Rule	Behavior
Up to 10 values, no duplicates	More than 10, or a duplicate, fails with INVALID_ARGUMENT.
conversation_id required	Sending selected_item_ids without conversation_id fails with INVALID_ARGUMENT.
Every value must be valid	If any value is unknown, expired, from another conversation, or from another account, the whole call fails with INVALID_ARGUMENT. Search again to get fresh values.

Each answer returns new item_id values, even for a product shown before. Use the values from the answer the shopper is looking at. Treat item_id as an opaque string: do not parse it or build it.

When a conversation ends

Situation	Result	What to do
No call for 48 hours, or 30 days since the conversation started	CONVERSATION_EXPIRED	Omit conversation_id to start a new one.
conversation_id unknown or from another account	NOT_FOUND	Start a new conversation.
conversation_id not 32 lowercase hex characters	INVALID_ARGUMENT	Send the value exactly as returned.