agent-orchestrator

Agent Orchestrator — Production Best Practices

Patterns from a production multi-agent system. The body is decisions; the mechanisms are one file away, and it is held under a 4750-token budget — a body that grows absorbs the layer that should have been split, and this one did until 2026-08-16.

Triggers

"tool calling", "LLM router", "fallback chain", "memory layer", "token wallet", "роутер моделей", "слой памяти", "граф задач".

Also routed here by scope, the list the description carried until 0.30.0: tool-calling loops, human-checkpoint pipelines, provider routing, fallback/retry, memory architecture, retrieval and decay, context budgets, sub-agent coordination, error hierarchies; the work as a graph (parallel layers, fake edges, a checker before convergence); for resale: tiered wallets, one markup boundary, the saga across database and provider API, spend-delta polling, budget and loop guards, per-tenant keys.

Architecture Overview

User Question
    ↓
OrchestratorAgent.run(AgentContext)
    ├─ Shape check → one loop, or a planned path (§5, references/pipeline.md)
    ├─ Context loading (a parallel layer: staleness, sources, KB — §13)
    ├─ History trimming, then context budget allocation
    ├─ System prompt built from the live capabilities (§10)
    └─ Execute:
        ├─ SIMPLE: LLM → tools → sub-agents → results → LLM → … → answer   (§2)
        └─ PLANNED: plan → dependency layers → checker → checkpoints → done (§5)

1. The Orchestrator Pattern

Shared Context Object

Pass a single immutable-ish context object to every sub-agent. It carries the request (project_id, user_question, chat_history), the machinery (llm_router, tracker, workflow_id), the resolved provider and model, and one extra dict for pipeline flags. The full dataclass is in references/patterns.md → The orchestrator's shared context and sub-agent protocol.

Key principles:

• Sub-agents never modify context — they return typed results
• Provider/model preferences flow down from user → project defaults → app defaults
• extra dict carries pipeline state, flags like _skip_complexity, session IDs