How agents hand work over through saved records

“The fix is done” is not enough for a reviewer. The reviewer needs to find the changed code, know which request it addresses and see which checks ran. Saving that information makes the handover work even when coding and review happen in different sessions.

Give the next step something it can inspect#

In this example design, planning saves a work item. Development saves a branch and creates a pull request. Review adds findings for that code version, and the test pipeline saves its results. Each record remains available after the process that produced it has stopped. These saved outputs are often called artifacts.

The handover record below tells a reviewer what to inspect next. It is illustrative JSON, not a required format or a real task. A production record should point to the actual repository, full code revision and test results. The example’s identifiers are placeholders.

{
  "handoff_id": "work-184:build-to-review",
  "attempt": 2,
  "goal": "Add a bounded retry to the import job",
  "scope": "src/importer and its integration tests",
  "state": "ready_for_review",
  "revision": "example-revision-2",
  "evidence": ["pull request 42", "build 781 passed"],
  "risks_or_blockers": ["provider timeout behavior unverified"],
  "next_action": "review the diff and timeout assumption"
}

The handover ID identifies the same piece of work across attempts. The attempt number changes when the work is retried. The remaining risk is visible: the build passed, but the provider’s timeout behaviour has not been verified. Review must not mistake that build result for proof that the whole requirement is settled.

The string “build 781 passed” is only a reference. The reviewer must be able to retrieve build 781, inspect its checks and confirm that it tested the listed revision. A model’s summary is not a substitute for the source result.

In the figure, work moves through saved records rather than a direct call from builder to reviewer. This suits a process where the next step may run later or on another machine. It also lets a person inspect the same input that the next agent receives.

Other kinds of handoff are useful too. The OpenAI Agents SDK handoff mechanism transfers control to another agent during a run. Its agents-as-tools pattern lets a manager call a specialist while keeping control. Those calls can have saved traces. The distinction here is that the records are also the input for a later stage, not merely a record of an earlier conversation.

Saved work makes recovery possible to investigate; it does not make every action reversible. A Git revert cannot retract a request already sent to another service or restore every deleted record. Save external effects and the available recovery steps alongside the code changes.

Start the next step when its input is ready#

A saved file does not start a worker on its own. Something must notice that work is ready and decide which step may run. That coordinating software is often called the orchestrator. It can be an existing CI or workflow service; it need not be a service you build and host yourself.

For example, opening a pull request can send a webhook: an HTTP notification to a configured endpoint. The receiver verifies the sender, checks the event type and avoids processing a repeated delivery twice. GitHub’s webhook guidance covers secrets, event checks and identifying deliveries.

Treat the notification as a reason to inspect the work, not as permanent proof of its current state. The branch might have changed since the event was sent, or the task might now be cancelled. Read the relevant records and check that the next action is still allowed before starting a worker.

Save any decision that affects the work. A developer taking over should be able to find the request, the code, the recorded approvals and the sequence of attempts. The history can live in several linked stores; it must not depend on an undocumented decision inside a process that has disappeared.

You can also keep external writes out of the model’s direct control. The model proposes an action with a target and payload. Ordinary code checks the format, the permitted operation and the task’s current state before executing it. For example, an agent that may add an assessment need not have permission to overwrite the requester’s original text.

Record who owns the task and what has happened#

A ticket’s label is useful to a person, but it is not automatically a safe way for two workers to claim the same job. If both can read “unassigned” and then set themselves as assignee, both may start. Check whether the actual API supports the indivisible claim operation your design needs.

One possible split is to keep the request in the issue tracker, code and review in the source host, and task ownership in a workflow store. Run history records attempts, tool results, configuration versions and costs. These are responsibilities to account for, not four mandatory databases.

When a worker can crash while holding a task, its claim may need an expiry time. This is called a lease. Another worker can take over after expiry, but the old worker must no longer be allowed to publish. Check current ownership at the point where changes are committed or external actions are performed. Expiry alone does not stop a paused process from waking up later.

Retries also need rules for actions that may already have happened. Use an operation that is safe to repeat where the API supports it. Otherwise, inspect the external result before retrying and stop when the outcome remains uncertain. Idempotency keys and safe retries explains why a timeout must not automatically produce a second write.

You do not need all this machinery before trying the first agent. A useful first workflow can run one agent in an isolated environment, save its result and let a person review it. Add more coordination when tasks need to wait, run concurrently or survive restarts.

The next agent also needs the relevant project instructions. Having an instruction file somewhere in the repository does not mean the agent read it. Context engineering explains how to choose and supply that information; the harness provides the tools and restrictions used to act on it.