convez.ai
AgenteAutomaçãoAvançado
Hisslyn

Orchestra

Hisslyn/orchestra

Fluxos multi-agente Claude via YAML, personas + code workers

Ver no GitHub
InicialPluginScore · de 0 a 100

Orquestrador de fluxos multi-agente com Claude config-driven. Coordena personas assessoras (com transcrição persistente) e subagentes autônomos (workers headless de código), roteando tarefas e mantendo estado compartilhado entre execuções.

Instalação

$npx convez-ai Hisslyn/orchestra

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Pipelines de revisão de código com arquitetos e testadores
  • Fluxos de auditoria de segurança com personas especializadas
  • Automação de tarefas de desenvolvimento com handoff entre agentes

Veredito

Orchestra é uma abordagem sofisticada para orquestração multi-agente, separando pensamento estratégico (personas) de execução (subagentes). Excelente para pipelines complexos, mas requer Python 3.10+, CLI do Claude e compreensão profunda da arquitetura.

README

A tradução para o português deste README ainda está na fila.

Orchestra

Formalized multi-agent Claude workflows from the command line. Orchestra coordinates two kinds of agents: advisory personas (long-lived strategic roles backed by the Anthropic Messages API with persistent transcripts) and autonomous subagents (task-scoped, headless Claude Code workers). All behavior is config-driven: roles, prompts, and handoff rules live in orchestra.config.yaml.

Concept

Real multi-agent work splits naturally into thinking and doing. Personas think: an architect critiques a plan, a security reviewer audits a diff. Subagents do: an implementer writes code, a tester runs and fixes the suite. Orchestra makes that split explicit, routes work between them via handoff rules, and persists shared state so a pipeline survives interruption and can resume.

Architecture

                ┌──────────────────────────────┐
                │         orchestra CLI         │
                │   (click entrypoint, cli.py)  │
                └──────┬───────────────┬───────┘
                       │               │
            ┌──────────▼─────┐  ┌──────▼──────────┐
            │  Config Loader │  │  State Manager  │
            │   (config.py)  │  │   (state.py)    │
            └──────────┬─────┘  └──────▲──────────┘
                       │               │ read/write
        ┌──────────────┼───────────────┤ .orchestra/state.json
        │              │               │
┌───────▼────────┐ ┌───▼──────────────┴───┐
│ Persona Runner │ │ Subagent Dispatcher  │
│ (personas.py)  │ │   (subagents.py)     │
│                │ │                      │
│ architect      │ │ implementer          │
│ security-rev.  │ │ tester               │
└───────┬────────┘ └───────┬──────────────┘
        │ advice/verdicts  │ spawns
        │                  ▼
        │          claude (Claude Code CLI,
        │           headless: -p / --print)
        └───────► handoff engine (handoffs.py)
                  routes (agent, event) → target

The persona / subagent model

PersonaSubagent
Backed byAnthropic Messages APIClaude Code CLI (headless -p)
LifetimeWhole session (transcript persisted)One task
OutputAdvice, verdicts, plansCode changes, test results
State.orchestra/transcripts/<name>.jsonWorking dir + .orchestra/logs/

Install

pip install orchestra-cli
# or from source:
pip install -e .

Requirements: Python ≥ 3.10; ANTHROPIC_API_KEY exported (personas); claude CLI installed and authenticated (subagents).

Usage

orchestra init                      # write example config + .orchestra/
orchestra status                    # agents, rules, pipeline state
orchestra ask architect "Is a queue or a cron job better here?"
orchestra ask architect "" --reset  # wipe its transcript
orchestra dispatch implementer --task "Add a /health endpoint"
orchestra run "Add OAuth login"     # full pipeline per handoff rules
orchestra run --resume              # continue after a failure
orchestra run "goal" --max-steps 6  # tighten the cycle cap
orchestra --config other.yaml status

Configuration

One YAML file defines the whole orchestra. Add a persona or subagent by adding a block and referencing it in handoffs — no code changes.

personas:
  architect:
    role: Senior software architect.
    prompt: |
      Produce a verdict (APPROVED or REVISE) and a step-by-step plan.
    events: [plan_approved, plan_rejected]

subagents:
  implementer:
    role: Writes code to satisfy an approved plan.
    command: claude
    args: ["-p", "--output-format", "json", "--max-turns", "{max_turns}"]
    prompt: |
      Implement the following plan exactly.
      {payload}
    events: [done, blocked]

handoffs:
  - on: { agent: architect, event: plan_approved }
    to: implementer
    payload: "{architect.plan}"

Events

Each agent declares its possible outcome events. Convention: events[0] is success, events[1] is failure. Agents may end output with an explicit EVENT: <name> line, which always wins; personas are automatically instructed to do so. Otherwise personas fall back to verdict keywords (APPROVED/REVISE/PASS/FAIL) and subagents map exit status to success/failure events.

Payload variables

VariableResolves to
{goal}The goal passed to orchestra run
{<agent>.output}That agent's latest output (aliases: .plan, .summary, .report, .findings, .text, .result)
{git.diff}git diff HEAD in the project workdir
{payload}(subagent prompts) the incoming handoff payload
{max_turns}, {model}Values from defaults / agent override

Unresolved variables are left intact rather than erroring.

Pipeline semantics

orchestra run GOAL starts at the source agent of the first handoff rule, passing the goal as its input. After each step the resulting (agent, event) is matched against the rules; the first match routes a rendered payload to the target. No match ends the pipeline: done normally, stalled if the last event was error. A --max-steps cap (default 10) prevents infinite revision loops. State is persisted to .orchestra/state.json after every step; a crashed step saves a resume point for orchestra run --resume.

Examples

See examples/:

  • refactor-flow.yaml — reviewer plans, refactorer executes, tester gates behavior.
  • the default config (orchestra init) — architect → implementer → tester → security-reviewer with failure loops back to architect/implementer.

Development

pip install -e ".[dev]"
pytest

See CONTRIBUTING.md. MIT licensed.

Ver o original no GitHub

Bom para

Relacionados