AgentRuntimeWorker

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-06 Execution
Platform / plane	Agent Mesh / Agent & Orchestration runtime
Deployment granularity	standalone host
Status	target · ConnectSoft.Factory.Runtime
Built from	connectsoft-ai-agent · libraries: connectsoft-extensions-ai, connectsoft-extensions-ai-agents-framework, connectsoft-extensions-ai-factory, connectsoft-extensions-model-context-protocol, connectsoft-extensions-messaging-model, connectsoft-extensions-messaging-model-orleans, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-saas-abstractions, connectsoft-extensions-saas-asp-net-core, connectsoft-extensions-observability
Decisions	ADR-0001, ADR-0012, ADR-0014, ADR-0016, ADR-0017, ADR-0022
Traceability	FR-03 FR-10 FUX-04 FUX-07 NFR-05 NFR-06 NFR-08 NFR-13 XL-06 XL-16

Purpose and responsibilities

AgentRuntimeWorker is the physical host of the Agent Mesh. It composes two modules, AgentRuntimeService (attempt execution, BC-06) and WorkflowEngineService (workflow definitions and engine, BC-38), into one worker process built from the ConnectSoft AI agent host template with the worker template's hosting shape: no public API beyond health and metadata, an Orleans silo for attempt and workflow-run grains, a messaging inbox and outbox over the MessagingModel port, and one NHibernate session factory over the runtime-sql store.

The host owns no domain state. Its responsibilities are composition, the execution adapter (Microsoft Agent Framework by default), workload identity towards the Control plane and the executors, capacity advertisement to Execution Capacity (BC-26), and the transactional infrastructure that lets a module commit its rows and its outbox record together.

Context and boundaries

