agentloom 0.5.0

Deterministic LLM workflow orchestration with native observability, resilience, and cost control.

Table of Contents

• Documentation
• Why AgentLoom?
• Quick Start
• Architecture
• Providers
• Workflow Definition (YAML)
• Python DSL
• Graph API
• Observability
• Deploy
• Checkpointing
• Testing & Replay
• Why not autonomous agents?
• Development
• Contributing
• License

Why AgentLoom?

Existing frameworks (LangGraph, CrewAI, AutoGen) treat observability and resilience as afterthoughts. AgentLoom is built from the ground up for production: circuit breakers, rate limiting, cost tracking, and OpenTelemetry traces are part of the core design — not plugins.

Quick Start

# Install
pip install agentloom

# Install with all extras (OTel + Prometheus observability, graph export)
pip install "agentloom[all]"

# Run a workflow on OpenAI
export OPENAI_API_KEY=sk-...
agentloom run examples/01_simple_qa.yaml --provider openai --model gpt-4o-mini

# Or with Ollama (free, local), the example's own provider
agentloom run examples/01_simple_qa.yaml

# Validate a workflow
agentloom validate examples/03_router_workflow.yaml

# Visualize the DAG
agentloom visualize examples/03_router_workflow.yaml

# Run with checkpointing (resume on failure)
agentloom run examples/01_simple_qa.yaml --checkpoint
agentloom runs            # list checkpointed runs
agentloom resume <run_id> # resume from checkpoint

Architecture

+-----------------------------------------------------+
|                   CLI / Python API                  |
+-----------------------------------------------------+
|                   Workflow Engine                   |
|  +-----------+  +-----------+  +---------------+    |
|  |DAG Parser |  | Scheduler |  | State Manager |    |
|  |& Validator|  |  (anyio)  |  |  (dict+lock)  |    |
|  +-----------+  +-----------+  +---------------+    |
+-----------------------------------------------------+
|                   Step Executors                    |
|  +--------+ +---------+ +------+ +------------+     |
|  |LLM Call| |Tool Exec| |Router| | Subworkflow|     |
|  +--------+ +---------+ +------+ +------------+     |
|  +---------------+ +-------+ +-------+              |
|  | Approval Gate | | Embed | | Agent |              |
|  +---------------+ +-------+ +-------+              |
+-----------------------------------------------------+
|                  Provider Gateway                   |
|  +-----------------------------------------------+  |
|  | OpenAI | Anthropic | Google | Ollama          |  |
|  | + Fallback | Circuit Breaker | Rate Limiter   |  |
|  +-----------------------------------------------+  |
+-----------------------------------------------------+
|              Observability (optional)               |
|  +------------+  +----------+  +----------+         |
|  | OTel Traces|  |Prometheus|  | JSON Logs|         |
|  +------------+  +----------+  +----------+         |
+-----------------------------------------------------+

Providers

Four providers are included out of the box. The gateway routes requests based on model name and falls back automatically when a provider is unavailable.

# Switch provider in any workflow
config:
  provider: google
  model: gemini-2.5-flash

See the Architecture section for fallback, circuit breaker, and rate limiter details.

Workflow Definition (YAML)

name: classify-and-respond
config:
  provider: openai
  model: gpt-4o-mini
  budget_usd: 0.50

state:
  user_input: ""

steps:
  - id: classify
    type: llm_call
    system_prompt: "Classify as: question, complaint, or request."
    prompt: "Classify: {state.user_input}"
    output: classification

  - id: route
    type: router
    depends_on: [classify]
    conditions:
      - expression: "state.classification == 'question'"
        target: answer
    default: general_response

  - id: answer
    type: llm_call
    depends_on: [route]
    prompt: "Answer: {state.user_input}"
    output: response

  - id: general_response
    type: llm_call
    depends_on: [route]
    prompt: "Help with: {state.user_input}"
    output: response

Multi-modal Input

LLM call steps support image, PDF, and audio attachments. Sources can be URLs, local file paths, or inline base64. URL fetching includes SSRF protection and respects sandbox domain restrictions. See the Providers table for per-provider support.

steps:
  - id: analyze
    type: llm_call
    prompt: "Describe what you see in this image."
    attachments:
      - type: image
        source: "{state.image_url}"
    output: description

Streaming

Stream LLM responses token-by-token for real-time output. Enable at the workflow level, per-step, or via CLI flag.

config:
  stream: true    # workflow-level default

steps:
  - id: answer
    type: llm_call
    stream: true  # per-step override
    prompt: "Answer: {question}"

