Skip to content

Agent Runtime

Target Architecture — Final-State Design

The Agent Runtime is the heart of the Agent Mesh. It hosts agents on the Microsoft Agent Framework and drives a single agent execution through a fixed, governed pipeline: claim → context load → skill execution → model/tool invocation → validation → correction → event emission. This page is the deep dive into that pipeline.

Runtime Foundation: Microsoft Agent Framework

Implemented

Agents run on the Microsoft Agent Framework integrated through ConnectSoft.Extensions.AI.AgentsFramework. The reference shape is ConnectSoft.AI.SoftwareFactory.AgentTemplate, with its AgentFramework, AIModel, and ModelContextProtocol projects. Tooling is exposed over MCP via ConnectSoft.Extensions.ModelContextProtocol.

The runtime is hosted as the ConnectSoft.Factory.AgentMesh.AgentRuntimeService on .NET 10 / ASP.NET Core. It composes the Microsoft Agent Framework packages:

Package Use in the runtime
Microsoft.Agents.AI Core agent abstractions and execution.
Microsoft.Agents.AI.Abstractions Contracts shared across hosts and tools.
Microsoft.Agents.AI.OpenAI OpenAI / Azure OpenAI chat clients.
Microsoft.Agents.AI.AzureAI Azure AI Foundry model access.
Microsoft.Agents.AI.Workflows Multi-step agent workflows within an execution.
Microsoft.Agents.AI.Hosting ASP.NET Core hosting and DI integration.
Microsoft.Agents.AI.DevUI Local developer UI for inspecting agent runs.

Model access is unified through Microsoft.Extensions.AI; provider connectivity (Azure OpenAI / OpenAI / Ollama) is supplied by the Integration Platform and selected by the ModelRouterService. Execution state is cached in Redis; durable records persist via NHibernate on Azure SQL / PostgreSQL.

Agent Mesh Execution Diagram

The runtime executes every agent task through the same pipeline. This is the canonical Agent Mesh execution flow:

flowchart TB
    Start(["AgentTask available"]) --> Claim["Claim task<br/>(AgentTaskService)"]
    Claim --> Pool["Acquire agent instance<br/>(AgentPoolManager)"]
    Pool --> Context["Load context package<br/>(Knowledge ContextBuilder)"]
    Context --> Resolve["Resolve skill + version<br/>(SkillRegistry)"]
    Resolve --> Exec["Execute skill on<br/>Microsoft Agent Framework"]
    Exec --> Decide{"Needs model<br/>or tool?"}
    Decide -->|"model"| Model["Invoke model<br/>(ModelRouterService)"]
    Decide -->|"tool"| Tool["Invoke tool over MCP<br/>(ToolAdapterService)"]
    Model --> Produce["Produce output artifacts"]
    Tool --> Produce
    Exec --> Produce
    Produce --> Validate["Validate output<br/>(AgentValidationService)"]
    Validate --> Pass{"Validation<br/>passed?"}
    Pass -->|"yes"| Emit["Emit events + register artifacts"]
    Pass -->|"no"| Correct{"Attempts<br/>remaining?"}
    Correct -->|"yes"| Feedback["Apply correction feedback<br/>(AgentCorrectionService)"]
    Feedback --> Exec
    Correct -->|"no"| Fail["Fail task → human escalation"]
    Emit --> Done(["AgentTaskCompleted"])
    Fail --> Done2(["AgentTaskFailed"])
Hold "Alt" / "Option" to enable pan & zoom

Pipeline Stages

1. Task claiming

The AgentTaskService exposes assigned agent tasks. The runtime claims a task idempotently — re-delivery of the same taskId never starts a duplicate AgentExecution. Claiming records the traceId and correlationId so the whole run is correlatable.

2. Agent acquisition (pooling)

The AgentPoolManager provides a warm agent instance of the required role and version, avoiding cold-start latency. Pools are sized per tenant and per cluster, and unhealthy instances are drained based on AgentHealthStatus. See Agent Registry for pool definitions.

3. Context loading

Before any model call, the runtime requests a governed context package from the Knowledge Context Builder:

sequenceDiagram
    participant RT as AgentRuntimeService
    participant CB as ContextBuilderService
    RT->>CB: BuildContextPackage(taskId, scope, tokenBudget)
    CB-->>RT: ContextPackage (sources, ttl, policyDecisionId)
    RT->>RT: bind context to prompt within budget
Hold "Alt" / "Option" to enable pan & zoom

The runtime never fabricates context — execution is always grounded in the returned package, and the contextPackageId is recorded on the AgentExecution for traceability and quality attribution.

4. Skill execution

The runtime resolves the requested skill and version from the Skill Registry, validates inputs against the skill contract, and runs it on the Microsoft Agent Framework (optionally as a Microsoft.Agents.AI.Workflows workflow for multi-step skills). Each skill run is recorded as a SkillExecution.

5. Model routing

When a skill needs inference, the ModelRouterService selects a provider and model by evaluating the task's modelPolicyId, tenant routing rules, capability requirements, cost, and availability.

flowchart LR
    Skill["Skill execution"] --> Router["ModelRouterService"]
    Router --> Policy["Evaluate model policy + tenant routing"]
    Policy --> Provider{"Selected provider"}
    Provider -->|"Azure OpenAI"| AOAI["Azure OpenAI"]
    Provider -->|"OpenAI"| OAI["OpenAI"]
    Provider -->|"Ollama"| OLL["Ollama (self-hosted)"]
    AOAI --> Record["Record ModelInvocation"]
    OAI --> Record
    OLL --> Record
Hold "Alt" / "Option" to enable pan & zoom

Every call is captured as a ModelInvocation (provider, model, tokens, latency, cost) for the AgentTelemetryService. Provider connections themselves are owned by the Integration Platform.

6. Tool adapters (MCP)

Tools — repository access, template scaffolding, validators, search — are exposed to agents over the Model Context Protocol through the ToolAdapterService (built on ConnectSoft.Extensions.ModelContextProtocol). Every call is governed (permission-scoped per agent) and recorded as a ToolInvocation.

7. Validation and correction

Outputs are validated by the AgentValidationService against schema, naming, dependency, and policy rules, producing a ValidationResult. On failure, the AgentCorrectionService constructs feedback and re-runs the skill, recording each CorrectionAttempt. Correction is bounded by maxCorrectionAttempts; exceeding it fails the task to human escalation in the Factory Studio review surface.

8. Event emission

Every state transition emits an event in the canonical envelope on Azure Service Bus via MassTransit: AgentExecutionStarted, ModelInvoked, ToolInvoked, ValidationFailed, CorrectionAttempted, and finally AgentTaskCompleted or AgentTaskFailed. See Events.

9. Observability

The AgentTelemetryService aggregates model and tool invocations into metrics and OpenTelemetry traces stitched on traceId, flushed to Application Insights / OTEL collectors. This feeds the Observability & Feedback Platform, closing the improvement loop.

Runtime Building Blocks Summary

Concern Owner service
Hosting & execution orchestration AgentRuntimeService
Task lifecycle AgentTaskService
Execution records AgentExecutionService
Model selection & calls ModelRouterService
Tool calls (MCP) ToolAdapterService
Validation AgentValidationService
Correction AgentCorrectionService
Telemetry AgentTelemetryService
Pooling & health AgentPoolManager