[FEATURE] Support Human-in-the-Loop (HIL) capabilities

[yike5460]

Problem Statement

Consider to provide Human-in-the-Loop (HIL) capabilities to enable human intervention at any point during execution

Proposed Solution

Enhancement on existing mechanism that could be used to implement HIL patterns:

Callback Handler System

Through the callback handler system. The Agent class accepts a callback_handler parameter that receives events throughout execution and processes events during the event loop cycle.

Tool-Based Intervention Points

Through custom tools that can pause execution and request human input. The tool system supports custom Python functions decorated with @tool, and tools can access the agent context through parameter injection.

Streaming Interface for Real-time Monitoring

Through stream_async() that yields events as they occur. This could enable real-time monitoring and intervention, though it would require custom implementation to pause execution.

Request State Management

The event loop maintains a request_state that can be modified during execution in event loop. A custom implementation could use this to signal when human intervention is needed.

Use Case

Provide robust mechanisms for pausing workflows, collecting human input, and resuming execution with the provided feedback or modifications, which are common cases in regulation impose and data sensitive industries, e.g. Finance

Alternatives Solutions

No response

Additional Context

No response

---

Status

• Support interruption from BeforeToolCallEvent hooks
  • PR: hooks - before tool call event - interrupt #987
• Support interruption from tool definitions
  • PR: interrupts - decorated tools #1041
• Support elicitation in MCP tool.
  • PR: mcp elicitation #1094
  • Note, we support elicitation by conventional means of an elicitation callback. There are plans though to have Strands translate elicitations into interrupts when the user does not provide an elicitation callback. This will be follow up work that we track separately.
• Signal that interrupts are not supported for direct tool calls.
  • PR: direct tool call - interrupt not allowed #1097
• Support same interrupt mechanism for multi-agent workflows.
  • Swarm PR: interrupts - swarm #1193
  • Graph PR: In progress

Updates

We still have graph interrupts left to support. The following is our progress:

• 2025-01-13: We are going to release a PR that introduces interrupt support in hooks only. Following, we will release support for node executor interrupts.
• 2025-01-14: Adding support for hook based interrupts in graphs with interrupts - graph - hook based #1478
  • Will need to follow up to allow interrupts from agent and multiagent nodes.
• 2025-01-15: Merged in support for raising interrupts from hooks in graphs (will go out with next release). Next I am working on supporting interrupts from agent nodes. The last item will be supporting interrupts from multi-agent nodes.

[awsarron]

Thank you for your feedback @yike5460. We have created #214 to encompass several multi-agent and return of control (HIL) features. This task is part of that epic.

[zastrowm]

We should also consider how hooks might also contribute to HIL scenarios. For instance, if a hook could somehow indicate that the loop should stopped, it'd be one way to implement tool consent.

Resumption from any point in the event_loop is also something we should be considering

[dbschmigelski]

MCP released Elicitation which will play a role in HIL.

[pgrayy]

For further discussion on this topic, you can share feedback in #666. Here we have detailed the approaches we started considering.