Skip to content

AIFACTORY-FEAT-155: Agent host template: model access through the Factory and the Orleans messaging profile

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 8 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 template reaches model providers directly through its provider switches (Azure OpenAI, OpenAI, Ollama, Azure AI inference) and executes tools inside the host, while the Factory allows model calls only through ModelRouterService and tool execution only through ToolAdapterService (ADR-0028, single-entry rules). Its messaging switch offers MassTransit and NServiceBus but not the Orleans outbox and inbox adapter the runtime uses (ADR-0024). This feature adds the switches a Factory agent host is scaffolded with: a model client that routes through the model gateway and returns a receipt, a tool client that calls the tool gateway, and the Orleans messaging profile. The Anthropic adapter itself is library work of the earlier feature. Component: AI Agent host template (extend).

Delivers —
Stubs —
Realizes components: cmp-agent-template
adrs: ADR-0024, ADR-0028
Requirements —
Depends on AIFACTORY-FEAT-097 AI and Factory libraries: scope in contracts, Anthropic adapter, durable base
Sources model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0024-durable-execution-substrate.md, ConnectSoft.AI.SoftwareFactory.AgentTemplate/.template.config/template.json

AIFACTORY-US-145: Agent host template: the UseFactoryModelRouter switch routes every completion through the model gateway with the attempt scope and keeps its receipt

enabling · persona asset-maintainer As an asset maintainer, I want a generated Factory agent host to reach models only through the model gateway of the Factory, so that ModelRouterService stays the only service that calls a model provider and every completion of an attempt has a receipt.

The template reaches model providers directly through the choice MicrosoftExtensionsAIServiceProvider (OpenAI, AzureOpenAI, AzureAIInference, Ollama) behind EnableMicrosoftExtensionsAI, whose computed Use...Provider symbols select the provider registration, while ADR-0028 decision 3 makes ModelRouterService the only service that calls model providers and its gateway the only route to it. This PBI adds the UseFactoryModelRouter switch to the compose pipeline. With the switch on, the IChatClient of the host is the Factory model client of the AI libraries of component-extensions-ai that calls the model gateway with the attempt scope of the library trace context bound by AIFACTORY-US-136 of component-agent-template (tenant, project, run, step, attempt), the model policy of the step and the correlation id, and keeps the receipt id of every completion on the attempt record. The template engine has no cross-symbol constraint, so no combination is refused at generation; instead, with the switch on, the computed provider symbols are forced false and the provider registration and the provider key settings are excluded, so that a generated host carries no provider registration and no provider key whatever provider choice was passed. The switch is on by default for the attempt-runtime value of the agent-host-kind symbol of AIFACTORY-US-138. A model gateway that is unreachable ends the completion with a failure class the lifecycle pipeline publishes on the envelope of AIFACTORY-US-143 of component-agent-template-contract, never with a fallback to a direct provider.

Acceptance criteria

AC1 Given a host generated with UseFactoryModelRouter on, when the exemplar runs a completion, then the IChatClient of the host calls the model gateway with the tenant, project, run, step and attempt identity of the trace context and the model policy of the step, and the receipt id of the completion is kept on the attempt record (ADR-0028 decision 3, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md).
AC2 Given UseFactoryModelRouter is on, when a host is generated with any value of MicrosoftExtensionsAIServiceProvider, then the computed provider symbols are false, no provider registration and no provider key setting is generated, and the host builds; the switch and the forced symbols appear in model/template-parameters/connectsoft-ai-agent.yaml after the next inventory.
AC3 Given the model gateway is unreachable, when a completion is attempted, then the attempt ends with the outcome value Failed and its failure class published on AttemptOutcomeReported, the event name AgentRuntimeService models, and no direct provider is called; a test with a fake gateway proves the receipt on success and the failure class on an unreachable gateway (ADR-0028 decision 3 keeps the gateway the only route to the model provider).
Traces: adrs ADR-0028
Depends on feature:component-extensions-ai, feature:component-agent-template, feature:component-agent-template-contract
Sources model/components.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/agent-runtime/agent-runtime.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-828 UseFactoryModelRouter symbol that forces the provider symbols off contract The merge script and the template configuration define UseFactoryModelRouter, on by default for the attempt-runtime host kind; with the switch on the computed UseMicrosoftExtensionsAI...Provider symbols are forced false and the provider registration files and provider key settings are excluded, whatever value MicrosoftExtensionsAIServiceProvider carries. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-829 Factory model client registered as the IChatClient with scope, policy and receipt implementation With the switch on, the host registers the Factory model client of the AI libraries as its IChatClient; the client sends the attempt scope, the model policy and the correlation id with every completion and stores the receipt id on the attempt record; an unreachable gateway ends the completion with a failure class. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-830 Fake model gateway fixture for the generated-host tests fixture A fake model gateway in the test projects of the template returns a receipt for a completion and simulates an unreachable gateway; the acceptance tests of a host with the switch on run against it. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-831 Verify model access through the gateway on a generated host verification Generate a host with UseFactoryModelRouter on and a provider choice passed, build it and run its tests against the fake gateway; the receipt and failure-class tests pass and the scan finds no provider registration or key setting, which proves AC1 to AC3 of AIFACTORY-US-145 (ADR-0028). ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-146: Agent host template: the UseFactoryToolAdapter switch sends tool invocations to the tool gateway with their side-effect class and keeps in-host execution for the default host development entry

