Agent Guide

The Agent Guide is the one guidance document for an employer job. Every authorized agent that manages the job through the OpenTrain CLI, MCP server, SDK, or API receives the same guide, and every employer team member can read and shape it from the job’s Agent Guide tab. It combines two things under one context revision:

• The canonical operating context. A read-only, typed projection of what OpenTrain already knows about the job: the objective and typed workflow gates, effective typed policies and prohibitions, recorded decisions and exceptions, open action claims, fresh attention signals, the job’s Work Catalog, and external coverage. This part is authoritative because it is generated from canonical records.
• The Playbook. Human-written guidance that your team publishes in versions. It carries the judgment that canonical records cannot: how to handle edge cases, what “good” looks like for this job, and where agents should slow down and ask.

Agents do not maintain competing local copies. They read the guide from OpenTrain, follow the exact changes it reports, and propose improvements that a human reviews.

​

Authority is explicit and ordered

Every Agent Guide states its precedence, highest authority first: When Playbook text disagrees with a typed record, the agent raises the disagreement to the responsible human instead of acting on the text. Typed records win.

​

The Playbook is versioned Markdown, not an editor file

Your team writes the Playbook in a rich-text editor inside the OpenTrain app. That editor document is private editor storage. No agent surface returns it. What agents receive is the published version: a bounded set of Markdown sections, each with

• a stable section id that survives edits and reorders;
• a content hash (SHA-256) over the exact canonical section text;
• the section level, heading, and Markdown body.

Each published version also records the exact delta against the version it supersedes: addedSectionIds, changedSectionIds, and removedSectionIds. Removed ids are tombstones. An agent that holds version 3 and learns that version 5 is current can fetch the exact delta from 3 to 5, refresh only the added and changed sections, and drop the removed ones. It never re-reads the whole document to stay current. Versions are immutable and linear. Publishing never edits a version in place; it creates the next one. Limits that agents can rely on: at most 64 sections per version, at most 12,000 characters of Markdown per section, version history pages of up to 200 entries, and proposal listings of up to 200 entries.

​

Humans publish, agents propose

Publishing a Playbook version is a human job-manager act. The organization owner, or a team member with access to the job, publishes from the Agent Guide tab or through the API under a human token. An agent account cannot publish, and an agent acting under a human’s token is recorded by its agentLabel on the version. Agents contribute through proposals. A proposal carries RECOMMENDED authority: it is never enforced and no projection or policy resolver reads it. Three kinds exist: Rules that keep proposals honest:

• basePlaybookVersion must equal the current published head, so a proposal is always written against what humans actually published.
• A dedupeKey deduplicates concurrent submissions. A live open proposal under the same key is returned as DEDUPLICATED instead of creating a duplicate.
• A proposal can expire after a bounded time to live between one hour and 90 days.
• Accepting a SECTION_UPSERT or SECTION_REMOVE is the human court and must name the published version that landed it. OpenTrain verifies that the landed section’s content hash equals the proposed hash exactly. A human can also accept open proposals as part of a publication; the same exact-hash check runs before anything is written.
• Declining is the assigned job court. Withdrawing is the proposer only.

​

Synchronization is automatic

The Agent Guide rides the same automatic sync envelope as the rest of Shared Job Context. The behavior an agent can rely on:

1. Bootstrap directs one read. When a session starts or resumes, sync.nextOperations ends with job_operations.agent_guide.get. The agent reads the composite guide once. It never reads it again as a second bootstrap.
2. Deltas are conditional. Whenever the published Playbook head moves past the version the agent could have held at its last acknowledged revision, the next covered response carries recommendation.agent_guide_changed. It names the exact delta read, fromVersion to toVersion, so the agent fetches only what changed. Unchanged guidance is silence, never noise.
3. Nothing published yet is taught, not hidden. While no Playbook exists, a new session receives recommendation.agent_guide_playbook_absent: read the guide once, then propose sections; humans publish.
4. Acknowledge only what was delivered. An agent acknowledges a context revision it actually received. The delivery token can never acknowledge undelivered pages; they replay on the next call. Every agent session’s last delivered and acknowledged revisions are visible to your team in the Activity node.

The canonical operating context already appears in every context read as a digest (its version and checksum). The Agent Guide read adds the Playbook and the open-proposal count under one checksum.

​

Client-instance persistence

The official clients keep the private sync state that makes this automatic:

• The CLI persists it only when the runtime supplies a stable agent identity through PASEO_AGENT_ID or OPENTRAIN_AGENT_INSTANCE. Without one, every command is deliberately ephemeral: it re-bootstraps, is directed to the guide read again, and receives the advisory recommendation.establish_durable_agent_session. Never reuse one instance value across concurrent agents; they would share a cursor.
• The MCP server keeps the state private to the authenticated connection.
• The SDK keeps it private to one OpenTrainClient instance.

Deleting local state is always safe. Canonical OpenTrain context remains the authority, and the next covered call bootstraps again.

​

What the rest of the guide tells an agent

The canonical part of the Agent Guide is where the other shared-context planes meet, so an agent sees them together:

• Attention and priorities. The top fresh attention signals with their claim state. Priority is a triage aid, not permission to act.
• Action claims and leases. Who owns which coordinated action and when the lease expires. Claim before work; respect an unexpired claim.
• Policies and exceptions. Effective typed policies, prohibitions, and recorded exceptions with attribution and supersession.
• Work Catalog. This job’s own work definitions, provisional work, and coordination mode. Work types are per-job catalog data that agents define and propose during real use, never a fixed platform list of grading or retraining task types. See Dynamic Work Catalog.
• Activity. Recent shared-context events and each agent session’s last sync, visible to the team in the app.

​

Job Instructions are a different document

The Agent Guide is operational guidance for agents and managers. Job Instructions remain the only canonical source of worker-facing instructions for AI trainers. Publishing a Playbook never changes what AI trainers see, and editing Instructions never changes the Agent Guide.

​

Where to go next