Introducing fundation for human-in-the-loop mechanism for tool calling

Author: chr-hertel

docs/components/agent.rst

@@ -405,6 +405,107 @@ If you need to react more granularly to the lifecycle of individual tool calls,
         // Let the client know, that the tool $event->toolCall->name failed with the exception: $event->exception
     });
 
+Human-in-the-Loop Confirmation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Agent component provides a confirmation system for implementing human-in-the-loop patterns when executing tools.
+This allows you to require user approval before potentially dangerous operations are performed.
+
+The confirmation system uses the :class:`Symfony\\AI\\Agent\\Toolbox\\Event\\ToolCallRequested` event, which is
+dispatched before each tool execution. A :class:`Symfony\\AI\\Agent\\Toolbox\\Confirmation\\ConfirmationSubscriber`
+listens to this event and applies a policy-based confirmation workflow::
+
+    use Symfony\AI\Agent\Toolbox\Confirmation\ConfirmationSubscriber;
+    use Symfony\AI\Agent\Toolbox\Confirmation\DefaultPolicy;
+    use Symfony\AI\Agent\Toolbox\Toolbox;
+    use Symfony\Component\EventDispatcher\EventDispatcher;
+
+    // Create a policy that auto-allows read operations
+    $policy = new DefaultPolicy();
+
+    // Create a confirmation handler (implement ConfirmationHandlerInterface)
+    $handler = new MyConfirmationHandler();
+
+    // Wire everything together
+    $dispatcher = new EventDispatcher();
+    $dispatcher->addSubscriber(new ConfirmationSubscriber($policy, $handler));
+
+    $toolbox = new Toolbox($tools, eventDispatcher: $dispatcher);
+
+Policy Configuration
+....................
+
+The :class:`Symfony\\AI\\Agent\\Toolbox\\Confirmation\\DefaultPolicy` provides smart defaults:
+
+- **Auto-allows** read-only operations (tools with names containing: read, get, list, search, find, show, describe)
+- **Asks the user** for all other operations
+- **Remembers** user decisions for subsequent calls
+
+You can customize the policy behavior::
+
+    $policy = new DefaultPolicy();
+
+    // Explicitly allow specific tools without confirmation
+    $policy->allow('safe_tool');
+
+    // Explicitly deny tools (blocked without asking)
+    $policy->deny('dangerous_tool');
+
+    // Customize read patterns
+    $policy->setReadPatterns(['fetch', 'query', 'lookup']);
+
+For scenarios where no confirmation is needed, use the :class:`Symfony\\AI\\Agent\\Toolbox\\Confirmation\\AlwaysAllowPolicy`::
+
+    use Symfony\AI\Agent\Toolbox\Confirmation\AlwaysAllowPolicy;
+
+    $policy = new AlwaysAllowPolicy(); // Bypasses all confirmation - use with caution
+
+Implementing a Confirmation Handler
+...................................
+
+To ask the user for confirmation, implement the :class:`Symfony\\AI\\Agent\\Toolbox\\Confirmation\\ConfirmationHandlerInterface`.
+Here's an example CLI handler::
+
+    use Symfony\AI\Agent\Toolbox\Confirmation\ConfirmationHandlerInterface;
+    use Symfony\AI\Agent\Toolbox\Confirmation\ConfirmationResult;
+    use Symfony\AI\Platform\Result\ToolCall;
+
+    class CliConfirmationHandler implements ConfirmationHandlerInterface
+    {
+        public function requestConfirmation(ToolCall $toolCall): ConfirmationResult
+        {
+            echo sprintf(
+                "Allow tool '%s' with args %s? [y/N/always/never] ",
+                $toolCall->getName(),
+                json_encode($toolCall->getArguments())
+            );
+
+            $input = strtolower(trim(fgets(\STDIN)));
+
+            return match ($input) {
+                'y', 'yes' => ConfirmationResult::confirmed(),
+                'always' => ConfirmationResult::always(),
+                'never' => ConfirmationResult::never(),
+                default => ConfirmationResult::denied(),
+            };
+        }
+    }
+
+The :class:`Symfony\\AI\\Agent\\Toolbox\\Confirmation\\ConfirmationResult` supports remembering decisions:
+
+- ``ConfirmationResult::confirmed()`` - Allow this execution only
+- ``ConfirmationResult::always()`` - Allow this and future executions of the same tool
+- ``ConfirmationResult::denied()`` - Deny this execution only
+- ``ConfirmationResult::never()`` - Deny this and future executions of the same tool
+
+When a tool is denied, the toolbox returns the denial reason as the tool result, allowing the LLM to handle
+the situation gracefully.
+
+Code Examples
+.............
+
+* `Human-in-the-Loop Confirmation`_
+
 Keeping Tool Messages
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -755,3 +856,4 @@ Code Examples
 .. _`RAG with Pinecone`: https://github.com/symfony/ai/blob/main/examples/rag/pinecone.php
 .. _`Chat with static memory`: https://github.com/symfony/ai/blob/main/examples/memory/static.php
 .. _`Chat with embedding search memory`: https://github.com/symfony/ai/blob/main/examples/memory/mariadb.php
