Guilduo

Human ⇄ Agent · Handoff and review

AI Agent Handoff and Human Review

Give the next person or agent enough context to continue: who owns the task, what changed, what was checked and which decision is still needed. Guilduo keeps that work record and human feedback alongside a Quest while coding happens in your external tools.

Read the review workflow Open Guilduo / Relay Forge

A finished edit still needs a clear handoff

A coding agent can return “fixed” without explaining what remains unverified. A reviewer may reply in another chat, leaving the next session without the decision. The useful handoff carries the original goal, assignee, progress, evidence and next action together.

In Guilduo, a Quest is the task record and Handoff describes its handover state. Agent registration saves a role and permission policy; it does not start a model. Assigning work or changing a state does not launch execution either. The connected Codex, Claude or other coding environment must explicitly read the task and do the work.

In an agent SDK, “handoff” can mean transferring execution to another agent within a runtime. Guilduo's persisted task handoff records responsibility and review context. It does not transfer a running model session or its hidden context.

Carry the work forward, then read the decision

  1. Define and assign. Write the target, constraints and completion criteria. Read the current Quest and registered Agent; preview assign_quest_to_agent, then save authorized changes with the latest expectedUpdatedAt.
  2. Work in the connected tool. The agent reads the Quest, records working, edits and verifies externally. Save a concise result, evidence location and remaining checks; return work for review as review_required. If blocked, record the reason and what must change.
  3. Ask a specific human question. Check existing requests with list_human_requests. Preview request_human_review with a reason, check target and completion criteria; save with current expectedUpdatedAt. This creates a separate confirmation Quest.
  4. Save the human answer. The intended human checks the external artifact or device, then saves an outcome and text feedback through Web authentication. Opening a link, seeing a request or deferring it is not an answer.
  5. Read before resuming. Explicitly instruct the agent to reread list_human_requests, including humanRequest.response and outcome. Apply changes_requested feedback and verify again; for approved, check the accepted scope before closing work.
Saved state and the next explicit action
Handoff stateMeaningNext action
workingWork is in progress.Edit and verify in the external client.
blockedWork cannot continue.Record the blocker; resume after resolution.
review_requiredWork was returned for human review.Inspect results and remaining checks.
acceptedThe Handoff was accepted.Check original Quest completion separately.

Human response, confirmation Quest completion, Handoff acceptance and original Quest completion have separate conditions and operations. A saved approval does not automatically finish the original task.

Example: fix a smartphone menu and review its feel

Illustrative task and feedback only. These are invented examples, not a customer incident or evidence of a completed device test.

Original Quest: “Fix the mobile menu so every link is usable and it can be closed one-handed. Keep desktop navigation unchanged. Return the changed files, checks run and remaining device checks.” This gives the agent an outcome and boundaries.

The agent fixes the menu in its coding tool and reports the actual checks. Automated checks may cover viewport behavior, but comfortable thumb reach needs a person's judgment. The review request asks: “On your usual phone, open and close the menu and try its links. Reply with no changes, or the element to change and why.”

The human checks the external preview and saves changes_requested: “The links work, but the close button is hard to reach with my thumb. Move it lower while keeping the labels.” The agent explicitly reads that saved response, returns the Handoff to working and implements the feedback.

For another review round, use a new requestKey and preserve the earlier answer. After the reviewer saves approved, check the remaining acceptance criteria, accept the Handoff and complete the original Quest as separate actions.

Where this workflow fits—and its limits

Use it when implementation crosses sessions, responsibility changes or device behavior and preferences need human judgment. Include enough evidence that the next reader can distinguish completed checks from assumptions. A routine lint check the agent can run itself does not need a human request.

Guilduo is not a model runner or a guarantee that another agent has started. Plan explicit task reads and resumption in your client. Execution access is the intersection of the OAuth grant and Agent policy; registration or linking does not expand it.

Keep credentials and personal data out of task examples, shared logs and artifact URLs. An agent cannot impersonate the human answer through ordinary Quest updates. Preview supported changes; use current expectedState for Handoff transitions and reread after conflicts.

Start with one task and one review question

Follow Agents and Handoffs to register an Agent and link your coding client, then Human Relay to create a review and read its answer. Check authentication and permissions before writes. Begin with a small task whose completion criteria both sides can inspect.

Published sources and review date

Reviewed . This guide uses published source revision 42caab0fa1f396f15e4e1277f6e36dda1ac9bd04.