enabling · persona asset-maintainer As an asset maintainer, I want a generated Factory agent host to execute tools only through the tool gateway of the Factory, so that ToolAdapterService stays the only service that executes tools and no write-class tool runs inside an agent host.

The template executes tools inside the host, while ADR-0028 decision 3 makes ToolAdapterService the only service that executes tools and ADR-0022 decision 2 sends every tool call, from a Factory agent included, through the governed executor with scope, policy decision, side-effect class, idempotency key, receipt and audit. This PBI adds the UseFactoryToolAdapter switch to the compose pipeline. With the switch on, the tool invocations of the agent go to the tool gateway with the attempt scope of the library trace context bound by AIFACTORY-US-136 of component-agent-template, the tool descriptor id and version and the side-effect class of the step, and the receipt of every invocation is kept on the attempt record. In-host tool execution is a development-only exception to ADR-0022 decision 2: the in-host executor is generated only for the development entry path of the default agent host kind, is excluded from the attempt-runtime and workflow-engine values of the agent-host-kind symbol of AIFACTORY-US-138, and is refused for every other path; a write-class tool (shared-write, external, production, publication or spend) is never executed in the host, and an attempt to do so is refused and recorded. The switch is on by default for the attempt-runtime host kind. A tool gateway that is unreachable ends the invocation with a failure class the lifecycle pipeline publishes.

Acceptance criteria

AC1 Given a host generated with UseFactoryToolAdapter on, when the agent invokes a tool, then the invocation goes to the tool gateway with the attempt scope, the descriptor id and version and the side-effect class of the step, and the receipt is kept on the attempt record, as ADR-0022 decision 2 and ADR-0028 decision 3 require.
AC2 Given a host with the switch on, when a write-class tool (shared-write, external, production, publication or spend) is requested for in-host execution through any path, then the host refuses and records the refusal; a test proves that the tool is not executed in the host (docs/architecture/adr/0022-mcp-as-tool-protocol.md).
AC3 Given the development entry path of a generated host of the default agent kind, when a read or sandbox tool is invoked in-host, then it executes locally and is recorded with its side-effect class as a development-only exception to ADR-0022 decision 2; the in-host executor is generated for that path alone, is excluded from the attempt-runtime and workflow-engine host kinds so that a generated Factory host contains no in-host executor, and the switch appears in model/template-parameters/connectsoft-ai-agent.yaml after the next inventory.
Traces: adrs ADR-0022, ADR-0028
Depends on AIFACTORY-US-145, feature:component-agent-template, feature:component-agent-template-contract
Sources model/components.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-832 UseFactoryToolAdapter symbol and the development-only in-host executor of the default host kind contract The merge script and the template configuration define UseFactoryToolAdapter, on by default for the attempt-runtime host kind; the in-host tool executor is generated only for the development entry path of the agent host kind and is excluded for the attempt-runtime and workflow-engine kinds; the exception is recorded in the generation guide as development-only against ADR-0022 decision 2. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-833 Factory tool client with scope, descriptor, side-effect class and receipt implementation With the switch on, tool invocations of the agent go to the tool gateway with the attempt scope, the descriptor id and version and the side-effect class; the receipt is kept on the attempt record; a write-class tool requested in-host is refused and recorded; an unreachable gateway ends the invocation with a failure class. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-834 Fake tool gateway fixture and the write-class refusal test fixture A fake tool gateway in the test projects returns a receipt per invocation; a test requests a write-class tool in-host through every entry path and asserts the refusal and that no local execution happened. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-835 Verify tool access through the gateway on a generated host verification Generate a host with UseFactoryToolAdapter on, build it and run its tests against the fake tool gateway; the receipt, refusal and development-path tests pass and the attempt-runtime probe carries no in-host executor, which proves AC1 to AC3 of AIFACTORY-US-146 (ADR-0022). ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-147: Agent host template: MessagingModelType accepts Orleans from the base template and a Factory host kind defaults to the Orleans outbox and inbox profile

