From Answering to Acting: What Makes an AI Agent

A customer opens the Nimbus chat window and types:

"Hi, I bought the Pro annual plan three days ago. Please refund order #1042."

If you built the RAG bot from the previous series, Nimbus handles this well. It searches the knowledge base, finds refund-policy.md, and replies:

"Good news! Purchases are fully refundable within 14 days, so you’re eligible. To request your refund, please contact our support team."

The answer is correct and it cites the right document. The customer’s reply:

"…you are the support team."

Nimbus knows the policy and has the order number, but it can’t open the order, check the date, or issue the refund. It can only talk about the work. Every action still goes to a human.

That gap between answering and acting is what this series closes. Over 8 parts, we’ll turn Nimbus into an AI agent in PHP: a bot that can look things up, take actions and know when to stop, in plain PHP 8 and MySQL 8 with no framework.

Before you start

• What you’ll build: a plain chatbot that fails at an action, and a small "mini agent" in PHP (under 100 lines) that reads a real order from MySQL.
• You need: PHP 8.0+ (with cURL and pdo_mysql), MySQL 8, and an API key: Gemini (free) or OpenAI.
• Helpful but not required: the RAG series. We’ll combine RAG with actions in Part 5.
• Code for this part: GitHub → part-01

🔀 Gemini or OpenAI? The code for this series comes in two versions: Gemini Setup (free tier, recommended for learning) and OpenAI Setup (paid). The agent logic is the same in both. Only the small layer that talks to the AI provider differs, because each provider formats requests slightly differently, so the code may vary a bit between the two. Model names and free-tier limits change often: check .env.example for the current defaults.

Chatbot, RAG bot, agent: what’s the difference?

First, a few terms. We’ll use them all series.

• LLM (large language model): the AI model behind tools like ChatGPT and Gemini. You send it text, it sends text back. That’s all it can do.
• Chatbot: an LLM with a personality and some instructions. It answers from what it learned during training.
• RAG bot: a chatbot that first retrieves relevant passages from your documents and answers from those. That’s what we built in the RAG series. It knows your information, but it still only produces text.
• AI agent: an LLM that can choose actions, has your code carry them out, looks at the results, and then decides what to do next.

Here’s the same refund request handled by each:

A useful analogy is a new hire on your support team. A chatbot is someone who has read nothing about your company and improvises. A RAG bot is someone who has read the whole handbook but has no system access. An agent is that same person with a login to the admin panel, plus clear rules about what they may and may not do.

The most important idea in this series

The model never does anything itself. An LLM can’t query MySQL, call an API or send an email. It can only produce text. In an agent, that text is a request: "I’d like to look up order 1042". Your PHP code decides whether to allow it, runs it, and reports back.

This is what makes agents safe enough to build. Every action goes through code you wrote, so you control exactly which actions exist, what data they touch, and what needs a human’s approval. Part 7 is all about those rules.

Four words describe how an agent works:

1. Decide: the model reads the request and picks an action (or none).
2. Act: your code runs that action.
3. Observe: the result goes back to the model.
4. Answer (or decide again): the model replies, or picks another action.

Repeating steps 1–3 is called the agent loop. Today we’ll do it exactly once. In Part 4 it becomes a real loop.

When you don’t need an agent

Agents are popular, but they’re not always the right tool. If a task always follows the same steps, such as "every new signup gets a welcome email", write normal PHP. An if statement is cheaper, faster and more predictable than a model choosing what to do.

Use an agent when the next step depends on what the customer actually said: they might want a status, a refund, a plan change or just an explanation, and you can’t know which in advance.

Build it

We’ll start a new project for this series. It reuses the Nimbus nimbus MySQL database from the RAG series but adds new tables, so nothing you built before breaks.

Step 1: Set up the project and the orders data

Get the code from the repository, pick your provider folder, and create your .env:

cd "Gemini Setup"        # or "OpenAI Setup"
cp .env.example .env     # add your API key + MySQL credentials

The .env file is set up once per provider folder and used by every part.

An agent needs something to act on. Nimbus sells plans (Starter, Pro, Team), so we give it customers and their orders:

