Repeated AdSense Rejections Led Me to Rethink My WordPress Content

Illustration of Kia at a laptop, surrounded by website pages and error notifications, reflecting the frustration of repeated AdSense rejections.

A developer working through website setbacks at a laptop.

Several years ago, I built my first website in WordPress. I created pages, added content, and gradually worked on the site until it felt more complete. At the time, I wasn’t publishing blog posts. Everything went into pages.

The website took much longer to finish than I expected. When I finally decided to try Google AdSense, I hoped it would be the next step forward. Instead, my application was rejected again and again.

Each rejection was frustrating. I had already spent so much time building the site, and I struggled to understand what I needed to change.

The advice that made me feel I had to start over

A friend who worked in web development looked at my situation and suggested that I publish my article content as posts rather than keeping everything in pages. He thought I would need to recreate the content and delete the old versions.

That was difficult to hear. The thought of rebuilding work that had already taken so long left me discouraged. I wanted to improve the website, but I didn’t want to copy everything manually and begin again.

Looking back, there were two separate questions: how to organize my WordPress content, and why AdSense had rejected the site. Changing the first would not necessarily answer the second.

How AI helped me find a simpler approach

Before committing to a complete rebuild, I asked an AI assistant whether there was an easier way to turn existing pages into posts.

It suggested a WordPress plugin called Post Type Switcher.

The plugin lets you change an existing item’s content type, including converting a page into a post. It also supports bulk changes. That meant I had an alternative to manually recreating each article. See the plugin’s official description.

I used it to convert many of my pages into posts. For me, its value was practical: it made a task that had felt overwhelming much more manageable.

Website content cards being reorganized into a clear article collection.

What this taught me about pages, posts, and AdSense

There is an important correction to the advice I originally received: AdSense does not require you to publish your content as WordPress posts rather than pages. Google’s published requirements focus on original, useful content, policy compliance, and a website that visitors can navigate. They do not specify a WordPress content type. Read Google’s eligibility requirements and site-readiness guidance.

Posts can help organize a growing collection of articles through categories and a blog archive. Pages still have a useful role for content such as About, Contact, and service information.

The right choice depends on what the content is for. Turning a page into a post does not improve the writing by itself, and it does not guarantee AdSense approval.

I also cannot conclude from this experience that using pages was the reason for my rejections. What I can say is that the plugin helped me reorganize existing content without manually recreating it.

What I recommend before converting content

If you are in a similar situation, Post Type Switcher may be worth considering. Start with a backup and test one item on a staging copy before making bulk changes. The plugin’s documentation notes that conflicts with other plugins can occur. Plugin documentation.

After a conversion, check these details:

  • Layout: Does the article still display correctly, especially if it uses a page builder?
  • Address: Has the URL changed? If so, redirect the old address to the new one.
  • Navigation: Do menus and internal links still lead to the right place?
  • Organization: Does the article appear in the intended category and blog archive?

You do not need to convert every page. Choose the content that belongs in your article collection, and keep other pages where they make sense.

A small tool made a difficult task feel possible

The most useful part of this experience was discovering that I had another option. I could reorganize what I had already written instead of assuming I needed to rebuild everything.

AI helped me find the tool, and Post Type Switcher helped me carry out the change. The experience also reminded me to check the reasoning behind advice, even when it comes from someone with more experience.

If your WordPress articles are currently stored as pages, this plugin could save you some work. If your goal is AdSense approval, review the quality and usefulness of the whole website as well. Content organization is one part of that work.

Blog posts

Why Product Thinking Comes First Have you ever launched a product that looked impressive… but…


Why Product Thinking Comes First

Have you ever launched a product that looked impressive… but didn’t truly solve anything meaningful?

Many teams move quickly into development. Features get built. Interfaces look polished. But somewhere along the way, the real problem gets lost.

That’s why product thinking matters.

Product thinking is a strategic mindset that starts before design and development. It asks a simple but powerful question:

What real problem are we solving — and for whom?

Instead of focusing only on features, it focuses on value.


A Complete View of the Product Journey

Product thinking looks at the entire lifecycle of a product:

  • Idea and validation
  • User research
  • Design and development
  • Launch and iteration
  • Long-term growth

It connects strategy with execution. It ensures that every decision serves a clear purpose.


1. User-Centered by Design

At the heart of product thinking is empathy.

Teams invest time in understanding user behavior, frustrations, motivations, and goals. Rather than assuming what people need, they validate insights through research and feedback.

When products are built around real needs:

  • Adoption increases
  • Satisfaction improves
  • Loyalty strengthens

Users don’t just use the product — they depend on it.


2. Solving the Right Problems

Feature-first development often leads to complexity without clarity.

Product thinking slows the process down — in a productive way. It encourages teams to identify the core challenge before proposing solutions.

This approach ensures:

  • Features are meaningful
  • Resources are used wisely
  • Development stays focused

Nothing is built “just because.” Everything has a reason.


