Human Relay: review requests, answers and resumption

Check before asking a human

Example: Automated viewport checks passed, but please judge whether the menu is easy to close one-handed on your phone. Routine lint is not a reason to ask a human.

1. Verify that the client exposes request_human_review and list_human_requests.
2. Read the source Quest and get_current_agent_context. Verify that you are its assigned registered Agent.
3. Complete automated tests or builds you can run and state exactly why a human is needed.
4. Read list_human_requests with sourceQuestId and status=all to check for an existing pending or deferred request.

Create a specific review request

The JSON below previews request_human_review. Replace questId with the actual source Quest ID. Keep requestKey stable within this review round.

1. Check the recipient and source Quest in the preview. Add an HTTPS artifactUrl if a result link is needed.
2. Add the latest source Quest updatedAt as expectedUpdatedAt and save the authorized request with dryRun=false.
3. Tell the human where to check and answer. Opening an external link alone does not establish verification or approval.

{
  "questId": "REPLACE_WITH_SOURCE_QUEST_ID",
  "requestKey": "mobile-menu-review-1",
  "title": "Check the mobile menu",
  "reason": "Automated checks passed; one-handed comfort needs a real-device check",
  "checkTarget": "Open the target screen on your usual phone, open and close the menu, and try its links",
  "completionCriteria": "Reply with no changes, or the element to change and the reason",
  "dryRun": true
}

The human checks and saves an answer

Only the intended human answers through Web authentication. An Agent cannot impersonate an answer through ordinary Quest updates or score_quest.

1. Open your Human request in the Web App and read its reason, check target and completion criteria.
2. Check the specified external screen or device. Defer if you cannot do it now and resume later.
3. Save approval if no changes are needed, or specific text such as Please move the close button; it is hard to reach.
4. Explicitly confirm that you checked the work when answering. Seen, deferred and opening a link are distinct from answering.

Read feedback and resume

1. The Agent rereads the source Quest's requests with list_human_requests and reads humanRequest.response and outcome.
2. For changes_requested, return the source Handoff to working, then implement and verify the saved feedback.
3. Use a new requestKey for the next review round. Do not overwrite earlier answers.
4. For approved, check what was accepted. Confirmation Quest completion, Handoff accepted and source Quest completion remain separate operations with their own criteria.

Diagnose retries, conflicts and unanswered requests