Agent Runtime Guide

Claim Playbook Runs, work through Doku-issued Work Items, and finish safely through Doku MCP.

Doku turns a selected Playbook into a Playbook Run. The dashboard creates a Run Intent, then an external harness such as Codex or Claude claims that intent through the Doku MCP resource URL.

Connect

Use the MCP resource URL from the Agent Work Brief. It is scoped to one Workspace and backed by an Agent Credential, not by the user's dashboard session.

If the harness is not authorized yet, ask the user to complete the Agent Installation authorization shown in Doku before claiming the Run.

Claim a Run

Use the Run Intent ID from the Agent Work Brief. The Launch Snapshot and its assignments are immutable once the Run Intent is created.

const work = await tools.doku.playbooks.runs.claim({
  intentId: "intent_...",
});

The claim creates the Playbook Run and returns a bounded packet containing an opaque executionHandle, current Task Work Items, Variable resolution Work Items, and typed blockers. Keep the returned packet and use only the handles Doku issues.

Discover tools

Use CodeMode discovery as the live contract for tool names and parameters.

await tools.search({ query: "playbook run work" });
await tools.describe.tool("doku.playbooks.runs.claim");

Do not rely on memory if tool contracts differ from this guide. Discovery wins.

Work loop

Inspect the latest packet. Work only on a Task that has a Doku-issued workItemHandle.
If one or more Variables have resolution Work Items and human input is required, request one bounded Human Resolution batch through the opaque handles:
```
const human = await tools.doku.playbooks.variables.requestHumanResolution({
  workItemHandles: ["rwi_..."],
  presentation: "Confirm the missing values.",
});
```
Doku returns a concrete Handoff when the private owner is waiting. A direct authenticated member answers in focused Run UI; only a later, continue-only runs.continue boundary validates and materializes that answer once, consumes the bound Work Item, and returns resolved recovery with the latest Packet—it does not restore or reissue that consumed Work Item. An identical immediate continue replays the stored resolved result while the Packet is unchanged. An originating agent may relay a chat answer only through submitHumanAnswers; that action atomically validates agent-relayed policy/provenance, materializes accepted or downgraded Variables, consumes Work Items, and returns authoritative packet/recovery exactly once. Use that result; re-enter or continue only when it indicates. Relay rejection/block leaves the request waiting for direct UI; owner rejection, cancellation, or expiry is authoritative—do not retry closed state or invent handles.
```
await tools.doku.playbooks.variables.submitHumanAnswers({
  requestHandle: human.requestHandle,
  answers,
});
```
Read the Task's bounded guidance and Connector resources through its Work Item, perform the work, and complete the Task:
```
await tools.doku.playbooks.runs.completeTask({ workItemHandle: "rwi_..." });
```
After each mutation, or after any interruption, re-enter from current Doku state:
```
const nextWork = await tools.doku.playbooks.runs.continue({
  executionHandle: work.executionHandle,
});
```
runs.continue is the synchronization boundary after a direct member answer. A relay is synchronized by submitHumanAnswers; use its authoritative packet/recovery and re-enter or continue only when indicated. Use opaque handles: the continue-only direct path materializes the owner answer once and consumes the bound Work Item; an identical immediate continue replays the stored resolved result while the Packet is unchanged, while changed or stale state requires the latest Packet. Do not poll generic Handoff, approval, or Question APIs.

When the packet includes finishWorkItem, finish with a truthful completion note:

await tools.doku.playbooks.runs.finish({
  workItemHandle: nextWork.finishWorkItem.handle,
  completionNote: "Summarize the completed work and any material caveats.",
});

If Doku returns a typed blocker or Human Resolution Handoff, follow the owning Doku or human action. For a direct member answer, call runs.continue with the latest execution handle; for an agent relay, use the submitHumanAnswers packet/recovery. Direct member answers and agent-relayed answers remain separately authorized and attributed; Doku is the source of runtime authority.

Variables and checkpoints

Launch assignments are frozen in the Launch Snapshot. A runtime Variable that still needs resolution appears as an opaque Variable Work Item in the packet. Use tools.doku.playbooks.variables.resolve only for a known safe value supplied through that Work Item. For missing values or human input, request Human Resolution with the bounded Work Item handles Doku issued; do not invent a Variable handle, task-level Question, or launch-state mutation.

For connector-backed choices, use the connector and resource-discovery tools exposed by Doku. If a value cannot be resolved safely, leave the checkpoint open and explain the blocker.

Evidence

Evidence records what you inspected or produced while doing the work. Submit it against the Claim whose statement it supports. A completed Task without the required Claim Evidence is not a completed Outcome.

Blocked work

If you are blocked:

record the blocker in evidence when useful;
leave blocked Tasks incomplete;
do not invent missing connector credentials, approvals, or user decisions;
follow the owning Doku or human checkpoint, then re-enter with the latest Work packet.

Recover after interruption or Handoff

If the agent is interrupted, use the latest Work packet and call tools.doku.playbooks.runs.continue({ executionHandle }). A Run Work mutation may return a concrete Handoff inline; wait for that private owner and do not poll generic Handoff, approval, or Agent Question APIs for Run Work. A direct member answers in focused UI; after that, the continue-only runs.continue boundary validates and materializes the answer once, consumes the bound Work Item, and returns resolved recovery with the latest Packet—it does not restore or reissue that consumed Work Item. An identical immediate continue replays the stored resolved result while the Packet is unchanged. The originating agent may relay chat only through submitHumanAnswers, which atomically materializes accepted or downgraded values and returns authoritative packet/recovery exactly once. Changed payloads and stale or closed handles require a fresh packet.

Takeover is the only ownership transition. When Doku says takeover is required, use its takeover operation and the fresh execution handle it returns; never reuse an old execution or Work Item handle. Safety-paused, failed, and cancelled states are authoritative blockers and must not be bypassed.

Every protected MCP call is independently authenticated for the exact Workspace resource. Doku does not create transport continuation state or expose a generic interaction status/resume API. The private Agent Question Owner does not replace the Run Work Handoff returned by a Human Resolution request: a direct member answer recovers with runs.continue, while an allowed agent relay uses submitHumanAnswers and its packet/recovery, with no extra retry unless that result requires re-entry. Relay rejection/block leaves the request waiting for direct UI; owner rejection, cancellation, and expiry close it and never become a successful Variable value.

Safety

Never bypass Doku runtime state. Do not mark work complete unless the required task work and evidence exist. If Doku rejects completion, treat the feedback as the next task list.

On this page