# CLI flag (overrides workflow config)
agentloom run workflow.yaml --stream

All providers support streaming (see Providers for protocol details). Token usage, cost, and time-to-first-token are tracked normally.

Python DSL

from agentloom.core.dsl import workflow

wf = (
    workflow("my-workflow", provider="ollama", model="phi4")
    .set_state(question="What is Python?")
    .add_llm_step("answer", prompt="Answer: {question}", output="answer")
    .build()
)

Graph API

Programmatic access to the workflow DAG for analysis, visualization, and test coverage.

from agentloom import WorkflowGraph
from agentloom.core.parser import WorkflowParser

workflow = WorkflowParser.from_yaml("examples/03_router_workflow.yaml")
graph = WorkflowGraph.from_workflow(workflow)

graph.roots            # entry-point step IDs
graph.leaves           # terminal step IDs
graph.critical_path()  # longest path (latency bottleneck)
graph.all_paths()      # every root-to-leaf path
graph.prime_paths()    # maximal simple paths for test coverage

# Export
graph.to_dot()       # Graphviz DOT
graph.to_mermaid()   # Mermaid flowchart
graph.to_pnml()      # Petri Net Markup Language
graph.to_dict()      # JSON-serializable dict

Optional NetworkX integration:

pip install agentloom[graph]

nx_graph = graph.to_networkx()  # networkx.DiGraph

Observability

With the [observability] extra, which the Docker image includes, every workflow step emits OpenTelemetry traces and Prometheus metrics. No external SaaS required — the full stack runs alongside your workloads.

# Start Prometheus + Grafana + Jaeger
cd deploy && docker compose up -d

# Access:
#   Grafana:    http://localhost:3000
#   Prometheus: http://localhost:9090
#   Jaeger:     http://localhost:16686

See Dashboard Documentation for panel descriptions, metrics reference, and troubleshooting.

Deploy

AgentLoom is designed to run anywhere — from a single Docker container on your laptop to a fully orchestrated Kubernetes cluster with GitOps and observability. Every deployment method is production-hardened with non-root containers, read-only filesystems, Pod Security Standards enforcement, and network policies.

The CLI processes a workflow and exits. There is no long-running server, no HTTP API, and no persistent connections. This makes Kubernetes Jobs (not Deployments) the correct primitive: finite execution, automatic retries, scheduled runs via CronJobs, and clean resource isolation per workflow.

Docker

The fastest way to run a workflow. The multi-stage Dockerfile produces a minimal image (~120MB) with a non-root user and read-only filesystem.

docker build -t agentloom .
docker run --rm -e OPENAI_API_KEY=sk-... \
  -v ./examples:/workflows:ro \
  agentloom run /workflows/01_simple_qa.yaml --provider openai --model gpt-4o-mini

Kubernetes (Kustomize)

Plain YAML manifests organized with Kustomize overlays. Three environments are provided, each with progressively stricter security and resource controls:

• dev: minimal resources, no NetworkPolicy, latest tag for fast iteration.
• staging: moderate resources, NetworkPolicy enabled, CI image tag.
• production: strict NetworkPolicy (no Ollama egress), activeDeadlineSeconds hard timeout, pinned image version.

kubectl apply -k deploy/k8s/overlays/dev
kubectl logs job/agentloom-workflow -n agentloom

Helm

The recommended method for teams that need parameterized deployments. The chart packages all Kubernetes resources with built-in input validation — deploying without a workflow definition fails at render time, not at runtime.

helm install agentloom deploy/helm/agentloom \
  -n agentloom --create-namespace \
  --set workflow.definition="$(cat examples/01_simple_qa.yaml)" \
  --set provider.existingSecret=my-secret

Supports Job and CronJob modes, configurable NetworkPolicies, ResourceQuotas, and optional namespace creation with PSS labels.

Terraform

Provisions a complete local development environment in one command: a kind cluster with agentloom, plus the full observability stack (OTel Collector, Prometheus, Grafana, Jaeger). Set enable_observability = false for a lightweight setup without metrics and traces.

cd deploy/terraform
cp terraform.tfvars.example terraform.tfvars
terraform init && terraform apply

After apply, Grafana is available at localhost:3000, Prometheus at localhost:9090, and Jaeger at localhost:16686 — all pre-configured with agentloom dashboards and datasources.

ArgoCD

GitOps deployment with automated sync, self-heal, and retry policies. ArgoCD watches the Helm chart in the repository and syncs changes automatically. The Application CRD handles Kubernetes Job immutability via Replace=true and ignoreDifferences on selectors.

