liveBook · Manning

Tool-based HITL

As explained in Build a Multi-Agent System (from Scratch)

Tool-based HITL is a human-in-the-loop pattern in which an agent invokes a tool to request information from a human during task execution.

Tool-based human-in-the-loop (HITL) lets an agent request information from a human during task execution. For example, a restaurant-search agent can ask for cuisine preferences when it cannot narrow the options. The agent invokes the input tool at its discretion and uses the response to continue; the processing loop does not need a special approval step. section 8.0 section 8.2

This differs from result approval, where a human reviews the completed result, and supervised execution, where a human controls progress step by step. Tool-based HITL requests clarification, not automatic approval of every action or result. section 8.0 section 8.1

A HumanInputTool can fit into an existing tool interface:

  • Subclass BaseTool and provide name, description, parameters_json_schema, and __call__(). The schema specifies a required prompt and optional choices that constrain the human response. section 8.2
  • Validate the ToolCall arguments before prompting. On validation failure, return a ToolCallResult with the call ID, serialized error details, and error=True. section 8.2
  • Display the prompt and any choices, wait for the operator’s response, and return it through the tool-call flow. A separate _prompt_human() helper keeps console interaction reusable. section 8.2

Request a starting value

Equip an agent with HumanInputTool and a next_number tool, then ask it to compute a Hailstone sequence using a starting number supplied by the operator. The agent requests the number before calculation; an input of 2 produces the sequence [2, 1]. section 8.2

In a multi-agent system, concurrent subagents can race to use a single console, making prompts and responses hard to associate. SharedConsoleHumanInputTool replaces the synchronous tool with an AsyncBaseTool and a class-level asyncio.Lock. Each call acquires the shared lock before prompting, so only one subagent uses the console at a time; an optional agent_name labels the prompt. section 9.3

Listing 9.12 Implementing SharedConsoleHumanInputTool: __call__()
# llm_agents_from_scratch/tools/default/human_input.py
… #A
 
class SharedConsoleHumanInputTool(AsyncBaseTool):
    … #B
 
    async def __call__(
        self,
        tool_call: ToolCall,
        *args: Any,
        **kwargs: Any,
    ) -> ToolCallResult:
        """Acquire the console lock, then prompt the human in a thread.""" #C
        … #D
        try:
            async with SharedConsoleHumanInputTool._console_lock: #E
                response = await asyncio.to_thread( #F
                    _prompt_human,
                    prompt,
                    choices,
                    self.agent_name, #G
                )
        … #H

The asynchronous call holds the shared lock while running the blocking human prompt in a thread. section 9.3

How Build a Multi-Agent System (from Scratch) covers it

How deep it goes
Implements tool schemas, validation, console prompting, and a synchronized asynchronous variant for concurrent subagents.
Examples
Uses a restaurant preference question and a Hailstone sequence requiring a human-supplied starting number.
What you can do after
Build a human-input tool from scratch and adapt it for concurrent subagents using a shared console lock.
How it connects
Connects human-in-the-loop agents with tool calls, result approval, supervised execution, and multi-agent systems.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build a Multi-Agent System (from Scratch). The section links point to the parts of the book it draws on.