Beddel

---

name: beddel

description: >-

Execute declarative YAML AI workflows with branching, retry,

multi-provider LLM support, guardrails, and OpenTelemetry tracing

via the Beddel Python SDK. Use when asked to run, create, validate,

or debug YAML AI workflows, multi-step pipelines, or LLM chains.

Triggers on: "run workflow", "execute pipeline", "validate YAML workflow",

"create a workflow", "beddel", "multi-step LLM".

metadata:

clawdbot:

emoji: "🔄"

tags: [workflow, yaml, llm, python, automation, pipeline, observability, guardrail]

requires:

bins: [python3, pip, beddel]

env: [GEMINI_API_KEY]

primaryEnv: GEMINI_API_KEY

---

# Beddel

Declarative YAML workflow engine for AI pipelines — run multi-step LLM chains with branching, guardrails, retry, and observability out of the box.

Prerequisites

export GEMINI_API_KEY="your-key"

Installation

python3.11 -m pip install "beddel[all]"
beddel version

> **Note:** System Python may be 3.10. Always use `python3.11` explicitly.

Quick Start

1. Write a workflow file `hello.yaml`:

id: hello
name: Hello World
input_schema:
  topic: { type: str, required: true }
steps:
  - id: greet
    primitive: llm
    config:
      model: gemini/gemini-2.0-flash
      prompt: "Write a one-sentence greeting about $input.topic"
      max_tokens: 50

2. Run it:

beddel run hello.yaml -i topic="AI agents" --json-output

Tool Integration (OpenClaw Plugin)

The `beddel` tool is available via the OpenClaw plugin `@botanarede/beddel`:

openclaw plugins install @botanarede/beddel

Once installed, the agent can invoke `beddel` with actions: `run`, `validate`, `list-primitives`.

