Agentic Flows¶

A deterministic, contract-first execution and replay framework — strict invariants, reproducible runs, and traceable outputs. Build audit-ready agent workflows with stable artifacts and replayable traces.

At a glance: deterministic execution • invariant enforcement • replayable traces • CLI surface • API schema only • structured telemetry
Quality: coverage floors enforced per module, benchmark regression gate active, docs linted and built in CI, no telemetry.

Why Agentic Flows?¶

Most agent tooling optimizes for velocity. Agentic Flows prioritizes repeatability, traceability, and audit-ready execution:

Determinism first for reliable experiments and CI validation.
Invariant enforcement with fail-fast execution semantics.
Replayable traces for deterministic verification.
Clear boundaries between execution, retrieval, and verification.

Try It in 20 Seconds¶

pipx install agentic-flows  # Or: pip install agentic-flows
agentic-flows --help
agentic-flows plan path/to/manifest.json

Key Features¶

Deterministic execution — reproducible runs with explicit budgets.
Contract-first design — schema and invariants enforced at boundaries.
Replayable traces — audit-grade execution records.
Dual surface — CLI and API share the same contracts.
Structured telemetry — correlation IDs and traceable events.

Installation¶

Requires Python 3.11+.

# Isolated install (recommended)
pipx install agentic-flows

# Standard
pip install agentic-flows

Upgrade: pipx upgrade agentic-flows or pip install --upgrade agentic-flows.

Quick Start¶

# Discover commands/flags
agentic-flows --help

# Plan a flow from a manifest
agentic-flows plan path/to/manifest.json

# Run a deterministic execution
agentic-flows run path/to/manifest.json --db-path /tmp/execution.duckdb

Artifacts & Reproducibility¶

Artifacts are immutable and hash-addressed. Replaying a run verifies hashes before returning outputs.

agentic-flows diff run <run_a> <run_b> --tenant-id <tenant> --db-path /tmp/execution.duckdb

Docs: Execution Lifecycle · Invariants

API Surface¶

The HTTP API exposes the same contracts as the CLI.

Docs: API Overview · Schema

Built-in Commands¶

Command	Description	Example
`plan`	Resolve a manifest into a plan	`agentic-flows plan manifest.json`
`run`	Execute a flow	`agentic-flows run manifest.json --db-path /tmp/flow.duckdb`
`dry-run`	Trace execution without calling tools	`agentic-flows dry-run manifest.json --db-path /tmp/flow.duckdb`
`inspect run`	Inspect a stored run	`agentic-flows inspect run <run_id> --tenant-id <tenant> --db-path /tmp/flow.duckdb`
`diff run`	Compare two runs	`agentic-flows diff run <a> <b> --tenant-id <tenant> --db-path /tmp/flow.duckdb`

Full surface: CLI Surface

Tests & Quality¶

Coverage floors: enforced per module in CI.
Benchmarks: regression gate on critical path.
Docs: linted and built in CI.

Quick commands:

make test
make lint
make quality

Artifacts: Generated in CI; see GitHub Actions for logs and reports.

Project Tree¶

api/            # OpenAPI schemas
config/         # Lint/type/security configs
docs/           # MkDocs site
makefiles/      # Task modules (docs, test, lint, etc.)
scripts/        # Helper scripts
src/agentic_flows/  # Runtime + CLI implementation
tests/          # unit / regression / e2e

Docs & Resources¶

Overview: Why agentic-flows exists · Mental model · Minimal run · Relationship to agentic-proteins · Audience
Concepts: Concepts index · Determinism · Failures
Execution: Failure paths
Site: https://bijux.github.io/agentic-flows/
Changelog: https://github.com/bijux/agentic-flows/blob/main/CHANGELOG.md
Repository: https://github.com/bijux/agentic-flows
Issues: https://github.com/bijux/agentic-flows/issues
Security (private reports): https://github.com/bijux/agentic-flows/security/advisories/new
Artifacts: https://bijux.github.io/agentic-flows/artifacts/

Contributing¶

Welcome. See CONTRIBUTING.md for setup and test guidance.