3. Alignment with Business Strategy

A product should support broader company objectives.

Product thinking connects product decisions with business goals such as:

  • Revenue growth
  • Market expansion
  • Brand positioning
  • Competitive differentiation

When strategy and product development move in the same direction, momentum builds.


4. Cross-Functional Collaboration

Strong products are not created in isolation.

Product thinking brings together:

  • Designers
  • Engineers
  • Marketing teams
  • Sales and customer support

Each perspective strengthens the outcome. Collaboration reduces blind spots and improves decision-making across the board.


5. Continuous Validation and Market Fit

Markets evolve. User expectations shift.

Product thinking embraces testing and iteration. Ideas are validated with real users before scaling. Assumptions are challenged early, not after launch.

This leads to better product-market fit and faster adaptation to change.


6. Quality and Consistency

When teams share a user-focused mindset, the entire product feels cohesive.

Design, functionality, and messaging align under one clear principle: delivering value.

This consistency builds trust — and trust drives retention.


7. Meaningful Innovation

Innovation is not about adding more. It’s about understanding deeper.

By focusing on underlying problems, teams discover smarter and often simpler solutions. These insights lead to differentiated features and stronger competitive positioning.


8. Scalability and Long-Term Vision

Product thinking extends beyond launch day.

Products built on validated problems and strong foundations are easier to scale. As the user base grows, the solution evolves naturally.

This mindset supports sustainable, long-term success — not just short-term releases.


The Strategic Advantage

Product thinking transforms development from a task-based process into a strategic discipline.

It helps organizations:

  • Build what truly matters
  • Reduce waste
  • Deliver measurable value
  • Innovate intentionally
  • Scale with confidence

In today’s fast-moving, user-driven market, this approach is not optional — it is a competitive advantage.

If your goal is to build products that last, product thinking is where the journey begins.

Deploying and Connecting the i9 AI Agent to WordPress   Why Users Complain About Digital…

Deploying and Connecting the i9 AI Agent to WordPress

 

Why Users Complain About Digital Assistants: The Real Problems Behind Smart Features

As smart applications continue to evolve, digital assistants, AI recommendations, and automation tools have become central to modern user experiences. From shopping apps to banking platforms, these intelligent features promise convenience, speed, and personalization.

But there’s a growing problem.

Based on insights from KiaApp’s analysis of smart app behavior, many users are increasingly frustrated—not because the technology is weak, but because it often fails to align with real human expectations.

The biggest complaints about digital assistants reveal one clear truth:

Intelligence without transparency creates distrust.

1. Lack of Transparency and User Control

One of the most common complaints about digital assistants is simple:

“The app changed something without telling me.”

This frustration points to a serious flaw in many AI-powered systems. Digital assistants often make decisions behind the scenes—changing settings, filtering content, triggering workflows, or saving personal preferences—without clearly explaining why.

While automation is designed to save time, hidden decisions can feel invasive.

Users want three things:

 

    • To know what changed

    • To know why it changed

    • To have the power to undo or adjust it

Without these controls, even advanced AI features feel unpredictable.

Why it matters:

A smart assistant should support human decisions, not replace them without permission.


2. Blocking Access to Human Support

Another major complaint sounds like this:

“I just want to talk to a real person.”

This is one of the most damaging mistakes in digital assistant design.

Instead of helping users solve problems, some assistants trap them in endless loops of automated replies, repetitive questions, and irrelevant suggestions.

This becomes especially critical in industries like:

 

    • Banking

    • Insurance

    • Healthcare

    • Travel

In these situations, users are often stressed and need fast, accurate human help.

When AI refuses to step aside, it stops being helpful and becomes a barrier.

Best practice:

Smart systems must know their limits and provide a clear path to human support.


3. No Explanation Behind Decisions

A major weakness in many AI assistants is the inability to explain:

“Why this option and not another?”

For example:

 

    • Why was this product recommended?

    • Why was this payment method selected?

    • Why did the app choose this route or schedule?

Most assistants give answers without showing the reasoning behind them.

This creates uncertainty.

If users don’t understand the logic, they can’t judge whether the recommendation matches their actual needs.

This is where trust breaks.

The solution:

AI should explain its reasoning in simple language, especially when multiple options exist.


4. Too Much Talking, Too Little Value

Another common complaint:

“It talks too much but says very little.”

Many digital assistants overload users with:

 

    • Long responses

    • Generic explanations

    • Repetitive instructions

    • Unclear answers

This becomes even worse when the assistant misunderstands the same question multiple times.

Instead of reducing effort, the interaction becomes exhausting.

Good digital assistants should be:

 

    • Fast

    • Direct

    • Context-aware

    • Easy to understand

Users value clarity more than complexity.


The Future of Smart Assistants: Human-Centered AI

The future of AI-powered apps depends on one important principle:

Respect the user’s intent.

Digital assistants should:

