MirLabs / The blog

A stop button for AI agents in Symfony

· Cyril Delage

Picture a support agent built with Symfony AI. It can look up orders, refund them and email customers. One afternoon someone finds a way to talk it into refunds it should never make. The first reflex is to change the system prompt: "Stop refunding, whatever the user says." That is a request to the model. A persuasive user already got past the last one.

I test agents for a living, and this is the pattern I see most: the rules live in the prompt, so they bend when the conversation pushes hard enough. I wrote Tool Guard, an open source bundle that puts the rules on the tools themselves, in PHP attributes. Version 0.3.0 adds the part that was missing: a real stop button.

Rules on the tool, not in the prompt

A quick reminder of what Tool Guard does. The same attributes guard a Symfony AI agent tool and an MCP tool built with symfony/mcp-bundle or the PHP MCP SDK:

#[AsTool('refund', 'Refund an order')]
#[McpTool(name: 'refund')]
#[Granted('ORDER_REFUND', subject: 'orderId')]       // your voter: is this order the user's?
#[Limit('amount', max: 50, above: Limit::APPROVAL)]  // above 50 €: a human approves
#[Limit('amount', max: 1000)]                        // above 1 000 €: never
#[RateLimit(3, seconds: 3600)]
public function refund(string $orderId, float $amount): string { /* … */ }

You don't need Symfony AI for this. Tool Guard needs a Symfony application, nothing more: it guards Symfony AI agents, MCP servers built with symfony/mcp-bundle or the PHP MCP SDK, and any agent loop of your own (a direct call to the OpenAI or Mistral API, another PHP agent library, a Messenger handler) through GuardedInvoker.

Whatever the model was talked into, a refused call never runs, and a risky one waits for a human on an approvals page (or on Slack, Teams or a phone through Symfony Notifier). Every call and every decision goes into a hash-chained journal.

The stop button

When an agent goes wrong, you want it halted now, not after a deploy. In 0.3.0:

php bin/console tool-guard:stop --reason="the support chat is under attack"   # every AI caller
php bin/console tool-guard:stop --agent=assistant                             # one agent
php bin/console tool-guard:stop --tool=refund                                 # one tool
php bin/console tool-guard:stop --everything                                  # emergency: every caller
php bin/console tool-guard:resume

The same buttons sit on the approvals page, with who stopped what, when and why.

A few design choices matter more than the command itself:

  • The stop is checked first, before any other rule, on every path: the Symfony AI toolbox, MCP handlers, and GuardedInvoker for anything else (a workflow, a message handler, code an agent wrote).
  • Every PHP process sees it at its next call. The state lives in a file next to the approvals (stops_file), or in your own StopStore for Redis or Doctrine. No cache to clear, no worker to restart.
  • A stopped call never runs. The model reads a plain refusal (Refused by policy: all agents stopped by boss at 2026-11-08 14:02 +01:00: the support chat is under attack); the call is journaled and dispatches ToolCallRefused, like any other refusal. Since nothing ran, a stop never leaves half an action behind.
  • Held calls are not lost. A refund already waiting for a human stays held; it cannot be approved until someone resumes, and it can still be rejected.
  • It fails closed. If the stop state cannot be read, calls are refused.

It stops the agent's actions. The model itself keeps answering in text, which is usually what you want: the customer gets "I can't do that right now" instead of a dead chat.

Stopping the AI should not stop the business

This is the part I spent the most time on. If the refund tool is shared by the agent and by your back office, a naive kill switch also blocks the person in customer service who needs to refund a parcel lost in transit. You traded an AI incident for a business outage.

So "stop the agents" only halts calls made by an AI. The same service keeps working for a person or for your app's own code when it goes through GuardedInvoker with the human channel:

$this->tools->call(OrderTools::class, 'refund', ['orderId' => 'A-1', 'amount' => 30],
    channel: Invocation::HUMAN);

Those calls keep every rule, limit, approval and the journal; they are just not bound by the agents' roles or by an agent stop. Only "Stop everything" halts every caller. It is a degraded mode without the AI, which is also what the ANSSI recommends for generative AI systems (R15: provide a downgraded version of business services without the AI). One warning, written in the docs too: never use the human channel for code an agent wrote or asked for.

Tool Guard runs an approved request exactly once, but it does not know your business. If someone refunds by hand during the stop, reject the held request rather than approve it after the resume, and give the refund service its own idempotency key. That part belongs to the app.

Testing it without a model

You can prove all of this in CI, like you test your voters, with no model and no API key:

$this->actingAs('alice');
$this->stopToolGuard(reason: 'incident');   // every AI caller, like tool-guard:stop
$this->assertToolStopped('refund', ['orderId' => 'A-1', 'amount' => 20]);
$this->resumeToolGuard();
$this->assertToolRan('refund', ['orderId' => 'A-1', 'amount' => 20]);

debug:tool-guard and the profiler panel also show what is stopped, in red.

What it does not do

A tool guard is not the whole answer, and I would rather say it plainly. Tool Guard does not detect prompt injection, does not filter what the model says, and does not undo an action that already ran. It does not cover a tool reached by a path it cannot see. The repository has a page, docs/recommendations.md, that maps what the AI Act (article 14, for high-risk systems), the ANSSI's recommendations for generative AI and the OWASP Top 10 for Agentic Applications recommend, to the feature that helps implement each, and lists what Tool Guard leaves to you.

Try it

The demo needs no API key, no model and no database: a scripted hostile agent attacks a demo shop over MCP, with and without Tool Guard, and it now shows a stop.

git clone https://github.com/acencyril/tool-guard-bundle && cd tool-guard-bundle
composer install && sh demo/run.sh

The changelog lists everything in 0.3.0. Feedback and issues are welcome on GitHub, especially from people running Symfony AI agents with real tools.

A prompt is not a lock. A stop button in code is.

A project like this one?AI integration, a site to make readable by assistants, security: let's talk.
Contact me

Read next