Agent Orchestration in Amprealize

What It Is

Amprealize implements a supervisor-pattern multi-agent system where the orchestrator routes tasks to specialized agents based on role declarations, behavior conditions, and task requirements.

How It Maps to Concepts

AI/ML Concept	Amprealize Implementation
Multi-Agent Orchestration	`agent_orchestrator_service.py` — supervisor pattern
Prompt Engineering	Per-agent system prompts with role-specific instructions
RAG	Each agent call includes BCI-retrieved behaviors

Architecture

Task Request
    ↓
[Agent Orchestrator]
    ├── Role Detection (Student/Teacher/Strategist)
    ├── Behavior Retrieval (BCI)
    ├── Context Composition
    └── Agent Dispatch
         ↓
[Agent Execution Loop]
    ├── Tool Calls (MCP tools)
    ├── Self-Monitoring (adherence tracking)
    └── Result / Handoff
         ↓
[Handoff Work Item] (if ADOPT/ADAPT verdict)

Key Components

agent_orchestrator_service.py — Routes tasks to agents
agent_execution_loop.py — Runs the agent cycle (think → act → observe)
agent_registry_service.py — Registers available agents and their capabilities
execution_gateway_adapter.py — Lets REST and MCP start paths use ExecutionGateway while preserving legacy response contracts
adherence_tracker.py — Monitors whether agents follow their behaviors

Execution Gateway Start Boundary

Enterprise matches OSS for the GUIDEAI-1046 execution migration: REST and MCP work item execution starts route through ExecutionGateway by default. GatewayWorkItemExecutionAdapter preserves the legacy WorkItemExecutionService response shape for clients while forwarding start requests into the gateway contract.

AMPREALIZE_EXECUTION_GATEWAY_ENABLED=false remains as an explicit fallback for incident response. Normal runtime should treat the gateway as the canonical boundary where orchestration, source resolution, execution mode selection, and run/task-cycle creation begin.

For GUIDEAI-1047, Enterprise also supports queue-first gateway dispatch. In dispatch_mode="queue", the gateway creates the run and task-cycle records, links the run to the work item, and enqueues an ExecutionJob with a normalized GatewayQueuePayload. That payload keeps the agent worker grounded in the same request context the user saw: intent, surface, source, output target, chat links, policy evaluation, approval state, and idempotency key. If no queue publisher is configured, the gateway fails before creating orphaned execution records.

For GUIDEAI-1054, Enterprise also has the durable plan artifact contract. PlanArtifact gives plan-only chat and work item cards a stable plan ID, version history, links back to the message/work item/agent/source run, and explicit draft, approved, discarded, and executed states. Approval only makes the artifact eligible for a separate execution run; it does not rewrite the plan history.

For GUIDEAI-1055, Enterprise also supports plan-only as a first-class gateway mode. ExecutionIntent.PLAN_ONLY requests derive a read-only policy, deny write and platform-mutating tools, create a draft PlanArtifact, return a summary card, complete the gateway run as run_type=plan_only, and skip both queue dispatch and background executor launch. The result is a governed plan artifact, not an execution run with writes disabled after the fact.

For GUIDEAI-1056, Enterprise also has the approval bridge from plan artifact to execution. PlanApprovalService lets users revise or discard draft artifacts without starting work, and approve_and_start_execution() creates a fresh gateway ExecutionRequest with intent=execute, approval context, and the approved plan_artifact_id. The artifact is marked executed only after the new run is successfully created, keeping plan history separate from write-capable execution.

For GUIDEAI-1057, Enterprise also has the deterministic chat action router. ChatActionRouter converts user messages and preset commands into typed ChatActionCandidate objects for read/synthesis, work management, agent management, execution planning, execution start, MCP tools, attachments, and invite/share. Each candidate carries confidence, permission surface/action, required scopes, risk, and approval/clarification flags, giving governance and UI cards a shared pre-dispatch contract.

For GUIDEAI-1058, Enterprise also has the first governed platform-action boundary behind those candidates. AgentLifecycleActionService handles agent discovery, project assignment, custom-agent creation, tool/policy modification, publishing, and archive/delete requests. Before it dispatches to registry/project services, it evaluates PolicyCompositionEngine; sensitive operations require approval and every attempt emits a GovernedChatAuditLogger platform-action record.

For GUIDEAI-1059, Enterprise extends the same pattern to platform management. PlatformManagementActionService handles project, org, board, work item, invite/share, file, upload, image, and MCP-tool access actions. It validates target and scope before policy evaluation, requires approval for invites/shares and tool access changes, and dispatches only through configured typed services.

For GUIDEAI-1061, Enterprise also renders those governed moments as live chat artifacts. MessageBubble recognizes structured_payload.card_kind values for work items, runs, plan artifacts, and recovery prompts, so the transcript can show assignment state, execution queue/phase, plan review actions, progress, and blocked-run recovery without creating a separate message type for each artifact.

For GUIDEAI-1062, Enterprise keeps board, drawer, and chat controls aligned with a shared execution-control model. executionControls.ts normalizes gateway states such as queued, running, paused, clarification-needed, failed, completed, and cancelled, then derives the same active-run gating and action labels for board cards, WorkItemDrawer, and chat run artifact cards.

For GUIDEAI-1063 and GUIDEAI-1064, Enterprise also validates the gateway and chat-governance boundaries. Gateway parity tests compare REST, MCP, CLI-shaped, and chat-shaped start requests against the same ExecutionRequest signature, while chat governance tests prove global chat withholds inaccessible resources, group-chat execution uses conversation/project/agent scopes, MCP tool grants require approval, attachments require scope, and agent lifecycle mutations can be blocked before registry dispatch.

Handoff Pattern

When an agent's work produces an actionable verdict (e.g., research evaluation yields ADOPT), the orchestrator creates a work item for the next agent. This is the sequential pipeline pattern from Multi-Agent Orchestration.