Skip to content

AIFACTORY-FEAT-096: Agent host template: one execution port and Factory scope

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 2 of 185 (Templates and libraries)

Before development

Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).

The agent host template carries the Factory scope on every entry point and converges its lifecycle, MCP, REST and development entry points on one execution port, so that every run enters the same way. AgentRuntimeService and WorkflowEngineService are scaffolded from it. Component: AI Agent host template (extend).

Delivers —
Stubs —
Realizes components: cmp-agent-template
Requirements —
Depends on —
Sources model/components.yaml, docs/architecture/ecosystem-composition.md

AIFACTORY-US-136: Agent host template: the Factory scope travels on the trace context of the Factory libraries and every entry point refuses a request without it

enabling · persona asset-maintainer As an asset maintainer, I want every entry point of a generated agent host to bind the trusted tenant, project, run, step and attempt identity into the scoped trace context of the Factory libraries, so that no attempt executes without the scope that Run Control, the policy engine and the audit trail attribute it to.

The trace context a generated agent host carries is AgentTraceContext of the library ConnectSoft.Extensions.AI.Factory.Abstractions, which today holds trace id, blueprint id, agent origin and workflow step and nothing else. ADR-0014 makes tenant id, project id, run id, step id and attempt id required on every Factory message, keeps the trace id as diagnostic correlation that is never an authorization or idempotency key, and places the additive change on the shared libraries. The library feature component-extensions-ai extends the type: the tenant and project scope under AIFACTORY-TASK-161 and the run id, step id, attempt id and schema version in a PBI of that feature, where D113 places them; this PBI consumes the result by pin. The template pins the versions of ConnectSoft.Extensions.AI.Factory.Abstractions and ConnectSoft.Extensions.AI.Factory that carry the scoped trace context, adds no trace context of its own, and makes every entry point of a generated host (the lifecycle pipeline, the MCP tool, the REST operation and the development entry) bind the five identifiers into the library type from the caller before the pipeline starts. A request that arrives without tenant, project, run or attempt identity is refused before any model or tool call, and the refusal is recorded with its reason and the entry path it came through. The scope flows from the entry point into the lifecycle events, the outbox record and the telemetry of the attempt, so that later features put it on the envelope without a second plumbing pass.

Acceptance criteria

AC1 Given a generated agent host built against the pinned Factory libraries, when a request enters through any of its entry points with a trusted tenant id, project id, run id, step id and attempt id, then the AgentTraceContext of ConnectSoft.Extensions.AI.Factory.Abstractions carries the five identifiers and the trace id, as ADR-0014 requires, and every lifecycle event and log entry of the attempt is attributable to them.
AC2 Given a request that reaches an entry point without a tenant, project, run or attempt identity, when the entry point binds the scope, then the request is refused before the pipeline starts, no model or tool call is made, and the refusal is recorded with its reason and the name of the entry path (ADR-0014, docs/planes/agent-runtime/agent-runtime.md).
AC3 Given the template tests, when the unit suite runs, then a test per entry path proves the refusal of a scope-less request and the propagation of a complete scope, and the library AgentTraceContext is the only scope carrier the host uses: the template defines no second trace context (ADR-0028 amendment on the Factory templates, D94: AgentRuntimeService and WorkflowEngineService are scaffolded from this host).
Traces: adrs ADR-0014, ADR-0028
Depends on feature:component-extensions-ai
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/agent-runtime/agent-runtime.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-793 Pin the Factory libraries that carry the scoped trace context and bind the scope at every entry point implementation The template pins ConnectSoft.Extensions.AI.Factory.Abstractions and ConnectSoft.Extensions.AI.Factory at the versions whose AgentTraceContext carries tenant id, project id, run id, step id and attempt id beside the trace id, blueprint id, agent origin and workflow step; every entry point of a generated host binds the five identifiers into that type; the template defines no trace context of its own. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-794 Scope binding and refusal at every entry point implementation The lifecycle pipeline, the MCP tool, the REST operation and the development entry bind the scope from the caller before execution; a request without tenant, project, run or attempt identity is refused with a recorded reason and entry path. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-795 Scope on the telemetry and log enrichment of an attempt implementation Log entries, traces and metrics of an attempt are enriched with tenant, project, run, step and attempt identity from the library trace context; a test asserts the enrichment on one attempt. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-796 Verify the scope refusal and propagation per entry path verification Run dotnet test -c Release --no-build; one test per entry path proves AC1 to AC3 of AIFACTORY-US-136: a scope-less request is refused before any model or tool call and a complete scope reaches the lifecycle events through the library AgentTraceContext (ADR-0014). ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-137: Agent host template: the lifecycle, MCP, REST and development entry paths converge on one execution port

enabling · persona asset-maintainer As an asset maintainer, I want the four entry paths of a generated agent host to call one execution port that runs the lifecycle pipeline, so that no caller reaches the raw agent and every run enters the same way, under the same scope and policy checks.

