Agent execution workflow
Discover live schemas, propose exact changes, follow Approval, and verify durable results.
Start here when operating Jetrepo from an external agent. Management MCP is /agent/mcp on the installation’s Management origin. It exposes exactly inspect, propose, execute, and control_operation; domain actions are versioned Operation Definitions returned by inspection.
These docs explain the workflow. The connected installation’s tool schemas, Operation Definitions, IDs, permissions, and state are authoritative for each call. Never invent a tool, definition version, permission, identifier, or field configuration from an example.
1. Establish identity and scope
Use OAuth or delegated Agent Auth for authoring. Organization-owned Agent keys are limited to allowlisted operational permissions and cannot create or delete model or content resources. Model-provider credentials stay in the agent host.
Begin with an explicit inspection kind:
{ "kind": "ORGANIZATIONS" }Select the user’s intended Organization. Inspect BACKENDS for an existing Backend, then ENVIRONMENTS with that stable Backend ID. Match names to returned IDs; do not create duplicates because an earlier conversation omitted an ID.
Normal calls carry backend and environment together. Organization bootstrap uses Organization scope without either field. Stable Backend, logical Environment, and physical generation IDs are different values; use each where the returned schema requires it.
2. Bootstrap only if needed
For an empty Organization where canCreateBackend is true, inspect OPERATION_DEFINITIONS with organization set to its ID. Discover backend.create@1 and its live input schema.
An Organization Change Set has version: 1, base { organizationId, perspective: "ORGANIZATION" }, and a single backend.create operation with a localRef. It has no fabricated manifest, Backend, or Environment. Propose it without top-level resource scope, then execute the returned Candidate ID/digest with an idempotency key.
Wait for the Operation and use the returned stable Backend, main Environment, and initial Draft manifest for subsequent work. Bootstrap requires backend.create and operation.execute; it is autonomous and does not publish Content.
3. Discover the exact change contract
Inspect OPERATION_DEFINITIONS with the selected Backend and Environment. Follow cursors until you have the needed definitions; the default page size is 50 and maximum is 100. Inspect SETTINGS with backend.read for the scope and current Draft manifest ID/hash.
Each definition includes inputSchema for its operation’s arguments and outputSchema for the domain result recorded after execution. These are separate from the enclosing Candidate and Operation responses. List responses use items and nextCursor; copy that cursor into the same scoped inspection until it is null.
Read the Change Set schema through the advertised resource templates when supported. Use the returned definition schema for required values, defaults, identity classes, permissions, policy, quotas, and recovery. Models, Content, Assets, locales, Taxonomy, Releases, webhooks, and Preview each have their own definitions.
Existing-resource selectors require resourceKind, resourceId, and expectedRevisionId. Creation declares localRef; dependencies use a local selector or { "$localRef": "name" }. Do not submit internal $localId values.
A Data Type and its Field Set have different IDs. Use the actual Field Set ID when creating Fields. If later work needs an ID produced by an earlier action, read the completed output instead of guessing an output-property reference.
4. Propose and inspect
Call propose with the same scope and a version-1 Change Set bound to the exact base. Proposing persists an immutable Candidate and performs no managed-content mutation.
The response contains row, document, and uri. Use row.id as candidateId and copy document.digest unchanged into execute.digest. Proposing again can create another Candidate, so inspect existing work after a lost response before submitting another proposal. The default Candidate lifetime is 900 seconds; expiresInSeconds accepts 60–3600.
Read validation, proposed values, affected resources, scope, requester, policy, expiry, and digest. Resolve failures by inspecting the current schema/state and proposing a corrected Candidate. Do not execute an invalid or expired proposal.
Use retained review evidence when available. Missing historical names or before-values are unknown; never substitute current mutable values and present them as historical facts.
5. Execute once and follow the Operation
Call execute with the same Backend/Environment, exact candidateId, exact digest, and a caller-chosen idempotencyKey. Organization bootstrap omits Backend/Environment. Reuse the same key after a transport failure for that same execution; a different Candidate requires a different key.
The response starts or resumes durable execution. It is not proof of completion. Inspect the returned Operation or call control_operation with action: "STATUS" and its operationId. Preserve scope and follow polling hints when supplied.
| State | Agent action |
|---|---|
AWAITING_APPROVAL |
Return Candidate/review and Operation links. Wait for an authorized human to decide in Jetrepo. |
QUEUED, RUNNING, CANCELLING, RECOVERING |
Observe the existing Operation; do not submit a duplicate Change Set. |
SUCCEEDED, RECOVERED |
Read the recorded outcome and resulting state before reporting success. |
FAILED |
Inspect failures and recovery evidence. Retry only when explicitly retryable and within the user’s authorized work. |
CANCELLED, EXPIRED, SUPERSEDED |
Report the state and inspect the reason before proposing replacement work. |
APPROVE and REJECT require a human principal, operation.approve, and the exact approver permission. Chat consent or a client’s tool confirmation does not substitute for Approval. Distinct policy excludes requester and delegating human from approving.
6. Verify and hand back context
Inspect OPERATION with its ID. limit and cursor paginate item outcomes; outcomeSummary describes the complete Operation. Do not report every item successful from the first page or collapse repeated steps because their names match.
Return readable names, resulting state, failures, and exact Candidate/Operation links supplied by the client or installation. Keep IDs for follow-up. A Draft result is not Published; publication needs an explicit request and policy check.
After a lost response, inspect existing work before retrying. When base, revision, policy, or authority changes, read current state and propose again. Do not overwrite drift or bypass guards through direct database/API writes.
7. Choose the next surface
- Publication: discover the lifecycle definition, follow the user’s requested scope, and use the same Candidate/Approval/Operation sequence.
- Frontend: inspect
DELIVERY, read exact OpenAPI bytes/hash, and follow contract generation. REST relationships remain IDs and Components remain inline. - Agent retrieval: use Context MCP with a Delivery key or Preview Bearer. Management credentials do not authorize Delivery.
- Rendered Candidate: use Preview handoffs, a Verified target, and the same requesting credential for the one-time claim.
- Runtime key: request the governed Delivery-key flow. Human Approval is mandatory; claim and store the secret once with the requesting credential. Keep it out of code, logs, and summaries.
- Publication recovery: use eligible rollback controls. Rollback creates a new Candidate over current Published history; it is not a generic Draft undo.
Documentation for agents
Read /llms.txt for the prioritized index. Append .md to a guide URL for plain Markdown; the home is /index.md. /llms-full.txt contains the complete public corpus. These static reading aids are not a Management endpoint or credentials.