Orchestration API

The orchestration module provides four multi-agent execution patterns: auto planning, parallel racing, sequential pipeline, and eval scoring.

orchestrateAuto()

Describe a goal and let the system plan, execute, and evaluate a full pipeline automatically.

import { orchestrateAuto } from "prompts-gpt";

const result = await orchestrateAuto({
  goal: "Add user authentication with JWT tokens, write tests, and update docs",
  maxSteps: 5,
  qualityGate: 80,
  cwd: process.cwd(),
  onProgress: (event) => {
    if (event.type === "auto_plan") {
      console.log("Generated plan:", event.steps.map(s => s.name).join(" → "));
    }
  },
});

console.log(`Goal: ${result.goal}`);
console.log(`Steps: ${result.generatedSteps.length}`);
if (result.evaluation) {
  console.log(`Score: ${result.evaluation.score}/100`);
}

OrchestrateAutoInput

OrchestrateAutoResult

orchestrateParallel()

Race the same prompt across multiple providers simultaneously.

import { orchestrateParallel } from "prompts-gpt";

const result = await orchestrateParallel({
  promptFile: ".prompts-gpt/refactor.md",
  providers: ["codex", "claude", "cursor"],
  model: "auto",
  cwd: process.cwd(),
  timeoutSeconds: 600,
  onProgress: (event) => {
    console.log(`${event.provider}: ${event.status}`);
  },
});

for (const [provider, run] of Object.entries(result.results)) {
  console.log(`${provider}: ${run.ok ? "OK" : "FAILED"} (${run.durationMs}ms)`);
}

OrchestrateParallelInput

OrchestrateParallelResult

orchestratePipeline()

Chain multiple providers sequentially — output from each step feeds into the next.

import { orchestratePipeline } from "prompts-gpt";

const result = await orchestratePipeline({
  steps: [
    {
      name: "research",
      promptFile: ".prompts-gpt/orchestrations/pipeline-steps/research.md",
      agent: "claude",
      model: "claude-sonnet-4-20250514",
    },
    {
      name: "implement",
      promptFile: ".prompts-gpt/orchestrations/pipeline-steps/implement.md",
      agent: "codex",
      model: "gpt-5.5",
    },
    {
      name: "review",
      promptFile: ".prompts-gpt/orchestrations/pipeline-steps/review.md",
      agent: "cursor",
    },
  ],
  cwd: process.cwd(),
});

for (const step of result.steps) {
  console.log(`${step.name}: ${step.result.ok ? "OK" : "FAILED"}`);
}

OrchestratePipelineInput

OrchestratePipelineStep

OrchestratePipelineResult

orchestrateEval()

Execute a prompt and automatically evaluate/score the output.

import { orchestrateEval } from "prompts-gpt";

const result = await orchestrateEval({
  promptFile: ".prompts-gpt/code-review.md",
  provider: "codex",
  model: "gpt-5.5",
  criteria: [
    { name: "correctness", weight: 0.4 },
    { name: "completeness", weight: 0.3 },
    { name: "code-quality", weight: 0.3 },
  ],
  evaluatorProvider: "claude",
  cwd: process.cwd(),
});

console.log(`Overall score: ${result.overallScore}`);
for (const score of result.scores) {
  console.log(`  ${score.name}: ${score.score}/1.0`);
}

OrchestrateEvalInput

ScoringCriterion

OrchestrateEvalResult

Helper Functions

buildEvalPrompt()

Build a prompt for evaluating agent output:

import { buildEvalPrompt } from "prompts-gpt";

const evalPrompt = buildEvalPrompt({
  originalPrompt: "Review security...",
  agentOutput: "Fixed 3 issues...",
  criteria: ["correctness", "completeness"],
});

parseEvalResponse()

Parse evaluation scores from agent output:

import { parseEvalResponse } from "prompts-gpt";

const scores = parseEvalResponse(evalOutput);

scoreIterationOutput()

Score a single iteration's output:

import { scoreIterationOutput } from "prompts-gpt";

const score = await scoreIterationOutput({
  prompt: "Original prompt...",
  output: "Agent output...",
  criteria: ["correctness"],
  provider: "claude",
});

See Also

• Runtime API — Single-shot execution
• Sweep API — Multi-iteration sweeps
• Orchestrate CLI — CLI interface