enabling · persona asset-maintainer As an asset maintainer, I want a generated agent host to carry the Orleans messaging profile with its outbox dispatcher and inbox grains, so that the two Agent Mesh silo kinds run on the durable substrate and the messaging profile the Factory decided on.

The compose pipeline of the agent template forces two symbols of the base template: MessagingModelType to the constant MassTransit and UseMassTransit to the computed value true, so that the messaging choice cannot be changed at generation. ADR-0012 makes the Orleans outbox and inbox adapter the default profile of Factory hosts and ADR-0024 makes Orleans grains the durability substrate of attempts and workflow runs. The Orleans value of MessagingModelType with the registration of the Orleans messaging adapter library, the outbox dispatcher and the inbox grains and the ADR-0014 envelope on every outbox record is the work of component-base-template-factory-profile (AIFACTORY-TASK-580); the agent template composes on it through its base-template submodule (inherits: connectsoft-base), so the choice arrives through the submodule pointer. The owner decided the outcome (D113): the forced MassTransit constant is removed, the Orleans messaging profile is the default of the Factory host kinds and MassTransit stays a selectable transport. This PBI moves the submodule to the commit that carries that choice, stops forcing both symbols so that they derive from the choice again, makes the registration of the MassTransit lifecycle publisher of ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit follow the MassTransit choice in place of being unconditional, defaults the choice to Orleans for the attempt-runtime and workflow-engine values of the agent-host-kind symbol of AIFACTORY-US-138, and adds only what is agent-specific: the lifecycle publisher of AIFACTORY-US-144 on the Orleans outbox and the messaging service name of the agent. The MassTransit and NServiceBus profiles stay available as transports and are never used for run or workflow state, and the saga scaffolding of the FlowModel project is excluded from every Factory host kind and from the Orleans profile, as ADR-0024 decision 4 removes broker sagas from the design. The generated configuration smoke tests of the template cover the Orleans profile.

Acceptance criteria

AC1 Given the agent template on the base-template submodule that carries the Orleans choice, when a host is generated with MessagingModelType Orleans, then the host registers the Orleans messaging adapter library, the outbox dispatcher and the inbox grains with its actor model as the base template feature component-base-template-factory-profile generates them, the outbox record carries the envelope and is written with the state transition in one transaction (ADR-0012 decision 4, ADR-0024 decision 1), and the agent template adds the lifecycle publisher on that outbox and the messaging service name of the agent.
AC2 Given the attempt-runtime or the workflow-engine host kind, when a host is generated without an explicit messaging value, then its messaging profile is Orleans; MessagingModelType is no longer forced to MassTransit and UseMassTransit is no longer computed true in the compose pipeline, the generated host contains no MassTransit registration, a host generated with an explicit MassTransit value still carries the MassTransit transport and its lifecycle publisher, and the choice appears in model/template-parameters/connectsoft-ai-agent.yaml after the next inventory.
AC3 Given the generated configuration smoke tests of the template, when the Orleans case runs, then the host starts with its silo, outbox and inbox configured from the generated settings; the saga scaffolding of the flow model is excluded from every Factory host kind and from the Orleans profile and the generated host carries no saga type, as ADR-0024 decision 4 removes broker sagas from the design (docs/architecture/adr/0024-durable-execution-substrate.md).
Traces: adrs ADR-0012, ADR-0024, ADR-0028
Depends on AIFACTORY-US-145, feature:component-base-template-factory-profile, feature:component-agent-template, feature:component-agent-template-contract
Sources model/components.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/architecture/adr/0024-durable-execution-substrate.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-836 Both forced messaging symbols released, Orleans default for the Factory host kinds and the saga files excluded contract MessagingModelType is no longer forced to the constant MassTransit and UseMassTransit is no longer computed true in build/Merge-AgentTemplateSymbols.ps1; both derive from the choice again; the attempt-runtime and workflow-engine host kinds default the choice to Orleans; the registration of the MassTransit lifecycle publisher is generated only when the MassTransit transport is chosen, which stays selectable; the FlowModel saga files are excluded behind the choice for every Factory host kind and for the Orleans profile. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-837 Base-template submodule moved to the Orleans choice and the agent-specific additions implementation The base-template submodule of the agent template is moved to the commit that carries the Orleans choice of AIFACTORY-TASK-580 (adapter registration, outbox dispatcher, inbox grains, envelope on the outbox record); the agent template adds only the lifecycle publisher on the Orleans outbox and the messaging service name of the agent; no registration of the base feature is re-implemented in the template. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-838 Configuration smoke test case for the Orleans profile fixture The generated configuration smoke tests of the template matrix gain an Orleans case that starts the host with its silo, outbox and inbox from the generated settings and asserts the registrations and the absence of a saga type. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-839 Verify the Orleans profile on the generated Factory hosts verification Generate the attempt-runtime and workflow-engine hosts with the default messaging profile; both carry Orleans, no MassTransit registration and no saga type, build, pass their tests and the smoke case, and a host generated with an explicit MassTransit value builds with the MassTransit transport and its lifecycle publisher, which proves AC1 to AC3 of AIFACTORY-US-147 (ADR-0012, ADR-0024). ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-102: Agent host template: model access through the Factory and the Orleans messaging profile is delivered and proven on a generated solution

