Yagra Documentation

Declarative LangGraph Builder powered by YAML

Yagra enables you to build LangGraph’s StateGraph from YAML definitions, separating workflow logic from Python implementation.

What is Yagra?

Yagra is a Python library that lets you define LLM agent workflows declaratively in YAML files. Instead of writing boilerplate LangGraph code for every workflow variation, you define nodes, edges, and branching logic in YAML—then swap configurations without touching code.

Key Benefits

• Faster iteration: Adjust workflows by editing YAML, not Python

• Non-engineer friendly: Prompt engineers and domain experts can modify workflows

• Validation by design: Pydantic-based schema catches errors before runtime

• Visual editing: Studio WebUI for drag-and-drop workflow construction

• AI-ready: JSON Schema export enables coding agents to generate workflows

Quick Links

Getting Started

• Getting Started
  • Installation
  • Your First Workflow
  • Observability and get_last_trace()
  • Next Steps
  • Common Issues
  • Using LLM Handlers

User Guide

• Workflow YAML Reference
  • Overview
  • Top-Level Structure
  • State Schema
  • Node Specification
  • Edge Specification
  • Start and End Points
  • Global Parameters
  • HITL / Interrupt
  • Validation Rules
  • Example: Complete Workflow
  • Next Steps
• Prompt & Model Configuration
  • Overview
  • Prompt Configuration
  • Prompt Variable Type-Safety Validation
  • Prompt Versioning
  • Model Configuration
  • Studio Integration
  • Best Practices
  • Example: Complete Configuration
  • Troubleshooting
  • Next Steps
• Branching & Loops
  • Conditional Branching
  • Loop Patterns
  • Advanced Patterns
  • Visualizing Branching and Loops
  • Best Practices
  • Common Pitfalls
  • Examples
  • Next Steps
• Template Library
  • Available Templates
  • Using Templates
  • Extending Templates
  • Template Design Principles
  • Creating Custom Templates
  • Next Steps
• Optimization Cycle
  • Overview
  • Prerequisites
  • Step 1: Build — Define Your Workflow
  • Step 2: Run & Observe — Capture Traces
  • Step 3: Analyze — Identify Improvement Opportunities
  • Step 4: Propose & Review — Generate a YAML Diff
  • Step 5: Regression Test — Validate with Golden Cases
  • Step 6: Apply or Rollback — Commit the Change
  • Worked Example: Improving a Translation Workflow
  • Agent Automation
  • Next Steps

CLI & API

• CLI Reference
  • Command Overview
  • yagra init
  • yagra schema
  • yagra validate
  • yagra golden
  • yagra studio
  • yagra handlers
  • yagra explain
  • yagra analyze
  • yagra prompt
  • yagra mcp
  • Environment Variables
  • Exit Codes
  • Next Steps
• API Reference
  • Yagra
  • main()

Additional Resources

• Examples
• Contributing to Yagra
• Changelog

Architecture Overview

Yagra follows Hexagonal Architecture (Ports and Adapters):

• Domain: Core workflow entities (GraphSpec, NodeSpec, EdgeSpec)

• Application: Use cases (build_state_graph, validate_workflow)

• Ports: Interfaces for extensibility (NodeRegistryPort)

• Adapters: Implementations (file system, WebUI server)

Dependency rule: Outer layers depend on inner layers, never the reverse.

Use Cases

• Prototyping LLM agent flows: Rapidly test different workflow variations

• Collaborative workflow development: Enable non-engineers to adjust prompts and branching

• AI-assisted workflow generation: Let coding agents generate and validate workflows

• Reducing boilerplate: Build complex LangGraph applications with less code

Community

• GitHub: https://github.com/shogo-hs/Yagra

• Issues: https://github.com/shogo-hs/Yagra/issues

• PyPI: https://pypi.org/project/yagra/

License

MIT License - see LICENSE for details.