This feature is in preview. The API may change before general availability. To try it out, contact support@intunedhq.com and we’ll enable it for your workspace.
Overview
Some automations can’t finish on their own. A login asks for a one-time code, a CAPTCHA won’t solve, or a page needs a judgment call. Human in the loop lets a Run pause, ask for help, and continue with the answer. Usually a person answers, but your own system or an agent can answer through the same links. The Runtime SDK has two methods for this:askForInputasks a question and waits for a JSON answer, such as a 6-digit code.handoffhands over live control of the Run’s browser. Whoever takes over acts in the browser, then presses Done to hand it back.
How it works
- Your code calls
askForInputorhandoff. The Run pauses on that line. - Intuned creates the interaction and gives it a link. For
askForInput, the link takes the answer (inputUrl). Forhandoff, it opens a page that controls the browser (handoffUrl). - The link reaches whoever answers, either through the
urlyour code passed or from the Run or AuthSession operation result API. - They answer or press Done. Your code continues with the answer.
Ask for input
schema, the answer is validated and typed, and the schema is sent as JSON Schema so whoever answers knows what to submit.
To answer, POST the JSON to the interaction’s inputUrl:
To cancel the interaction instead of answering it, POST to its
cancelUrl with no body. askForInput throws InteractionCanceledError. The responses are the same.
Hand off the browser
handoffUrl opens a page with the live browser, the prompt, a countdown, and Done and Cancel buttons. Done resumes the Run. Cancel makes handoff throw InteractionCanceledError. If your workspace restricts access by IP address, the page opens only from allowed addresses.
handoff needs a visible browser. Set headful to true in Intuned.json. In a headless Run, handoff throws InteractionUnsupportedError. A Run can have one handoff open at a time.Check the page after a handoff
Whoever takes over can navigate, open tabs, or change what’s on the page. Don’t assume the page is where your code left it:- Wait for the state you need, such as
page.waitForURLor a selector, instead of continuing right away. - Re-find elements after the handoff instead of reusing handles from before it.
- If they may have opened a new tab, pick the page you need from
context.pages().
Deliver the link
Withurl. Intuned sends a POST to the URL with the headers your code passed, for example an Authorization header that your endpoint checks. The URL must be public HTTPS. Redirects aren’t followed. Deliveries are retried for up to 5 minutes; if they keep failing, the method throws InteractionDeliveryError.
handoff interaction has handoffUrl in place of inputUrl, and its cancelUrl works like the page’s Cancel button. Every delivery carries an x-intuned-interaction-id header with the interaction id, so you can ignore repeats.
Without url. While a Run is waiting, the Run result API lists its open interactions in pendingInteractions, with the same fields. Poll it from your app, then show the link to whoever answers or answer from your own code. AuthSession create, validate and update operations work the same way: while one is in_progress, its result (create, validate, update) has the same pendingInteractions field.
From the CLI. intuned platform runs get lists a waiting Run’s interactions, and intuned platform interactions resolve answers one: it prompts for the input like a local run, or opens the handoff page. intuned platform interactions cancel cancels one.
Timeouts and cost
While an interaction waits, the Run’s own timeout is extended every minute, so an answer can take longer than the Run timeout. Pass
extendRunTimeout: false (extend_run_timeout=False in Python) to keep the Run timeout in force instead.
The machine keeps running while it waits, so waiting time counts as compute time. A waiting Run also occupies a machine that other Runs can’t use.
In the IDE and CLI
Local Runs don’t useurl. The developer answers in the terminal:
askForInputasks for each field when the schema has only string, number, and boolean fields, and asks for JSON otherwise. Press Esc to cancel.handoffasks you to use the browser, then press Enter to continue or Esc to cancel.- Interactions are answered one at a time.
Limitations
- Interactions fail right away with
InteractionUnsupportedErrorwhen nobody can answer in a terminal: agent runs, and CLI runs whose input isn’t an interactive terminal. - When an interaction fails (for example, it times out), the attempt fails and is retried like any other error, which asks again.
- Redeploying a project ends its open interactions.