✔ Explain their actions
✔ Offer easy controls
✔ Escalate to humans when needed
✔ Adapt to changing context
✔ Keep communication clear and concise

The smartest assistant is not the one with the most advanced algorithm.

It’s the one that makes users feel understood, respected, and in control.

Final Thought

Smart features are no longer optional in modern apps.

But if they ignore transparency, flexibility, and human needs, they quickly become a source of frustration.

The lesson is clear:

Technology should feel like help—not like resistance.

 

Why Users Complain About Digital Assistants: The Real Problems Behind Smart Features

As smart applications continue to evolve, digital assistants, AI recommendations, and automation tools have become central to modern user experiences. From shopping apps to banking platforms, these intelligent features promise convenience, speed, and personalization.

But there’s a growing problem.

Based on insights from KiaApp’s analysis of smart app behavior, many users are increasingly frustrated—not because the technology is weak, but because it often fails to align with real human expectations.

The biggest complaints about digital assistants reveal one clear truth:

Intelligence without transparency creates distrust.

1. Lack of Transparency and User Control

One of the most common complaints about digital assistants is simple:

“The app changed something without telling me.”

This frustration points to a serious flaw in many AI-powered systems. Digital assistants often make decisions behind the scenes—changing settings, filtering content, triggering workflows, or saving personal preferences—without clearly explaining why.

While automation is designed to save time, hidden decisions can feel invasive.

Users want three things:

 

    • To know what changed

    • To know why it changed

    • To have the power to undo or adjust it

Without these controls, even advanced AI features feel unpredictable.

Why it matters:

A smart assistant should support human decisions, not replace them without permission.


2. Blocking Access to Human Support

Another major complaint sounds like this:

“I just want to talk to a real person.”

This is one of the most damaging mistakes in digital assistant design.

Instead of helping users solve problems, some assistants trap them in endless loops of automated replies, repetitive questions, and irrelevant suggestions.

This becomes especially critical in industries like:

 

    • Banking

    • Insurance

    • Healthcare

    • Travel

In these situations, users are often stressed and need fast, accurate human help.

When AI refuses to step aside, it stops being helpful and becomes a barrier.

Best practice:

Smart systems must know their limits and provide a clear path to human support.


3. No Explanation Behind Decisions

A major weakness in many AI assistants is the inability to explain:

“Why this option and not another?”

For example:

 

    • Why was this product recommended?

    • Why was this payment method selected?

    • Why did the app choose this route or schedule?

Most assistants give answers without showing the reasoning behind them.

This creates uncertainty.

If users don’t understand the logic, they can’t judge whether the recommendation matches their actual needs.

This is where trust breaks.

The solution:

AI should explain its reasoning in simple language, especially when multiple options exist.


4. Too Much Talking, Too Little Value

Another common complaint:

“It talks too much but says very little.”

Many digital assistants overload users with:

 

    • Long responses

    • Generic explanations

    • Repetitive instructions

    • Unclear answers

This becomes even worse when the assistant misunderstands the same question multiple times.

Instead of reducing effort, the interaction becomes exhausting.

Good digital assistants should be:

 

    • Fast

    • Direct

    • Context-aware

    • Easy to understand

Users value clarity more than complexity.


The Future of Smart Assistants: Human-Centered AI

The future of AI-powered apps depends on one important principle:

Respect the user’s intent.

Digital assistants should:

✔ Explain their actions
✔ Offer easy controls
✔ Escalate to humans when needed
✔ Adapt to changing context
✔ Keep communication clear and concise

The smartest assistant is not the one with the most advanced algorithm.

It’s the one that makes users feel understood, respected, and in control.

Final Thought

Smart features are no longer optional in modern apps.

But if they ignore transparency, flexibility, and human needs, they quickly become a source of frustration.

The lesson is clear:

Technology should feel like help—not like resistance.

Deploying and Connecting the i9 AI Agent to WordPress

Add Your Deploying and Connecting the i9 AI Agent to WordPress

I created my i9 AI Agent with Python and Google ADK. It uses MongoDB as its NoSQL database. After testing the agent on my Mac, I prepared it for uploading to my host.

First, I put all the project files in one folder and compressed the folder as a ZIP file. I did not include my API keys or passwords in the ZIP file because this information must stay private.

Next, I opened cPanel and went to File Manager. I uploaded the ZIP file to the correct folder and extracted it. Then, I configured the Python application, installed the required packages, and added the API key as an environment variable. After starting the application, my agent received a public HTTPS link.

To connect the agent to my WordPress website, I entered the WordPress dashboard. Then, I went to Appearance → Menus.

 

WordPress dashboard showing the Appearance and Menus options

                                                                                                                                        Go to Appearance and select Menus in the WordPress dashboard.

 

I selected Custom Links, entered the agent’s public link, and used AI Agent for i9 as the navigation label. Finally, I added it to the menu and clicked Save Menu.

Now visitors can open and use my AI shopping assistant directly from the website menu.

