{"slug":"architecture/ADX_ORCHESTRATOR","title":"ADX Orchestrator & Agent Runtime","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/ADX_ORCHESTRATOR.mdx","bytes":6063,"description":"The brain that coordinates all agent activity — orchestration, runtime, workflows, and agent hand-off","updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n**Orchestration Engine + Agent Runtime + Workflow Engine.**\n\nThe ADX Orchestrator is the brain that coordinates all agent activity in SpineWorkspace. It manages the lifecycle of every agent action, from task decomposition to execution to reconciliation.\n\n## Design Principles\n\n1. **Single orchestrator** — One engine coordinates all agent activity\n2. **Task decomposition** — Complex work is broken into executable units\n3. **Context assembly** — Every agent gets the right context\n4. **Agent hand-off** — Work flows between agents via A2CP\n5. **Observable** — Every action is traced and logged\n\n---\n\n## Components\n\n| Component | Purpose |\n|-----------|---------|\n| **Orchestration Engine** | Coordinates multi-step agent workflows |\n| **Agent Runtime** | Executes individual agent actions |\n| **Workflow Engine** | Manages complex business processes |\n| **Task Decomposition** | Breaks work into executable units |\n| **Context Assembly** | Builds the context window for agents |\n| **Agent Hand-off (A2CP)** | Transfers work between agents |\n| **State Management** | Tracks workflow and agent state |\n| **Scheduling** | Time-based and event-based triggers |\n| **Retries** | Automatic retry on failure |\n| **Monitoring** | Observability and alerting |\n\n---\n\n## Orchestration Flow\n\n```\nWork Item → Task Decomposition → Context Assembly → Agent Selection → Execution → Reconciliation → Memory\n```\n\n1. **Work Item** — A work item enters the orchestration pipeline\n2. **Task Decomposition** — Broken into atomic, executable tasks\n3. **Context Assembly** — Each task gets the right context from the Spine\n4. **Agent Selection** — The right agent is selected based on capability and role\n5. **Execution** — The agent executes the task\n6. **Reconciliation** — Outcome is verified against intent\n7. **Memory** — Learning is fed back to the Spine\n\n---\n\n## Task Decomposition\n\nComplex work is broken into atomic tasks:\n\n| Level | Description | Example |\n|-------|-------------|---------|\n| **Work Item** | High-level business objective | \"Close Q3 deal with Acme\" |\n| **Task Group** | Related set of tasks | \"Prepare proposal\", \"Schedule review\" |\n| **Task** | Single executable unit | \"Draft proposal document\" |\n| **Action** | Atomic operation | \"Insert pricing table into doc\" |\n\n### Decomposition Rules\n\n- Each task has a single owner (human or agent)\n- Each task has clear input/output contracts\n- Tasks can be parallel or sequential\n- Dependencies are explicit and enforced\n\n---\n\n## Context Assembly\n\nEvery agent receives a context window built from the Spine:\n\n```typescript\ninterface AgentContext {\n  workItem: WorkItem;           // The current work item\n  entityContext: Entity[];      // Related entities\n  eventHistory: Event[];        // Recent events\n  communicationHistory: Message[]; // Recent messages\n  decisions: Decision[];        // Related decisions\n  risks: Risk[];                // Identified risks\n  userPreferences: Preferences; // How the user works\n  domainKnowledge: Knowledge[]; // Organizational patterns\n}\n```\n\n### Context Rules\n\n- Context is role-scoped — agents only see what their role allows\n- Context is time-bounded — recent events weighted more heavily\n- Context is relevance-scored — most relevant information surfaces first\n- Context is token-budgeted — fits within model context limits\n\n---\n\n## Agent Selection\n\nThe orchestrator selects agents based on:\n\n| Factor | Description |\n|--------|-------------|\n| **Capability match** | Agent has the required capability |\n| **Role scope** | Agent's role matches the work domain |\n| **Availability** | Agent is not overloaded or offline |\n| **Performance** | Historical success rate for similar tasks |\n| **Cost** | Token and compute cost within budget |\n\n---\n\n## Agent Hand-off (A2CP)\n\nThe Agent-to-Agent Communication Protocol enables work transfer:\n\n```\nAgent A → A2CP Message → Agent B\n```\n\n### A2CP Message Format\n\n```typescript\ninterface A2CPMessage {\n  from: AgentRef;\n  to: AgentRef;\n  workItem: WorkItemRef;\n  context: ContextSnapshot;\n  intent: string;\n  constraints: Constraint[];\n  deadline?: string;\n}\n```\n\n### Hand-off Rules\n\n- Hand-offs are logged in the Spine\n- Context is transferred, not lost\n- The receiving agent can accept, reject, or delegate\n- Hand-offs are governed — high-risk transfers require approval\n\n---\n\n## State Management\n\nThe orchestrator tracks state for every workflow:\n\n| State | Description |\n|-------|-------------|\n| **Identified** | Work item recognized |\n| **Contextualizing** | Gathering context |\n| **Defined** | Tasks decomposed and assigned |\n| **Allocated** | Agents assigned to tasks |\n| **Deciding** | Agent reasoning in progress |\n| **Governing** | Governance check pending |\n| **Executing** | Task being executed |\n| **Observing** | Monitoring execution outcome |\n| **Re-ingesting** | Processing execution results |\n| **Reconciling** | Verifying intent vs. outcome |\n| **Resolved** | Work item completed |\n| **Learning** | Feeding back to memory |\n| **Continuing** | Next cycle beginning |\n\n---\n\n## Scheduling\n\n| Trigger | Description |\n|---------|-------------|\n| **Event-driven** | Triggered by Spine events |\n| **Time-based** | Cron-like scheduled execution |\n| **Dependency-driven** | Triggered when prerequisites complete |\n| **Manual** | Triggered by human action |\n| **Agent-initiated** | Triggered by agent recommendation |\n\n---\n\n## Monitoring & Observability\n\n| Metric | Description |\n|--------|-------------|\n| **Task completion rate** | Percentage of tasks completed successfully |\n| **Average execution time** | Time from task start to completion |\n| **Agent utilization** | How busy each agent is |\n| **Error rate** | Percentage of tasks that fail |\n| **Retry rate** | Percentage of tasks requiring retry |\n| **Context quality** | How well context assembly performs |\n"}