Skip to main content
Use shared job context when an agent needs to answer questions such as:
  • What should we do next?
  • Who is blocked, and why?
  • Which messages still need an employer response?
  • Which deterministic attention signals are highest priority?
  • Are any evaluators stale or incomplete?
  • Which action is another manager already handling?
  • What changed since this agent last checked?
  • Who is ready under the current workflow?
This guide describes the operating loop shared by the API, CLI, and MCP server. See Shared Job Context for the data model and provenance rules.

​
Before you start

You need:
  • an employer account or employer team membership;
  • access to the specific job;
  • jobs:read to inspect context; and
  • jobs:write for supported decisions, observations, actions, checkpoints, and handoffs.
The job also needs a valid workflow before anyone can be derived as ready. If the context reports a missing or invalid workflow, resolve that inconsistency before relying on readiness totals.
Shared Job Context is delivered by the matching app and agent-package release. Before using these examples against a deployment, confirm GET /api/public/v1/capabilities reports the job_operations family as available. The base shared-context family requires CLI/MCP 0.8.0+ or SDK 0.7.0+. The deterministic signals, typed policies, and generated operating guide used below require CLI/MCP 0.10.0+ or SDK 0.9.0+. Automatic cross-command synchronization, intents, proposals, and scoped overlays require CLI/MCP 0.11.0+ or SDK 0.10.0+. If npm latest is older, the release has not reached that package yet.

​
The operating loop

​
1. Resolve one exact job

Do not infer the target from a similar title alone. Resolve the job ID and confirm the acting token can access it. If an employer team member has organization access but not access to that job, OpenTrain denies the context request. Ask an authorized employer admin to update job or folder access rather than trying to broaden the token.

​
2. Read, then reconcile a writable session

Always begin with a normal context read. It returns the contextRevision required by the first sweep. The same coherent snapshot includes the current attention queue, evaluator health, effective-policy summary, and Job Operating Guide digest. The agent does not need separate full scans merely to discover candidate priorities. In a writable management session, sweep once at startup. This covers:
  • the agent is starting a new session;
  • an external provider may have changed asynchronously;
  • stale people or incomplete reconciliation;
  • a previous operation timed out before returning its receipt; or
  • the job has been idle long enough that freshness is uncertain.
A sweep consumes pending canonical events and reconciles bounded canonical drift on the server. The client does not maintain the platform event cursor. When a sweep returns hasMore: true, call it again with that response’s contextRevision. Continue until hasMore is false, then read the context again so triage uses the newly derived snapshot. A read-only session does not sweep. Save the returned context version as the precondition for the work you plan to do. With CLI/MCP 0.11.0 or SDK 0.10.0, later covered calls carry this session forward automatically. Inspect the additive sync and syncCoverage fields on each response. sync.conflicts, sync.recommendations, and sync.nextOperations can change what the agent should do next without another full-system scan. syncCoverage.coverage: none means that call did not refresh shared context; perform a covered context read before relying on it.

​
3. Triage before acting

Review these sections in order:
  1. Evaluator health, inconsistencies, and unknowns — stale or incomplete evidence can invalidate otherwise simple status conclusions.
  2. Job Operating Guide, objective, workflow, and effective policies — they define the current operating rules and what “next” and “ready” mean.
  3. Fresh priority signals and open blockers — treat them as an investigation queue, grouped by impact and dependency.
  4. Message response signals — treat them as prompts to inspect a conversation, not as message content.
  5. Actions and claims — avoid duplicating work already owned by another manager.
  6. Recent changes or delta — identify records that changed since your last checkpoint.
Do not collapse different gates into one count. “Assessment passed,” “identity complete,” “training complete,” and “production ready” answer different questions. An attention score does not prove a root cause or authorize a mutation. A repeated LMS failure may point to unclear instructions, a difficult question, an assignment problem, or a genuine knowledge gap. Claim the signal, inspect the canonical evidence, and record the verified outcome. Capability recommendations also help the agent discover existing OpenTrain workflows. For example, a confusing message may suggest an individualized LMS retraining plan. Treat that suggestion as a product-discovery prompt:
  1. inspect the conversation, current Instructions, training history, and relevant evidence;
  2. explain the verified misunderstanding;
  3. generate a no-write retraining outline or assignment plan; and
  4. ask the employer to approve it before creating content or assigning a Project To-do.
The recommendation does not prove that retraining is necessary and never authorizes a write by itself.

​
4. Claim the action

Claim coordinated work before performing it. Include the expected action or context version. When work begins from an attention signal, use the signal-claim operation. It atomically creates or reuses the linked action and acquires its lease. A signal is claimable only while its condition is active, its evaluation is fresh, and its effective triage is open or acknowledged. Stale, incomplete, live-snoozed, dismissed, and shadow-rule signals cannot be claimed. Acknowledge, snooze, and dismiss are triage operations; they do not claim ownership. If another owner has an unexpired claim:
  • choose different work;
  • wait for the current owner; or
  • coordinate outside the system and have the owner release it.