WordPress custom menu settings for the i9 AI Agent

Add the agent’s public URL and enter “AI Agent for i9” as the navigation label.

Add Your Heading Text Here

Explore Smarter Apps and Digital Tools

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:

bash
xcode-select --install

Install Homebrew, then Python:

bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" brew install python

Check:

bash
python3 --version

Create the project on a Mac

Open Terminal. Create a folder and a virtual environment:

bash
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.

Why Users Complain About Digital Assistants: The Real Problems Behind Smart Features

Frustrated user overwhelmed by digital assistant interfaces

Why Users Complain About Digital Assistants: The Real Problems Behind Smart Features

As smart applications continue to evolve, digital assistants, AI recommendations, and automation tools have become central to modern user experiences. From shopping apps to banking platforms, these intelligent features promise convenience, speed, and personalization.

But there’s a growing problem.

Based on insights from KiaApp’s analysis of smart app behavior, many users are increasingly frustrated—not because the technology is weak, but because it often fails to align with real human expectations.

The biggest complaints about digital assistants reveal one clear truth:

Intelligence without transparency creates distrust.

1. Lack of Transparency and User Control

One of the most common complaints about digital assistants is simple:

“The app changed something without telling me.”

This frustration points to a serious flaw in many AI-powered systems. Digital assistants often make decisions behind the scenes—changing settings, filtering content, triggering workflows, or saving personal preferences—without clearly explaining why.

While automation is designed to save time, hidden decisions can feel invasive.

Users want three things:

 

    • To know what changed

    • To know why it changed

    • To have the power to undo or adjust it

Without these controls, even advanced AI features feel unpredictable.

Why it matters:

A smart assistant should support human decisions, not replace them without permission.


2. Blocking Access to Human Support

Another major complaint sounds like this:

“I just want to talk to a real person.”

This is one of the most damaging mistakes in digital assistant design.

Instead of helping users solve problems, some assistants trap them in endless loops of automated replies, repetitive questions, and irrelevant suggestions.

This becomes especially critical in industries like:

 

    • Banking

    • Insurance

    • Healthcare

    • Travel

In these situations, users are often stressed and need fast, accurate human help.

When AI refuses to step aside, it stops being helpful and becomes a barrier.

Best practice:

Smart systems must know their limits and provide a clear path to human support.


3. No Explanation Behind Decisions

A major weakness in many AI assistants is the inability to explain:

“Why this option and not another?”

For example:

 

    • Why was this product recommended?

    • Why was this payment method selected?

    • Why did the app choose this route or schedule?

Most assistants give answers without showing the reasoning behind them.

This creates uncertainty.

If users don’t understand the logic, they can’t judge whether the recommendation matches their actual needs.

This is where trust breaks.

The solution:

AI should explain its reasoning in simple language, especially when multiple options exist.


4. Too Much Talking, Too Little Value

Another common complaint:

“It talks too much but says very little.”

Many digital assistants overload users with:

 

    • Long responses

    • Generic explanations

    • Repetitive instructions

    • Unclear answers

This becomes even worse when the assistant misunderstands the same question multiple times.

Instead of reducing effort, the interaction becomes exhausting.

Good digital assistants should be:

 

    • Fast

    • Direct

    • Context-aware

    • Easy to understand

Users value clarity more than complexity.


The Future of Smart Assistants: Human-Centered AI

The future of AI-powered apps depends on one important principle:

Respect the user’s intent.

Digital assistants should:

✔ Explain their actions
✔ Offer easy controls
✔ Escalate to humans when needed
✔ Adapt to changing context
✔ Keep communication clear and concise

The smartest assistant is not the one with the most advanced algorithm.

It’s the one that makes users feel understood, respected, and in control.

Final Thought

Smart features are no longer optional in modern apps.

But if they ignore transparency, flexibility, and human needs, they quickly become a source of frustration.

The lesson is clear:

Technology should feel like help—not like resistance.

Why Users Complain About Digital Assistants: The Real Problems Behind Smart Features

As smart applications continue to evolve, digital assistants, AI recommendations, and automation tools have become central to modern user experiences. From shopping apps to banking platforms, these intelligent features promise greater convenience, speed, and personalization.

But there is a growing problem.

Based on KiaApp’s analysis of smart application behavior, many users are becoming increasingly frustrated—not because the technology is incapable, but because it often fails to meet real human expectations.

The most common complaints about digital assistants reveal one important truth:

Intelligence without transparency creates distrust.

1. Lack of Transparency and User Control

One of the most common complaints about digital assistants is:

“The app changed something without telling me.”

This frustration highlights a serious flaw in many AI-powered systems. Digital assistants frequently make decisions behind the scenes, such as changing settings, filtering content, triggering workflows, or saving personal preferences without clearly explaining what happened or why.

Although automation is intended to save time, hidden decisions can feel intrusive and unpredictable.

What Users Expect

