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
)
… #HThe asynchronous call holds the shared lock while running the blocking human prompt in a thread. section 9.3
