orchestrating-agents-recipe

Agent Orchestration

Quick Reference

Sequential:

const results = await orchestrator.execute({
  agents: ['agent-a', 'agent-b', 'agent-c'],
  mode: 'sequential',
  scope: { context: {...} }
})

Parallel:

const results = await orchestrator.execute({
  agents: ['agent-a', 'agent-b', 'agent-c'],
  mode: 'parallel',
  scope: { context: {...} }
})

Conditional:

const results = await orchestrator.execute({
  agents: [
    { name: 'agent-a', stopOnFailure: true },
    { name: 'agent-b', condition: 'prev.success' },
    { name: 'agent-c', condition: 'prev.success' }
  ],
  mode: 'conditional'
})

When to Use

Multi-agent coordination | agent result storage | semantic search | pattern discovery

Orchestration Patterns

Mode	When	Execution	Failure
Sequential	Dependent tasks	One-by-one	Continue OR stop
Parallel	Independent tasks	Concurrent	Collect all
Conditional	Gated workflow	Chain with predicates	Stop on condition

Sequential:

Agent A → Agent B → Agent C

Parallel:

Agent A ┐
Agent B ├→ Aggregate
Agent C ┘

Conditional:

Agent A → PASS → Agent B → PASS → Agent C
          FAIL → ABORT

Orchestrator Responsibilities

Responsibility	Pattern	Rule
Execute agents	Invoke with enriched scope	Sequential/parallel/conditional
Accumulate outputs	In-memory scope.agent_results	No file storage between agents
Handle persistence	ALL DB/file writes	Agents return data only
Coordinate sequence	Mode-based execution	Sequential enriches scope

Agent Integration

Agent Discovery & Loading

Load agents from JSON configs:

private loadAgent(agentName: string): Result<AgentConfig, LoadError> {
  const configPath = `plugins/*/agents/${agentName}.json`
  return this.readJSON(configPath)
    .andThen(this.validateAgentConfig)
    .andThen(this.interpolateTemplate)
}

private validateAgentConfig(json: unknown): Result<AgentConfig, ValidationError> {
  return json.name && json.promptTemplate
    ? ok(json as AgentConfig)
    : err({ type: 'validation', message: 'Missing required fields' })
}

private interpolateTemplate(config: AgentConfig, scope: Scope): Result<string, Error> {
  return ok(
    config.promptTemplate
      .replace(/{scope\.(\w+)}/g, (_, key) => scope[key] || '')
  )
}

