# DeclarAgent: Declarative Runbook Executor for Safe AI Agent Workflows

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/shiehn-declaragent
Generated for open source discovery and AI-assisted research.

DeclarAgent is an innovative declarative runbook executor specifically designed for AI agents. It enables agents to validate, dry-run, and safely execute multi-step YAML workflows. This tool provides a structured, auditable, and secure way for LLM agents to interact with real CLI workflows, enhancing their operational safety and reliability.

GitHub: https://github.com/shiehn/DeclarAgent
OSRepos URL: https://osrepos.com/repo/shiehn-declaragent

## Summary

DeclarAgent is an innovative declarative runbook executor specifically designed for AI agents. It enables agents to validate, dry-run, and safely execute multi-step YAML workflows. This tool provides a structured, auditable, and secure way for LLM agents to interact with real CLI workflows, enhancing their operational safety and reliability.

## Topics

- Go
- AI Agents
- Automation
- DevOps
- CLI Tools
- Runbooks
- LLM Tools
- Model Context Protocol

## Repository Information

Last analyzed by OSRepos: Sat Sep 12 2026 16:46:09 GMT+0100 (Western European Summer Time)
Detail views: 0
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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](https://go.dev/dl/){:target="_blank"} installed on your system.

bash
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:

bash
# 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:

yaml
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:

bash
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](https://github.com/shiehn/DeclarAgent){:target="_blank"}