Orchestral

Workflow orchestration for grounded agents.

中文版本

What It Does

• Orchestrates stateful workflows, not one-off tool calls
• Executes typed actions with an agent loop and mini-DAG
• Replans from real state and verifies before finishing

See It Work

One user command. Orchestral coordinates an MCP data source, a domain skill, and shell execution into a multi-step pipeline:

You:  "Query Q4 sales from the API, fill the Excel template with actuals
       and formulas, write a markdown summary comparing to budget."

Orchestral automatically:
  ├─ mcp__sales-api__query_sales_data  → fetch actuals from external API
  ├─ file_read budget.yaml             → load budget targets
  ├─ shell (venv python + openpyxl)    → fill Excel: values, formulas, status
  └─ file_write report.md              → generate comparison report

The planner discovers MCP tools at startup via tool_lookup, activates the xlsx skill for openpyxl guidance, and uses the skill's virtual environment to run Python. When a step fails, the agent loop observes the error and replans — no manual intervention needed.

Try it:

export OPENROUTER_API_KEY="sk-or-..."
cargo build -p orchestral-cli
cargo run -p orchestral-cli -- scenario \
  --spec configs/scenarios/sales_report_pipeline.smoke.yaml

Architecture

Intent → Planner (LLM) → Normalizer (DAG validation) → Executor (parallel + retry)
            ↑                                                    ↓
            └──── agent loop: observe execution result ──────────┘

• Agent loop — planner iterates up to 6 rounds, observing results and replanning
• MCP integration — servers probed at startup, each tool registered as a callable action with deferred schema loading via tool_lookup
• Skills — domain knowledge (SKILL.md files) auto-discovered and injected into planner context; skill_activate for on-demand loading
• Typed actions — document inspect/patch/verify, structured config patch/verify, shell, file I/O, HTTP

SDK

Use Orchestral as a library — register custom actions and lifecycle hooks with a builder API:

use orchestral::{Orchestral, core::action::*};

let app = Orchestral::builder()
    .action(MyCustomAction::new())
    .hook(MyLoggingHook::new())
    .planner_backend("openrouter")
    .planner_model("anthropic/claude-sonnet-4.5")
    .build()
    .await?;

let result = app.run("Analyze the data and generate a report").await?;
println!("{}", result.message);

See examples/sdk_quickstart.rs and examples/sdk_hooks.rs.

Install

# As a library
cargo add orchestral

# As a CLI tool
cargo install orchestral-cli

Quick Start

Export one provider key:

export GOOGLE_API_KEY="..."  # or OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY

CLI:

orchestral-cli run

As a library:

let app = Orchestral::builder()
    .planner_backend("google")
    .planner_model("gemini-2.5-flash")
    .build().await?;
let result = app.run("read README.md").await?;

Project Structure

core/orchestral-core     — Pure abstractions: Intent/Plan/Step, traits, DAG executor
core/orchestral-runtime  — LLM planners, actions, MCP bridge, skill system
core/orchestral          — Facade re-exporting core + runtime
apps/orchestral-cli      — CLI + TUI (ratatui)
apps/orchestral-telegram — Telegram bot adapter

Telegram Bot

Run Orchestral as a Telegram bot — each message goes through the full orchestration pipeline:

export TELEGRAM_BOT_TOKEN="your-bot-token"
export GOOGLE_API_KEY="your-key"  # or OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
cargo run -p orchestral-telegram

LLM backend is configurable in code (defaults to Google Gemini). The bot supports file operations, shell commands, and multi-turn conversations.

Current Status

• Core orchestration loop working with agent loop + mini-DAG
• MCP per-tool registration with deferred schema loading
• Skill auto-discovery and on-demand activation
• SDK with builder API, lifecycle hooks, and programmatic execution
• Telegram bot adapter (configurable LLM backend)
• Document and structured config typed pipelines
• Scenario smoke tests covering core workflows

License

See LICENSE.