Agent Orchestration: A Deterministic Workflow Orchestration Framework for Large Model Agents

This project is an orchestration system that defines LLM Agent workflows using YAML. Its core features include strict runtime contracts, reproducible execution states, and a modular design-plan-implement-review workflow stack. It aims to address the core challenge of reliably orchestrating large model Agent workflows, emphasizing predictability and debuggability, making it suitable for integration into production environments.

As LLMs evolve from question-answering tools to complex task Agents, reliably orchestrating their workflows has become a core challenge. This project addresses this need by providing a deterministic, sequentially executed workflow orchestration mechanism that manages command steps and Provider-driven Agent loops. Unlike frameworks that pursue intelligent autonomy, this project emphasizes predictability and debuggability, ensuring reproducible results through YAML DSL and strict runtime contracts, making it a pragmatic choice for production environment integration.

The project defines three core abstractions: 1. YAML DSL: A declarative way to describe workflows, supporting steps, input/output, control flows, and sub-workflow imports. It is easy for non-programmers to understand and friendly to version control. 2. Runtime Contracts: Clear type constraints for step inputs and outputs, catching errors at compile time. 3. Native File System State: Execution states are persisted in the .orchestrate/runs// directory, including execution history, intermediate products, and logs, enabling intuitive debugging.

The project provides a "design-plan-implement-review" workflow stack: The design phase generates technical solutions based on requirements; the planning phase converts them into implementation plans; the implementation phase executes specific tasks (code generation, file operations, etc.); the review phase performs quality checks, and any issues are returned for fixes. It supports the --dry-run mode to validate workflow structure and parameters before execution, facilitating CI/CD integration.

Observability aspects: 1. Runtime logs record prompts, outputs, and errors for each step; 2. state.json records execution results, products, and error contexts; 3. Generates Markdown reports; 4. The monitor subcommand supports email notifications for running status. Execution control and recovery: Resume from breakpoints (resume command), streaming output (--stream-output), debug mode (flags like --debug).

The project is loosely coupled with external tools. It uses Codex CLI as an example Provider but is not tied to any specific Provider. Any system that complies with the CLI contract can be integrated (e.g., open-source model Ollama, internal Agents). Applicable scenarios: Tasks requiring reproducible results (compliance/audit), multi-step complex workflows, human-machine collaboration processes, CI/CD integration.

The project embodies an engineering philosophy: In the AI era, traditional software engineering best practices (type safety, version control, testability, observability) are still necessary. Through YAML DSL and runtime contracts, it encapsulates the non-deterministic intelligence of LLMs within a deterministic framework, balancing creativity and reliability. It provides a pragmatic reference for introducing LLM Agents into production environments, considering both new technologies and engineering discipline.