+.. _`Human-in-the-Loop Confirmation`: https://github.com/symfony/ai/blob/main/examples/toolbox/confirmation.php

examples/composer.json

@@ -44,14 +44,13 @@
         "symfony/ai-cloudflare-store": "^0.3",
         "symfony/ai-decart-platform": "^0.3",
         "symfony/ai-deep-seek-platform": "^0.3",
-        "symfony/ai-doctrine-message-store": "^0.3",
         "symfony/ai-docker-model-runner-platform": "^0.3",
+        "symfony/ai-doctrine-message-store": "^0.3",
         "symfony/ai-elasticsearch-store": "^0.3",
         "symfony/ai-eleven-labs-platform": "^0.3",
         "symfony/ai-failover-platform": "^0.3",
         "symfony/ai-gemini-platform": "^0.3",
         "symfony/ai-generic-platform": "^0.3",
-        "symfony/ai-session-message-store": "^0.3",
         "symfony/ai-hugging-face-platform": "^0.3",
         "symfony/ai-lm-studio-platform": "^0.3",
         "symfony/ai-manticore-search-store": "^0.3",
@@ -79,6 +78,7 @@
         "symfony/ai-scaleway-platform": "^0.3",
         "symfony/ai-scraper-tool": "^0.3",
         "symfony/ai-serp-api-tool": "^0.3",
+        "symfony/ai-session-message-store": "^0.3",
         "symfony/ai-similarity-search-tool": "^0.3",
         "symfony/ai-supabase-store": "^0.3",
         "symfony/ai-surreal-db-message-store": "^0.3",
@@ -94,10 +94,11 @@
         "symfony/console": "^7.4|^8.0",
         "symfony/dependency-injection": "^7.4|^8.0",
         "symfony/dotenv": "^7.4|^8.0",
+        "symfony/filesystem": "8.1.x-dev",
         "symfony/finder": "^7.4|^8.0",
         "symfony/http-foundation": "^7.4|^8.0",
-        "symfony/rate-limiter": "^7.4|^8.0",
         "symfony/process": "^7.4|^8.0",