Users want three basic things:

  • To know what changed

  • To understand why it changed

  • To have the ability to undo or adjust the change

Without these controls, even the most advanced AI features can become difficult to trust.

Why It Matters

A smart assistant should support human decision-making, not replace it without permission. Transparency gives users confidence and helps them remain in control of their experience.

2. Blocking Access to Human Support

Another major complaint is:

“I just want to talk to a real person.”

Preventing users from reaching human support is one of the most damaging mistakes in digital assistant design.

Instead of helping people solve their problems, some assistants trap them in endless loops of automated replies, repetitive questions, and irrelevant suggestions.

Where Human Support Matters Most

The ability to reach a person is especially important in industries such as:

  • Banking

  • Insurance

  • Healthcare

  • Travel

In these situations, users may already be stressed and need fast, accurate, and personalized assistance.

When an AI assistant refuses to step aside, it stops being helpful and becomes another obstacle.

Best Practice

Smart systems must recognize their limitations and provide a clear, visible, and immediate path to human support when automation cannot resolve the issue.

3. No Explanation Behind Decisions

Many AI assistants are unable to answer a simple but important question:

“Why did you choose this option instead of another?”

For example, users may want to know:

  • Why a particular product was recommended

  • Why a specific payment method was selected

  • Why the application chose a certain route or schedule

Most assistants provide an answer or recommendation without explaining the reasoning behind it.

How This Damages Trust

When users cannot understand the logic behind a decision, they cannot determine whether the recommendation matches their actual needs.

This uncertainty weakens confidence in the system and can eventually cause users to stop relying on it.

The Solution

AI assistants should explain their reasoning in clear, simple language—especially when several options are available or when a decision could significantly affect the user.

4. Too Much Talking and Too Little Value

Another common complaint is:

“It talks too much but says very little.”

Many digital assistants overwhelm users with:

  • Long responses

  • Generic explanations

  • Repetitive instructions

  • Unclear answers

The experience becomes even more frustrating when the assistant repeatedly misunderstands the same question.

Instead of reducing effort, the interaction becomes exhausting.

What a Good Digital Assistant Should Be

An effective assistant should be:

  • Fast

  • Direct

  • Context-aware

  • Easy to understand

Users value clarity and usefulness more than unnecessary complexity.

The Future of Smart Assistants: Human-Centered AI

The future of AI-powered applications depends on one essential principle:

Respect the user’s intent.

Principles of Human-Centered AI

Digital assistants should:

  • Explain their actions

  • Provide simple and accessible controls

  • Escalate to human support when necessary

  • Adapt to changing circumstances and context

  • Keep communication clear and concise

The smartest assistant is not necessarily the one with the most advanced algorithm. It is the one that makes users feel understood, respected, and in control.

Final Thoughts

Smart features are no longer optional in modern applications. However, when they ignore transparency, flexibility, and human needs, they quickly become a source of frustration.

The lesson is clear:

Technology should feel like help—not like resistance.

How we made I-9 Agent on a Mac

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.

ProgramWhy it was used
Code editorThe editor where the agent, tools, and catalog page were written.
Python 3.13The language the agent and catalog server run in. A virtualenv (.venv) keeps packages isolated.
Terminal / zshRuns adk web for chat, python -m i9_agent.catalog_ui for the list, and gcloud for deploy.
GitVersion control for the I9_Agent project.
HomebrewInstalls 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. 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. 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. 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. 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. 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. 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. 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

PathRole
i9_agent/agent.pyGemini instructions and tools
i9_agent/tools.pyProduct search + Telegram notify
i9_agent/i9_api.pyCatalog pages of 20 from API or JSON
i9_agent/catalog_ui.pyHTTP server for the list and thumbnails
i9_agent/static/catalog.htmlThe dark RTL product UI
Dockerfile + entrypoint.shWhat Cloud Run runs

Complete Command Guide for ADK Web Development and Google Cloud Deployment

Complete Google ADK CLI Command List

The current Google ADK Python CLI command tree includes api_server, conformance, create, deploy, eval, eval_set, migrate, optimize, run, test, and web. Your installed version may differ, so verify it locally with adk --help. Official ADK CLI reference

1. Display ADK help

adk --help

Shows every top-level command available in your installed ADK version.

For help with a specific command:

adk COMMAND --help

Example:

adk web --help

2. Display the installed ADK version

adk --version

Confirms which ADK CLI version is active.


3. Create a new agent project

adk create APP_NAME

Example:

adk create my_agent

Creates a new directory containing a prepopulated agent template.

Useful options:

adk create my_agent --model=MODEL_NAME
adk create my_agent --api_key=API_KEY
adk create my_agent \
  --project=PROJECT_ID \
  --region=REGION

Available options:

  • --model: Model for the root agent
  • --api_key: Google AI API key
  • --project: Google Cloud project for Vertex AI
  • --region: Google Cloud region for Vertex AI

Avoid placing API keys directly in shell history; environment variables or secret management are safer.


