DeclarAgent: Declarative Runbook Executor for Safe AI Agent Workflows

Introduction

DeclarAgent is an innovative declarative runbook executor specifically designed for AI agents. It empowers large language model (LLM) agents to safely and reliably execute multi-step YAML workflows, including real CLI commands, HTTP requests, and built-in actions. By providing validation, dry-run capabilities, and explicit approval for destructive steps, DeclarAgent ensures that AI agents can interact with real-world systems in a controlled and auditable manner.

Why Use and Key Benefits

DeclarAgent offers a range of features and benefits that make it an essential tool for secure and structured workflow execution by AI agents:

• YAML Plans: Human-readable, version-controllable runbooks.
• Three Step Types: Shell commands (run), built-in actions (action), and HTTP requests (http).
• Dry-run & Explain: Inspect exactly what will happen before execution.
• Destructive-Step Gating: Steps marked destructive: true require explicit approval.
• Structured JSON Results: Machine-readable output with typed errors for every run.
• Built-in Actions: File I/O, JSON manipulation, and environment access.
• Template Engine: Reference outputs from prior steps with ${{steps.<id>.outputs.<key>}}.
• MCP Server: Expose plans as directly callable tools over the Model Context Protocol.
• Plan-as-Tool: YAML files in a directory automatically become MCP tools.

Installation

To install DeclarAgent, you will need Go installed on your system.

go install github.com/shiehn/declaragent@latest

# Verify
declaragent --help

Note: This project is currently tested on macOS, and Linux should work out of the box. Windows requires WSL or a similar POSIX-compatible shell.

Examples

DeclarAgent offers a straightforward command-line interface for managing your runbooks. Here are some quick start examples:

# Validate a plan
declaragent validate plan.yaml

# See what it would do
declaragent explain plan.yaml --input branch=main

# Dry-run (resolves templates, shows commands)
declaragent dry-run plan.yaml --input branch=main

# Execute for real
declaragent run plan.yaml --input branch=main

# Execute with destructive steps allowed
declaragent run plan.yaml --input branch=main --approve

For a practical demonstration, consider the hello.yaml plan:

name: hello
description: Say hello to someone
inputs:
  name:
    description: Who to greet
    default: World
steps:
  - id: greet
    run: echo "Hello, ${{inputs.name}}!"
    outputs:
      message: stdout

You can run this plan with:

declaragent run plans/hello.yaml --input name=Alice

This will output a greeting, demonstrating a simple shell command execution within a declarative plan.

Links

Find the official repository and contribute on GitHub:

• DeclarAgent GitHub Repository