kubectl apply -f deploy/argocd/application.yaml

See deploy/INFRASTRUCTURE.md for the full deployment guide, security hardening details, Helm chart reference, and CI/CD pipeline documentation.

Checkpointing

Persist workflow execution state so failed or interrupted runs can be resumed without re-executing completed steps.

# Enable checkpointing
agentloom run workflow.yaml --checkpoint

# List all runs
agentloom runs

# Resume a failed run (skips completed steps)
agentloom resume <run_id>

Checkpoints are stored as JSON files in .agentloom/checkpoints/ by default. The backend is pluggable — implement BaseCheckpointer to store checkpoints in Redis, S3, or any other backend. In Kubernetes, mount a PersistentVolumeClaim to share checkpoints across Jobs.

Human-in-the-loop

An approval_gate step pauses a checkpointed run until someone approves or rejects it, from the CLI or over HTTP through agentloom callback-server. An optional webhook notifies Slack, CI, or a dashboard when the gate pauses, and timeout_seconds with on_timeout settles a gate nobody decides in time.

- id: approve
  type: approval_gate
  depends_on: [draft]
  output: decision          # "approved" | "rejected"

agentloom run workflow.yaml --checkpoint
agentloom resume <run_id> --approve   # or --reject

Testing & Replay

Record real LLM responses once, replay them offline forever — reproducible tests, CI without API keys, statistical evaluation without paying per-run.

# Capture a real run to disk (flushes per call; crashes leave partial recordings)
agentloom run workflow.yaml --record recordings/run1.json

# Replay offline — no network, no key, no cost, byte-identical output
agentloom replay workflow.yaml --recording recordings/run1.json

Or configure the mock directly in YAML (provider: mock + responses_file) and run it with plain agentloom run — see examples/32_yaml_mock.yaml and docs/testing-and-replay.

Responses are keyed by step_id or a SHA-256 hash of the messages. MockProvider supports three latency models (constant, normal, replay) for faithful performance reproduction. Replays emit Prometheus metrics (agentloom_mock_replays_total, agentloom_recording_captures_total) and a dedicated "Mock & Replay" row in the stock Grafana dashboard. See docs/testing-and-replay and examples/31_record_and_replay.yaml.

Why not autonomous agents?

Most LLM frameworks focus on autonomous agents: self-directed reasoning, multi-agent delegation, unbounded tool loops. This works for demos and open-ended research, but breaks down in production where you need predictable costs, debuggable failures, and SLA compliance.

AgentLoom is not an autonomous agent framework. An agent runs as one step of the DAG, its turn bounded in model calls and cost: there are no unbounded loops and no emergent control flow. It is a deterministic workflow orchestrator that uses LLMs as execution steps within a declared DAG.

The difference matters:

• You define the DAG, not the LLM. Steps, dependencies, and routing logic are declared upfront in YAML. Within a step, the model writes text or picks the tools and agents it calls, up to the step's limits; it does not decide what runs next. Routers use explicit boolean conditions, not LLM judgement.
• Observability is not optional. Every step emits OpenTelemetry traces and Prometheus metrics. You can see exactly what ran, how long it took, and how much it cost. Autonomous agents are notoriously hard to debug; a static DAG with full tracing is not.
• Cost is bounded. Budget limits, circuit breakers, and rate limiters are first-class. A runaway autonomous agent can burn through an API budget in minutes. A workflow with budget_usd: 0.50 cannot.
• Fallback is structural. If OpenAI is down, the gateway falls back to the other providers it has keys for, and to Ollama when AGENTLOOM_OLLAMA_FALLBACK is set. This is a routing decision at the infrastructure level, not an agent "choosing" a provider.

Autonomous agent frameworks solve a real problem — open-ended tasks where the execution path cannot be known in advance. But most LLM workloads in production are not open-ended. They are pipelines: classify, enrich, route, generate, validate. For those, you want predictability and control, not autonomy. That is what AgentLoom is for.

Development

uv sync --group dev --all-extras   # install with all extras
uv run pytest                       # ~5s
uv run ruff check src/ tests/      # lint (ruff replaces flake8+isort)
uv run ruff format src/ tests/     # autoformat
uv run mypy src/                   # strict type checking

Pre-commit hooks run ruff automatically on staged files — see CONTRIBUTING.md for the full workflow.

Contributing

See CONTRIBUTING.md for setup instructions, code style, and PR guidelines.

License

MIT