DEV Community: Khaled Hammrouni

I built a PHP AI agent library with zero dependencies - here's the code

Khaled Hammrouni — Thu, 15 Oct 2026 19:51:59 +0000

If you've tried to add an LLM agent to a PHP application, you've probably hit the same wall: every serious library is Python. So the "obvious" answer is to bolt a Python microservice behind your PHP app a sidecar that speaks to your agent, your agent speaks to your APIs, and now you're maintaining two runtimes, two deployments, and a network hop you didn't ask for.

I got tired of that. So I built NanoAgent: a PHP library that does agents natively. One composer require. Zero runtime dependencies. No Python. No framework. No DSL.

composer require hammrouni/nanoagent

What it does

One config array, any provider. OpenAI, Groq, Anthropic, DeepSeek, OpenRouter or a local model behind any OpenAI-compatible endpoint (Ollama, llama.cpp server). Swap with one line.
Tool-first. You map plain PHP functions as tools. Your agent can query your database, hit your internal APIs, read your device telemetry the code you already wrote.
MCP support. Register any Model Context Protocol server (Streamable HTTP); its tools behave exactly like local ones, with an allowlist so you control what gets registered.
Persistent memory. Conversations survive across requests via pluggable drivers: JSON files, SQLite, MySQL, PostgreSQL or your own.
Minimal footprint. One package, no hidden magic. You can audit the whole thing in an afternoon (it's small on purpose).

The 30-second tour

<?php
use NanoAgent\Agent;

$agent = new Agent(llm: [
    'provider' => 'groq',
    'model'    => 'llama-3.3-70b-versatile',
    'api_key'  => getenv('GROQ_API_KEY'),
    // 'base_url' => 'http://localhost:8080/v1',  // …or a local model server
]);

// Your plain PHP function, now a tool:
$agent->tool('weather', fn (string $city) => "It is 22°C in {$city}.");

echo $agent->chat('How warm is it in Marrakech?');

That's it. The agent decides to call weather, your function runs in-process, the result comes back, and the reply is generated. No sidecar, no queue, no second language.

Why PHP, really?

Because a huge amount of production AI isn't greenfield. It's Laravel services talking to legacy databases, internal HTTP APIs, and ten years of business logic. The agent that's useful there is not a shiny framework it's a boring, local library that lives inside the process you already run. NanoAgent is deliberately boring. Boring is the feature.

What I'm not doing

No auto-generated prompts, no "magic" abstractions, no 14 dependencies. If you want a framework, there are great ones. If you want a library you can read end-to-end, point at a hosted API or a model on your own hardware, and ship in an afternoon that's what this is.

Try it

Repo: https://github.com/hammrouni/nanoagentphp (full docs + runnable examples)
Docs site: https://hammrouni.github.io/nanoagentphp/
Composer: composer require hammrouni/nanoagent

MIT licensed. Issues and PRs welcome.

Full 12-part series on building agents in PHP is linked in my profile this post is the short version.

A local agent loop that graded its own homework

Khaled Hammrouni — Tue, 13 Oct 2026 12:31:00 +0000

The first time my local agent loop "finished" a task, nothing had changed on disk. The drafter reported success, the critic signed off, the task moved to done - and the working directory was exactly as I'd left it. It took me a week of staring at audit logs to understand why, and the answer was one dead branch of code that I had written myself and never exercised.

This is what happens when you build a drafter/critic loop that runs entirely on your own hardware. I'll walk through the loop, the five things that actually broke it, and the one non-obvious lesson that came out of all of it.

The loop, in one paragraph

The pattern is deliberately simple. A drafter model - a CLI coding agent with real file access - is dispatched into a task's working directory and told to produce a change. A separate critic model then judges that attempt against the task's acceptance criteria. If the critic fails it, the drafter retries with the critic's named errors folded back into the prompt. After a configurable number of consecutive failures - the iteration cap, default three - the task escalates to a human as blocked; a comment resets the cap and resumes the loop with your guidance.

Two independent models judging each other, and a hard cap so it can't spin forever. On paper it's a reasonable loop. In practice, on a single 24 GB GPU, it taught me a lot.

War story 1: the critic was never the critic you thought

The design said the critic would be a "direct structured-output call at temperature 0" - a pure judgment, no tools, schema-enforced. That is the whole point of the role: a judge that returns a verdict, not an agent that does things.

The code did not do that. The critic's model tag was read off the critic's agent record, and that record was always populated. So the flag that decides "dispatch as agent" versus "dispatch as a structured call" was always true. The structured-output branch - the one that would have enforced the verdict schema - was dead code. It never ran.

The consequence: the critic ran inside the same CLI harness as the drafter, with tools. And a small model handed a tool harness doesn't behave like a judge. It behaves like an agent. Instead of returning a verdict, it tried to read the prompt file - it emitted a tool call for read, narrated that it "can use the Read tool," and then failed to parse. The loop retried, failed again, and gave up.

The fix was a new setting that makes the structured path reachable again - but the lesson was that a role you describe in a doc is not a role your code enforces. The critic was "conceptually" read-only; nothing in the dispatch made it so.

War story 2: the judge wrote the files it was judging

This is the one I'd tell anyone building an autonomous pipeline. During a run, the working directory suddenly contained a complete Angular project scaffold - 23 files, angular.json, package.json, the whole lot. The task explicitly forbade a framework and a package manager.

It wasn't the drafter. The audit log's action diffs - computed from real before/after directory snapshots, so a model can't fake them - attributed those 23 files to the critic model. In the same dispatch, it returned a clean {"verdict":"pass"} and scaffolded an application into the very directory it was supposed to be impartially judging.

Why? Because of war story 1. The critic dispatching through the CLI agent got the exact same invocation as the drafter: a working directory, full write access, and a flag that skips permission prompts. A model that decides to "build the thing to check it" simply does.

The fix that finally made this structurally impossible: route the critic through a text-only judgment call with no subprocess and no working directory - a component with no capability to write anything at all. A read-only judge that can't touch the artifact is not a nicety; it's the difference between a verdict you can trust and a verdict rendered against a directory the judge itself changed.

War story 3: model choice silently decides whether any file gets written

After fixing the runtime, the drafter ran twice, reported success, and wrote nothing. The audit log showed why: one of my "coder" models emits a fabricated <tool> block as plain prose instead of performing a real tool call. The harness sees text, takes zero actions, and nothing touches disk. The model described writing the file; it never did.

I had assigned that model based on its file size and reputation. The audit log already contained the evidence to predict the failure - a count of which models actually produce real file actions through the harness. Two models made hundreds of real actions; two others made zero. I hadn't consulted the log before reassigning.

The systemic gap: the agent dropdown offered a model purely because the local server had it pulled. There was no capability probe for tool use. A drafter on a non-tool-calling model will burn its entire iteration cap producing confident, empty attempts, and report success the whole time.

War story 4: the load tax

A drafter/critic loop alternates roles constantly - drafter, critic, drafter, critic - inside a single run. Each model switch on a local runtime can mean a cold load. In my first run, 81% of the wall-clock time went to model loading, not to actual generation. The runtime was configured to keep only one model resident at a time and pin it forever. The fix was two environment variables; the insight was that the bottleneck was the runtime config, not the models and not the GPU.

What worked (so it's not all war stories)

Mostly, it held. Auto-generated acceptance criteria were genuinely strong - nineteen items, each traceable to the task description, locked with no prompting. The state machine never produced an illegal transition, even through repeated dispatch failures. And the observability is what made all of this debuggable at all: a JSONL audit log of every model call, with durations, token counts, and - crucially - file-action diffs from real directory snapshots. Nearly every number in this post came straight out of that log.

When I did re-run the pipeline after the fixes, it delivered a seven-file site with zero human intervention - and when I checked it outside the system, with a script that never consults the loop, it held on 64 of 66 points.

The non-obvious lesson

A claim is not a verification. The drafter claimed it wrote the file. The critic claimed it judged it. The task claimed it was done. None of those claims were backed by what actually happened on disk - until I reconstructed the run from the recorded state, directory snapshots and all. The single strongest signal in the whole system, status: done, turned out to be a copy of one step's verdict, not a whole-task check.

If you're building a local agentic loop, three things I'd do before trusting it:

Enforce the judge's role in the dispatch, not just in the doc. A read-only critic that cannot write is the difference between a trustworthy verdict and a self-contradiction.
Probe models for the capability you're actually using. Tool-calling and structured output are different capabilities. "It's a coding model" is not evidence it can drive your harness.
Make the runtime config a first-class suspect. When 80% of your time is loading, the problem is almost never the model.

How I Built an Open-Source LLM Key-Pool Gateway (and Why You Might Want One)

Khaled Hammrouni — Sun, 11 Oct 2026 12:19:53 +0000

I hit a wall that felt familiar to anyone building with LLMs.

The problem: I had three OpenAI keys (two free-tier, one paid), an Anthropic key, and a Gemini key. Every app I built needed its own logic to handle rate limits, and quota exhaustion. When one key hit its limit, the app died - unless I wrote custom failover logic in every single app. Provider keys were scattered across .env files, shared insecurely, and impossible to rotate without breaking something.

The realization: This isn't an app problem. It's an infrastructure problem. Every team building with LLMs solves the same three things badly:

Key pooling - spreading load across multiple keys
Failover - automatically switching when a key fails
Session continuity - keeping the conversation alive across the switch

So I built the thing I wanted to exist: Palimpsest Gateway a self-hosted, OpenAI-compatible gateway that sits in front of all your LLM keys, pools them, fails over automatically, and keeps every conversation going across the switch.

It's open source (MIT), written in Python/FastAPI, and runs with a single docker compose up. This is the story of why I built it, how it works, and the hard parts I didn't expect.

The Problem: Keys Run Out, Apps Break

If you've built anything with LLMs at scale, you know the pain points:

Pain Point	What Actually Happens
Rate limits	Your free-tier key hits 429. App crashes. You catch it, sleep, retry... but the user already left.
Quota exhaustion	Monthly spend cap hit. Or daily free-tier allowance gone. No warning, just 402/429.
Key sprawl	5 apps × 3 providers = 15 keys in 15 `.env` files. Rotating one is a deployment.
No visibility	You don't know which key served which request, how much you spent, or why a request failed.

I wanted one endpoint that:

Accepts standard OpenAI client calls (zero code change)
Pools all my provider keys behind it
Fails over transparently when a key hits a limit or errors
Keeps conversation context so the user doesn't notice the switch
Runs on my hardware, with my keys encrypted at rest
Gives me a dashboard to see everything

Architecture: What Actually Runs

┌─────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│  Your App   │────▶│  Palimpsest Gateway  │────▶│  LLM Providers  │
│ (OpenAI     │     │  • Auth & Admission  │     │  OpenAI         │
│  client)    │     │  • Key Selection     │     │  Anthropic      │
└─────────────┘     │  • Failover Loop     │     │  Google Gemini  │
                    │  • Session Memory    │     │  OpenRouter     │
                    │  • Usage Metering    │     └─────────────────┘
                    │  • Encrypted Storage │
                    └──────────┬───────────┘
                               │
                    ┌──────────▼───────────┐
                    │       Redis          │
                    │  • Key registry      │
                    │  • Session history   │
                    │  • Usage counters    │
                    │  • Audit log         │
                    └──────────────────────┘

The Request Flow

Authenticate - App sends its gateway key (pgw_live_...), never a provider key
Admit - Check user's daily cap + pool capacity
Load context - With X-Session-ID, pull stored history so the app only sends the new message
Choose a key - Pick from active keys serving the requested model, preferring capped keys with room left
Call provider - Forward in provider-native format (OpenAI, Anthropic, Google, OpenRouter)
Fail over if needed - Rate limit, outage, bad key → rest/exhaust/suspend that key, retry on next (same call, context carried)
Answer & record - Return OpenAI-format response, save turn, count usage once

The Hard Parts (And How I Solved Them)

1. Streaming Failover Without Breaking the Client

This was the hardest part. When a provider returns a streamed response, you can't just "retry on another key" - the client is already receiving tokens.

Solution: The gateway buffers the entire provider stream in memory before sending anything to the client. If the provider fails mid-stream, the gateway retries on the next key with full context (system prompt + last N turns + current message). The client only ever sees a complete, valid OpenAI stream.

# Simplified: the failover loop in app/router/exhaustion.py
async def _call_with_failover(chain: list[KeyRecord], payload: dict) -> Response:
    for attempt, key in enumerate(chain):
        try:
            return await provider.call(key, payload)  # buffers full stream
        except ProviderError as e:
            classification = classify(e)
            if classification.state == "transient":
                await registry.mark_cooldown(key.id, model, settings.cooldown_seconds)
                continue  # try next key
            elif classification.state == "exhausted":
                await registry.mark_exhausted(key.id)
                continue
            elif classification.state == "rejected":
                await registry.suspend(key.id)
                continue
            else:  # fatal
                raise
    raise PoolExhaustedError(...)

The key insight: buffer the stream, failover before any bytes leave the gateway. The client never sees a partial response.

2. Context Carry-Over Across Providers

When failover happens, the replacement provider needs the conversation history. But each provider has different context window sizes and message formats.

Solution: The gateway stores every turn in Redis per session. On failover, it reconstructs a "verbatim window" - the last N turns (default 4) sent exactly as they were, plus the system prompt and current message. This fits in any reasonable context window and preserves the conversation thread.

# app/context/rebuild.py - simplified
def build_failover_context(session_history: list[Turn], current_message: Message) -> list[Message]:
    verbatim = session_history[-settings.verbatim_turns_n:]  # last 4 turns
    return [
        {"role": "system", "content": system_prompt},
        *verbatim,
        current_message,
    ]

3. Encrypted Key Storage That Survives Restarts

Provider keys are the crown jewels. They must be encrypted at rest, never logged, never returned after creation - but the gateway needs to decrypt them at request time.

Solution: A master key (Fernet) generated on first boot, persisted in a Docker volume. Every provider key is encrypted with it before hitting Redis. The master key never leaves the container. Rotating it is a destructive operation (make rotate-secrets) - by design.

# app/core/crypto.py
class SecretsManager:
    def __init__(self, master_key: bytes):
        self._fernet = Fernet(master_key)

    def encrypt(self, plaintext: str) -> str:
        return self._fernet.encrypt(plaintext.encode()).decode()

    def decrypt(self, ciphertext: str) -> str:
        return self._fernet.decrypt(ciphertext.encode()).decode()

4. Key Selection That Respects Your Intent

You have free keys (daily caps) and paid keys (uncapped). You want free keys used first, paid keys as backstop.

Solution: Selection algorithm orders keys by:

Keys with a request cap + requests remaining → most remaining first
Keys with no cap → last

Within each group, prefer the provider that served the session's previous turns (locality).

# app/pool/registry.py - routable_keys()
def sort_for_selection(keys: list[KeyRecord]) -> list[KeyRecord]:
    capped = [k for k in keys if k.daily_cap is not None]
    uncapped = [k for k in keys if k.daily_cap is None]
    capped.sort(key=lambda k: k.remaining_requests, reverse=True)
    return capped + uncapped

Quick Start: 60 Seconds to Running

git clone https://github.com/hammrouni/palimpsest-gateway.git
cd palimpsest-gateway
docker compose up -d --wait

That's it. On first boot it generates a master key and operator key, persists them in a Docker volume, and starts the API at http://localhost:8000.

# Add a provider key (one-time, or use the dashboard)
echo 'PALIMPSEST_PROVIDER_API_KEY=sk-your-openai-key' >> .env
docker compose up -d

# Create a user in the dashboard (or via API), get a pgw_live_... key
# Then call it from any OpenAI client:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="pgw_live_...")
reply = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)

Send X-Session-ID: my-chat header to keep the conversation going server-side.

What It Looks Like In Practice

The dashboard shows you everything:

Pool Keys - health, usage, caps, reset schedules, cooldown status
Utilization & Failover - which key served what, failover events, retry chains
Users & Sessions - per-account usage, active sessions, cap consumption
Costs - spend by model/user/day against prices you enter (nothing bundled)
Alerts - low capacity, key problems, error rates, webhook support
Audit & Export - every operator action logged, CSV exports for usage/requests/audit

Click to see a sample request log line

{
  "timestamp": "2026-09-04T20:00:00Z",
  "request_id": "req_abc123",
  "account_id": "acc_xyz",
  "session_id": "sess_123",
  "model": "gpt-4o-mini",
  "status_code": 200,
  "latency_ms": 850,
  "outcome": "success",
  "chain": ["key_openai_free_1", "key_openai_paid"],
  "attempts": 2,
  "n": 4
}

First key rate-limited → failover to paid key → context carried → success

Why "Palimpsest"?

A palimpsest is a manuscript page written on, scraped clean, and written on again - the old text still faintly visible underneath. That's what this gateway does: it layers your conversation history across provider switches, so the new provider sees the "old writing" (context) even though the underlying key changed.

What's Next

Multi-gateway clustering - run multiple gateway instances behind a load balancer, shared Redis
Provider quota sync - read actual provider quota (OpenRouter already supported) instead of manual caps
Request transformations - normalize tool calls across providers, inject system prompts
Your PR here - good first issues tagged, CONTRIBUTING.md has the dev loop

Try It, Star It, Break It

Repo: github.com/hammrouni/palimpsest-gateway

Docs: User Guide · Development

License: MIT

Docker: docker pull ghcr.io/hammrouni/palimpsest-gateway:latest

If you run it and hit something weird, open an issue. If you fix it, open a PR. If you hate it, tell me why - I've probably already hit that wall too.

What if your JSON schema was just a tool ?

Khaled Hammrouni — Fri, 09 Oct 2026 12:30:00 +0000

Every integration I've inherited has the same line somewhere in it: "return valid JSON."

Then the parser throws commentary before the object, markdown fences around it, a field dropped because the source text was messy. The schema was never enforced - it was requested, in a language the model has no reason to obey.

There's a trick I keep coming back to stop describing the schema. Make it the tool.

    $extracted = null;

    $saveProfile = new FunctionTool(
        name: 'save_profile',
        description: 'Saves the extracted profile data into the system.',
        parameters: [
            'type' => 'object',
            'properties' => [
                'full_name'        => ['type' => 'string'],
                'skills'           => ['type' => 'array', 'items' => ['type' => 'string']],
                'experience_years' => ['type' => 'integer'],
            ],
            'required' => ['full_name', 'skills'],
        ],
        callable: function (array $args) use (&$extracted) {
            $extracted = $args;
            return "Captured profile for {$args['full_name']}.";
        },
    );

    $agent = new Agent(
        llm: $llmConfig,
        systemPrompt: 'You extract profile details. Your ONLY task is to call save_profile once. Answer only via tool call.',
        tools: [$saveProfile],
    );

    $agent->chat($unstructuredText);
    // $extracted is now a typed array — full_name, skills, experience_years

You don't validate the output afterwards, you don't strip fences, the model has to produce arguments that satisfy your schema, because that is the shape of a tool call - the same mechanism that makes every tool call reliable is what makes your "JSON" reliable.

It works with any provider that does tool calling, hosted or running on the machine next to you, and the validation happens on your side, in your language, where you can react to it.

The full pattern with more examples is article #04 of my PHP-AI series

What's your structured-output approach, schema-as-tool, a provider's native mode, or regex salvage ? Genuinely asking, because I've argued myself out of two of the three.

11 - Multi-Tool Orchestration in PHP - One Agent, Many Tools, One Answer

Khaled Hammrouni — Sun, 27 Sep 2026 20:56:16 +0000

A single tool is easy to reason about. The interesting problem is an agent with several specialized tools that has to figure out which to call, in what order, and how to combine the results into one answer.

This example is a personal concierge with three tools - location, weather, events - and the user's request needs all three chained together: "Check where I am, get the weather there, and see if there are any jazz events tonight."

Three focused tools

The first tool takes no input at all - it just reports where the (simulated) user is:

use NanoAgent\Agent;
use NanoAgent\Tools\FunctionTool;

$locationTool = new FunctionTool(
    name: 'detect_user_location',
    description: 'Determines the user\'s current city and country.',
    parameters: ['type' => 'object', 'properties' => new stdClass()],  // no params
    callable: fn() => ['city' => 'Paris', 'country' => 'France']
);

The second and third tools both take a city - the value the location tool just produced is what will get passed into these two:

$weatherTool = new FunctionTool(
    name: 'get_current_weather',
    description: 'Fetches the live weather forecast for a given city.',
    parameters: [
        'type' => 'object',
        'properties' => ['city' => ['type' => 'string', 'description' => 'The city name']],
        'required' => ['city']
    ],
    callable: function (array $args) {
        $obs = ['Paris' => 'Cloudy, 14°C', 'London' => 'Rainy, 11°C', 'New York' => 'Sunny, 22°C'];
        return $obs[$args['city']] ?? 'Weather data unavailable.';
    }
);

$eventTool = new FunctionTool(
    name: 'search_local_events',
    description: 'Searches for upcoming cultural events or concerts in a specific city.',
    parameters: [
        'type' => 'object',
        'properties' => ['city' => ['type' => 'string', 'description' => 'The city name']],
        'required' => ['city']
    ],
    callable: function (array $args) {
        if ($args['city'] === 'Paris') {
            return [
                ['name' => 'Jazz Festival at Le Caveau', 'time' => '20:00'],
                ['name' => 'Monet at Grand Palais', 'time' => '10:00-18:00']
            ];
        }
        return "No specific events found for {$args['city']} today.";
    }
);

The agent decides the order

$agent = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a personal concierge with location, weather, and event tools. "
                . "When answering, first describe the location and weather, then list any "
                . "relevant events.",
    tools: [$locationTool, $weatherTool, $eventTool]
);
$agent->enableActivityLogging();

