Why this series exists

In the RAG series, we built Nimbus HelpDesk AI: a support bot that answers from a company’s own documents, cites its sources, and says “I don’t know” instead of making things up. It knows the refund policy word for word.

Then a customer writes: “Please refund order #1042.” And Nimbus can only explain the policy. It can’t open the order, check the date, or start the refund. It knows what to do, but it can’t do anything. Every real request still ends with “please contact our support team”.

That gap, between a bot that answers and a bot that acts, is what AI agents close. An agent is an AI model that can choose actions, have your code carry them out, look at the results, and decide what to do next. It’s the most talked-about idea in AI right now, and also one of the most confusing, because most tutorials hide it behind Python frameworks that do the interesting parts for you.

This series builds an agent the way the RAG series built retrieval: step by step, in plain PHP and MySQL 8, with no agent framework. By the end you’ll understand every moving part: how a model asks your code to run a function, how the loop works, how memory works, and most importantly, how to stop an agent from doing something it shouldn’t.

Who this is for

You’ll feel at home if you:

  • Write PHP comfortably and know your way around MySQL.
  • Have called an AI API before, or have followed the RAG series.
  • Want to understand how agents work, not just install a library and hope.

You don’t need any machine-learning background. As in the RAG series, every AI term is explained in the post where it first appears. The RAG series isn’t required either; Part 5 brings in everything it needs from it.

What you’ll have built by the end

Nimbus HelpDesk AI, now with hands. The same support bot, upgraded into an agent that can:

  • Look up orders and check refund eligibility against the policy, written in PHP so the model can’t bend it.
  • Open support tickets and request refunds, with a human approving every refund before any money moves.
  • Work through multi-step requests like “refund my order” (check, then request, then confirm) on its own.
  • Search the help center when it needs the policy, and find exceptions such as duplicate charges.
  • Remember the conversation, so “what about my other order?” just works.
  • Hand over to a person when the customer asks, or when it gets stuck.
  • Resist prompt injection, the attack where hidden text tries to take control of the bot.

And you’ll ship it: tested against real support scenarios, with the cost of every conversation measured, behind a secure web chat.

Free to follow: Gemini or OpenAI

All the code comes in two versions:

  • Gemini Setup uses Google Gemini. Its free tier means you can follow the whole series without paying anything. Recommended for learning.
  • OpenAI Setup uses OpenAI (gpt-4o-mini), a paid API.

The agent logic is identical in both. Only the small layer that talks to the AI provider differs, because each provider formats requests and tool calls a little differently, so the code may vary slightly between the two. Each post shows both versions wherever they differ.

The roadmap

Eight parts take you from “what is an agent?” to a deployed, tested agent. Each one builds on the last, so read them in order.

# Part What it covers
1 From Answering to Acting: What Makes an AI Agent Chatbot vs RAG bot vs agent, and a first hand-made agent that reads real orders.
2 Tool Calling in Plain PHP How the model asks your code to run a function, for Gemini and OpenAI.
3 Giving Nimbus Its First Real Tools Refund checks and support tickets, and how to design tools the model picks correctly.
4 The Agent Loop: Thinking in Steps Multi-step tasks, with step limits, retries and a trace of every decision.
5 RAG + Tools Together Help-center search as a tool: policies, exceptions and citations.
6 Memory: Conversations That Remember Storing conversations in MySQL, and trimming them so costs stay low.
7 Guardrails and Human Approval Permissions, a human-approval queue, escalation, and a prompt-injection attack that fails.
8 Evaluate, Control Cost, and Ship Test scenarios, cost per conversation, and a secure web chat.

Before you start: prerequisites

  • PHP 8.0+ with the cURL and pdo_mysql extensions (php -v to check). Plain PHP, no framework.
  • MySQL 8.0+ (SELECT VERSION();). Stock MySQL 8, no plugins.
  • An AI API key: a free Gemini key from Google AI Studio, or an OpenAI key.
  • A code editor and a terminal. That’s all.

The full code for every part, for both providers, is on GitHub: AI-Agents-in-PHP-MySQL. Each part has its own folder, so you can start from any checkpoint.

💡 On cost: with Gemini’s free tier, the whole series costs nothing. Free tiers have daily request limits, and an agent makes several requests per question, so if you hit a limit, switch to a “Flash-Lite” model in your settings. With OpenAI, a question costs a fraction of a cent; Part 8 shows you how to measure it exactly.

⚠️ On privacy: on Gemini’s free tier, Google may use what you send to improve its products. Use the sample data from the series, not real customer data.

How to read this series

  • Build along. Agents make much more sense when you watch one decide, step by step, in your own terminal.
  • Read the traces. From Part 4 on, every run prints what the agent decided and why. That’s where the real learning happens.
  • Try to break it. Ask confusing questions, give wrong order numbers, try to talk it into a refund it shouldn’t give. Part 7 is all about what happens next.
  • Trust the order. Each part’s code is the starting point for the next.

Ready? Let’s start with the question everything else depends on: what actually makes something an agent? That’s Part 1.