AgentLoom

• DAG-based workflows

  Define workflows as directed acyclic graphs in YAML or Python. Steps, dependencies and routing are declared upfront: the LLM generates text, not control flow.

• Native observability

  OpenTelemetry traces and Prometheus metrics for every step, and a Grafana dashboard to read them. No external SaaS required.

• Built-in resilience

  Retries with backoff, timeouts, and a circuit breaker and rate limiter per provider. Checkpoints let a failed or paused run resume where it left off.

• Cost control

  Tokens and cost tracked for every step, and a budget per workflow: once budget_usd is spent, no further step starts.

Requirements

• Python 3.11 or newer. AgentLoom supports 3.11 to 3.14.
• A model to call. An API key for OpenAI, Anthropic or Google, or a local Ollama. No key at all works too: the mock provider answers offline.
• No provider SDKs. AgentLoom calls each provider’s HTTP API itself, so pip installs nothing from OpenAI, Anthropic or Google.

Installation

pip install agentloom

pip install "agentloom[observability]"

pip install "agentloom[graph]"

pip install "agentloom[all]"

With extras, keep the quotes: zsh reads unquoted brackets as a file pattern. To check the install, agentloom info prints the version, the Python it runs on, which optional extras are installed and which provider keys are set (never their values).

Quick start

1. Create a workflow — my_workflow.yaml:

name: simple-qa
config:
  provider: openai
  model: gpt-4o-mini

state:
  question: "What is Python in one sentence?"

steps:
  - id: answer
    type: llm_call
    prompt: "Answer this question concisely: {state.question}"
    output: answer

One step calls the model with a prompt built from the state, and writes the reply to the answer key.

2. Run it with the provider you have:

export OPENAI_API_KEY=sk-...
agentloom run my_workflow.yaml

export ANTHROPIC_API_KEY=sk-ant-...
agentloom run my_workflow.yaml --provider anthropic --model claude-haiku-4-5-20251001

export GOOGLE_API_KEY=...
agentloom run my_workflow.yaml --provider google --model gemini-2.5-flash

ollama pull phi4
agentloom run my_workflow.yaml --provider ollama --model phi4

agentloom run my_workflow.yaml --provider mock

3. Read the result. The run prints a summary:

Running workflow: simple-qa

============================================================
Workflow: simple-qa
Status:   [OK] success
Duration: 812.4ms
Tokens:   41
Cost:     $0.0000

Steps:
  [OK] answer (809ms)

Final State Keys: ['question', 'answer', 'steps']
============================================================

The summary lists what each step did, not what the model said. To see the answer, ask for the whole result as JSON, or stream the text as it arrives:

agentloom run my_workflow.yaml --json | jq -r .final_state.answer
agentloom run my_workflow.yaml --stream

4. Validate and visualize:

agentloom validate my_workflow.yaml    # check the file without running it
agentloom visualize my_workflow.yaml   # draw the DAG as text; --format mermaid for a diagram

Keys and providers

• Keys come from the environment: OPENAI_API_KEY, ANTHROPIC_API_KEY and GOOGLE_API_KEY. AgentLoom reads no .env file, so load one with your shell or a tool like direnv. Each provider whose key is set is available to every step.
• The model name finds the providers. gpt-*, o1, o3 and o4 models go to OpenAI, claude* to Anthropic, gemini* to Google. --provider says which provider is tried first, if it can serve the model. On a workflow with no model, --provider anthropic brings Anthropic’s default; on one that names a model, pass --model too.
• Ollama takes no key. It is used when a workflow says provider: ollama (or --provider ollama), and accepts any model name.
• Endpoints can be changed with OPENAI_BASE_URL, ANTHROPIC_BASE_URL, GOOGLE_BASE_URL and OLLAMA_BASE_URL, for a proxy or a self-hosted gateway. Any other OpenAI-compatible server works through the generic_openai provider.

Providers covers every provider, model and capability.

What a run leaves behind

Both directories sit in the current directory: add agentloom_runs/ and .agentloom/ to your .gitignore.

Exit codes

Scripts and CI jobs can rely on them; --json prints the full result either way.

Common first-run errors

What’s next

• Concepts

  Workflows, steps, state, providers and runs: the ideas every other page builds on.

• Workflow files

  Every key of a workflow file, every config option and what validate checks.

• Steps

  The seven step types, with routers, subworkflows, approval gates and embeddings in full.

• State & templates

  How steps write to the state, and the template syntax that reads it.

• Providers

  Providers, models, attachments, reasoning and pricing.

• CLI reference

  Every agentloom command and option.

• Examples

  39 example workflows, from one LLM call to production-grade pipelines.

• Python DSL

  Build and run workflows from Python.

• Testing & Replay

  Record real runs and replay them offline, deterministically.

• Observability

  Traces, metrics, dashboards and run records.

• Deployment

  Docker, Kubernetes, Helm, Terraform and ArgoCD.

• Architecture

  How the engine schedules, runs and records a workflow.

• Graph API

  Analyze, visualize and export workflow DAGs.

• Changelog

  Every release and what changed in it.