4. Run an agent in the terminal

Interactive mode:

adk run path/to/my_agent

Single-query mode:

adk run path/to/my_agent "Hello"

This runs the agent directly in the terminal without starting a browser.

Useful options:

adk run path/to/my_agent --save_session
adk run path/to/my_agent --resume=SESSION_FILE.json
adk run path/to/my_agent --replay=REPLAY_FILE.json
adk run path/to/my_agent --state='{"language":"English"}'
adk run path/to/my_agent --timeout=30s
adk run path/to/my_agent --in_memory
adk run path/to/my_agent --jsonl

Important options:

  • --save_session: Save the session when exiting
  • --session_id: Set the saved session ID
  • --resume: Continue a saved session
  • --replay: Replay queries from a JSON file
  • --state: Provide initial state as JSON
  • --timeout: Limit the duration of a turn
  • --in_memory: Avoid persistent session storage
  • --jsonl: Produce machine-readable JSONL output
  • --default_llm_model: Set the default model
  • --session_service_uri: Select session storage
  • --artifact_service_uri: Select artifact storage
  • --memory_service_uri: Select memory storage

5. Start the ADK development web interface

adk web

From the parent directory containing your agents:

adk web .

Specify the agents directory:

adk web path/to/agents

Specify a port:

adk web --port=8080 path/to/agents

Allow a frontend origin:

adk web \
  --allow_origins=https://example.com \
  path/to/agents

Enable debugging and automatic reload:

adk web \
  --log_level=DEBUG \
  --reload \
  --reload_agents \
  path/to/agents

Important options:

  • --host: Binding address; default is 127.0.0.1
  • --port: Server port
  • --allow_origins: Allowed CORS origins
  • -v or --verbose: Debug logging
  • --log_level: Logging level
  • --reload: Restart the server after code changes
  • --reload_agents: Reload changed agents
  • --url_prefix: Serve behind a path such as /adk
  • --logo-text: Customize the UI logo text
  • --logo-image-url: Customize the UI logo image
  • --a2a: Enable the Agent-to-Agent endpoint
  • --trace_to_cloud: Export Cloud Trace data
  • --otel_to_cloud: Export OpenTelemetry data
  • --default_llm_model: Supply a default model
  • --extra_plugins: Enable additional plugins
  • --trigger_sources: Enable sources such as Pub/Sub or Eventarc
  • --session_service_uri: Configure session storage
  • --artifact_service_uri: Configure artifact storage
  • --memory_service_uri: Configure memory storage
  • --use_local_storage: Store local ADK data under .adk

adk web is intended for development and testing—not as a production web interface.


6. Start the ADK API server

adk api_server

Specify the agents directory:

adk api_server path/to/agents

Specify the host and port:

adk api_server \
  --host=127.0.0.1 \
  --port=8000 \
  path/to/agents

Allow requests from a frontend:

adk api_server \
  --allow_origins=https://example.com \
  path/to/agents

Automatically create missing sessions:

adk api_server \
  --auto_create_session \
  path/to/agents

Include the web interface:

adk api_server \
  --with_ui \
  path/to/agents

This exposes agents through REST endpoints for connection to a website, mobile application, backend, or test client. By default, it runs at http://localhost:8000. ADK API Server documentation

It supports most of the server options available to adk web, including:

  • --host
  • --port
  • --allow_origins
  • --log_level
  • --reload
  • --reload_agents
  • --a2a
  • --url_prefix
  • --trigger_sources
  • --session_service_uri
  • --artifact_service_uri
  • --memory_service_uri
  • --trace_to_cloud
  • --otel_to_cloud

Deployment commands

7. Display deployment options

adk deploy --help

ADK currently provides deployment subcommands for:

  • Cloud Run
  • Agent Engine
  • Google Kubernetes Engine

8. Deploy to Cloud Run

adk deploy cloud_run \
  --project=PROJECT_ID \
  --region=REGION \
  path/to/my_agent

With an explicit service name:

adk deploy cloud_run \
  --project=PROJECT_ID \
  --region=REGION \
  --service_name=my-agent-service \
  --app_name=my_agent \
  path/to/my_agent

Development deployment with the ADK UI:

adk deploy cloud_run \
  --project=PROJECT_ID \
  --region=REGION \
  --service_name=my-agent-service \
  --with_ui \
  path/to/my_agent

The UI is intended only for development and testing. Production deployments should normally expose the API server without --with_ui.

Important options:

  • --project: Google Cloud project
  • --region: Cloud Run region
  • --service_name: Cloud Run service name
  • --app_name: ADK API application name
  • --port: Server port
  • --with_ui: Include the development UI
  • --trace_to_cloud: Enable Cloud Trace
  • --otel_to_cloud: Enable Google Cloud observability
  • --log_level: Logging level
  • --adk_version: ADK version deployed
  • --a2a: Enable the A2A endpoint
  • --allow_origins: Configure CORS
  • --trigger_sources: Enable Pub/Sub or Eventarc triggers
  • --session_service_uri: Configure session storage
  • --artifact_service_uri: Configure artifact storage
  • --memory_service_uri: Configure memory storage