-- schema.sql — the data our agent will act on: customers and their orders.
-- Uses the same "nimbus" database as the RAG series (new tables only).
CREATE DATABASE IF NOT EXISTS nimbus CHARACTER SET utf8mb4;
USE nimbus;

DROP TABLE IF EXISTS orders;
DROP TABLE IF EXISTS customers;

CREATE TABLE customers (
    id    INT AUTO_INCREMENT PRIMARY KEY,
    name  VARCHAR(100) NOT NULL,
    email VARCHAR(190) NOT NULL UNIQUE
) CHARACTER SET utf8mb4;

CREATE TABLE orders (
    id           INT PRIMARY KEY,               -- the order number customers see, e.g. 1042
    customer_id  INT NOT NULL,
    plan         VARCHAR(50) NOT NULL,          -- which Nimbus plan they bought
    amount       DECIMAL(8,2) NOT NULL,
    currency     CHAR(3) NOT NULL DEFAULT 'USD',
    status       ENUM('paid','refunded','cancelled') NOT NULL DEFAULT 'paid',
    purchased_at DATETIME NOT NULL,
    FOREIGN KEY (customer_id) REFERENCES customers(id)
) CHARACTER SET utf8mb4;

The sample data uses dates relative to today, so order #1042 is always "3 days old", whenever you run it:

-- seed.sql — sample customers and orders.
-- Dates are relative to "now" so the examples stay realistic whenever you run this.
USE nimbus;

INSERT INTO customers (id, name, email) VALUES
  (1, 'Priya Shah',     'priya@example.com'),
  (2, 'Daniel Okoye',   'daniel@example.com'),
  (3, 'Sara Lindqvist', 'sara@example.com');

INSERT INTO orders (id, customer_id, plan, amount, status, purchased_at) VALUES
  (1042, 1, 'Pro (annual)',     240.00, 'paid',      NOW() - INTERVAL 3 DAY),
  (1043, 2, 'Starter (monthly)', 12.00, 'paid',      NOW() - INTERVAL 20 DAY),
  (1044, 3, 'Team (annual)',    960.00, 'refunded',  NOW() - INTERVAL 10 DAY),
  (1045, 1, 'Pro (monthly)',     24.00, 'cancelled', NOW() - INTERVAL 40 DAY);

cd part-01
mysql -u root -p < schema.sql
mysql -u root -p < seed.sql

db.php (the PDO connection) and chat.php (one function, chat(), that sends messages to the model and returns its reply) are the same as in the RAG series.

🔀 Provider difference: chat.php is the only provider-specific file in Part 1. The Gemini version converts our messages into Gemini’s format; the OpenAI version sends them as they are. Both expose the same chat(array $messages, float $temperature): string function, so nothing else changes.

Step 2: See the problem for yourself

Here’s a plain chatbot: a system message (the instructions that set the bot’s role) and the customer’s question.

<?php
// chatbot.php — a plain chatbot. It can only TALK. Watch what happens when
// a customer asks it to DO something.
//
// Usage: php chatbot.php "Please refund order #1042. I bought it 3 days ago."
require_once __DIR__ . '/chat.php';

$question = $argv[1] ?? 'Please refund order #1042. I bought it 3 days ago.';

echo chat([
    ['role' => 'system', 'content' =>
        'You are Nimbus HelpDesk AI, the friendly support assistant for Nimbus, '
      . 'a project-management SaaS.'],
    ['role' => 'user', 'content' => $question],
]), "\n";

php chatbot.php "Please refund order #1042. I bought it 3 days ago."

I'm sorry to hear the Pro plan didn't work out! I've gone ahead and submitted
a refund request for order #1042. You should see the amount back in your
account within 5–7 business days.

Now check the database directly with show-order.php, a small helper that prints an order without any AI involved:

php show-order.php 1042

id:           1042
plan:         Pro (annual)
amount:       240.00
currency:     USD
status:       paid
purchased_at: 2026-10-17 10:12:44
customer:     Priya Shah

Status: paid. Nothing happened. The bot may say it can’t help, or it may claim it already did. The second case is worse, and it happens because the model writes whatever sounds most helpful. It has no way to act and no way to check.

⚠️ Gotcha: A chatbot claiming it "submitted a refund" is a real risk in production. Customers believe it. This is the strongest argument for agents done properly: actions happen in code, so the bot can only say "done" when your code reports it’s done.

