Control agent workflows without giving up control

agentctl compiles reviewed YAML into a deterministic task graph, bounds every model task, records effects before execution, and keeps recovery state in local SQLite.

Get started View on GitHub

Deterministic graphBounded model tasksExplicit effectsDurable local stateProvider-neutral core

What agentctl is

A control layer between reviewed intent and uncertain execution

Ordinary automation is predictable but cannot reason. Agent scripts can reason but often hide control flow, retries, authority, and recovery. agentctl gives deterministic orchestration the final say while a model handles only the tasks you assign to it.

Declare the whole run

Inputs, tasks, dependencies, agents, tools, policy, memory, and outputs live in strict versioned YAML.

Bound every uncertain part

Models receive explicit instructions, tools, token limits, turn limits, timeouts, and provider capabilities.

Recover from evidence

SQLite records tasks, effects, approvals, checkpoints, audit events, and trace correlation before recovery is needed.

How it works

Compile first. Execute within policy. Persist before guessing.

CheckReject invalid YAML, references, templates, policy, and capability mismatches.
PlanBuild a declaration-ordered DAG and classify what can be predicted.
RunExecute deterministic actions and bounded agents through explicit effect boundaries.
RecoverResume safe work, replay recorded truth, or fork only when fresh effects are intentional.

Verified workflow

A bounded repository check, not a free-running agent

This exact file is imported from examples/acceptance/mock-tool/workflow.yaml. The acceptance suite copies it to a clean directory and runs it without credentials.

Deterministic: The graph, assertion, and artifact write.
Bounded agent: Two turns, one read tool call, 32 output tokens, five seconds.
Persisted: Run state, effects, tool correlation, checkpoints, audit, and trace IDs.
Verified: An assertion rejects any verdict other than the expected fixture marker.

Run the repository audit example

apiVersion: agentctl.dev/v1
kind: Workflow
metadata:
  name: acceptance-mock-tool
spec:
  inputs:
    reportPath: artifacts/mock-report.txt
  outputs:
    verdict: "${{ tasks.inspect.output.text }}"
    artifact: "${{ inputs.reportPath }}"
  providers:
    fake:
      kind: fake
  policy:
    workspaceRoot: .
    writableRoots: [artifacts]
    approval: never
  tools:
    read_fixture:
      kind: builtin.workspace.read
      description: Read a UTF-8 file inside the authorized workspace.
      inputSchema:
        type: object
        properties:
          path: { type: string }
        required: [path]
        additionalProperties: false
      outputSchema:
        type: object
        properties:
          path: { type: string }
          content: { type: string }
          bytes: { type: integer }
          sha256: { type: string }
        required: [path, content, bytes, sha256]
        additionalProperties: false
      capability: filesystem.read
      risk: low
      effectClass: observe
      idempotency: idempotent
      retrySafe: true
      timeoutSeconds: 5
      approval: never
  agents:
    inspector:
      provider: fake
      model: scripted
      instructions: Read the fixture and report its marker.
      tools: [read_fixture]
      maxTurns: 2
      maxToolCalls: 1
      maxOutputTokens: 32
      timeoutSeconds: 5
      providerOptions:
        toolInput: { path: fixture/service.txt }
        finalText: AGENTCTL_MOCK_FIXTURE_VERIFIED
  actions:
    assert:
      kind: builtin.assert
    write:
      kind: builtin.write
  tasks:
    - id: inspect
      uses: agent:inspector
      with:
        prompt: Use read_fixture before answering.
    - id: verify
      uses: action:assert
      needs: [inspect]
      with:
        that: "${{ tasks.inspect.output.text == 'AGENTCTL_MOCK_FIXTURE_VERIFIED' }}"
        message: the mock provider did not complete its tool continuation
    - id: report
      uses: action:write
      needs: [inspect, verify]
      with:
        path: "${{ inputs.reportPath }}"
        content: "${{ tasks.inspect.output.text }}"

Trust and control

The model proposes. The runtime decides what can happen.

Policy outside prompts

Filesystem, process, environment, network, provider, tool, and approval rules are runtime decisions.

Effect identity

Non-pure requests are recorded before dispatch with stable identity, risk, idempotency, and confirmation.

Durable approvals

Non-interactive runs pause and exit 3. An operator resolves the exact request and resumes the same run.

Native providers

OpenAI, Azure OpenAI, Anthropic, and Gemini map native APIs behind a neutral core. Capabilities still differ.

Local-first state

One process and SQLite keep the correctness boundary inspectable without a hosted control plane.

Honest uncertainty

A crash after dispatch can leave an uncertain effect. agentctl stops instead of silently repeating it.

Use cases

Add bounded reasoning where deterministic automation needs judgment

Repository auditRead reviewed files and verify the report.Release readinessGate model analysis behind deterministic evidence.Scheduled reviewPersist a bounded run invoked by cron or Kubernetes.CI quality gateReturn stable JSON and process status to a pipeline.Approval-gated actionPause a proposed mutation for operator review.Selective repairReuse compatible upstream results and execute a corrected suffix.Offline replayReconstruct a terminal run without network or credentials.

One runtime, three invocation paths

Run it where your work already lives

Local

Review before execution

Use check, plan, check mode, run, inspect, and resume from a normal terminal.

Operate locally

Scheduled

Bring your own clock

Cron, systemd, or Kubernetes owns triggers and overlap. agentctl owns one durable bounded run.

Schedule runs

CI and containers

Use a generic OCI step

Mount config, workspace, state, and artifacts. Consume one versioned JSON result and exit code.

Run the container

Durable execution

What happens if a run stops after it already did something?

agentctl records an effect request before execution. A confirmed result can be reused on resume. A started result without confirmation becomes uncertain, which stops automatic recovery until an operator reconciles the external system.

Understand resume and recorded replay

requestedstartedconfirmeduncertain

Choose the right boundary

agentctl complements scripts, CI, and workflow systems

Approach	Best at	Where agentctl differs
Shell script plus model API	Small direct integrations	Adds strict graph compilation, external policy, effects, approvals, and durable recovery.
Chat-agent framework	Interactive conversations and dynamic handoffs	Keeps reviewed workflow control flow authoritative instead of model-owned.
General workflow engine	Broad scheduling and distributed execution	Focuses on one local durable run with bounded model and tool semantics.
Ansible	Configuration management and idempotent convergence	Uses agent tasks and an effect ledger, but is not a configuration-management replacement.
CI/CD pipeline	Runners, triggers, secrets, and artifact retention	Runs inside CI as one step; CI still owns the surrounding job lifecycle.

Current maturity

Exact-commit evidence across local and hosted gates

The workflow API is agentctl.dev/v1. Deterministic composition, durable recovery, local persistence, native Linux arm64 containers, and bounded GPT-5.6 journeys have executable evidence. The pinned 0.3 release source also passed hosted Linux x64, macOS arm64, Windows x64, container, security, package, SBOM, and release-preparation gates. Other native providers and protocols have mock coverage at documented levels.

Stable workflow API v1; CLI and crates remain pre-1.0
No exactly-once or in-process sandbox claim
No distributed or cross-run scheduler claim
No claim of live validation across every provider

Start with evidence

Run a credential-free workflow in a clean directory

Validate the YAML, inspect the deterministic plan, execute it, then read the durable run record.

Get started