Do not steal an active claim because the task looks urgent. If a claim expired, refresh the context before claiming it again. If the work is spontaneous and has no shared action yet, declare an intent before starting it. Another matching intent returns the current owner instead of creating parallel work. Resolve the intent when it is complete, abandoned, or replaced by a canonical action. When a manager proposes a different workflow or policy, do not silently follow the competing local instruction. Show the current team policy, the alternative, and the conflict. Ask whether to continue under the current policy or submit a reviewable Job Operations proposal. Proposal review records agreement; it does not execute the proposed change.

​
5. Re-read the canonical source

Context helps an agent choose the right work, but the source record is the final pre-action check. For a message, re-read the latest authorized conversation and thread. Confirm that:
  • no employer teammate already answered;
  • a later AI trainer message did not reopen the question;
  • the requested requirement is still incomplete;
  • the conversation type still matches the relationship; and
  • the participant and conversation remain visible to the acting user.
For the guarded send, pass that exact latest message ID. Pass null only when the authorized conversation was actually observed empty. Use the exact synchronized managed-send operation (CLI manager messages send; MCP opentrain_send_managed_job_message), not the generic message tool. OpenTrain resolves the authorized Job Message or Proposal Message binding, validates the guarded state, and commits the message and shared-context advance atomically. It rejects the send if any reviewed state changed. For a Project To-do, assessment, contract, milestone, or training action, fetch that canonical record and confirm its current status and version.

​
6. Apply the action safely

For a consequential context-plane write:
  • send the expected context revision;
  • send the expected action version when changing an action;
  • use a stable idempotency key for one semantic operation; and
  • include evidence IDs instead of copying sensitive source content.
The underlying domain API remains the correct place to change a proposal, contract, message, Project To-do, milestone, or other canonical resource. Do not simulate the change by recording a context observation. Use a stable idempotency key for the managed message. It must be 8–128 characters using letters, numbers, ., _, :, or -. The operation requires both messages:write and messages:manage.

​
7. Verify before completion

After an operation succeeds, fetch the affected record again and confirm the intended state. Then:
  • complete the coordinated action with its result evidence;
  • release it if no work was performed or a different owner must continue;
  • acknowledge the newest processed context version; and
  • add a concise handoff when the next session needs more than the structured state already shows.
A timeout is not proof that the write failed. Refresh with the same idempotency key before creating a replacement action.

​
Handle version conflicts

A 409 stale-version response means another manager or event changed relevant state after your read. Do not overwrite it. Instead:
  1. fetch the latest context or delta;
  2. re-read the affected canonical records;
  3. inspect the other manager’s action result or claim;
  4. discard the plan if it is obsolete; and
  5. retry only if it remains correct.
The context version is a safety precondition, not a cursor that the client may increment locally.

​
Record durable judgment carefully

Record a decision when an authorized employer judgment must persist across sessions, such as an approved exception or manual assessment outcome. Record a typed policy when the change governs the workflow or agent behavior across the job. For MCP hosts that consume instruction resources, the generated Markdown guide is available at opentrain://jobs/{jobId}/operations/guide. It is a read-only projection of the same effective policies and context state; do not edit or treat it as a second authority. Use the structured guide tool when you need its exact context revision and checksum. When the current projection refers to prior judgment, list the durable decision history before acting. Use the decision and observation cursors to continue until the relevant history is complete; do not infer supersession from a truncated context summary. Include:
  • the exact subject and scope;
  • the decision type and operative value;
  • a concise rationale;
  • privacy-safe evidence references;
  • the effective and optional expiration time; and
  • the decision it supersedes, when applicable.
Use an observation for non-authoritative evidence. Do not use an observation to create a policy or override a mandatory gate. Do not edit a local shared prompt or free-form “agent memory” as the policy source. Supersede the active typed policy with the exact current decision ID, then read the new context and Job Operating Guide checksum before continuing. Choose an enforcement target that matches what the platform actually changes. A GUIDE policy with status APPLIED is published coordination guidance for managers and agents; it is not proof of runtime enforcement. For example, the training production gate can canonically switch between course completion and scored assessment review. A separate instruction to complete one production task and stop belongs in an attributed guide policy such as OPERATING_RULE.first-production-task-limit unless a canonical task limit exists.

​
End a session cleanly

Before the agent stops:
  • release claims it will not finish;
  • complete actions whose canonical results were verified;
  • acknowledge the last processed context version;
  • resolve or transfer spontaneous-work intents;
  • record unresolved blockers with their current owner; and
  • create a handoff only for continuation details that are not already structured in the context.
The next authorized agent should be able to start from the job context without receiving the previous chat transcript.

Shared Job Context

Understand provenance, readiness, versions, claims, and privacy boundaries.

Stay in sync

Combine job-scoped context with account updates and webhooks.

Project To-dos

Use the canonical assignment control plane for job requirements.

Errors, pagination, and limits

Handle conflict envelopes, paging, rate limits, and retries.