pantry-agent

Pantry Agent

Grocery shopping assistant powered by the Kroger API. Supports all Kroger-owned banners.

Workflow

1. Ask the user for their ZIP code if not already known.
2. Find the nearest store using find_stores. The response includes the chain name (Kroger, Ralphs, etc.) and the locationId.
3. Use the locationId from the store result for all subsequent product searches.
4. Store, search, and product commands work without authentication.
5. Use preview_cart with the locationId to validate item pricing and availability before adding to cart. No authentication required.
6. Before adding to cart, call check_auth_status to determine if the user is authenticated.
7. If not authenticated, call kroger_start_auth to get the authorization URL and present it to the user.
8. After the user completes login, retry the cart or profile operation.
9. Always confirm with the user before adding items to their cart.
10. Show prices and stock availability when displaying products.

Authentication flow (agent-managed OAuth)

Authentication is decoupled from cart operations — add_to_cart and get_profile return an AUTH_REQUIRED error without opening a browser. Follow these steps when authentication is needed:

1. Call check_auth_status to see if the user is already authenticated (avoids unnecessary auth prompts).
2. If not authenticated, call kroger_start_auth — this starts a local callback server and returns the Kroger authorization URL.
3. Present the URL to the user and ask them to open it in their browser.
4. The user completes the Kroger login in their browser; the callback server captures the token automatically.
5. Wait for the user to confirm that login is complete.
6. Retry the original cart or profile operation.

Do not attempt to open the URL yourself. Present it to the user for them to open.

You can also use the kroger-oauth prompt to get step-by-step guidance for this flow.

Example agentic flows

Shopping flow (search → preview → add)

1. find_stores(zipCode: "94102")          → get locationId
2. search_products(term: "milk", locationId: ...)  → pick product UPC
3. preview_cart(items: [{upc, qty}], locationId: ...) → verify price/stock
4. check_auth_status()                    → verify authentication
5. [if not auth] kroger_start_auth()      → user logs in
6. add_to_cart(items: [{upc, qty}])       → confirm to user