Agent config schema (plugins/*/agents/{agent-name}.json):

{
  "name": "agent-name",
  "description": "What agent does. Use when [trigger].",
  "skills": ["plugin:skill-name"],
  "subagentType": "plugin:agent-type",
  "promptTemplate": "Validate {scope.files} in {scope.repository}. Mode: {scope.mode}. Session: {scope.sessionId}."
}

Execution flow:

Orchestrator
  → Load agent JSON config from plugins/*/agents/{name}.json
  → Interpolate promptTemplate with scope values
  → Invoke agent (via Task tool using subagentType OR direct skill call)
  → Agent executes (invokes skills, returns JSON/Markdown)
  → Capture output in memory (NOT files)
  → Store in MongoDB
  → Extract content → Embed → Store for RAG
  → Return aggregated results

Example: Code review agents

Agent	Skill	Output	Mode Support
architecture-agent	hexagonal-architecture-recipe	JSON (violations + fix_summary)	Dual (info/exec)
production-code-agent	production-code-recipe	JSON (violations + fix_summary)	Dual (info/exec)
test-code-agent	test-code-recipe	JSON (violations + fix_summary)	Dual (info/exec)

Example: Research agents

Agent	Skill	Output	Mode Support
jira-researcher	jira-recipe	Markdown (search results)	Informative only
web-researcher	N/A	Markdown (search results)	Informative only

Data Storage & Search

See mongodb-embeddings.md for:

• MongoDB schema (patterns, agent_results, conversations, project_context)
• Collection indexes (vector search, sessionId, createdAt)
• Embedding generation (3 providers: sentence-transformers, anthropic, hash-based)
• Semantic vector search patterns
• MMR ranking for diversity

Orchestrator Service

Execute agents:

execute(config: OrchestrationConfig): Task<AggregatedResults, OrchestrationError> {
  return this.validateConfig(config)
    .andThen(validated =>
      config.mode === 'parallel'
        ? this.runParallel(validated)
        : config.mode === 'conditional'
        ? this.runConditional(validated)
        : this.runSequential(validated)
    )
    .andThen(this.storeResults)
    .andThen(this.extractPatterns)
}

Store results:

private storeResults(results: AgentResult[]): Task<StoredResult[], DbError> {
  return Task.all(
    results.map(r =>
      this.mongodb.insert('agent_results', {
        agent: r.agent,
        sessionId: r.sessionId,
        output: r.output,
        metadata: r.metadata,
        createdAt: new Date()
      })
    )
  )
}

Extract patterns:

private extractPatterns(
  content: string[],
  namespace: string,
  metadata: Record<string, unknown>[]
): Task<Pattern[], EmbeddingError> {
  return this.embedBatch(content)
    .andThen(embeddings =>
      Task.all(
        content.map((text, i) =>
          this.mongodb.insert('patterns', {
            content: text,
            embedding: embeddings[i],
            namespace,
            metadata: metadata[i],
            createdAt: new Date()
          })
        )
      )
    )
}

Agent Execution

Invoke agent:

private invokeAgent(agent: string, scope: Scope): Task<AgentResult, AgentError> {
  return fromResult(this.validateAgent(agent))
    .andThen(() => this.loadAgent(agent))
    .andThen(agentConfig => this.executeAgent(agentConfig, scope))
    .andThen(this.parseOutput)
}

private executeAgent(config: AgentConfig, scope: Scope): Task<string, ExecError> {
  return fromPromise(
    this.task.run({
      description: `${config.name} executing`,
      prompt: config.prompt(scope),
      subagent_type: 'general-purpose'
    }),
    this.mapError
  )
}

Result Aggregation

Combine results:

aggregate(results: AgentResult[]): AggregatedResults {
  return {
    agents: results.map(r => r.agent),
    outputs: results.reduce((acc, r) => ({
      ...acc,
      [r.agent]: r.output
    }), {}),
    metadata: {
      sessionId: results[0]?.sessionId,
      count: results.length,
      timestamp: new Date()
    }
  }
}

Custom aggregation:

aggregateWith<T>(
  results: AgentResult[],
  reducer: (acc: T, result: AgentResult) => T,
  initial: T
): T {
  return results.reduce(reducer, initial)
}

Configuration

Environment:

EMBEDDING_PROVIDER=sentence-transformers
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
EMBEDDING_DIMENSIONS=384
MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE=claude_flow

Type-safe config:

export type OrchestratorConfig = Readonly<{
  embedding: {
    provider: 'sentence-transformers' | 'anthropic' | 'hash-based'
    dimensions: number
    apiKey: string
  }
  mongodb: {
    uri: string
    database: string
  }
}>

Anti-Patterns

Anti-pattern	Issue	Fix
Agents write files	Breaks abstraction, slow	Return data, orchestrator persists
File-based handoff	I/O overhead, failure points	In-memory scope.agent_results

Validation Workflow

MANDATORY: Run after orchestrating agents.

Phase	Action
1. Execute	Orchestrate agents in chosen mode (sequential/parallel/conditional)
2. Validate	Verify all agents completed, outputs captured, results stored
3. Report	✓ ALL success → Done | ✗ ANY fail → Report failures
4. Fix	Failures → Retry failed agents → Re-validate
5. Store Metrics	After ALL validation passes, call mcp__agent-orchestrator__store-skill-metrics

Validation checks:

Check	Evidence Required	Pass	Fail
All agents invoked	Agent list matches config	Invoked	Missing agents
Outputs captured	All agents returned data	Captured	Empty outputs
Results stored	MongoDB inserts succeeded	Stored	Insert errors
Patterns embedded	Content embedded and stored	Embedded	Embedding errors
Aggregation complete	Combined results returned	Complete	Partial aggregation
Persistence centralized	Orchestrator stores results to DB/files	Centralized	Agents write directly
Memory-based passing	Agents communicate via scope	In-memory	File-based handoff

Output format (generic):

{
  "orchestration": {
    "mode": "sequential|parallel|conditional",
    "sessionId": "uuid",
    "timestamp": "ISO8601"
  },
  "agents": ["agent-a", "agent-b", "agent-c"],
  "results": {
    "agent-a": {...},
    "agent-b": {...},
    "agent-c": {...}
  },
  "storage": {
    "agent_results": 3,
    "patterns": 15,
    "conversations": 1
  },
  "status": "completed|partial|failed",
  "failures": []
}

Example: Code review orchestration:

{
  "orchestration": {"mode": "sequential", "sessionId": "abc123"},
  "agents": ["architecture-agent", "production-code-agent"],
  "results": {
    "architecture-agent": {"critical": 2, "errors": 5},
    "production-code-agent": {"critical": 0, "errors": 3}
  },
  "storage": {"agent_results": 2, "patterns": 12},
  "status": "completed"
}

Re-validation required after fixes. Repeat until ALL checks pass.

Reference

See claude-flow-patterns.md for advanced orchestration patterns See mongodb-vector-search.md for vector search optimization