How we made I-9 Agent

A website-ready making-of: the programs on the Mac, the Python agent, the product catalog page, and how that page is shown on i-9.ir with an iframe.

What you need on the Mac

I-9 Agent was written and tested on macOS with this toolkit. Nothing here is a WordPress plugin. WordPress only displays the finished page.

Program	Why it was used
Code editor	The editor where the agent, tools, and catalog page were written.
Python 3.13	The language the agent and catalog server run in. A virtualenv (`.venv`) keeps packages isolated.
Terminal / zsh	Runs `adk web` for chat, `python -m i9_agent.catalog_ui` for the list, and `gcloud` for deploy.
Git	Version control for the `I9_Agent` project.
Homebrew	Installs extra Mac tools, including the Google Cloud SDK.
Google Cloud SDK (`gcloud`)	Puts the catalog on Cloud Run so customers can open it, not only localhost.

Accounts and keys (not programs)

A Gemini API key in .env as GOOGLE_API_KEY — for chat.
A Google Cloud project with billing — for hosting. Use a real project such as i9-agent, not Default Gemini Project.
Optional: Telegram bot token — only if the agent should notify an operator.
The I-9 product JSON (or the live shop API) — the agent must not invent products.

Docker Desktop was not required on this Mac. Cloud Run built the container on Google’s side from the project Dockerfile.

What I-9 Agent is

I-9 Agent is the official product assistant for I-9 Group (آی‌ناین). It answers only from the store list. Chat stays short. The full match list loads on a dark RTL catalog page: search, photos, WhatsApp, price, and a link to i-9.ir.

Chat

Google ADK + Gemini

adk web runs the agent locally. Tools: search_i9_products (required before any product answer) and notify_me (Telegram).

Catalog page

Python server + HTML

catalog.html loads 20 products at a time from /api/catalog/search. Photos come from /api/catalog/thumb, fetched from the real i-9.ir product.

How a request moves

Visitor

Opens chat, or opens the catalog (direct link or WordPress iframe).

Agent

Calls search_i9_products once. Does not dump 1,800 rows into the chat. Sends the catalog URL.

Catalog UI

Same query, pages of 20, until the list is complete. Cards show image, WhatsApp, category, price, product link.

i-9.ir

The real shop. Product links and photos belong here. WordPress does not run the Python agent.

How it was built

1. Mac workspace. Install a code editor, Python 3.13, Git, Homebrew, then Google Cloud SDK. Create a virtualenv and install google-adk, requests, and python-dotenv.
2. Agent in the editor. Write i9_agent/agent.py as an ADK agent with a strict catalog-only policy: no invented products, Persian in / English out matching the user, budget taken from the number the user typed.
3. Product search tool. tools.py exposes search_i9_products. i9_api.py reads the I-9 API or local I9_db.json, returns one page of 20, plus total matches and a catalog URL.
4. Catalog page. Chat cannot show 1,898 pumps. catalog_ui.py serves catalog.html: RTL layout, search, infinite load, WhatsApp, product link. Run locally with:cd /Users/kiamalek/Agents/I9_Agent source .venv/bin/activate python -m i9_agent.catalog_uiThen open http://127.0.0.1:8787.
5. Chat on the Mac. For the AI box itself:cd /Users/kiamalek/Agents/I9_Agent source .venv/bin/activate set -a && source .env && set +a adk web .That local ADK UI is not the WordPress Kia plugin. Same idea (a chat box), different program.
6. Host on Google Cloud, not WordPress. WordPress cannot run this Python server. A Cloud Run service (i9-catalog in project i9-agent) serves the page to the internet. Default Gemini Project is only for Gemini credits; it cannot host Cloud Run.
7. Show it on the website. i-9.ir keeps the shop. A WordPress page iframes the Cloud URL (see below). The Kia-style AI Engine plugin can stay a chat widget; it should link to this list, not try to draw the cards itself.

What went live

Public catalog (Cloud Run, region us-central1):

https://i9-catalog-107457852891.us-central1.run.app

Deploy, from the project folder, after gcloud is pointed at project i9-agent:

gcloud run deploy i9-catalog \
  --source . \
  --project=i9-agent \
  --region=us-central1 \
  --allow-unauthenticated

The first deploy on Default Gemini Project failed with permission 403. Hosting works on the dedicated project i9-agent with billing linked.

Connect it to a WordPress iframe

Create a page on i-9.ir. Add a Custom HTML block. Paste:

<iframe
  src="https://i9-catalog-107457852891.us-central1.run.app/"
  style="width:100%;height:90vh;border:0;border-radius:12px;"
  title="فهرست محصولات آی‌ناین"
  loading="lazy">
</iframe>

Publish, then add that page to the menu. Do not upload catalog.html into the theme. The iframe src must stay the Cloud URL so search and photos keep working.

Project map

Path	Role
`i9_agent/agent.py`	Gemini instructions and tools
`i9_agent/tools.py`	Product search + Telegram notify
`i9_agent/i9_api.py`	Catalog pages of 20 from API or JSON
`i9_agent/catalog_ui.py`	HTTP server for the list and thumbnails
`i9_agent/static/catalog.html`	The dark RTL product UI
`Dockerfile` + `entrypoint.sh`	What Cloud Run runs