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. Prove what it did.
- Block before bill.
- Record workflow declarations as tamper-evident, externally anchored, independently witnessed evidence.
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 enforces that declared intent and records what happened.
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 | Keel closed the workflow after max_duration_seconds. |
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 workflow_intent.expected_calls_exceeded and 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. They are tamper-evident, externally anchored, and independently witnessed through Keel’s existing evidence infrastructure.
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 Gating — Production+ entitlement behavior.
- Header Convention —
X-Keel-Workflow-Idfor direct API users.