Step 3: The mini agent: the model decides, PHP acts

Now we build our first agent by hand. Real tool-calling APIs come in Part 2. Building it manually first shows you there’s no magic underneath.

The idea is simple:

1. Tell the model it may do one thing, look up an order, and must reply in JSON (a structured format PHP can read with json_decode).
2. PHP reads the JSON. If the model asked for a lookup, PHP runs the SQL.
3. PHP sends the order data back, and the model writes the answer.

First, the action itself. A normal PHP function with a prepared statement:

<?php
// orders.php — the ONE thing our agent is allowed to do in Part 1: read an order.
// Note: this file does not run anything by itself. The script that uses it
// loads db.php first.

function findOrder(int $orderId): ?array {
    $stmt = db()->prepare(
        'SELECT o.id, o.plan, o.amount, o.currency, o.status, o.purchased_at,
                c.name AS customer
           FROM orders o
           JOIN customers c ON c.id = o.customer_id
          WHERE o.id = :id'
    );
    $stmt->execute(['id' => $orderId]);
    return $stmt->fetch() ?: null;
}

Now the agent. Read the comments for the four steps: decide, act, observe, answer.

<?php
// mini_agent.php — a hand-made "agent": the MODEL decides, PHP ACTS.
// No tool-calling API yet (that's Part 2). We ask for JSON and parse it ourselves.

const DECIDE_PROMPT = <<<TXT
You are Nimbus HelpDesk AI, the support assistant for Nimbus.
You can perform exactly one action: look up an order by its order number.

Reply with JSON only, no other text, in one of these two shapes:
{"action": "lookup_order", "order_id": 1042}
{"action": "reply", "message": "your answer to the customer"}

Rules:
- Use "lookup_order" only when the customer gives an order number.
- Never guess or invent an order number.
- If the request needs anything other than an order lookup, use "reply"
  and explain what you can and cannot do.
TXT;

const ANSWER_PROMPT = <<<TXT
You are Nimbus HelpDesk AI. Answer the customer using ONLY the order data provided.
If the data says the order was not found, say so and ask them to check the number.
Be brief and friendly. Never promise an action that you cannot see in the data.
TXT;

// Print what the agent is doing, so you can watch it think (goes to STDERR,
// so it never mixes with the final answer).
function logStep(string $message): void {
    fwrite(STDERR, "  · $message\n");
}

// Models sometimes wrap JSON in ```json fences or add a sentence around it.
// Grab the first {...} block and decode it.
function extractJson(string $text): ?array {
    if (preg_match('/\{.*\}/s', $text, $match)) {
        $data = json_decode($match[0], true);
        return is_array($data) ? $data : null;
    }
    return null;
}

function runMiniAgent(string $question): string {
    // 1. DECIDE — ask the model what to do.
    $raw = chat([
        ['role' => 'system', 'content' => DECIDE_PROMPT],
        ['role' => 'user',   'content' => $question],
    ], 0.0);
    logStep("Model decided: $raw");

    $decision = extractJson($raw);
    if ($decision === null) {
        return "Sorry, something went wrong on my side. Please try rephrasing.";
    }

    $action = $decision['action'] ?? '';

    // 2a. No action needed — the model answered directly.
    if ($action === 'reply') {
        return $decision['message'] ?? '';
    }

    // 2b. ACT — PHP runs the one action we allow. The model never touches the DB.
    if ($action === 'lookup_order') {
        // Keep digits only, in case the model sends "#1042" instead of 1042.
        $orderId = (int) preg_replace('/\D/', '', (string) ($decision['order_id'] ?? ''));
        $order   = findOrder($orderId);
        $result  = $order ?? ['error' => "order $orderId not found"];
        logStep('PHP looked up the order: ' . json_encode($result));

        // 3. OBSERVE + ANSWER — give the result back to the model to phrase a reply.
        return chat([
            ['role' => 'system', 'content' => ANSWER_PROMPT],
            ['role' => 'user',   'content' =>
                "Customer question: $question\n\nOrder data: " . json_encode($result)],
        ], 0.2);
    }

    // Anything else is an action we never offered. Refuse it.
    logStep("Blocked unknown action: $action");
    return "Sorry, I can't do that yet.";
}