The bundled example `examples/setup-beddel.yaml` automates this installation — see [Bundled Example](#bundled-example-setup-beddel) below.

CLI Reference

| Command | Description |

|---------|-------------|

| `beddel run <file> [-i key=val] [--json-output]` | Execute a workflow |

| `beddel validate <file>` | Validate YAML syntax and schema |

| `beddel list-primitives` | Show available primitives |

| `beddel serve -w <file> [--port 8000]` | Serve workflow as HTTP endpoint |

| `beddel version` | Print installed version |

Core Concepts

A **workflow** is a YAML file with an `id`, `name`, optional `input_schema`, and a list of `steps`. Each step declares a **primitive** (the unit of work) and a **config** (primitive-specific parameters).

Steps execute sequentially. Each step's output is available to subsequent steps via `$stepResult.<step_id>.<path>`.

See `references/` for full schema documentation.

Primitives

| Primitive | Purpose |

|-----------|---------|

| `llm` | Single-turn LLM call with streaming support |

| `chat` | Multi-turn conversation with message history |

| `output-generator` | Template-based output rendering (JSON, Markdown, text) |

| `guardrail` | Data validation with strategies: raise, return_errors, correct, delegate |

| `call-agent` | Nested workflow invocation with depth tracking |

| `tool` | External function call — `shell_exec` is built-in |

| `agent-exec` | Unified adapter for external agent delegation |

Execution Strategies

Each step can declare an `execution_strategy` to control error handling:

| Strategy | Behavior |

|----------|----------|

| `fail` | Stop workflow on error (default) |

| `skip` | Log error, continue to next step |

| `retry` | Retry with exponential backoff and jitter |

| `fallback` | Execute an alternative step on failure |

| `delegate` | Delegate error recovery to agent judgment |

Variable Resolution

| Namespace | Example | Source |

|-----------|---------|--------|

| `$input` | `$input.topic` | Runtime inputs (`-i key=val`) |

| `$stepResult` | `$stepResult.greet.content` | Previous step outputs |

| `$env` | `$env.GEMINI_API_KEY` | Environment variables |

Key paths for step results:

Bundled Example: setup-beddel

This workflow checks whether the `@botanarede/beddel` OpenClaw plugin is installed and installs it if needed. It demonstrates 3 of the 7 primitives: `tool`, `guardrail`, and conditional execution via `if`.

id: setup-beddel
name: Beddel Plugin Setup
description: Install or update the @botanarede/beddel OpenClaw plugin and verify it loads.

steps:
  - id: check_plugin
    primitive: tool
    config:
      tool: shell_exec
      arguments:
        cmd: "python3.11 -c \"import subprocess,json,re;r=subprocess.run(['openclaw','plugins','list'],capture_output=True,text=True);has=bool(re.search(r'beddel',r.stdout));loaded=bool(re.search(r'beddel.*loaded',r.stdout));print(json.dumps({'action':'OK'if loaded else'REINSTALL'if has else'INSTALL'}))\""

  - id: validate_check
    primitive: guardrail
    config:
      data: "$stepResult.check_plugin.result.stdout"
      schema:
        fields:
          action: { type: str, required: true }
      strategy: correct

  - id: install_plugin
    primitive: tool
    config:
      tool: shell_exec
      arguments:
        cmd: "openclaw plugins install @botanarede/beddel"
      timeout: 120
    if: "$stepResult.validate_check.data.action != 'OK'"

  - id: verify
    primitive: tool
    config:
      tool: shell_exec
      arguments:
        cmd: "openclaw plugins info beddel"

What each step demonstrates

| Step | Primitive | Feature |

|------|-----------|---------|

| `check_plugin` | `tool` | Deterministic check via `shell_exec` — outputs JSON without LLM |

| `validate_check` | `guardrail` | `correct` strategy — parses JSON string, strips markdown fences, validates schema |

| `install_plugin` | `tool` | Conditional execution (`if`) — skips when plugin already loaded. `timeout: 120` for network ops |

| `verify` | `tool` | Post-install verification |

Run it:

beddel run examples/setup-beddel.yaml --json-output

Security & Privacy

External Endpoints

| Endpoint | When | Purpose |

|----------|------|---------|

| LLM provider API (e.g. `generativelanguage.googleapis.com`) | `llm`, `chat`, `guardrail` (delegate) steps | Model inference |

| PyPI (`pypi.org`) | Installation only | Package download |

| npm registry (`registry.npmjs.org`) | Plugin install step | Plugin download |

Trust Statement

Beddel executes user-defined YAML workflows. It does not phone home, collect telemetry by default, or transmit data beyond the configured LLM provider endpoints. OpenTelemetry export is opt-in.

Observability

Beddel emits OpenTelemetry spans for every workflow and step execution:

Enable with any OTel-compatible collector via standard `OTEL_*` environment variables.

Troubleshooting

| Error | Cause | Fix |

|-------|-------|-----|

| `BEDDEL-PRIM-300` | Tool not found | Ensure tool name is `shell_exec` (built-in). Custom tools need `-t name=module:func` |

| `BEDDEL-RESOLVE-001` | Unresolvable variable | Check step id spelling and result path. Tool results use `.result.stdout`, LLM uses `.content` |

| `BEDDEL-GUARD-201` | Guardrail validation failed | Check schema field types. Use `strategy: correct` for JSON string inputs |

| `python3.11: not found` | Wrong Python version | Install Python 3.11+. System Python may be 3.10 |

| Step shows `SKIPPED` | `if` condition was false or `execution_strategy: skip` | Expected behavior — downstream steps should handle SKIPPED values |

Advanced: Python SDK

from beddel import WorkflowExecutor, VariableResolver

resolver = VariableResolver()
resolver.register_namespace("secrets", lambda path, ctx: get_secret(path))

executor = WorkflowExecutor(resolver=resolver)
result = await executor.execute(workflow, {"topic": "AI"})

For FastAPI integration: `beddel serve -w workflow.yaml --port 8000`

References

Additional documentation in `references/` (loaded on demand):