$response = $agent->chat(
    "Check where I am, get the weather there, and see if there are any jazz events tonight."
);
echo $response;

You did not script the sequence. The model:

Calls detect_user_location (no args) → Paris.
Calls get_current_weather with city: "Paris" → Cloudy, 14°C.
Calls search_local_events with city: "Paris" → the jazz festival.
Composes the final answer in the order the prompt asked for.

The dependency is implicit. The model reads the location result, then passes that city into the next two tools. You gave it the pieces and the goal; it built the pipeline.

The two things that make this work

Each tool is narrow and well-described. description is what the model reads to choose a tool. "Determines the user's current city and country" tells it this is the first step. Vague descriptions = wrong tool picks.
The prompt sets the shape of the answer, not the tool calls. "First describe location and weather, then list events" steers the composition while leaving the orchestration to the model.

Tool with no parameters - the `stdClass()` trick

detect_user_location takes no input. In JSON Schema an object with no properties is {'type':'object','properties':{}} - in PHP you write new stdClass() for that empty object. Small gotcha, easy to miss: a [] (empty array) encodes as a JSON array, not an object.

When to use this vs. an agent chain

Multi-tool, one agent (this): the steps are interdependent and the model should choose the path. Good for concierges, assistants, anything open-ended.
Agent chain (this article): the stages are fixed and you want different models/prompts per stage. Good for deterministic pipelines.

