Request human input

Pause automation while a person provides one response. human.request is asynchronous only: it returns a ToolCall that remains in requires_input until the response is submitted or the request expires.

Request a response

1
const call = await bctrl.tools.start("human.request", {
2
  prompt: "Please confirm the account email before continuing.",
3
  responseSchema: {
4
    type: "object",
5
    properties: { confirmed: { type: "boolean" } },
6
    required: ["confirmed"],
7
  },
8
  expiresInSeconds: 1800,
9
}, { runtimeId: runtime.id });
10
11
console.log(call.id, call.status);

The Runtime must be active. Human input can be used with browser, desktop, and spreadsheet Runtime types.

Request parameters

Complete the request

Submit the response with the ToolCall ID, then read the completed result:

1
await bctrl.toolCalls.respond(call.id, {
2
  confirmed: true,
3
});
4
5
const result = await bctrl.toolCalls.result(call.id, {
6
  waitSeconds: 30,
7
});
8
9
console.log(result);

The result is a JSON value: a string, number, boolean, null, array, or object. Cancel an outstanding request with bctrl.toolCalls.cancel(call.id). An expired or cancelled request does not produce a human response.

ToolCall lifecycle

Next

• Views — give a person a live surface for automation
• Tools — understand ToolCalls and Toolsets
• Runs — inspect the execution record