flowchart LR
    S["AgentRuntimeWorker"]
    ControlPlaneApi["ControlPlaneApi"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| ControlPlaneApi["ControlPlaneApi"]
    S -->|grpc| ModelGatewayHost["ModelGatewayHost"]
    S -->|grpc| ToolExecutorHost["ToolExecutorHost"]
    S -->|grpc| KnowledgeHost["KnowledgeHost"]
    S -->|grpc| RuntimeCloudHost["RuntimeCloudHost"]
    S -->|sync-http| ext_identity_platform["ext-identity-platform"]

Hold "Alt" / "Option" to enable pan & zoom

The worker never receives a run from a client. Work arrives as AttemptDispatched events from Run Control with a lease and a fencing token; everything the worker does afterwards carries that token, and the only way an attempt ends is a single outcome report back to Run Control. Model calls go to the Model & Compute gateway, tool calls to the Tools & MCP executor, context to Knowledge, artifacts to the artifact store. The worker has no credentials of its own for any external system.

flowchart LR
    subgraph Host["AgentRuntimeWorker (2 to 20 replicas)"]
        direction TB
        Inbox["Inbox: AttemptDispatched, ApprovalDecided, RunCancelled, LeaseExpired, releases"]
        Exec["AgentRuntimeService<br/>AttemptGrain per attempt"]
        Engine["WorkflowEngineService<br/>WorkflowRunGrain per run"]
        Adapter["Execution adapter: Microsoft Agent Framework"]
        Outbox["Outbox dispatcher"]
    end
    CP["ControlPlaneApi"] -- events --> Inbox
    Inbox --> Exec & Engine
    Exec --> Adapter
    Exec -- gRPC --> CP
    Engine -- events --> Outbox --> CP
    Adapter --> MG["ModelGatewayHost"] & TE["ToolExecutorHost"] & KH["KnowledgeHost"]
    Exec --> SQL["('runtime-sql')"]
    Engine --> SQL

Hold "Alt" / "Option" to enable pan & zoom

Domain model

None modelled

No aggregates are modelled for this item yet.

No entities modelled.

The host has no aggregates; see the two module pages.

Entities and value objects

None modelled

No entities or value objects are modelled for this item yet.

Data model and storage

Store	Role	Engine / profile	Tables
Runtime worker durable store	primary	azure-sql / nhibernate-sqlserver	—
Cache and coordination	cache	redis / azure-cache	—

None modelled

No tables are modelled for this item yet.

runtime-sql is owned by this host and is separate from control-sql: the worker's journal of attempts and checkpoints must survive and restore independently of the Control plane (restore order: run journal first, then this store, D30). Adapter checkpoints and produced artifacts are blobs in artifact-blob referenced by hash.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/runtime/health	RuntimeHealth	factory.health.read	read	natural	GW-01	Liveness, readiness (store, silo, control plane reachability, model gateway, tool executor) and capacity of this worker.
GET	/runtime/meta/modules	RuntimeModules	factory.meta.read	read	natural	GW-03	Runtime adapter version, checkpoint format version, loaded modules and supported tool schema versions; used for release compatibility checks.

None modelled

No gRPC methods are modelled for this item yet.

Messages

None modelled

No events are modelled for this item yet.

None modelled

No commands are modelled for this item yet.

None modelled

No consumed events are modelled for this item yet.

Workers and jobs

None modelled

No workers are modelled for this item yet.

Actors and grains

None modelled

No grains are modelled for this item yet.

The silo hosts AttemptGrain and WorkflowRunGrain from the modules; placement is per tenant and run so that a run's attempts and its workflow projection stay on the same replica when possible.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Runtime:Host	EnabledModules	string[]	[attempt-execution, workflow-engine]	no	no	Modules composed into this worker.
Runtime:Host	PoolId	string	default	no	no	Execution capacity pool (BC-26) this worker registers with.
Runtime:Host	MaxConcurrentAttempts	int	8	yes	no	Attempts one replica executes at once; advertised to capacity.
Runtime:Adapter	Kind	enum	maf	no	no	Execution adapter (maf = Microsoft Agent Framework); the checkpoint format version is derived from it.
OrleansMessaging	ServiceName	string	runtime	no	no	Messaging profile service name for the inbox and outbox.
ConnectSoftIdentityPlatform	WorkloadIdentity	string	spiffe://connectsoft.ai/factory/runtime	no	no	Workload identity presented to the Control plane and executors (ADR-0101).

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.runtime.host.attempt_slots	gauge	{slot}	pool, replica	Free attempt slots advertised to capacity.
connectsoft.factory.runtime.host.inbox_lag	gauge	s	replica	Age of the oldest unprocessed inbox message.
connectsoft.factory.runtime.host.control_plane_rtt	histogram	s	method	Round-trip time of Run Control gRPC calls.

Security

Authentication	client-credentials
Scopes	factory.health.read (Health probes.); factory.meta.read (Adapter and module metadata.)
Roles	Operator, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	production
Secrets	runtime-sql (key-vault, rotate 90 d); messaging-transport (key-vault, rotate 90 d); workload-identity-key (key-vault, rotate 30 d)

The worker authenticates with a workload identity (SPIFFE-style id issued by the Authorization Server) and derives a per-attempt token from the lease for its calls to the executors; it never holds tenant user credentials. Sandboxes for shell, file and browser tools are brokered by Execution Capacity and Tools & MCP, never opened by the worker process itself.

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
ControlPlaneApi	grpc	Leases, outcomes, approvals, release loading (Run Control and Asset Publication modules).	fail-fast	yes
ModelGatewayHost	grpc	Model invocations through the gateway.	degrade	yes
ToolExecutorHost	grpc	Tool and MCP invocations with side-effect classes.	fail-fast	yes
KnowledgeHost	grpc	Context assembly and artifact storage.	degrade	yes
RuntimeCloudHost	grpc	Capacity registration and sandbox brokering (BC-26).	degrade	no
ext-identity-platform	sync-http	Workload identity tokens.	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
ControlPlaneApi	grpc	Interrupt requests and timeline reads.	—	yes
StudioBff	sync-http	Attempt timeline and workflow-run graph reads.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Control plane unreachable	lease renewal failures	attempts pause at the next checkpoint; after the lease grace period the Control plane reconciles them; no outcome is invented	none	15
Worker replica crash	Orleans membership and lease expiry	attempt grains re-activate on another replica from the last checkpoint when compatible; otherwise Run Control starts a new attempt	work since the last checkpoint	5
Model gateway degraded	invocation errors and latency	fallback chain of the model profile; attempt fails with class transient when exhausted	none	30

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	standalone host
Topologies	saas-default, hybrid, on-prem, hybrid-compute
Runtime	aks; replicas 2–20
Ports	https 7500, grpc 7502, silo 11500, gateway 30500

Runs on AKS in every profile; in the hybrid profile the worker runs inside the customer's network and reaches the Control plane over a private link, which is the reason the worker has no inbound public surface. In hybrid-compute the worker stays in ConnectSoft's cloud and only the model and compute pools move.

Current implementation

The AI agent host template exists (29 projects) with three entry paths that call AIAgent.RunAsync directly, an Orleans grain that is a credit counter, Hangfire jobs that only log and a MassTransit saga scaffold; FactoryAgentBase provides the accept → prompt → run → validate → retry loop without persistence, lease or run identity. The template is the starting point for this host (ecosystem component status "extend").

Later capabilities

Worker pools per model profile class (GPU-adjacent workers); warm adapter sessions for latency-sensitive workflows; a second execution adapter passing the same contract suite (durability spike).

Decisions and traceability

Family	Ids
FR	FR-03, FR-10
FUX	FUX-04, FUX-07
NFR	NFR-05, NFR-06, NFR-08, NFR-13
XL	XL-06, XL-16

Related

• Agent Mesh overview · Deployment · Security · Durability spike

• AgentRuntimeService · WorkflowEngineService · ControlPlaneApi

• Agent Mesh microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map