A generated agent host today has four entry paths. The lifecycle pipeline of FactoryAgentBase accepts a request, builds the prompt, runs the model, validates the output, retries within a bound and completes or escalates. The MCP tool wrapper, the REST operation and the development entry call the agent directly and skip that pipeline, which is the bypass ADR-0022 closes in its decision 7: exposing an agent as an MCP tool is allowed only through the lifecycle pipeline, never by calling the raw agent. This PBI defines one execution port in the application layer of the template, makes the lifecycle, MCP, REST and development paths call it with the bound scope of the earlier PBI, and removes every direct path to the agent. The port records which entry path an attempt came through. A test proves that no path bypasses scope and policy, and an architecture rule of the template fails the test run, and with it the generated-solution gate, when a new path calls the agent without the port.

Acceptance criteria

AC1 Given a generated agent host, when a request enters through the lifecycle, the MCP tool, the REST operation or the development entry, then the same execution port runs the pipeline accept, prompt, run, validate, retry, complete or escalate described in docs/planes/agent-runtime/agent-runtime.md, and the attempt records the entry path it came through.
AC2 Given the MCP surface of a generated host, when its agent operation is invoked, then the invocation goes through the execution port and never calls the raw agent, as ADR-0022 decision 7 requires; a unit test calls the MCP tool with a scope-less request and asserts the refusal of the port.
AC3 Given the architecture tests of the template, when a type outside the execution port calls the agent directly, then the architecture test fails the test run of the authoring and generated solutions, which fails the generated-solution gate; the test suite proves that none of the four entry paths bypasses scope and policy (ADR-0028, docs/architecture/ecosystem-composition.md).
Traces: adrs ADR-0022, ADR-0028
Depends on AIFACTORY-US-136
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/planes/agent-runtime/agent-runtime.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-797 Execution port contract in the application layer contract An execution port interface in the application model of the template takes a scoped request and returns the agent result; it is the only type that invokes IFactoryAgent; the port records the entry path of the attempt. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-798 Reroute the MCP tool, the REST operation and the development entry through the port implementation The MCP tool wrapper, the REST operation and the development entry call the execution port; the direct calls to the agent are removed; the generated host builds with every entry switch combination. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-799 Architecture rule against a direct agent call fixture An architecture test of the template fails the test run when any type outside the execution port references the agent execution method; the rule is part of the generated solution as well, so the generated-solution gate fails on it. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-800 Verify that no entry path bypasses scope and policy verification Run dotnet test -c Release --no-build; the unit and architecture tests prove AC1 to AC3 of AIFACTORY-US-137: each of the four entry paths reaches the execution port and the raw agent is unreachable (ADR-0022). ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-138: Agent host template: a host-kind switch scaffolds the attempt-runtime host and the workflow-engine host

enabling · persona asset-maintainer As an asset maintainer, I want the agent template to scaffold the two Agent Mesh silo kinds from one host-kind switch, so that AgentRuntimeService and WorkflowEngineService start from a host that already carries their shape instead of a sample host that is cut down by hand.

ADR-0028 decides in decision 4 that AgentRuntimeService and WorkflowEngineService deploy alone as two silo kinds of one Orleans cluster, and its amendment on the Factory templates (D94) scaffolds both from the agent template. The compose pipeline of the template has an agent-profile symbol, but that symbol selects the hosting environment (local-safe by default, cloud-ready) and is kept for that purpose. The owner decided the symbol (D113): the template gains the choice symbol agent-host-kind with the choices agent, attempt-runtime and workflow-engine and the default agent, orthogonal to agent-profile, which keeps its meaning. This PBI adds it. The two Factory kinds shape only what the template owns at I0: the silo-kind configuration of one Orleans cluster (cluster id and silo kind name in the generated settings), the declaration that the default messaging profile of these kinds is Orleans, as D113 decides (the choice, its default and the removal of the forced MassTransit constant are delivered by AIFACTORY-US-147 of component-agent-template-factory-access), and the presence of the execution port and the exemplar for the attempt-runtime kind against their exclusion for the workflow-engine kind, which executes no agent of its own. The attempt grain, the workflow run grain, the definition loader and the outcome report to Run Control are the I1 work of the two services on top of the scaffolded host and are not generated here. A value outside the choices is refused by the template engine with the choices listed. Both generated hosts build, pass the template tests and carry the execution port and the scope binding of the earlier PBIs where the kind includes them; the generated case of each kind joins the template test matrix.

Acceptance criteria