Rule of thumb: if the path is fixed, use a chain; if the path depends on the input, give one agent many tools and let it decide.

Part of the NanoAgent examples series. Landing + demos.

10 - Stateful Tools in PHP - An Agent That Reads and Mutates Inventory

Khaled Hammrouni — Sun, 27 Sep 2026 20:51:39 +0000

So far the tools have been read-only (weather, search). The more interesting case is a tool that changes state - placing an order, updating a record, firing an action. The agent has to query state, decide, then mutate it, all in one turn.

This example is an inventory agent: the user asks to buy something, the agent checks stock, then places the order.

Simulated state, real mutation

A plain PHP class stands in for a real database - an in-memory array of products, with methods to read and write it. This keeps the example runnable with no setup, while behaving exactly like a DB-backed store would.

class ProductDatabase {
    private array $products = [
        'p1' => ['name' => 'Quantum Laptop', 'price' => 1500, 'stock' => 5],
        'p2' => ['name' => 'Nano Phone',     'price' => 800,  'stock' => 0],
        'p3' => ['name' => 'AI Headset',     'price' => 300,  'stock' => 12],
    ];

    public function search(string $query): array {
        $out = [];
        foreach ($this->products as $id => $p) {
            if (stripos($p['name'], $query) !== false) $out[$id] = $p;
        }
        return $out;
    }

order() is the mutating half: it validates the product exists and has enough stock before touching anything, then decrements the count and returns a human-readable result.

