agentctl

agentctl is a deterministic, declarative control plane for policy-constrained agentic automation. A versioned YAML workflow is compiled into a deterministically ordered task graph; deterministic actions and bounded model agents execute under one policy, effect ledger, SQLite history, and audit model.

Rust is the only production implementation. Node.js is not required to build, test, install, or run it. The former TypeScript runtime remains solely as an archived compatibility reference.

Quickstart

The repository pins Rust 1.88, the minimum supported version.

cargo build --locked
cargo run -p agentctl-cli -- check examples/v1/hello.yaml
cargo run -p agentctl-cli -- plan examples/v1/hello.yaml
cargo run -p agentctl-cli -- run examples/v1/hello.yaml --db .agentctl/quickstart.db

The last command is credential-free and deterministic. Install from crates.io with:

cargo install --locked agentctl-cli

For local development, use cargo install --locked --path crates/agentctl-cli.

For a tool-using credential-free journey, copy examples/acceptance/mock-tool to a clean directory and run its workflow.yaml. The repository acceptance suite executes that exact journey outside the source tree.

Workflow

apiVersion: agentctl.dev/v1
kind: Workflow
metadata:
  name: hello
spec:
  actions:
    greeting:
      kind: builtin.assign
  tasks:
    - id: hello
      uses: action:greeting
      with:
        message: hello from agentctl

Use check for strict syntax, references, templates, policy, and provider-capability validation. Use plan for deterministic order and predictability, run --check --diff for a non-mutating preview, resume after interruption, replay to reconstruct recorded results without effects, retry to rerun failed boundaries of an identical terminal workflow, repair to reuse compatible successful task boundaries with a corrected workflow, and fork when a broader fresh execution is intentional.

Terminal retry and selective repair are planned before execution:

agentctl retry workflow.yaml SOURCE_RUN_ID --failed --plan
agentctl retry workflow.yaml SOURCE_RUN_ID --failed
agentctl repair repaired.workflow.yaml SOURCE_RUN_ID --from failed_task --plan
agentctl repair repaired.workflow.yaml SOURCE_RUN_ID --from failed_task
agentctl compensate SOURCE_RUN_ID --plan
agentctl compensate SOURCE_RUN_ID

See Retry a terminal workflow, Repair a failed workflow, and Compensate applied effects for compatibility, lineage, state reconstruction, and uncertain-effect handling. Use Structured role handoffs for bounded multi-role workflows without hidden conversation state. For retained pre-schema-5 history, use Legacy run upgrade. For ambiguous external outcomes, use Effect reconciliation. For confidential workflow history, use Sensitive-state encryption. For environment, mounted-file, and policy-gated process credentials, use Secret references. For bounded independent branches and working-memory conflict rules, use Deterministic parallel tasks. For bounded static task expansion and child-level recovery, use Matrix and foreach tasks. For typed branching and durable decisions, use Conditions and routers. For iterative work with a hard execution ceiling and iteration-level recovery, use Bounded loops. For typed reusable graphs with namespaced recovery boundaries, use Reusable sub-workflows. For bounded provider progress, JSONL output, and recorded stream replay, use Durable provider streaming. For schema-checked MCP reconnect and task-ID-based A2A continuation, use MCP support and A2A support. For deterministic dependency locking and publisher policy, use Packs. For reviewed local executables, use the bounded process extension protocol. For typed cross-run text, vector, and hybrid retrieval with explicit promotion, use State and memory. For durable run-wide request, token, tool, wall-time, process-output, artifact, graph-size, and optional monetary limits, use Resource and cost budgets.

Safety boundary

• Secrets are environment, mounted-file, or policy-gated process references, never inline values or CLI flags.
• Files, processes, providers, MCP servers, and A2A peers require explicit policy grants.
• Pack sources are locked by digest; optional Sigstore identity verification and explicit unsigned-process policy run before pack actions are loaded.
• Every non-pure operation is recorded before execution. A crash after an at-most-once effect starts is reported as uncertain and is never silently repeated.
• Model turns, output tokens, tool calls, retries, and time are bounded. Workflows can also set durable run-wide request, token, tool, wall-time, process-output, artifact, graph-size, and monetary ceilings.
• Shell stdout/stderr capture is bounded, concurrently drained, and terminated/reaped on output, timeout, or cancellation limits.
• Check mode predicts deterministic actions; it does not claim to predict models or remote systems.
• The process policy is an allowlist, not an operating-system sandbox.

Providers and protocols

CI uses the scripted fake provider. Native, mock-tested adapters cover OpenAI Responses, Azure OpenAI Responses, Anthropic Messages, and Google Gemini generateContent. MCP is pinned to 2025-11-25; A2A is pinned to 1.0. Live calls are always opt-in.

Repository map

• crates/agentctl-core: DSL, compiler, templates, policy, state, effects, provider/tool contracts
• crates/agentctl-runtime: scheduler, actions, agent loop, resume/replay/repair/fork
• crates/agentctl-store: versioned SQLite persistence
• crates/agentctl-providers: native HTTP provider adapters
• crates/agentctl-protocols: MCP and A2A clients
• crates/agentctl-observability: audit-safe OpenTelemetry bridge
• crates/agentctl-cli: production CLI
• xtask: generated artifacts and canonical verification

Start with Getting started, Product, Architecture, DSL, Operations, Container contract, Troubleshooting, Contributing, Limitations, Security, and the generated CLI reference. Run the release-readiness layers with:

cargo xtask verify
cargo xtask acceptance
cargo xtask acceptance-container
cargo xtask package

cargo xtask acceptance-live-openai is the explicit, credentialed live gate and is never part of normal CI. The production image uses /config, /workspace, /state, and /artifacts mounts, runs as non-root, and supports a read-only root filesystem.

Exit codes are stable: 0 success, 2 usage/validation, 3 policy or approval, 4 run failure, 5 persistence, 6 remote provider/protocol, and 130 cancellation. JSON output always uses the agentctl.dev/cli/v1 envelope and never includes ANSI color.

Licensed under Apache-2.0.