How to create a product catalog AI agent on a Mac

This guide explains how to build a store assistant like yourOwnAgent: a program that answers only from a real product list. It runs on a Mac with Python. It is not a WordPress plugin, and it is not a static HTML page.

The agent has a simple job. A customer asks about a pump, a valve, or a price. The agent searches the store catalog, then answers with names, categories, prices, and links that exist in that list. If the item is not in the catalog, it says so. It does not invent products.

What the agent is made of

Four parts work together:

1. The brain — a Gemini model with written rules (answer only from the catalog, same language as the customer, keep replies short).

2. Tools — small functions the brain is allowed to call, such as product search and an optional Telegram notice.

3. The catalog — the real store data: product names, categories, prices in toman, and product URLs.

4. Keys and settings — a Gemini API key and the path or address of the catalog. These stay in a local .env file and are never published.

Chat stays short on purpose. A search may match thousands of items. The model receives one page (for example 20 products) plus the exact total. The full list belongs in a catalog page, not in a long chat message.

What you need on a Mac

• A Mac with internet access

• Python 3.11 or newer

• A Gemini API key from Google AI Studio

• A product file or a product API (JSON with names, prices, and links)

Install Apple’s command-line tools if they are not already installed:

xcode-select --install

Install Homebrew, then Python:

Check:

python3 --version

Create the project on a Mac

Open Terminal. Create a folder and a virtual environment:

mkdir -p ~/Agents/yourOwnAgent
cd ~/Agents/yourOwnAgent
python3 -m venv .venv
source .venv/bin/activate

Install the agent libraries:

bash

pip install "google-adk[a2a]" requests python-dotenv

Create this layout:

text

yourOwnAgent/
  your_own_agent/
    __init__.py
    agent.py
    tools.py
    catalog_api.py
  .env
  .env.example
  requirements.txt

__init__.py must import the agent package so the ADK runner can find it:

python

from . import agent

Configure the Mac environment

Copy the example file and edit .env in a text editor. Put the Gemini key there. Point the catalog to a JSON file on the Mac, or to a running product API.

Example variables:

text

GOOGLE_API_KEY=your_gemini_api_key_here
GOOGLE_GENAI_USE_VERTEXAI=0
CATALOG_API_BASE_URL=http://localhost:5001
CATALOG_DB_JSON_PATH=/path/to/catalog.json

Do not upload .env to GitHub or to the website. It contains secrets.

Load the file in Terminal before every run:

bash

cd ~/Agents/yourOwnAgent
source .venv/bin/activate
set -a && source .env && set +a

Write the agent

agent.py defines the name, the model, the rules, and the tools. The rules should include:

• Call product search before any answer about name, price, category, or stock

• Use only rows returned by that search

• Never invent products, prices, or brands

• If search returns nothing, say the item is not in the list

• Answer in the same language as the latest message (Persian or English)

• For a budget question, wait until the customer types an amount, then search with that exact figure in toman

• Keep the chat short; report the exact match count from the tool

tools.py exposes search (and optional Telegram) as functions the model can call.

catalog_api.py talks to the store API, or reads the local JSON if the API is down. That file is the source of truth for prices.

Run it on the Mac

From the project folder, with the virtual environment and .env loaded:

bash

adk web .

This opens a local developer chat in the browser, usually at http://127.0.0.1:8000. Ask a real catalog question, for example a pump price in Persian. The agent should call search first, then answer from those results.

If the catalog is served by a local backend, start that backend in a second Terminal window so search is not empty.

Optional commands:

bash

adk run your_own_agent
adk api_server --host=0.0.0.0 --port=8080 .

adk web is for building and testing on the Mac. adk api_server is the form used later if the agent is connected to a public website chat bubble.

How a good answer looks

For a product question, the agent should:

1. Search the catalog once

2. State the exact number of matches

3. Give a short sample (name, category, price in toman, link)

4. Direct the customer to the store site or support for a final check before purchase

It should refuse politics, coding help, other shops, and any product that is not in the list.

What this agent is not

• It is not an HTML file to upload into WordPress. Without the Python process, there is no agent.

• It is not a generic website chatbot that talks to Gemini with no product tool. That setup will guess and invent items.

• It is not a page that prints the entire catalog in one message. Large results belong in a catalog view; chat only reports the total and a sample.

Checklist before you call it finished

• Python virtual environment works on the Mac

• .env has a valid Gemini key and is not published

• Catalog JSON or API returns real products

• A Persian product question returns names and prices from the list

• An unknown item is rejected instead of invented

• Off-topic questions are refused

That is the whole Mac workflow: install Python, create the project, write rules and a search tool, connect the store list, then run adk web and test.