+        "symfony/rate-limiter": "^7.4|^8.0",
         "symfony/var-dumper": "^7.4|^8.0"
     },
     "require-dev": {

examples/toolbox/confirmation.php

@@ -0,0 +1,73 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\AI\Agent\Agent;
+use Symfony\AI\Agent\Bridge\Filesystem\Filesystem;
+use Symfony\AI\Agent\Toolbox\AgentProcessor;
+use Symfony\AI\Agent\Toolbox\Confirmation\ConfirmationHandlerInterface;
+use Symfony\AI\Agent\Toolbox\Confirmation\ConfirmationResult;
+use Symfony\AI\Agent\Toolbox\Confirmation\ConfirmationSubscriber;
+use Symfony\AI\Agent\Toolbox\Confirmation\DefaultPolicy;
+use Symfony\AI\Agent\Toolbox\Toolbox;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\ToolCall;
+use Symfony\Component\Console\Helper\QuestionHelper;
+use Symfony\Component\Console\Input\ArgvInput;
+use Symfony\Component\Console\Question\ChoiceQuestion;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+use Symfony\Component\Filesystem\Filesystem as SymfonyFilesystem;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+$eventDispatcher = new EventDispatcher();
+$eventDispatcher->addSubscriber(new ConfirmationSubscriber(new DefaultPolicy(), new class implements ConfirmationHandlerInterface {
+    public function requestConfirmation(ToolCall $toolCall): ConfirmationResult
+    {
+        $args = json_encode($toolCall->getArguments());
+        output()->writeln(sprintf('🔐 Tool "%s" wants to execute with args: %s', $toolCall->getName(), $args));
+        $question = new ChoiceQuestion('Do you want to allow this?', ['y', 'N', 'always', 'never'], 1);
+
+        return match ((new QuestionHelper())->ask(new ArgvInput(), output(), $question)) {
+            'y' => ConfirmationResult::confirmed(),
+            'always' => ConfirmationResult::always(),
+            'never' => ConfirmationResult::never(),
+            default => ConfirmationResult::denied(),
+        };
+    }
+}));
+
+$toolbox = new Toolbox(
+    [new Filesystem(new SymfonyFilesystem(), __DIR__)],
+    logger: logger(),
+    eventDispatcher: $eventDispatcher,
+);
+
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+$processor = new AgentProcessor($toolbox, eventDispatcher: $eventDispatcher);
+$agent = new Agent($platform, 'gpt-4o-mini', [$processor], [$processor]);
+
+output()->writeln('Human-in-the-Loop Tool Confirmation Demo');
+output()->writeln('=========================================');
+output()->writeln('The DefaultPolicy auto-allows read operations (filesystem_list) but asks for write operations (filesystem_delete).');
+
+$messages = new MessageBag(Message::ofUser(
+    'First, list the files in this folder. Then delete the file confirmation.php',
+));
+
+$result = $agent->call($messages, ['stream' => true]);
+
+foreach ($result->getContent() as $chunk) {
+    echo $chunk;
+}
+
+echo \PHP_EOL;

src/agent/CHANGELOG.md

@@ -5,6 +5,8 @@ CHANGELOG
 ---
 
  * [BC BREAK] Rename `Symfony\AI\Agent\Toolbox\Tool\Agent` to `Symfony\AI\Agent\Toolbox\Tool\Subagent`
+ * Add human-in-the-loop tool confirmation system
+ * Add `ToolCallRequested` event dispatched before tool execution
 
 0.3
 ---

src/agent/src/Toolbox/Confirmation/AlwaysAllowPolicy.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox\Confirmation;
+
+use Symfony\AI\Platform\Result\ToolCall;
+
+/**
+ * Policy that always allows tool execution without confirmation.
+ * Use with caution - this bypasses all safety checks.
+ *
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+final class AlwaysAllowPolicy implements PolicyInterface
+{
+    public function decide(ToolCall $toolCall): PolicyDecision
+    {
+        return PolicyDecision::Allow;
+    }
+}

src/agent/src/Toolbox/Confirmation/ConfirmationHandlerInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox\Confirmation;
+
+use Symfony\AI\Platform\Result\ToolCall;
+
+/**
+ * Handles user confirmation requests for tool execution.
+ *
+ * Implementations can provide CLI prompts, web UI dialogs, or other
+ * mechanisms to ask the user for permission.
+ *
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+interface ConfirmationHandlerInterface
+{
+    public function requestConfirmation(ToolCall $toolCall): ConfirmationResult;
+}

src/agent/src/Toolbox/Confirmation/ConfirmationResult.php

@@ -0,0 +1,54 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox\Confirmation;
+
+/**
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+final class ConfirmationResult
+{
+    private function __construct(
+        private readonly bool $confirmed,
+        private readonly bool $remember,
+    ) {
+    }
+
+    public function isConfirmed(): bool
+    {
+        return $this->confirmed;
+    }
+
+    public function shouldRemember(): bool
+    {
+        return $this->remember;
+    }
+
+    public static function confirmed(): self
+    {
+        return new self(true, false);
+    }
+
+    public static function denied(): self
+    {
+        return new self(false, false);
+    }
+
+    public static function always(): self
+    {
+        return new self(true, true);
+    }
+
+    public static function never(): self
+    {
+        return new self(false, true);
+    }
+}