enabling · persona asset-maintainer As an asset maintainer, I want AI Agent host template to carry model access through the Factory and the Orleans messaging profile, 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 model client switch, the Factory tool client switch and the Orleans messaging profile of the earlier PBIs, installs the package and instantiates it in the template pipeline across the access cases of the matrix: both Factory switches on with Orleans for each Factory host kind, the development case of the default host kind with in-host read tools, and the broker transports for comparison. Every generated case restores, builds, passes its tests against the fake gateways and passes the configuration smoke 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 migrated tasks of this PBI are its proofs on the generated solution; the implementation lives in the behaviour PBIs and in the library and base-template features the feature depends on. The feature is done when a generated Factory host reaches models only through the model gateway with a receipt per completion, executes tools only through the tool gateway with their side-effect class, carries no provider registration and no in-host executor, refuses a write-class tool in-host, and defaults to the Orleans outbox and inbox, which is what ADR-0028 and ADR-0024 require of the hosts AgentRuntimeService and WorkflowEngineService are scaffolded from.

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 access case builds, its tests pass against the fake gateways and the configuration smoke tests pass before the package publishes with a verified version (ADR-0028, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-574 (model client switch UseFactoryModelRouter) is done, then with the switch on the IChatClient of the host is the Factory model client that calls the model gateway with the attempt scope and keeps the receipt id of every completion, no provider registration or key setting is generated when it is on, and a generated host with the switch builds and its tests pass (ADR-0028 decision 3, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md).
AC3 Given the work of AIFACTORY-TASK-575 (tool client switch UseFactoryToolAdapter) is done, then with the switch on tool invocations of the agent go to the tool gateway with the side-effect class of the step, in-host tool execution is generated only for the development entry path of the default host kind, and a test proves that a write-class tool is not executed in the host (ADR-0028 decision 3).
AC4 Given the work of AIFACTORY-TASK-576 (messaging profile Orleans for the outbox and inbox) is done, then MessagingModelType accepts Orleans through the base-template submodule and the generated host registers the Orleans messaging adapter, the outbox dispatcher and the inbox grains, the default of a Factory host kind is Orleans, and the generated configuration smoke tests cover the profile (ADR-0024 decision 1, docs/architecture/adr/0024-durable-execution-substrate.md).
Traces: adrs ADR-0024, ADR-0028
Depends on AIFACTORY-US-145, AIFACTORY-US-146, AIFACTORY-US-147, feature:component-agent-template, feature:component-agent-template-contract
Sources model/components.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-574 Model client switch UseFactoryModelRouter verification The generated access cases prove the outputs of AIFACTORY-TASK-828 to AIFACTORY-TASK-831 (AC2 of AIFACTORY-US-102): the IChatClient of a host with the switch on is the Factory model client with a receipt per completion and the probe carries no provider registration or key setting. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-575 Tool client switch UseFactoryToolAdapter verification The generated access cases prove the outputs of AIFACTORY-TASK-832 to AIFACTORY-TASK-835 (AC3 of AIFACTORY-US-102): tool invocations go to the tool gateway with their side-effect class, the in-host executor exists only on the development path of the default host kind, and a write-class tool is not executed in the host. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-576 Messaging profile Orleans for the outbox and inbox verification The generated Factory host kind cases prove the outputs of AIFACTORY-TASK-836 to AIFACTORY-TASK-839 (AC4 of AIFACTORY-US-102): the default messaging profile is Orleans with the adapter, outbox dispatcher and inbox grains registered and the configuration smoke case passes. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-663 Verify agent-template-factory-access-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 access case of the matrix; they pass and prove AC1 to AC4 of AIFACTORY-US-102. ConnectSoft.AI.SoftwareFactory.AgentTemplate