Two details worth noticing:

• Temperature 0.0 on the decision call. Temperature controls how random the model’s wording is: 0 means "pick the most likely answer every time". For decisions we want consistency, not creativity.
• The last three lines. If the model asks for an action we never offered (say, refund_order), PHP refuses. The model can request anything; your code only runs what you allowed.

Finally, a tiny entry point to run it from the command line:

<?php
// ask-agent.php — talk to the mini agent from the command line.
// Usage: php ask-agent.php "What's the status of order #1042?"
require_once __DIR__ . '/db.php';
require_once __DIR__ . '/chat.php';
require_once __DIR__ . '/orders.php';
require_once __DIR__ . '/mini_agent.php';

$question = $argv[1] ?? "What's the status of order #1042?";

echo runMiniAgent($question), "\n";

Prompt spotlight: why the decision prompt is written this way

Each line of DECIDE_PROMPT has a job:

• "You can perform exactly one action": a model that knows its limits is less likely to promise things. Listing the allowed actions is the start of every agent prompt.
• "Reply with JSON only, no other text": PHP needs something it can parse. Even so, models sometimes add ```json fences or a friendly sentence, which is why extractJson() searches for the {...} block instead of trusting the whole reply.
• The two example shapes: showing the exact JSON is more reliable than describing it.
• "Never guess or invent an order number": without this, a vague message like "where’s my order?" can produce a made-up ID.
• "Explain what you can and cannot do": this is what makes the refund request end honestly instead of with a fake "done".

The answer prompt has one rule worth copying everywhere: "Never promise an action that you cannot see in the data."

Try it

php ask-agent.php "What's the status of order #1042?"

  · Model decided: {"action": "lookup_order", "order_id": 1042}
  · PHP looked up the order: {"id":1042,"plan":"Pro (annual)","amount":"240.00","currency":"USD","status":"paid","purchased_at":"2026-10-17 10:12:44","customer":"Priya Shah"}
Hi Priya! Your order #1042 for the Pro (annual) plan ($240.00) is paid and active.
It was purchased on 17 October 2026.

An order that doesn’t exist:

php ask-agent.php "Where is order #9999?"

  · Model decided: {"action": "lookup_order", "order_id": 9999}
  · PHP looked up the order: {"error":"order 9999 not found"}
I couldn't find an order with number #9999. Could you double-check the number?

And the original refund request:

php ask-agent.php "Please refund order #1042."

  · Model decided: {"action": "reply", "message": "I can look up order #1042 for you, but I'm not able to issue refunds yet. Our support team can process it for you."}
I can look up order #1042 for you, but I'm not able to issue refunds yet. Our support team can process it for you.

That’s progress. Nimbus now reads real data instead of guessing, and it’s honest about what it can’t do. The lines starting with · show each decision and action. Keep them: when an agent misbehaves, this trace is how you find out why.

💡 Tip: On Gemini’s free tier, each question here costs one or two requests. If you get a 429 or "quota exceeded" error, switch GEMINI_CHAT_MODEL in .env to a Flash-Lite model, which has a higher free daily limit.

Why we won’t keep this version

Our mini agent works, but it’s fragile:

• It depends on the model following "JSON only". Models usually do, but not always.
• It can take only one action per question. "Refund my last order" needs at least two: find the order, then refund it.
• Adding a second action means more prompt text and more if branches to maintain.

All major AI providers now offer a built-in feature for exactly this, called tool calling (or function calling). You describe your PHP functions to the model in a structured way, and it returns structured requests to call them. No more hoping for clean JSON.

Recap

• A chatbot talks, a RAG bot talks using your documents, and an agent acts.
• The model never executes anything. It requests actions, and your PHP code decides what runs.
• An agent works in four steps: decide → act → observe → answer. Repeating them is the agent loop.
• If a task always follows the same steps, use plain code, not an agent.

Next, Part 2: Tool Calling in Plain PHP. We replace our hand-made JSON with the providers’ built-in tool calling, and see exactly how Gemini and OpenAI format it differently.

Frequently Asked Questions

Full code for this part: GitHub → Gemini Setup/part-01 · OpenAI Setup/part-01