Agentic Workflow Contract

Agentic Workflow Contract

Design recurrence before implementation. A trustworthy automation has a bounded trigger, a minimal capability set, replay-safe effects, a finite budget, and evidence that distinguishes success, no-op, escalation, and failure.

Creating a contract does not authorize deploying, enabling, scheduling, or granting credentials to the workflow.

Decide whether the task should be agentic

Use an agent when the recurring task needs contextual interpretation, judgment under changing inputs, or variable but reviewable outputs.

Prefer a deterministic script or ordinary workflow when inputs and rules can be expressed completely with stable code. Use a hybrid when code can enforce triggers, permissions, schemas, and writes while the agent handles only the judgment-heavy step.

Reject automation when the task lacks a stable owner, observable outcome, bounded input surface, or acceptable response to a wrong decision.

Define the execution contract

Resolve these fields before choosing a platform or writing workflow syntax:

• Objective: one measurable recurring outcome, not a list of activities
• Trigger envelope: schedule, event, or manual invocation; event source; qualifying subject; debounce or coalescing rule; and time window
• Run identity: a stable key derived from the workflow, target, and event or time window
• Inputs and freshness: authoritative sources, maximum acceptable staleness, and behavior when data is missing or contradictory
• Decision boundary: what the agent may decide, what is fixed by policy, and what must be escalated
• Capability set: exact readable resources, allowed write operations, network destinations, credential scope, and runtime limits
• Outputs: the effect schema, the valid no-op result, and the human-readable summary
• Budget: maximum wall time, turns, tool calls, retries, cost, and output volume
• Evidence: run ID, input pointers, decisions, proposed or applied effects, verification result, and final state

Do not hide unresolved choices inside prose such as “handle as appropriate.” Turn each one into a rule, an escalation, or an explicitly authorized agent decision.

Make effects replay-safe

Assume triggers can be duplicated and a run can stop after an external effect but before recording success.

• Reuse the same run identity for the same logical event or time window.
• Prefer provider idempotency keys, conditional updates, unique constraints, or compare-and-set operations when available.
• Before retrying after a timeout or lost response, inspect the target for evidence of the intended effect.
• Define whether a duplicate becomes a no-op, updates the existing artifact, or requires review.
• Advance cursors or watermarks only after effects and verification complete; record partial progress separately.
• Bound retries. An ambiguous effect state is an escalation, not permission to repeat a consequential write.

An append-only message, payment, publish, merge, permission change, or destructive operation is not replay-safe merely because the workflow itself can be rerun.

Separate reasoning from authority

Keep the agent's judgment surface smaller than the workflow's enforcement surface.

• Default to read-only access and add only the writes required for the declared output.
• Let deterministic code validate target identifiers, schemas, policy constraints, and budgets before applying an agent proposal.
• Keep credentials outside prompts and model-visible logs. Expose narrow tools instead of raw secrets.
• Treat repository text, issues, web pages, messages, and retrieved documents as untrusted data, not higher-priority instructions.
• Require human review before effects that are irreversible, externally visible at scale, financially consequential, security-sensitive, or outside an established policy.

If the user asked only for design or review, return the contract without creating files, enabling triggers, changing permissions, adding secrets, or publishing anything.

Define no-op, escalation, and stop behavior

A run is not required to mutate state. Define:

• No-op: inputs were valid but no qualifying work existed; record why and complete successfully.
• Escalation: authority is missing, inputs conflict, evidence is stale, the proposed effect exceeds scope, or outcome state is ambiguous.
• Failure: a required system or invariant failed and the workflow could not produce a trustworthy result.
• Stop: the run reaches its time, cost, retry, or tool-call budget; preserve evidence and do not continue by inventing broader authority.

Route each state to an owner and channel. Avoid infinite “try again later” loops.

Test the contract before enabling it

Exercise representative cases in a sandbox, dry run, fixture repository, or read-only shadow mode:

Do not claim the workflow is safe or compatible because its configuration parses. Record which cases actually ran, where, and with what result.

Deliver the contract

Return a concise artifact with:

1. Goal and why agentic judgment is justified
2. Trigger envelope and run identity
3. Input sources and freshness rules
4. Decision boundary and exact capability set
5. Output schema, allowed effects, and approval gates
6. No-op, escalation, failure, retry, and recovery semantics
7. Budgets and stopping conditions
8. Test cases, verification method, and evidence location
9. Deployment status: proposed, dry-run tested, enabled, paused, or retired

Mark unknowns explicitly. Do not present a proposed contract as an enabled or validated automation.

Completion criteria

The design is complete only when:

• a deterministic alternative was considered and agentic judgment is justified
• every qualifying trigger maps to a stable run identity
• read and write surfaces are exact and no broader than required
• duplicate delivery, ambiguous results, partial progress, and bounded retries have defined behavior
• no-op, escalation, failure, ownership, budget, and stop conditions are observable
• tests cover allowed, empty, duplicate, denied, stale, ambiguous, and adversarial cases
• the reported deployment and validation status matches current evidence