    public function order(string $id, int $qty): string {
        if (!isset($this->products[$id])) return "Error: Product not found.";
        if ($this->products[$id]['stock'] < $qty) return "Error: Insufficient stock.";
        $this->products[$id]['stock'] -= $qty;   // <-- the mutation
        return "Success: Ordered $qty of {$this->products[$id]['name']}. "
             . "New stock: {$this->products[$id]['stock']}";
    }

    public function getInventory(): array { return $this->products; }
}

$db = new ProductDatabase();

Two tools: one reads, one writes

The read tool is a thin wrapper around $db->search() - no logic of its own, just a schema the model can call:

use NanoAgent\Agent;
use NanoAgent\Tools\FunctionTool;

$searchTool = new FunctionTool(
    name: 'search_products',
    description: 'Search for products by name in the store inventory.',
    parameters: [
        'type' => 'object',
        'properties' => ['query' => ['type' => 'string', 'description' => 'Product name or keyword']],
        'required' => ['query'],
        'additionalProperties' => false
    ],
    callable: fn(array $args) => $db->search($args['query'])
);

The write tool is the same shape, just pointed at $db->order() instead - the mutation itself lives entirely in the ProductDatabase class, not in the tool:

$orderTool = new FunctionTool(
    name: 'place_order',
    description: 'Place an order for a specific product by its ID.',
    parameters: [
        'type' => 'object',
        'properties' => [
            'product_id' => ['type' => 'string',  'description' => 'The unique product ID'],
            'quantity'   => ['type' => 'integer', 'description' => 'Units to purchase']
        ],
        'required' => ['product_id', 'quantity'],
        'additionalProperties' => false
    ],
    callable: fn(array $args) => $db->order($args['product_id'], $args['quantity'])
);

