Agent & Orchestration runtime plane¶
Target
This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.
The runtime executes attempts of steps of a run whose release, policy and model profile the Control plane pinned. It reports outcomes through owner contracts; it does not complete a run on its own authority.
Responsibilities¶
| Responsibility | Target behaviour |
|---|---|
| One execution port | REST, MCP, queue, workflow, IDE and chat entry points invoke the same application port; raw framework calls (AIAgent.RunAsync) stay behind the adapter |
| Resolution | Resolve agent version, skills, tool schemas, policies, model profile, knowledge scope, memory policy and budget into an immutable execution snapshot |
| Loop | Build context → plan → model call → tool call → observe → update state → next step → verification → result |
| Durable execution | Persist input, resolved versions, model decisions, plan, steps, LLM and tool calls, context snapshots, approvals, checkpoints, artifacts, errors, result; resumable after worker loss |
| Run states | Pending/Created, Queued, Running, WaitingForTool, WaitingForApproval, Paused, Retrying, Completed, Failed, Cancelled (proposed vocabulary; see ADR-0014) |
| Verification and correction | Schema-constrained output, validation before deserialization and before downstream actions, bounded correction attempts ending in explicit failure or escalation |
| Human interaction | Stop and request a decision with options, recommendation and risk; approvals bound to exact versions; escalation and assignment |
| Workflows | Deterministic DAG orchestration (conditions, retries, compensation, timers, approvals, agent/tool/human steps) coexisting with dynamic agent reasoning |
| Multi-agent | Supervisor/sub-agent delegation only when task complexity justifies it; same run authority and approval semantics |
| Multi-turn | Conversation state outside the model: recent turns + state summary + relevant evidence; never resend full history |
| Recovery | Resume from a compatible checkpoint or record a new attempt; uncertain external effects reconciled before retry; cancellation request distinct from observed termination |
Current implementation¶
ConnectSoft.Extensions.AI.FactoryFactoryAgentBase: Accepted → prompt →AIAgent.RunAsync→ validate → retry (default 3) → Completed, or Escalated + Failed on exhaustion. Exceptions and cancellation rethrow without a terminal event; noCancelledstage exists. No persistence, checkpoint, idempotency or run identity.ConnectSoft.Extensions.AI.AgentsFramework: keyed agents with missing-service fallback (not provider failover), explicit tools, RAG, file skills (script runner disabled), in-memory chat history, optional DevUI endpoints.- Agent host template: three entry paths — lifecycle path, MCP sample tool (direct
RunAsync, enabled by default), REST sample use case (hardcoded prompt) — plus DevUI when enabled. Orleans grain is a credit counter; Hangfire jobs only log; MassTransit saga is a scaffold. - Platform repo: six placeholder duckflux workflows; docs name a Go CLI; nothing executes them.
- Unit tests: 7 (Factory) and 29 (adapter) as last reported by the 2026-10-08 packet; not re-run.
Existing pages that belong to this plane¶
- Agent Mesh overview, agent clusters, agent runtime, task contracts, APIs, workers, events, aggregate roots, storage, security
- Agent system overview, agent execution flow, agent collaboration patterns
- Orchestration layer, orchestration domain, agentic system design, human–agent collaboration, coordinators
- Execution engine, failure and recovery
- Reference: agent task contract
Later capabilities¶
Folded from the former Agent Mesh extension roadmap (no dates, no commitments). Extension principles that remain valid: registry-first (new capability is a published release, not a runtime change); contract-stable; governed by default; grounded and observable; provider-agnostic behind the model gateway; MCP-extensible tools.
| Candidate | Purpose | Owner today |
|---|---|---|
| Continuous and A/B evaluation of agent versions; prompt-drift detection; prompt and skill optimization from feedback | Quality loop | BC-22 (Trust & Operations) |
| Replay-based simulation of runs against historical traces | Regression safety | BC-22, after run journal exists (ADR-0014 makes no replay promise yet) |
| Real-time token/cost governor and budget enforcement; model failover orchestration per policy | Cost and reliability | BC-05 / BC-07 |
| Long-running multi-agent coordinator beyond deterministic workflows | Supervisor/sub-agent delegation | BC-06 |
Agent pack installation from a marketplace; POST /agent-packs/install, evaluation and usage queries, policy dry-run |
Distribution and inspection APIs | BC-27 / BC-29 |
| Vertical, compliance, skill-library, tool-adapter and model-policy packs | Marketplace packs | BC-27 |
| Cost-optimization, prompt-engineering, reliability, cross-tenant insight (strictly anonymized), compliance-auditor and knowledge-curation agents | New agent roles | Software Factory pack |
Capability-based agent discovery, agent contracts and delegation, goal-oriented operation and additional runtime adapters passing the same contract suite remain long-term directions from the Oct-2026 target. OpenClaw is not a Factory adapter target (D19).
Platform design pages (2026-10-09, design plan P2)¶
- Narrative: overview · workflows · UI surfaces · security · observability · deployment · later capabilities · durability spike
- Service design pages: AgentRuntimeWorker (host) · AgentRuntimeService · WorkflowEngineService
Open questions¶
The workflow durability adapter spike was written on 2026-10-09 (durability spike); its recommendation is ADR-0024, Accepted by the product owner on 2026-10-12 (D46). Q-07 was decided on 2026-10-09 (D21, approvals).
Modernization (2026-10-09, design plan M1)¶
Horizon now to next, per the technology radar: Microsoft Agent Framework as the execution adapter; durable execution on Orleans grains with the journal (ADR-0024 Accepted); supervisor topologies as bounded workflows. Exists in ConnectSoft today: AgentsFramework 1.21.0 and the agent host template exist; three entry paths must converge. Each platform page of this plane states its horizon in its overview and later-capabilities pages.
Platforms in this plane¶
| Platform | Bounded contexts | Services | Modelled | Pages |
|---|---|---|---|---|
| Agent Mesh (PF-02) | BC-06, BC-38 | 6 | 3 | overview · services · APIs · events |
Bounded contexts¶
| Context | Platform | Authoritative state |
|---|---|---|
| BC-06 Execution | Agent Mesh | Attempt execution, adapter checkpoint references, outcomes reported to BC-03 |
| BC-38 Workflow Definitions & Engine | Agent Mesh | Workflow definition versions, DAG semantics, compensation and timers, workflow run state projected to BC-03 |
Services¶
| Service | Platform | Context | Granularity | Status | Page |
|---|---|---|---|---|---|
| AgentCorrectionService | Agent Mesh | BC-06 | module of host | unmodelled | — |
| AgentExecutionService | Agent Mesh | BC-06 | module of host | unmodelled | — |
| AgentRuntimeService | Agent Mesh | BC-06 | module of host | target | design |
| AgentRuntimeWorker | Agent Mesh | BC-06 | standalone host | target | design |
| AgentValidationService | Agent Mesh | BC-06 | module of host | unmodelled | — |
| WorkflowEngineService | Agent Mesh | BC-38 | module of host | target | design |
Events crossing the plane boundary¶
| Direction | Event | Producer | Consumer | Topic |
|---|---|---|---|---|
| out | AttemptStarted | AgentRuntimeService | StudioBff | execution.attempts.v1.attempt-started |
| out | AttemptStarted | AgentRuntimeService | DashboardService | execution.attempts.v1.attempt-started |
| out | AttemptStarted | AgentRuntimeService | QualityScoreService | execution.attempts.v1.attempt-started |
| out | AttemptPhaseChanged | AgentRuntimeService | StudioBff | execution.attempts.v1.attempt-phase-changed |
| out | AttemptPhaseChanged | AgentRuntimeService | DashboardService | execution.attempts.v1.attempt-phase-changed |
| out | AttemptCheckpointed | AgentRuntimeService | DashboardService | execution.attempts.v1.attempt-checkpointed |
| out | AttemptDecisionRequested | AgentRuntimeService | StudioBff | execution.attempts.v1.attempt-decision-requested |
| out | AttemptDecisionRequested | AgentRuntimeService | StudioNotificationService | execution.attempts.v1.attempt-decision-requested |
| out | AttemptDecisionRequested | AgentRuntimeService | DashboardService | execution.attempts.v1.attempt-decision-requested |
| out | AttemptCancellationObserved | AgentRuntimeService | StudioBff | execution.attempts.v1.attempt-cancellation-observed |
| out | AttemptCancellationObserved | AgentRuntimeService | DashboardService | execution.attempts.v1.attempt-cancellation-observed |
| out | AttemptOutcomeReported | AgentRuntimeService | MemoryPromotionService | execution.attempts.v1.attempt-outcome-reported |
| out | AttemptOutcomeReported | AgentRuntimeService | DashboardService | execution.attempts.v1.attempt-outcome-reported |
| out | AttemptOutcomeReported | AgentRuntimeService | QualityScoreService | execution.attempts.v1.attempt-outcome-reported |
| out | SubAgentDelegated | AgentRuntimeService | StudioBff | execution.attempts.v1.sub-agent-delegated |
| out | SubAgentDelegated | AgentRuntimeService | DashboardService | execution.attempts.v1.sub-agent-delegated |
| out | ReleaseLoaded | AgentRuntimeService | DashboardService | execution.releases.v1.release-loaded |
| out | ReleaseLoadRejected | AgentRuntimeService | StudioBff | execution.releases.v1.release-load-rejected |
| out | ReleaseLoadRejected | AgentRuntimeService | DashboardService | execution.releases.v1.release-load-rejected |
| out | ReleaseLoadRejected | AgentRuntimeService | AuditService | execution.releases.v1.release-load-rejected |
| out | WorkflowDefinitionLoaded | WorkflowEngineService | DashboardService | workflows.definitions.v1.workflow-definition-loaded |
| out | WorkflowRunStarted | WorkflowEngineService | StudioBff | workflows.runs.v1.workflow-run-started |
| out | WorkflowRunStarted | WorkflowEngineService | DashboardService | workflows.runs.v1.workflow-run-started |
| out | StepReady | WorkflowEngineService | RunControlService | workflows.runs.v1.step-ready |
| out | StepReady | WorkflowEngineService | DashboardService | workflows.runs.v1.step-ready |
| out | StepRunStateChanged | WorkflowEngineService | StudioBff | workflows.runs.v1.step-run-state-changed |
| out | StepRunStateChanged | WorkflowEngineService | DashboardService | workflows.runs.v1.step-run-state-changed |
| out | TimerFired | WorkflowEngineService | DashboardService | workflows.runs.v1.timer-fired |
| out | CompensationStarted | WorkflowEngineService | StudioBff | workflows.runs.v1.compensation-started |
| out | CompensationStarted | WorkflowEngineService | DashboardService | workflows.runs.v1.compensation-started |
| out | CompensationStarted | WorkflowEngineService | AuditService | workflows.runs.v1.compensation-started |
| out | WorkflowRunCompleted | WorkflowEngineService | RunControlService | workflows.runs.v1.workflow-run-completed |
| out | WorkflowRunCompleted | WorkflowEngineService | StudioBff | workflows.runs.v1.workflow-run-completed |
| out | WorkflowRunCompleted | WorkflowEngineService | DashboardService | workflows.runs.v1.workflow-run-completed |
| out | WorkflowRunFailed | WorkflowEngineService | RunControlService | workflows.runs.v1.workflow-run-failed |
| out | WorkflowRunFailed | WorkflowEngineService | StudioBff | workflows.runs.v1.workflow-run-failed |
| out | WorkflowRunFailed | WorkflowEngineService | DashboardService | workflows.runs.v1.workflow-run-failed |
| out | WorkflowRunCancelled | WorkflowEngineService | DashboardService | workflows.runs.v1.workflow-run-cancelled |
| in | AssetReleasePublished | AgentRegistryService | WorkflowEngineService | asset-publication.releases.v1.asset-release-published |
| in | AssetReleasePublished | AgentRegistryService | AgentRuntimeService | asset-publication.releases.v1.asset-release-published |
| in | AssetReleaseDeprecated | AgentRegistryService | AgentRuntimeService | asset-publication.releases.v1.asset-release-deprecated |
| in | AssetReleaseRevoked | AgentRegistryService | AgentRuntimeService | asset-publication.releases.v1.asset-release-revoked |
| in | RunAccepted | RunControlService | WorkflowEngineService | run-control.runs.v1.run-accepted |
| in | RunCancelled | RunControlService | WorkflowEngineService | run-control.runs.v1.run-cancelled |
| in | RunCancelled | RunControlService | AgentRuntimeService | run-control.runs.v1.run-cancelled |
| in | AttemptDispatched | RunControlService | AgentRuntimeService | run-control.attempts.v1.attempt-dispatched |
| in | AttemptOutcomeRecorded | RunControlService | WorkflowEngineService | run-control.attempts.v1.attempt-outcome-recorded |
| in | LeaseExpired | RunControlService | AgentRuntimeService | run-control.leases.v1.lease-expired |
| in | ApprovalDecided | RunControlService | WorkflowEngineService | run-control.approvals.v1.approval-decided |
| in | ApprovalDecided | RunControlService | AgentRuntimeService | run-control.approvals.v1.approval-decided |
| in | ToolEffectUncertain | ToolAdapterService | AgentRuntimeService | tool-execution.invocations.v1.tool-effect-uncertain |
| in | DeliveryReceived | ConnectorRegistryService | WorkflowEngineService | connectors.deliveries.v1.delivery-received |
| in | DeletionOrderIssued | RetentionResidencyService | AgentRuntimeWorker | data-foundations.orders.v1.deletion-order-issued |
Gateways¶
No gateway role is anchored in this plane.
Model coverage¶
| Count | |
|---|---|
| Services in the registry | 6 |
| Modelled (YAML exists) | 3 |
| With a design page | 3 |
| Unmodelled | 3 |