Human-in-the-Loop

The agent pauses execution and emits special events when it encounters two situations: a tool call that requires user confirmation (permission system returns ASK), or a tool marked as external execution (the result must come from outside the agent). In both cases, you resume the agent by passing a result event back via reply. While paused, reply returns a waiting notice message whose finished_reason is None: the reply is parked, not finished, and no remaining tool calls are executed until the outside result arrives.

User Confirmation

When the permission system determines a tool call needs user approval, the agent emits a RequireUserConfirmEvent and pauses.

Receive the RequireUserConfirmEvent

Use reply_stream to detect the pause. The event has the following structure:

str

required

ID of the current reply, used to resume the agent.

list[ToolCallBlock]

required

Tool calls pending user confirmation. Each ToolCallBlock contains:

Show child attributes

str

Unique identifier for this tool call.

str

The tool name (e.g. "Bash", "Write").

str

JSON-encoded input parameters.

list[PermissionRule]

Auto-generated permission rules the user can accept to allow similar future calls.

from agentscope.event import RequireUserConfirmEvent

async for event in agent.reply_stream(msg):
    if isinstance(event, RequireUserConfirmEvent):
        for tc in event.tool_calls:
            print(f"Tool: {tc.name}, Input: {tc.input}")
            print(f"Suggested rules: {tc.suggested_rules}")

Build the confirmation result

For each pending tool call, create a ConfirmResult indicating whether to allow or deny it. You can also modify the tool call input or accept suggested permission rules:

from agentscope.event import ConfirmResult, UserConfirmResultEvent

confirm_results = []
for tc in event.tool_calls:
    confirm_results.append(ConfirmResult(
        confirmed=True,           # or False to deny
        tool_call=tc,             # pass back (optionally modified)
        rules=tc.suggested_rules, # accept rules for future auto-allow
    ))

Resume the agent

Pass the UserConfirmResultEvent back to reply or reply_stream:

confirm_event = UserConfirmResultEvent(
    reply_id=event.reply_id,
    confirm_results=confirm_results,
)
result = await agent.reply(confirm_event)

Confirmed tool calls execute immediately and the agent continues reasoning
Denied tool calls produce an error result visible to the LLM, which may retry with a different approach
Accepted rules are persisted to the permission engine, so matching future calls are auto-allowed without prompting again

External Tool Execution

When the agent calls a tool with is_external_tool = True, it emits a RequireExternalExecutionEvent and pauses. The tool’s logic runs outside the agent, typically by a human operator or an external system.

Receive the RequireExternalExecutionEvent

The event has the following structure:

str

required

ID of the current reply, used to resume the agent.

list[ToolCallBlock]

required

Tool calls to be executed externally. Each ToolCallBlock contains:

Show child attributes

str

Unique identifier for this tool call.

str

The external tool name.

str

JSON-encoded input parameters.

from agentscope.event import RequireExternalExecutionEvent

async for event in agent.reply_stream(msg):
    if isinstance(event, RequireExternalExecutionEvent):
        for tc in event.tool_calls:
            print(f"Execute externally: {tc.name}({tc.input})")

Execute externally and build results

Run the operation outside the agent and wrap the results as ToolResultBlock objects:

from agentscope.message import ToolResultBlock, TextBlock, ToolResultState
from agentscope.event import ExternalExecutionResultEvent

execution_results = []
for tc in event.tool_calls:
    # Perform the actual operation (API call, human action, etc.)
    output = await run_external_operation(tc.name, tc.input)

    execution_results.append(ToolResultBlock(
        id=tc.id,
        name=tc.name,
        output=[TextBlock(text=output)],
        state=ToolResultState.SUCCESS,
    ))

Resume the agent

Pass the ExternalExecutionResultEvent back to resume:

external_event = ExternalExecutionResultEvent(
    reply_id=event.reply_id,
    execution_results=execution_results,
)
result = await agent.reply(external_event)

The results are injected into the agent’s context and reasoning continues from where it left off.

If multiple tool calls require outside interaction and only partial confirmation or execution results are passed back, the agent won’t re-send the requiring events for the unconfirmed or unexecuted tool calls.

Use reply_stream when building interactive UIs: it lets you detect pause events in real time and prompt the user immediately. Use reply when you have pre-built automation that handles events programmatically.

Get Started

Building Blocks

Agent as Service

Others

User Confirmation

External Tool Execution

​User Confirmation

​External Tool Execution

User Confirmation

External Tool Execution