The agent that runs both

$agent = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a retail sales assistant. You have tools 'search_products' and "
                . "'place_order'. You MUST use these tools to check availability and place "
                . "orders. Do not guess stock levels.",
    tools: [$searchTool, $orderTool]
);
$agent->enableActivityLogging();

$response = $agent->chat("I want to buy 2 Quantum Laptops. Check stock and order.");
echo $response;

Check the database afterward and the stock is genuinely lower - this wasn't just a chat reply, the agent actually called place_order and it actually ran:

var_dump($db->getInventory()['p1']['stock']);  // 5 -> 3

The "do not guess stock levels" line in the prompt is load-bearing. Without it, a model might answer "yes, we have some" from memory. With it, the agent must call search_products to read the real number, then place_order to act on it.

The patterns that make stateful tools safe

Read before write. The agent checks stock, then orders. The mutation is grounded in a fresh read, not an assumption.
Return human-readable results, not raw arrays. "Success: Ordered 2... New stock: 3" lets the model reason about the outcome and report it. A bare array gives it less to work with.
Fail as a result, not an exception. "Error: Insufficient stock." is returned to the model, which can then tell the user "only 0 in stock" instead of your app 500ing.
additionalProperties => false tightens the schema so the model can't pass junk fields.
enableActivityLogging() so you can audit exactly which tools fired in what order - non-negotiable once tools can write.

Scaling this up

Swap ProductDatabase for real persistence and you've got an agent that can read your DB, make a decision, and write back to your DB - the core of most "agentic" business automation (orders, tickets, inventory, bookings). The agent is the decision layer; your PHP functions are the hands.

Part of the NanoAgent examples series. Landing + demos.

09 - RAG in PHP - Answer From Your Own Docs, Not the Model's Memory

Khaled Hammrouni — Sun, 27 Sep 2026 20:47:33 +0000

The failure mode you hit the moment you point an LLM at internal questions: it hallucinates policy that sounds right but was never written. "Can I work from Hawaii for two months?" is exactly the kind of question where a confident wrong answer costs you real money.

Retrieval-Augmented Generation (RAG) fixes it: retrieve the relevant doc first, then answer from that - and say so when there's no answer. In NanoAgent, RAG is just a search tool. No vector database required to start.

The knowledge base (a plain array here)

$knowledgeBase = [
    'policy_wfh' => [
        'title' => 'Remote Work Policy 2024',
        'content' => 'Employees may work remotely up to 3 days a week. Full remote work '
                    . 'requires Director approval. Working from international locations is '
                    . 'limited to 30 days per year due to tax implications.'
    ],
    'policy_holiday' => [
        'title' => 'Holiday Schedule 2024',
        'content' => 'Closed on New Year\'s Day, Memorial Day, Independence Day, Labor Day, '
                    . 'Thanksgiving, and Christmas Day.'
    ],
    'it_support' => [
        'title' => 'IT Support Contacts',
        'content' => 'Urgent: ext 5555. Non-urgent: support@company.com. Password resets via portal.'
    ]
];

The search tool

The tool takes one argument - free-text keywords - and describes itself as a policy search, so the model knows to reach for it on anything HR-shaped.

use NanoAgent\Agent;
use NanoAgent\Tools\FunctionTool;

$searchTool = new FunctionTool(
    name: 'search_knowledge_base',
    description: 'Searches the internal knowledge base for policy documents. Input keywords.',
    parameters: [
        'type' => 'object',
        'properties' => [
            'query' => ['type' => 'string', 'description' => 'Keywords to search for']
        ],
        'required' => ['query']
    ],

The callable does a plain case-insensitive substring match against title and content, and returns either the matching documents or an explicit "nothing found" - never a guess.

    callable: function (array $args) use ($knowledgeBase) {
        $q = strtolower($args['query']);
        $hits = [];
        foreach ($knowledgeBase as $doc) {
            if (str_contains(strtolower($doc['title']), $q)
                || str_contains(strtolower($doc['content']), $q)) {
                $hits[] = "Title: {$doc['title']}\nContent: {$doc['content']}";
            }
        }
        return $hits
             ? implode("\n\n---\n\n", $hits)
             : "No relevant documents found.";
    }
);

The agent - and the prompt that makes RAG safe

$agent = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a professional HR assistant. You must ONLY answer based on the "
                . "search results. If the information is not present, politely say so. "
                . "Always cite the document title.",
    tools: [$searchTool]
);

$response = $agent->chat("Can I work from Hawaii for two months?");
echo $response;

That last prompt line is the whole safety model. Three rules do the heavy lifting:

"ONLY answer based on the search results" - no training-data memory allowed.
"If not present, say so" - the model is permitted to decline, which is what stops the confident hallucination.
"Cite the document title" - every claim is traceable to a source.

For the Hawaii question, the tool retrieves Remote Work Policy 2024 (it contains "international locations"), and the agent answers: limited to 30 days/year, so two months isn't allowed - per Remote Work Policy 2024. Grounded, cited, correct.

From array to real RAG - the same seam

The only thing that changes as you scale is what the callable does:

Stage	The `search_knowledge_base` callable does
Demo	keyword scan of a PHP array
Real (small)	query your SQL/Postgres docs table
Real (large)	embed the query + docs, hit a vector store (Qdrant, pgvector)

The agent code never changes. You keep the same tool name and the same prompt; you just make retrieval smarter inside the function. Start with the dumb keyword search - it's enough to prove the pattern and to handle small corpora - and upgrade the retrieval when you need to.

Why tools (not pre-prompting) for RAG

You could stuff the whole doc into the prompt. That blows the context window and wastes tokens on irrelevant content. A tool lets the model decide what to retrieve and when, pulling only what's relevant. As your corpus grows, that's the difference between "works" and "doesn't fit."

Part of the NanoAgent examples series. Landing + demos.

08 - Multi-Agent Workflow in PHP - Chain a Researcher into a Writer

Khaled Hammrouni — Sun, 27 Sep 2026 20:40:22 +0000