Pass additional gcloud flags after --:

adk deploy cloud_run \
  --project=PROJECT_ID \
  --region=REGION \
  path/to/my_agent \
  -- \
  --no-allow-unauthenticated \
  --min-instances=2

Official Cloud Run deployment reference


9. Deploy to Vertex AI Agent Engine

Using a Google Cloud project:

adk deploy agent_engine \
  --project=PROJECT_ID \
  --region=REGION \
  --display_name="My Agent" \
  path/to/my_agent

Using Express Mode:

adk deploy agent_engine \
  --api_key=API_KEY \
  path/to/my_agent

Update an existing Agent Engine resource:

adk deploy agent_engine \
  --project=PROJECT_ID \
  --region=REGION \
  --agent_engine_id=AGENT_ENGINE_ID \
  path/to/my_agent

Important options:

  • --api_key: Express Mode API key
  • --project: Google Cloud project
  • --region: Google Cloud region
  • --agent_engine_id: Update an existing deployment
  • --display_name: Agent display name
  • --description: Agent description
  • --adk_app: Python file defining the ADK application
  • --adk_app_object: Either root_agent or app
  • --env_file: Environment-variable file
  • --requirements_file: Python requirements file
  • --agent_engine_config_file: Agent Engine configuration file
  • --validate-agent-import: Validate imports before deployment
  • --trace_to_cloud: Enable Cloud Trace
  • --otel_to_cloud: Enable OpenTelemetry

10. Deploy to Google Kubernetes Engine

adk deploy gke \
  --project=PROJECT_ID \
  --region=REGION \
  --cluster_name=CLUSTER_NAME \
  path/to/my_agent

Expose it through a load balancer:

adk deploy gke \
  --project=PROJECT_ID \
  --region=REGION \
  --cluster_name=CLUSTER_NAME \
  --service_type=LoadBalancer \
  path/to/my_agent

Important options:

  • --project
  • --region
  • --cluster_name
  • --service_name
  • --app_name
  • --port
  • --service_type=ClusterIP
  • --service_type=LoadBalancer
  • --with_ui
  • --trace_to_cloud
  • --otel_to_cloud
  • --log_level
  • --adk_version
  • --trigger_sources
  • Storage and memory service URI options

Evaluation and testing

11. Evaluate an agent

adk eval \
  path/to/my_agent/__init__.py \
  path/to/eval_set.json

Evaluate multiple sets:

adk eval \
  path/to/my_agent/__init__.py \
  eval_set_1.json \
  eval_set_2.json

Run selected cases:

adk eval \
  path/to/my_agent/__init__.py \
  eval_set.json:eval_1,eval_2

Print detailed results:

adk eval \
  --print_detailed_results \
  path/to/my_agent/__init__.py \
  eval_set.json

Important options:

  • --config_file_path
  • --print_detailed_results
  • --eval_storage_uri
  • --log_level
  • --enable_features
  • --disable_features

12. Display evaluation-set commands

adk eval_set --help

The eval_set group manages collections of evaluation cases.


13. Create an empty evaluation set

adk eval_set create \
  path/to/my_agent/__init__.py \
  EVAL_SET_ID

With Cloud Storage:

adk eval_set create \
  --eval_storage_uri=gs://BUCKET_NAME \
  path/to/my_agent/__init__.py \
  EVAL_SET_ID

14. Add an evaluation case

Using a scenarios file:

adk eval_set add_eval_case \
  --scenarios_file=scenarios.json \
  path/to/my_agent/__init__.py \
  EVAL_SET_ID

Using a session input file:

adk eval_set add_eval_case \
  --session_input_file=session.json \
  path/to/my_agent/__init__.py \
  EVAL_SET_ID

15. Generate evaluation cases

adk eval_set generate_eval_cases \
  --user_simulation_config_file=user-simulation.json \
  path/to/my_agent/__init__.py \
  EVAL_SET_ID

This uses the Vertex AI evaluation tooling to generate conversation scenarios dynamically.


16. Run ADK JSON tests

adk test

Specify a folder:

adk test path/to/agents

Rebuild test files by running the real agent:

adk test --rebuild path/to/agents

Conformance testing

17. Display conformance commands

adk conformance --help

Conformance tests check whether agent behavior remains consistent.


18. Record conformance tests

Non-streaming:

adk conformance record tests none

SSE streaming:

adk conformance record tests sse

Bidirectional streaming:

adk conformance record tests bidi

This feature is marked as work in progress in the current reference.


19. Run conformance tests

adk conformance test

Specify test folders:

adk conformance test tests/core tests/tools

Generate a Markdown report:

adk conformance test \
  --generate_report \
  --report_dir=reports

Choose replay mode:

