Agent Orchestrator (ComposioHQ)

Agent Orchestrator is ComposioHQ’s production-grade layer for managing fleets of parallel AI coding agents. You give it a GitHub issue or Linear ticket, it spawns an agent (Claude Code, Codex, or Aider) in an isolated git worktree with its own branch and PR lifecycle. When CI fails, the agent reads the logs and fixes them autonomously. When a reviewer requests changes, the agent addresses the comments. You only get pinged when a human decision is genuinely needed.

It is not just a process manager — it is a reactive system. The config YAML defines “reactions”: CI-failed → send-to-agent, changes-requested → send-to-agent with 30-minute escalation, approved-and-green → notify human to merge. The whole thing runs under a web dashboard at localhost:3000.

The architecture has eight swappable plugin slots: Runtime (tmux, Docker), Agent (claude-code, codex, aider), Workspace (worktree, clone), Tracker (GitHub, Linear), SCM, Notifier (desktop, Slack, webhook), Terminal, and Lifecycle. Every abstraction implements a TypeScript interface — clean and extensible.

Where Ravi Fits

Agent Orchestrator has three natural Ravi integration points:

1. Credential injection at spawn time. When an agent is spawned for a project, it needs secrets — GitHub tokens, API keys for whatever services it builds against. Today these come from env vars or system-level auth. Ravi’s secrets store can be queried at ao spawn time to inject the right credentials per agent and project, scoped, auditable, and revokable without touching environment files.

2. Per-agent identity for PR authorship. Each agent opens PRs and posts review comments. Without Ravi they all share the same bot account, making it impossible to trace a PR back to a specific agent session. Ravi gives each agent its own email identity so PR activity is attributable — critical audit trail when you are running 30 or more parallel agents at once.

3. Human-in-the-loop via Ravi email or SMS. The Notifier plugin slot exists exactly for escalation. A @composio/ao-notifier-ravi plugin sends an email (or SMS) with the PR link, CI status, and decision summary when the orchestrator needs a human call. The human replies to approve or reject, and the orchestrator feeds the response back as an ao send command. Ravi becomes the human-in-the-loop channel — no Slack required, works wherever the human has a phone or inbox.

Setup

Install

npm install -g @composio/agent-orchestrator
ao init

Configure Ravi notifier

Add a notifier block to your ao.config.yaml:

notifier:
  plugin: "@composio/ao-notifier-ravi"
  config:
    ravi_api_key: "${RAVI_API_KEY}"
    escalation_email: "your@email.com"
    poll_interval_seconds: 30

Store your Ravi API key in the secrets store so agents can retrieve it without hardcoding:

ravi secrets set RAVI_API_KEY sk-ravi-...

Spawn an agent

ao spawn my-project 123   # where 123 is the GitHub issue number

When the agent hits an escalation condition — blocked reviewer, ambiguous scope, policy decision — it triggers the Ravi notifier. You receive an email with a summary and a reply-to-decide link. Reply approve, reject, or free-form instructions. The orchestrator resumes within one polling cycle.

Credential injection

Extend your spawn lifecycle plugin to pull secrets from Ravi at agent start:

import { RaviClient } from "@ravi/sdk";

const ravi = new RaviClient({ apiKey: process.env.RAVI_API_KEY });

async function onAgentSpawn(ctx: SpawnContext) {
  const secrets = await ravi.secrets.getAll({ project: ctx.projectId });
  ctx.env = { ...ctx.env, ...secrets };
}

This keeps credentials out of config files and makes them revokable per-agent without restarting the orchestrator.

Why Ravi

Agent Orchestrator solves the throughput problem — more agents, more parallelism, fewer manual PR reviews. Ravi solves the accountability and oversight problem that comes with that scale. When you are running dozens of agents simultaneously, you need to know which agent did what, you need secrets that expire and scope correctly, and you need a reliable channel to pull humans into decisions without building a custom approval workflow. Ravi provides all three through a single identity layer that the agents already know how to use.