A single agent can do a lot, but some jobs are cleaner as a pipeline: one agent gathers, another refines. The pattern is "agent chain" - the output of agent A becomes the input of agent B. Each agent has a narrow role and a focused system prompt, which is more reliable than one overloaded prompt trying to do both.

This example: a Researcher pulls facts, a Writer turns them into a polished post.

Two agents, one data flow

A mock research tool stands in for a real data source - a lookup table keyed by topic, so the example runs with zero external dependencies.

use NanoAgent\Agent;
use NanoAgent\Tools\FunctionTool;

$researchTool = new FunctionTool(
    name: 'fetch_topic_facts',
    description: 'Retrieves interesting facts about a given topic.',
    parameters: [
        'type' => 'object',
        'properties' => [
            'topic' => ['type' => 'string', 'description' => 'The subject to research']
        ],
        'required' => ['topic']
    ],
    callable: function (array $args) {
        $knowledge = [
            'php' => ['Created by Rasmus Lerdorf in 1994.',
                      'Powers over 75% of websites with a known server-side language.',
                      'The latest version is 8.4.'],
            'ai'  => ['The term AI was coined in 1956.',
                      'Transformer architecture (2017) revolutionized NLP.']
        ];
        return $knowledge[strtolower($args['topic'])]
             ?? ["No specific facts found for '{$args['topic']}'."];
    }
);

1. The Researcher - its only job is to gather

Its system prompt is narrow on purpose: fetch facts with the tool, return them as a list, nothing more.

$researcher = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a research specialist. Use the 'fetch_topic_facts' tool to "
                . "gather raw data. Return only the collected facts in a list.",
    tools: [$researchTool]
);

2. The Writer - its only job is to polish, and NOT invent

The Writer gets no tools at all - it only ever sees text the Researcher already gathered, and its prompt explicitly forbids adding facts of its own.

$writer = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a creative content writer. Transform raw research facts into an "
                . "engaging social media post with hashtags. Do not invent facts that were "
                . "not provided."
);

Run the chain

$topic = 'PHP';

$research = $researcher->chat("Research the topic: $topic");
// e.g. "1. Created by Rasmus Lerdorf in 1994. 2. Powers over 75% of websites..."

$post = $writer->chat("Write a post based on these facts:\n\n" . $research);
echo $post;

The seam is trivial: $writer->chat(... $research ...) - the Researcher's string is just the Writer's prompt. There's no framework, no message bus, no orchestration library. A chain is literally one chat() result fed into the next chat().

Why split it instead of one big agent?

Focus beats scope. A prompt that says "research AND write well AND don't hallucinate" does all three poorly. Two prompts do each one well.
Different models per stage. The Researcher can be cheap and fast; the Writer can be your best model. You choose per agent because each is its own new Agent(llm: ...).
Isolated failure. If research returns junk, you see it before it pollutes the final output. You can validate between stages.
Composability. Add a third stage (a Critique agent, a translator) by appending one chat() call.

Where this goes next

Researcher → Writer → Critic - a third agent scores the post and the loop retries if it's weak.
Fan-out - several Researcher agents on sub-topics, then one Writer merges.
Each stage can carry its own tools - the Researcher with a search tool, the Writer with a brand-voice tool.

The mental model: an agent is a function; a workflow is a composition of functions. PHP makes that composition boring in the best way - just call them in order.

Part of the NanoAgent examples series. Landing + demos.

07 - MCP in PHP - Connect an Agent to a Remote Tool Server in 4 Lines

Khaled Hammrouni — Sun, 27 Sep 2026 20:35:28 +0000

If you build AI tools in more than one language, you know the tax: every integration you write for Python, you re-write for PHP. MCP (Model Context Protocol) kills that tax. It's a standard protocol for exposing tools, so your PHP agent talks to the same tool servers a Python, Node, or Go agent would. You don't re-implement integrations per language - you point at a server and let the agent discover the tools.

This is the shortest path to a genuinely capable agent in PHP.

The four lines

1. Connect to the MCP server

McpClient just points at a URL - no handshake code, no auth setup for a public server like this one.

use NanoAgent\Agent;
use NanoAgent\Mcp\McpClient;

$mcpClient = new McpClient('https://mcp.deepwiki.com/mcp');

2. Build the agent as usual

Nothing MCP-specific here yet - it's a normal Agent with a system prompt describing what it's for.

$agent = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a research assistant with access to MCP tools for "
                . "exploring GitHub repositories. The user will name a repository "
                . "as 'owner/repo'. Use the available tools to answer their question."
);

3. Register the server, then chat

registerMcpServer() asks the remote server what tools it offers and wires them into the agent - that's the "discovery" step. From here, calling chat() works exactly like it would with local tools.

$discovered = $agent->registerMcpServer($mcpClient);
$agent->enableActivityLogging();

$answer = $agent->chat("Repository: facebook/react\nQuestion: What does this repo do?");

Connect → register → chat. The agent discovers the server's tools at runtime (that's what registerMcpServer() returns) and calls them exactly like local FunctionTools. No tool schema by hand, no new DSL, no sidecar process.

What the agent is talking to here

The example uses DeepWiki's public MCP server - free, no auth - which exposes tools for asking questions about the source and docs of any public GitHub repository. So the agent above can genuinely read and summarize an unfamiliar codebase. Point the same four lines at any other MCP server (search, databases, file systems, your own services) and the agent picks up that server's tools instead.

Local tool vs. MCP tool - the comparison

	`FunctionTool` (local)	MCP tool (remote)
Where it runs	in your PHP process	on a remote server
Who defines it	you, in PHP	the MCP server
Reuse across languages	no	yes - one server, any client
Auth / infra	none	server handles it
Discovery	you list them	automatic via `registerMcpServer()`

You use local tools for logic that lives in your app (your DB, your business rules). You use MCP for capabilities that should be shared, versioned, or maintained by someone else.

Why this matters for PHP specifically

PHP shops don't leave PHP to add an AI feature. MCP means they don't have to build the feature either - point at a server that already has the tool. The agent is a thin PHP layer over a standard protocol, which is exactly the shape you want for a language that has no AI framework ecosystem.

Getting started

Find or run an MCP server (DeepWiki is a zero-config one).
new McpClient($url).
$agent->registerMcpServer($client).
Ask it something the server can answer.

That's the whole integration.

Part of the NanoAgent examples series. Landing + demos.

06 - Calling Real APIs from a PHP Agent - Live Weather in Four Functions

Khaled Hammrouni — Sun, 27 Sep 2026 20:31:01 +0000