adk conformance test \
  --mode=replay \
  tests

The documented live mode is not yet implemented in the current reference.


Optimization and migration

20. Optimize the root-agent instructions

adk optimize \
  --sampler_config_file_path=sampler-config.json \
  path/to/my_agent/__init__.py

With a custom optimizer configuration:

adk optimize \
  --sampler_config_file_path=sampler-config.json \
  --optimizer_config_file_path=optimizer-config.json \
  --print_detailed_results \
  path/to/my_agent/__init__.py

This uses the GEPA optimizer to improve the root agent’s instructions based on evaluation data.


21. Display migration commands

adk migrate --help

The migration group currently provides session-database migration.


22. Migrate a session database

adk migrate session \
  --source_db_url=sqlite:///old-sessions.db \
  --dest_db_url=sqlite:///new-sessions.db

Migrates session data into the latest database schema.


Setup commands related to ADK

These are package-management commands, not ADK subcommands.

Install Google ADK

pip install google-adk

Upgrade Google ADK

pip install --upgrade google-adk

Inspect the installed package

pip show google-adk

Confirm the executable location

which adk

Stop any running ADK server

Ctrl+C

Complete command tree

adk
├── api_server
├── conformance
│   ├── record
│   └── test
├── create
├── deploy
│   ├── agent_engine
│   ├── cloud_run
│   └── gke
├── eval
├── eval_set
│   ├── add_eval_case
│   ├── create
│   └── generate_eval_cases
├── migrate
│   └── session
├── optimize
├── run
├── test
└── web

For everyday development, the five most important commands are:

adk create my_agent
adk run my_agent
adk web .
adk api_server .
adk deploy cloud_run --project=PROJECT_ID --region=REGION my_agent

Here is the command list with an additional explanation and its web-development usage:

  1. Activate the Python virtual environment:
source venv/bin/activate

Description: Activates the project’s isolated Python environment, so Python and pip use project-specific packages.

Web-development usage: Prevents dependencies from differentPython web projects—such as Django, Flask, FastAPI, or ADK—from conflicting.


  1. Confirm which Python installation is active:
which python

Description: Displays the filesystem path of the Python executable currently being used.

Web-development usage: Confirms that your terminal is using the project’s virtual-environment Python instead of the system Python.


  1. Check the installed Google ADK version:
adk --version

Description: Prints the installed version of the Google Agent Development Kit command-line tool.

Web-development usage: Helps verify compatibility when developing an AI agent that will connect to a website or web application.


  1. Display information about the installed ADK package:
pip show google-adk

Description: Shows the package version, installation location, dependencies, and other metadata.

Web-development usage: Useful for debugging missing packages, dependency conflicts, or differences between development and deployment environments.


  1. Start the ADK web interface from the current project:
adk web .

Description: Starts ADK’s local development server and web interface using the project in the current directory.

Web-development usage: Lets you test and interact with an AI agent through a browser before connecting it to your production website.


  1. Stop the running ADK server:
Ctrl+C

Description: Sends an interrupt signal to the active terminal process and stops the local server.

Web-development usage: Used to stop a development server before changing configuration, installing packages, or restarting the application.

Ctrl+C stops ADK, but it does not exit the virtual environment.


  1. Exit the virtual environment:
deactivate

Description: Returns the terminal to the system’s default Python environment.

Web-development usage: Useful when you finish working on one Python web project and want to switch to another environment or project.


  1. Open the current folder in macOS Finder:
open .

Description: Opens the terminal’s current directory in the macOS Finder application.

Web-development usage: Makes it convenient to inspect, move, or open project files with graphical applications and code editors.


  1. Display the .env file:
cat .env

Description: Prints the contents of the project’s environment-variable file in the terminal.

Web-development usage: Helps inspect configuration values such as database addresses, API endpoints, secret keys, ports, and environment settings.

Be careful: .env may contain API keys and passwords. Never share its output, commit it to Git, or include it in screenshots.

A safer way to list only the variable names is:

sed 's/=.*$/=***HIDDEN***/' .env

  1. List deployed Cloud Run services:
gcloud run services list

Description: Lists the Cloud Run services available in the active Google Cloud project.

Web-development usage: Helps locate deployed websites, APIs, backends, webhooks, and AI-agent services, along with their regions and URLs.

If necessary, specify the project and region:

gcloud run services list --project=YOUR_PROJECT_ID --region=YOUR_REGION

This is helpful when your local gcloud configuration points to a different project or default region.


  1. Check whether the Cloud Run API is enabled:
gcloud services list --enabled | grep run.googleapis.com

Description: Lists enabled Google Cloud APIs and filters the results for the Cloud Run API.

Web-development usage: Cloud Run cannot deploy or manage a containerized web application until its required API is enabled.

If nothing is returned, enable it with:

gcloud services enable run.googleapis.com

This prepares the active Google Cloud project to deploy web applications, APIs, and agent services on Cloud Run.