Workflow Intent
Workflow intent lets a caller declare a multi-call AI workflow before it runs. Keel records the declaration, evaluates it against the project’s controls, and enforces the declared limits as governed requests arrive.
This extends Keel’s existing permit model from one request to a bounded workflow:
- Decide what your AI can do. Verify the recorded decision and workflow evidence after.
- Block before bill.
- Record workflow declarations as tamper-evident governance chain events.
Keel does not infer a workflow from a single request. The caller or orchestrator declares the workflow shape, expected volume, enforcement ceiling and optional budget envelope. Keel evaluates that declared intent and records the decision and supported lifecycle evidence it observes.
What is a workflow?
A workflow is one declared run of a multi-call AI process. Examples include a batch invoice review, a support-ticket triage run, a document extraction job, or an agent task that may fan out into many model calls.
A workflow declaration is scoped to one Keel project and one caller-supplied workflow_id. The workflow_id is the handle that SDKs and direct API callers attach to subsequent governed requests.
Workflow intent is not:
- orchestration telemetry from inside an agent framework
- a template for recurring jobs
- a replacement for budget envelopes
- a prediction by Keel about how many calls the workflow will make
The declaration is caller-provided. If projected cost is returned, the projection is calculated from the declared values and records its methodology.
When to declare
Declare a workflow before the first governed request in that run. Declare when the caller knows the work has a coherent boundary and should be enforced as a unit.
Use workflow intent when:
- the work can produce more than one governed AI call
- the operator has an expected call count or a maximum call count
- exceeding the declared maximum should block later calls
- expected-versus-actual drift should be recorded for audit and review
Do not use workflow intent for a single standalone request unless you need the workflow audit surface. Use Permits, Execute, or Proxy Execution directly for ordinary one-call flows.
Lifecycle
Workflow intent has three caller-visible lifecycle operations.
| Step | Endpoint | What happens |
|---|---|---|
| Declare | POST /v1/workflows | Creates or replays a declaration for a caller-supplied workflow_id. The declaration must include expected_calls, max_calls, or both. |
| Amend | POST /v1/workflows/{workflow_id}/amend | Appends a signed amendment to the declaration. The original declaration remains part of the evidence record. |
| Complete | POST /v1/workflows/{workflow_id}/complete | Closes the workflow, reconciles actual calls, and records completion. |
Workflow status describes lifecycle only:
| Status | Meaning |
|---|---|
active | The workflow can accept governed requests, subject to max_calls. |
completed | The caller explicitly closed the workflow. |
expired | Maintenance has recorded lifecycle expiry after the declared duration. The existing 15-minute sweep expires at most 100 due workflows per run, so expiry may lag the declared time. Duration is advisory, not an exact dispatch deadline; explicitly complete workflows you close. |
rejected | The declaration was rejected before any workflow calls ran. |
Cap exhaustion is not a lifecycle status. A workflow that has reached max_calls remains active, but further governed requests are denied with workflow_intent.max_calls_exceeded until the caller amends the cap or completes the workflow.
Drift detection
expected_calls is a planning baseline. max_calls is the enforcement ceiling.
If actual call count exceeds expected_calls, Keel records drift with the chain event workflow_intent.drift_detected. This is informational and does not deny the request by itself.
If actual call count reaches max_calls, Keel denies later workflow requests before provider dispatch with workflow_intent.max_calls_exceeded.
Drift events are emitted at threshold transitions, not on every drifted call. If an amendment raises expected_calls, the workflow can later cross that new threshold and emit drift again.
Evidence model
Workflow declarations, amendments, max-call denials, completion, and drift transitions are recorded as chain events in the project’s tamper-evident governance chain. External checkpoints and their timestamp receipts cover chain events only up to the last published checkpoint, and the checkpoint artifact is visible on Production and Enterprise.
For per-request decisions, each permit can carry workflow state observed at decision time: workflow id, declaration version, effective intent hash, actual calls at decision, and the expected/max thresholds used for that decision.
Pages in this section
- Quickstart — minimal declare, run, complete flow.
- API Reference —
/v1/workflowsendpoint contracts. - Reason Codes — workflow-specific reason code table.
- Chain Events — event types and webhook behavior.
- SDK Examples — Python, JavaScript, and Go examples.
- Plan Availability — workflow intent on every plan.
- Header Convention —
X-Keel-Workflow-Idfor direct API users.