An agent that only talks is a toy. The moment you give it a tool that hits a real external API, it becomes useful - it can answer with current, real data instead of whatever it memorized in training.

This example gives the agent a FunctionTool that calls wttr.in (a free, no-key weather API) and returns live conditions.

The tool is just a PHP function that does HTTP

Start with the tool's shape: a name, a description the model reads to decide when to use it, and a single required city argument.

use NanoAgent\Agent;
use NanoAgent\Tools\FunctionTool;

$weatherTool = new FunctionTool(
    name: 'fetch_live_weather',
    description: 'Retrieves current weather for any city using a real weather API.',
    parameters: [
        'type' => 'object',
        'properties' => [
            'city' => ['type' => 'string', 'description' => 'The city name']
        ],
        'required' => ['city']
    ],

The callable is where the real HTTP call happens - a plain cURL request to wttr.in's JSON endpoint, with a timeout and a user agent so the request doesn't hang or get rejected outright.

    callable: function (array $args) {
        $url = "https://wttr.in/" . urlencode($args['city']) . "?format=j1";

        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL            => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 10,
            CURLOPT_USERAGENT      => 'NanoAgent/1.0',
        ]);
        $response = curl_exec($ch);

        if (curl_errno($ch)) {
            $err = curl_error($ch);
            curl_close($ch);
            return "Network error while reaching weather API: $err";
        }
        curl_close($ch);

Then decode the response and hand back a plain sentence - not raw JSON - so the model has something natural to fold into its answer.

        $data = json_decode($response, true);
        $current = $data['current_condition'][0] ?? null;
        if (!$current) return "Could not find weather data for '{$args['city']}'.";

        return "Current weather in {$args['city']}: "
             . $current['weatherDesc'][0]['value']
             . ", {$current['temp_C']}°C.";
    }
);

The agent decides when to call it

$city = $_GET['city'] ?? 'London';

$agent = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a meteorological assistant. You can retrieve real-time "
                . "weather information for any city.",
    tools: [$weatherTool]
);

$response = $agent->chat("What is the real-time weather in $city right now?");
echo $response;

The user never mentions fetch_live_weather. The model reads the tool's description, decides it's the right tool, fills in city, and the agent runs the function and folds the result into the answer. You wrote the HTTP; the model wrote the decision to use it.

Make the tool robust - the details that matter

A real-world tool lives or dies on error handling. Notice the patterns above:

Timeout (CURLOPT_TIMEOUT) so a slow API can't hang your request.
User-Agent - some APIs reject the default cURL UA.
Graceful failure string, not an exception. Return a human-readable error as the tool result. The model can then say "I couldn't reach the weather service" instead of your app crashing.
Validate the JSON before you trust $data['current_condition'][0].

Generalize it

Swap wttr.in for anything that speaks HTTP:

a payments API,
your own REST backend,
a search engine,
a CRM.

Rule of thumb: the tool's description is what the model reads, so write it like you're telling a smart intern what the tool does and when to use it. The parameters schema is the contract; the callable is your normal PHP (cURL, PDO, anything).

Part of the NanoAgent examples series. Landing + demos.

05 - Multi-Provider LLM in PHP - Switch Between Groq, OpenAI, and Mock

Khaled Hammrouni — Sun, 27 Sep 2026 18:26:47 +0000

Hard-coding one LLM provider is a trap. You want to test locally with a mock, run cheap on Groq, and fall back to OpenAI in production - without rewriting the agent. The whole provider choice is one config array.

This example loops over three providers with the identical agent code and shows the switch is genuinely that small.

The providers are just config

Read the default provider/model/key from config once, then lay out three provider configs as a plain array - a free offline mock, your configured default (Groq), and OpenAI as a paid fallback.

use NanoAgent\Agent;

$configFile = __DIR__ . '/../NanoAgent/config.php';
$default = file_exists($configFile) ? require $configFile : [];

$apiKey   = $default['api_key']  ?? '';
$provider = $default['provider'] ?? 'groq';
$model    = $default['model']    ?? 'llama-3.3-70b-versatile';

$configs = [
    'Mock'   => [
        'llm' => ['provider' => 'mock', 'model' => 'test-model', 'api_key' => 'mock-key'],
        'description' => 'Offline mock for local development.'
    ],
    'Groq'   => [
        'llm' => ['provider' => $provider, 'model' => $model, 'api_key' => $apiKey],
        'description' => 'High-performance inference.'
    ],
    'OpenAI' => [
        'llm' => ['provider' => 'openai', 'model' => 'gpt-4o', 'api_key' => getenv('OPENAI_API_KEY')],
        'description' => 'Commercial provider.'
    ]
];

The loop - same agent, different brain

Skip any provider you have no key for, then create an Agent per config and send it the same test message. Notice the Agent constructor call is identical every time except for the llm array.

foreach ($configs as $name => $cfg) {
    if ($name !== 'Mock' && empty($cfg['llm']['api_key'])) {
        echo "$name: skipped (no key)\n";
        continue;
    }

    $agent = new Agent(
        llm: $cfg['llm'],                       // <-- the ONLY thing that changes
        systemPrompt: "You are testing the $name provider. Reply briefly identifying yourself."
    );

Wrap the call in try/catch so one provider's outage or bad key doesn't stop you from testing the others.

    try {
        $response = $agent->chat("Verify connection.");
        echo "$name: OK -> $response\n";
    } catch (Throwable $e) {
        echo "$name: ERROR -> {$e->getMessage()}\n";
    }
}

The new Agent(llm: ...) line is the seam. Everything downstream - tools, history, streaming, structured output - is provider-agnostic. You never touch the rest of your code to change the model.

What this buys you

Offline development. Point at the mock provider and develop/test the whole agent flow with zero API spend and zero network. No .env required.
Cost control. Route high-volume, low-stakes calls to a cheap/fast model; reserve the expensive one for the hard paths.
Resilience. Wrap in a fallback: try the primary, catch Throwable, retry on a secondary provider. Same agent object shape.
A/B and evals. Run the same task against several providers and compare outputs programmatically - this loop is an eval harness.

The fallback pattern

$providers = ['groq', 'openai'];
foreach ($providers as $p) {
    try {
        return (new Agent(llm: ['provider' => $p, 'model' => $model, 'api_key' => $key]))
               ->chat($message);
    } catch (Throwable $e) {
        // log and try the next provider
    }
}

Bottom line: keep the provider in config, keep the agent code generic, and "switching models" stops being a refactor and becomes a one-line change.

Part of the NanoAgent examples series. Landing + demos.