AC1 Given the agent template, when dotnet new connectsoft-ai-agent --agent-host-kind attempt-runtime runs, then the generated host carries the silo-kind configuration of one Orleans cluster (cluster id and silo kind name), the execution port and the exemplar, and it builds and passes its tests; the attempt grain and the outcome report to Run Control are not generated and remain the I1 work of AgentRuntimeService (ADR-0024 decision 1, ADR-0028 decision 4).
AC2 Given the agent template, when dotnet new connectsoft-ai-agent --agent-host-kind workflow-engine runs, then the generated host carries the silo-kind configuration of the same cluster with its own silo kind name and no agent execution path, exemplar or execution port of its own, and it builds and passes its tests; the definition loader and the step readiness emission of ADR-0024 decision 3 remain the I1 work of WorkflowEngineService.
AC3 Given a value of agent-host-kind outside agent, attempt-runtime and workflow-engine, when the template is instantiated, then the template engine refuses the value with the choices listed; agent-profile keeps its values local-safe and cloud-ready beside it, and both symbols with their choices appear in model/template-parameters/connectsoft-ai-agent.yaml after the next inventory.
Traces: adrs ADR-0024, ADR-0028
Depends on AIFACTORY-US-136, AIFACTORY-US-137
Sources model/components.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0024-durable-execution-substrate.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-801 Choice symbol agent-host-kind with the choices agent, attempt-runtime and workflow-engine contract The merge script and the template configuration define the choice symbol agent-host-kind with the choices agent, attempt-runtime and workflow-engine, the default agent and a description per choice, orthogonal to the existing agent-profile symbol; a value outside the choices is refused by the template engine with the choices listed. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-802 Attempt-runtime host shape behind the host kind implementation With the attempt-runtime kind the generated host carries the silo-kind configuration of one Orleans cluster (cluster id, silo kind name) in its settings, the execution port wiring and the exemplar; no attempt grain and no Run Control report client are generated; the files of the other kinds are excluded. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-803 Workflow-engine host shape behind the host kind implementation With the workflow-engine kind the generated host carries the silo-kind configuration of the same cluster with its own silo kind name and excludes the agent execution path, the exemplar and the execution port; no definition loader and no readiness emission are generated; the host builds with no agent registered. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-804 Verify the two host-kind cases in the template matrix verification The template test matrix generates one case per host kind; both cases restore, build and pass their tests, which proves AC1 to AC3 of AIFACTORY-US-138 and the scaffolding of the two silo kinds under the ADR-0028 amendment on the Factory templates (D94) on a generated solution. ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-096: Agent host template: one execution port and Factory scope is delivered and proven on a generated solution

enabling · persona asset-maintainer As an asset maintainer, I want AI Agent host template to carry one execution port and Factory scope, so that it serves AgentRuntimeService and WorkflowEngineService without later rework.

This is the integration PBI of the feature. The asset maintainer packs the agent template with the Factory scope bound into the library trace context, the single execution port and the two Agent Mesh host kinds of the earlier PBIs, installs the package and instantiates it in the template pipeline. The generated solution of every case of the matrix restores, builds and passes its unit, architecture and acceptance tests before the package is allowed to publish with a verified version. A case that fails any stage fails the run and blocks publication; the run records which case and which stage failed. The migrated tasks of this PBI are its proofs on the generated solution; the implementation lives in the behaviour PBIs. The feature is done when the lifecycle, MCP, REST and development paths of a generated host call the same port, a test proves that no path bypasses scope and policy, and the attempt-runtime and workflow-engine hosts scaffold, build and pass the template tests, which is what the ADR-0028 amendment on the Factory templates needs before AgentRuntimeService and WorkflowEngineService are scaffolded.

Acceptance criteria

AC1 Given the template repository ConnectSoft.AI.SoftwareFactory.AgentTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution of every matrix case builds and its tests pass before the package publishes with a verified version (ADR-0028, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-158 (converge the entry points of the agent host on one execution port) is done, then the lifecycle, MCP, REST and development paths of a generated host call the same port and a test proves that no path bypasses scope and policy, as docs/architecture/ecosystem-composition.md requires of the component.
AC3 Given the work of AIFACTORY-TASK-159 (template switches for the two Agent Mesh services) is done, then the template scaffolds an attempt-runtime host and a workflow-engine host; both build and pass the template tests, which is the shape the ADR-0028 amendment on the Factory templates (D94) gives the two silo kinds of decision 4.
Traces: adrs ADR-0028
Depends on AIFACTORY-US-136, AIFACTORY-US-137, AIFACTORY-US-138
Sources model/components.yaml, docs/architecture/ecosystem-composition.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-158 Converge the entry points of the agent host on one execution port verification The generated solution of every matrix case proves the outputs of AIFACTORY-TASK-793 to AIFACTORY-TASK-800 (AC2 of AIFACTORY-US-096): the lifecycle, MCP, REST and development paths call the same port and the unit and architecture tests prove that no path bypasses scope and policy. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-159 Template switches for the two Agent Mesh services verification The generated cases of the attempt-runtime and workflow-engine kinds prove the outputs of AIFACTORY-TASK-801 to AIFACTORY-TASK-804 (AC3 of AIFACTORY-US-096): both hosts scaffold, build and pass the template tests. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-666 Verify agent-template-delivered by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build on the authoring solution and on every generated case of the matrix; they pass and prove AC1 to AC3 of AIFACTORY-US-096. ConnectSoft.AI.SoftwareFactory.AgentTemplate