AIFACTORY-FEAT-153: Agent host template: parameterized agent identity and a neutral exemplar¶
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 6 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).
A generated agent host carries the identity of its agent in its classes, manifest and MCP surface. Today the template rewrites only the namespace prefix: every generated host ships classes named SampleFactoryAgent*, the MCP method InvokeSampleFactoryAgent, demo weather and string tools switched on by default, and an exemplar whose logic is demo analytics with hard-coded figures (Docs/Generic Agent Audit Report.md of the template, gaps 1, 2, 5 and 7). AgentRuntimeService and WorkflowEngineService cannot be scaffolded from a host that is named after the sample. Component: AI Agent host template (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-agent-template adrs: ADR-0028 |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, docs/architecture/ecosystem-composition.md, ConnectSoft.AI.SoftwareFactory.AgentTemplate/Docs/Generic Agent Audit Report.md |
AIFACTORY-US-139: Agent host template: the agent class, its tools, the MCP method and the manifest entry take their names from the agent identity¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated agent host to name its agent class, tool classes, MCP method, keyed service and manifest entry after the agent I generate, so that AgentRuntimeService and WorkflowEngineService are scaffolded from a host that carries their identity and not the name of the sample.
The template rewrites the namespace prefix through sourceName, and its compose pipeline already defines the agent-class-name symbol with a replaces rule and a fileRename rule on SampleFactoryAgent; model/templates.yaml lists the symbol among the switches of connectsoft-ai-agent. The symbol is part of the work that Docs/Generic Agent Implementation Summary.md of the template records as applied without a compiler; D113 makes that recorded work the starting point, so the first task of this PBI builds and tests it and keeps what passes. Its default is the constant SampleFactoryAgent, which is the real defect: a host generated without the option keeps the classes SampleFactoryAgent, SampleFactoryAgentTools, SampleFactoryAgentMcpTool and SampleFactoryAgentMcpToolWrapper, the MCP method InvokeSampleFactoryAgent, the keyed-service name and the manifest value entry_agent_class: SampleFactoryAgent, which gap 1 of the audit report of the template records. This PBI derives the default of the symbol from the agent-id symbol in Pascal case and completes the renames of the types, the files, the MCP method, the keyed-service name and the manifest entry. A text symbol of the template engine has no pattern validation, so a class name that is not a valid identifier is caught by the placeholder scan before the build and otherwise fails the build of the generated host with the identifier named. The placeholder scan of the template fails when a generated host still contains a SampleFactoryAgent identifier or an unreplaced agent token, and the symbol stays in the generated template configuration so that the inventory of the documentation repository lists it.
Acceptance criteria
| AC1 | Given the agent template, when dotnet new connectsoft-ai-agent --agent-id connectsoft-probe runs without an explicit class name, then the agent class, its tools, the MCP tool and wrapper, the MCP method, the keyed-service name and the manifest entry_agent_class are named from the agent id in Pascal case, and the generated host contains no SampleFactoryAgent identifier (ADR-0028 amendment on the Factory templates, model/components.yaml). |
| AC2 | Given an explicit --agent-class-name that is not a valid C# identifier, when the host is generated, then the placeholder scan of the template reports the name as an invalid identifier before the build and the build of the generated host fails with the identifier named; given a valid name, then the files and types of the agent are renamed to it through fileRename and replaces (model/template-parameters/connectsoft-ai-agent.yaml lists the symbol with its derived default after the next inventory). |
| AC3 | Given the placeholder scan of the template pipeline, when a generated host still contains a SampleFactoryAgent identifier or an __AGENT_ token, then the scan fails the case; the scan is part of the generated-solution gate that docs/architecture/ecosystem-composition.md names as a need of this component and that Docs/AgentTemplate-Alignment-Verification.md of the template describes. |
| Traces: adrs | ADR-0028 |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-853 Compile and test the recorded agent-class-name work as the starting point |
implementation | The agent-class-name symbol with its replaces and fileRename rules, which Docs/Generic Agent Implementation Summary.md of the template records as written without a compiler, is composed, packed and generated with and without an explicit class name; the generated hosts build and pass their tests; a rule that passes is kept, a rule that fails is corrected or removed, and the outcome per rule is recorded in that summary (D113, the starting point of AC1 of AIFACTORY-US-139). |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-805 Default of agent-class-name derived from agent-id and the renames completed |
contract | The merge script derives the default of the existing agent-class-name symbol from agent-id in Pascal case in place of the constant SampleFactoryAgent, and its replaces and fileRename rules cover every sample type and file; an invalid identifier fails the build of the generated host with the identifier named. |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-806 MCP method, keyed-service name and manifest entry_agent_class renamed from the symbol |
implementation | The MCP method, the keyed-service registration and factory/agent.manifest.yaml of a generated host carry the class name of the symbol; the acceptance tests of the MCP surface resolve the renamed method. |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-807 Placeholder scan of a generated host for sample identifiers, agent tokens and invalid class names |
fixture | The template pipeline scans every generated case for SampleFactoryAgent, __AGENT_, __PRIMARY_ and __SECONDARY_ and for a class name that is not a valid C# identifier, and fails the case on a hit before the build; the scan has a fixture with one planted hit that proves it fails. |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-808 Verify the renamed identity on a generated host |
verification | Generate a host with --agent-id connectsoft-probe, build it and run its tests; no SampleFactoryAgent identifier remains and the MCP method and manifest entry carry the derived name, which proves AC1 to AC3 of AIFACTORY-US-139. |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-US-140: Agent host template: the demo MCP tools are generated only behind a switch that is off by default¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated agent host to expose only the agent operation on its MCP surface unless I ask for the demo tools, so that a Factory agent host does not ship weather and string demos as governed MCP capabilities.
The compose pipeline of the template already defines the IncludeMcpSamples switch, but its default is true, so the MCP project of every generated host ships the weather, echo and string demo tools, their prompts, their response types and their acceptance tests as its default MCP surface, which gap 2 of the audit report of the template records. The switch and its exclusion list are part of the uncompiled work the implementation summary of the template records; D113 makes that work the starting point, so the first task of this PBI builds and tests the switch in both positions and keeps what passes. ADR-0022 makes every MCP tool a governed capability with a descriptor, so a demo tool on a Factory host is a capability nobody declared. This PBI flips the default of the switch to false and completes its exclusion list: the weather, echo and string tools, the prompts, the response types and the acceptance tests of the samples. With the switch off, the MCP surface of a generated host exposes the agent operation alone, routed through the execution port of the earlier feature; with the switch on, the demo tools are generated and their tests run. A generated host with the switch off must build with no reference to an excluded type, which the configuration smoke tests of the template matrix cover in both positions of the switch.
Acceptance criteria
| AC1 | Given the agent template, when a host is generated without --IncludeMcpSamples, then the weather, echo and string demo tools, their prompts, their response types and their acceptance tests are absent, the host builds, and its MCP surface lists the agent operation alone (ADR-0022 decision 1 and 7, model/template-parameters/connectsoft-ai-agent.yaml). |
| AC2 | Given the agent template, when a host is generated with --IncludeMcpSamples true, then the demo tools and their acceptance tests are generated and pass; both positions of the switch are cases of the template matrix that docs/architecture/ecosystem-composition.md names as a need of this component and that Docs/AgentTemplate-Alignment-Verification.md of the template describes. |
| AC3 | Given a generated host with the switch off, when the MCP acceptance test enumerates the tools of the server, then exactly one tool is listed and its name is the agent operation of the class identity of AIFACTORY-US-139 (ADR-0028 amendment on the Factory templates). |
| Traces: adrs | ADR-0022, ADR-0028 |
| Depends on | AIFACTORY-US-139 |
| Sources | model/components.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-854 Compile and test the recorded IncludeMcpSamples switch as the starting point |
implementation | The IncludeMcpSamples switch and its exclusion list, which Docs/Generic Agent Implementation Summary.md of the template records as written without a compiler, are generated in both positions; both generated hosts build and pass their tests; an exclusion that leaves a dangling reference is corrected, and the outcome per position is recorded in that summary (D113, the starting point of AC1 and AC2 of AIFACTORY-US-140). |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-809 IncludeMcpSamples default flipped to false with a complete exclusion list |
implementation | The merge script and the template configuration set the existing IncludeMcpSamples switch to false by default; the exclusion list names the weather, echo and string tools, the prompts, the response types and the acceptance tests of the samples; the MCP registration of a generated host has no reference to an excluded type. |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-810 MCP acceptance test that enumerates the surface in both switch positions |
fixture | An acceptance test lists the tools of the MCP server of a generated host; with the switch off it asserts the agent operation alone, with the switch on it asserts the demo tools beside it. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-811 Verify the default MCP surface on generated hosts |
verification | Generate one host with the default switch and one with --IncludeMcpSamples true; both build and pass their tests and the enumeration test proves AC1 to AC3 of AIFACTORY-US-140 (ADR-0022). |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-US-141: Agent host template: a neutral exemplar agent replaces the demo analytics and the generation guide names the real options¶
enabling · persona asset-maintainer
As an asset maintainer, I want the exemplar agent of a generated host to execute one typed operation on its inputs and the generation guide to name the options the compose pipeline defines, so that a developer who scaffolds AgentRuntimeService or WorkflowEngineService starts from an exemplar and a guide that are true.
The sample agent of the template exposes workflow metrics analysis and blueprint recommendation whose tools return hard-coded figures, which gap 5 of the audit report of the template records, and the generation guide documents Pascal-case options while the merge script defines kebab-case ones, which is gap 7. The implementation summary of the template records a first answer to both gaps, a thin exemplar over FactoryAgentBase and kebab-case edits of the guide and of the behavioral specification, applied without a compiler; D113 makes that work the starting point, so the first task of this PBI builds and tests it and keeps what passes. This PBI replaces the demo analytics with a neutral exemplar that takes a typed request, executes one typed operation through the execution port and returns a typed result with no hard-coded figure, so that the unit and acceptance tests of the template assert the exemplar and a generated host carries an agent a developer can replace by implementing the prompt and the validation alone. It also rewrites the generation guide to the kebab-case options the compose pipeline defines and model/templates.yaml lists as the switches of connectsoft-ai-agent (agent-id, agent-display-name, agent-role, agent-cluster, agent-profile, agent-summary, agent-class-name, primary-workflow, and agent-host-kind, which D113 decides and the earlier feature adds) and adds a test that parses the guide and the merge script and fails when an option name of one is missing from the other.
Acceptance criteria
| AC1 | Given a generated host, when the exemplar agent executes a typed request through the execution port, then it returns a typed result computed from the inputs of the request, no hard-coded figure remains in the agent or its tools, and the unit and acceptance tests of the template assert the exemplar (docs/planes/agent-runtime/agent-runtime.md, ADR-0028 amendment on the Factory templates). |
| AC2 | Given the generation guide of the template, when the option-name test parses the guide and the merge script, then every option the compose pipeline defines is named in the guide in kebab-case and the test fails when a name of one is missing from the other; the names are the ones model/templates.yaml lists under switches of connectsoft-ai-agent. |
| AC3 | Given the behavioral specification of the exemplar in the generated host, when the host is generated, then the specification names the typed operation, its inputs and outputs, the lifecycle events of the attempt and the correction and escalation flow, and no demo analytics vocabulary remains (model/components.yaml). |
| Traces: adrs | ADR-0028 |
| Depends on | AIFACTORY-US-139 |
| Sources | model/components.yaml, model/templates.yaml, docs/planes/agent-runtime/agent-runtime.md, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-855 Compile and test the recorded thin exemplar, specification and guide edits as the starting point |
implementation | The exemplar that Docs/Generic Agent Implementation Summary.md of the template records as demoted to a thin wrapper over FactoryAgentBase, its behavioral specification and the kebab-case edits of the generation guide, all written without a compiler, are built and tested on the authoring solution and on a generated default host; what builds and passes is kept as the base of the neutral exemplar and of the guide rewrite, what fails is corrected or removed, and the outcome is recorded in that summary (D113, the starting point of AC1 and AC2 of AIFACTORY-US-141). |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-812 Neutral exemplar agent with one typed operation |
implementation | The exemplar agent takes a typed request, executes one typed operation on its inputs through the execution port and returns a typed result; the demo analytics methods and their hard-coded tool data are removed; the unit tests drive the exemplar with a scripted model. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-813 Generation guide and behavioral specification rewritten to the real options and the exemplar |
documentation | Docs/Template Generation Guide.md names the kebab-case options of the compose pipeline with one example per option; the behavioral specification of the exemplar names its operation, inputs, outputs, events and escalation flow. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-814 Option-name test over the guide and the merge script |
fixture | A unit test parses the option names of Docs/Template Generation Guide.md and of build/Merge-AgentTemplateSymbols.ps1 and compares the two against each other; it fails when a name of one is missing from the other. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-815 Verify the exemplar and the guide on a generated host |
verification | Generate a host, build it and run its tests; the exemplar tests pass, a grep for the demo analytics names and hard-coded figures returns nothing, and the option-name test passes, which proves AC1 to AC3 of AIFACTORY-US-141. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-US-100: Agent host template: parameterized agent identity and a neutral exemplar is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want AI Agent host template to carry a parameterized agent identity and a neutral exemplar, 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 derived class identity, the demo tools behind their switch and the neutral exemplar of the earlier PBIs, installs the package and instantiates it in the template pipeline across the identity cases of the matrix: a derived class name, an explicit class name, the demo switch off and on. Every generated case restores, builds, passes its unit, architecture and acceptance tests and passes the placeholder scan 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. The feature is done when a generated host contains no sample identifier, its default MCP surface exposes the agent operation alone, its exemplar executes one typed operation without hard-coded figures, and the generation guide names the options the compose pipeline defines, as the audit report of the template and ADR-0028 require 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 identity case builds, passes its tests and passes the placeholder scan before the package publishes with a verified version (ADR-0028, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-567 (agent class identity from the agent-id symbol) is done, then the agent class, its tools, MCP tool and wrapper, the MCP method and the manifest entry_agent_class are renamed from the agent-id symbol through fileRename and source replacement, and a generated host contains no SampleFactoryAgent name (docs/architecture/ecosystem-composition.md). |
| AC3 | Given the work of AIFACTORY-TASK-568 (MCP demo tools behind a switch that is off by default) is done, then the weather, echo and string demo tools and their response types are generated only when IncludeMcpSamples is true, and the default MCP surface of a generated host exposes the agent operation alone (model/template-parameters/connectsoft-ai-agent.yaml). |
| AC4 | Given the work of AIFACTORY-TASK-569 (a neutral exemplar agent in place of the demo analytics) is done, then the exemplar executes one typed operation on the inputs of the agent and returns a typed output, no hard-coded figures remain, and the unit and acceptance tests of the template assert the exemplar (docs/planes/agent-runtime/agent-runtime.md). |
| AC5 | Given the work of AIFACTORY-TASK-570 (option names of the generation guide match the merge script) is done, then Docs/Template Generation Guide.md of the template names the kebab-case options the compose pipeline defines (agent-display-name, agent-role, agent-cluster, primary-workflow among them) and a test parses the guide and the script and compares the names (model/templates.yaml lists the same names under switches). |
| Traces: adrs | ADR-0028 |
| Depends on | AIFACTORY-US-139, AIFACTORY-US-140, AIFACTORY-US-141 |
| Sources | model/components.yaml, model/templates.yaml, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-567 Agent class identity from the agent-id symbol |
verification | The generated cases with a derived and with an explicit class name prove the outputs of AIFACTORY-TASK-853 and AIFACTORY-TASK-805 to AIFACTORY-TASK-808 (AC2 of AIFACTORY-US-100): the agent class, its tools, MCP tool and wrapper, the MCP method and the manifest entry_agent_class are renamed and no SampleFactoryAgent name remains. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-568 MCP demo tools behind a switch that is off by default |
verification | The generated cases with the switch off and on prove the outputs of AIFACTORY-TASK-854 and AIFACTORY-TASK-809 to AIFACTORY-TASK-811 (AC3 of AIFACTORY-US-100): the demo tools and their response types exist only when IncludeMcpSamples is true and the default MCP surface exposes the agent operation alone. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-569 A neutral exemplar agent in place of the demo analytics |
verification | The generated default case proves the outputs of AIFACTORY-TASK-855, AIFACTORY-TASK-812 and AIFACTORY-TASK-815 (AC4 of AIFACTORY-US-100): the exemplar executes one typed operation on its inputs and returns a typed output, no hard-coded figures remain, and the unit and acceptance tests assert the exemplar. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-570 Option names of the generation guide match the merge script |
verification | The option-name test of AIFACTORY-TASK-814 passes on the authoring solution and proves the outputs of AIFACTORY-TASK-813 and AIFACTORY-TASK-814 (AC5 of AIFACTORY-US-100): Docs/Template Generation Guide.md names the kebab-case options of the compose pipeline. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-664 Verify agent-template-identity-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 identity case of the matrix; they pass and prove AC1 to AC5 of AIFACTORY-US-100. |
ConnectSoft.AI.SoftwareFactory.AgentTemplate |