04 - Structured Output in PHP - Extract JSON from Unstructured Text

Khaled Hammrouni — Sun, 27 Sep 2026 18:24:31 +0000

The most useful "AI feature" in a real app is rarely a chatbot. It's turning a blob of unstructured text into clean, typed data - a profile, an order, a support ticket, a CV. The trick to doing this reliably is to not ask the model to "return JSON." Instead, you define a tool with a JSON Schema and instruct the model to call that tool with the data. The schema becomes the contract.

This is the "tool-as-schema" pattern, and it's the most reliable structured-output approach in practice.

Define the schema as a tool

First, the shape of the data you want. Each field gets a type and a description - this is a plain JSON Schema object, no different from any other tool's parameters.

use NanoAgent\Agent;
use NanoAgent\Tools\FunctionTool;

$extractedData = null;

$extractionTool = new FunctionTool(
    name: 'save_profile',
    description: 'Saves the extracted user profile data into the system.',
    parameters: [
        'type' => 'object',
        'properties' => [
            'full_name'         => ['type' => 'string',  'description' => "The person's full name"],
            'job_title'         => ['type' => 'string',  'description' => 'Current job title'],
            'skills'            => ['type' => 'array',   'items' => ['type' => 'string'],
                                    'description' => 'Technical skills mentioned'],
            'experience_years'  => ['type' => 'integer', 'description' => 'Years of experience'],
            'is_open_to_work'   => ['type' => 'boolean', 'description' => 'Looking for opportunities']
        ],
        'required' => ['full_name', 'skills']
    ],

The callable here doesn't do real work - it just grabs whatever arguments the model filled in and stashes them in $extractedData by reference, so you can use them after the chat finishes.

    callable: function (array $args) use (&$extractedData) {
        $extractedData = $args;
        return "Internal: Profile for {$args['full_name']} captured.";
    }
);

Force the model to use only the tool

Give the agent an unstructured blob of text - a bio, in this case - and a system prompt that leaves it no other option than to call save_profile.

$inputText = "Hi, I'm Sarah Jenkins. I've been a Senior PHP Developer for about 8 years. "
           . "I love Laravel, Symfony, and Docker. I'm leading a team of 4. "
           . "Not actively looking, but open to interesting offers.";

$agent = new Agent(
    llm: $llmConfig,
    systemPrompt: "You are a precise data extraction specialist. Your ONLY task is to identify "
                . "profile details and call the `save_profile` tool once. Answer only via tool call.",
    tools: [$extractionTool]
);

$agent->chat($inputText);

After chat() returns, $extractedData holds a real, typed PHP array - no parsing, no regex, no hoping the model's JSON is valid:

// ['full_name' => 'Sarah Jenkins', 'job_title' => 'Senior PHP Developer',
//  'skills' => ['Laravel','Symfony','Docker'], 'experience_years' => 8, ...]

Why this beats "just return JSON"

The schema is enforced by the tool-calling layer, not by the model's good intentions. The model fills a defined shape; you get a guaranteed structure.
required fields mean the model knows what it must produce.
Your callable is where validation happens. $extractedData is a real PHP array - cast, validate, persist, however you like. The model never touches your storage.
additionalProperties / types keep it tight. No stray keys, no "kind of a number."

Where this shines

Form automation - parse a free-text email into a structured ticket.
ETL - clean messy upstream text into your database schema.
Classification - define a tool with category: enum[...] and you have a classifier.
CV parsing - the exact example above, at scale.

The pattern generalizes: whatever shape you need out, declare it as a tool, and make "call the tool" the model's only job.

Part of the NanoAgent examples series. Landing + demos.

DEV Community: Khaled Hammrouni

I built a PHP AI agent library with zero dependencies - here's the code

What it does

The 30-second tour

Why PHP, really?

What I'm not doing

Try it

A local agent loop that graded its own homework

The loop, in one paragraph

War story 1: the critic was never the critic you thought

War story 2: the judge wrote the files it was judging

War story 3: model choice silently decides whether any file gets written

War story 4: the load tax

What worked (so it's not all war stories)

The non-obvious lesson

How I Built an Open-Source LLM Key-Pool Gateway (and Why You Might Want One)

The Problem: Keys Run Out, Apps Break

Architecture: What Actually Runs

The Request Flow

The Hard Parts (And How I Solved Them)

1. Streaming Failover Without Breaking the Client

2. Context Carry-Over Across Providers

3. Encrypted Key Storage That Survives Restarts

4. Key Selection That Respects Your Intent

Quick Start: 60 Seconds to Running

What It Looks Like In Practice

Why "Palimpsest"?

What's Next

Try It, Star It, Break It

What if your JSON schema was just a tool ?

11 - Multi-Tool Orchestration in PHP - One Agent, Many Tools, One Answer

Three focused tools

The agent decides the order

The two things that make this work

Tool with no parameters - the stdClass() trick

When to use this vs. an agent chain

10 - Stateful Tools in PHP - An Agent That Reads and Mutates Inventory

Simulated state, real mutation

Two tools: one reads, one writes

The agent that runs both

The patterns that make stateful tools safe

Scaling this up

09 - RAG in PHP - Answer From Your Own Docs, Not the Model's Memory

The knowledge base (a plain array here)

The search tool

The agent - and the prompt that makes RAG safe

From array to real RAG - the same seam

Why tools (not pre-prompting) for RAG

08 - Multi-Agent Workflow in PHP - Chain a Researcher into a Writer

Two agents, one data flow

1. The Researcher - its only job is to gather

2. The Writer - its only job is to polish, and NOT invent

Run the chain

Why split it instead of one big agent?

Where this goes next

07 - MCP in PHP - Connect an Agent to a Remote Tool Server in 4 Lines

The four lines

1. Connect to the MCP server

2. Build the agent as usual

3. Register the server, then chat

What the agent is talking to here

Local tool vs. MCP tool - the comparison

Why this matters for PHP specifically

Getting started

06 - Calling Real APIs from a PHP Agent - Live Weather in Four Functions

The tool is just a PHP function that does HTTP

The agent decides when to call it

Make the tool robust - the details that matter

Generalize it

05 - Multi-Provider LLM in PHP - Switch Between Groq, OpenAI, and Mock

The providers are just config

The loop - same agent, different brain

What this buys you

The fallback pattern

04 - Structured Output in PHP - Extract JSON from Unstructured Text

Define the schema as a tool

Force the model to use only the tool

Why this beats "just return JSON"

Where this shines

Tool with no parameters - the `stdClass()` trick