Handoff to User

Lets the model pause the agent loop and surface a message to the user for human-in-the-loop input. Use this when the agent needs explicit confirmation, additional information, or user approval before proceeding.

Supported in: Node.js, modern browsers (TypeScript); all platforms (Python).

Bidirectional streaming not supported

handoff_to_user relies on the interrupt/resume mechanism, which requires the agent loop to fully halt and restart. It cannot be used inside bidirectional streaming sessions, where the loop runs continuously without a clean pause point.

The loop halts with a stop_reason / stopReason of "interrupt" and the message is available on the interrupt’s reason field in AgentResult.interrupts. Resume the agent by passing back an interruptResponse content block with the interrupt ID and the user’s reply; the tool then returns that reply as its result and the model continues. To recognize a handoff interrupt, match its name against the exported HANDOFF_INTERRUPT_NAME constant.

Combining with HumanInTheLoop

HumanInTheLoop() requires approval for every tool by default, so pairing it with handoff_to_user prompts the user twice — once to approve the call, then again to answer it. Allow-list the tool with HumanInTheLoop(allowed_tools=["handoff_to_user"]) / new HumanInTheLoop({ allowedTools: ["handoff_to_user"] }) so only the handoff itself prompts.

Example:

TypeScript

import { Agent, InterruptResponseContent } from '@strands-agents/sdk'
import {
  handoffToUser,
  HANDOFF_INTERRUPT_NAME,
} from '@strands-agents/sdk/vended-tools/handoff-to-user'

const agent = new Agent({
  tools: [handoffToUser],
  systemPrompt:
    'Before deleting any files, call handoff_to_user to confirm with the user.',
})

let result = await agent.invoke('Delete all .tmp files in /workspace.')
const interrupt = result.interrupts?.find((i) => i.name === HANDOFF_INTERRUPT_NAME)
if (interrupt) {
  console.log(interrupt.reason)
  result = await agent.invoke([
    new InterruptResponseContent({ interruptId: interrupt.id, response: 'confirmed' }),
  ])
}

Python

from strands import Agent
from strands.vended_tools.handoff_to_user import HANDOFF_INTERRUPT_NAME, handoff_to_user

agent = Agent(
    tools=[handoff_to_user],
    system_prompt=(
        "Before deleting any files, call handoff_to_user to confirm with the user."
    ),
)

result = agent("Delete all .tmp files in /workspace.")
interrupt = next(i for i in (result.interrupts or []) if i.name == HANDOFF_INTERRUPT_NAME)
print(interrupt.reason)

resumed = agent([
    {
        "interruptResponse": {
            "interruptId": interrupt.id,
            "response": "confirmed",
        }
    }
])

📖 Full API Reference

Tags

tool-authoring26