Reconsider agent use

[ploeh]

While being aware of ADR-0008: Agent Architecture I'm quite concerned about this architecture.

As far as I can tell from makeAppEnv, most of the system runs through five agents:

        let formularyAgent = createFormularyAgent provider
        let orderCtxAgent = createOrderCtxAgent logAgent logger provider
        // [...]
        let orderPlanAgent = createOrderPlanAgent logAgent provider orderCtxPort
        let nutritionAgent = createNutritionAgent logger provider orderCtxPort
        let interactionAgent = createInteractionAgent ()

This seems to include read operations.

Since the entire purpose of an agent (MailboxProcessor) is to serialise operations, this entails that most operations, including read operations, are serialised.

Each agent serialises all operations on a single thread. With five agents, this seems to effectively limit the system to five threads. For particular subdomains (e.g. nutrition), a single agent means effectively single-threaded access to every operation offered by that agent.

This could become a bottleneck if the system needs to scale.

While not a trivial change, I recommend reverting ADR-0008: Agent Architecture.

If a lock-free architecture is desired, a better alternative is CQRS with a persistent queue for Commands. This may, however, be overkill for this system. For instance, ADR-0008: Agent Architecture states that a benefit of using agents is that

"The agent serialises all access to the provider, removing the need for the explicit lock inside CachedResourceProvider."

While true, other solutions exist, including using lock, introducing a custom compare-and-swap atomic cell type, leveraging thread-safe BCL types, etc.

In fact, we should seriously consider not using F# agents at all. F# agents are useful for serialising and streaming information when persistence is not a concern, which could include logging. Still in light of #416, even this may not be something that warrants agent use.

To expand, a problem with F# agents is that while they serialise operations, they offer no persistence guarantees. You could send a command to an agent, only for the server to shut down before the agent completes the operation. This is particularly a risk in cloud environments.

[halcwb]

@ploeh I have to admit that this is where I went a bit "when you have a hammer everything looks like a nail".

That being said, I think that the concept behind it is not bad, offering different services that a more or less isolated and resilient. Basically that would be these services:

1. A knowledge service offering all the rules
2. A calculation/order management service
3. A product service
4. A patient/user service

It should be noted that there will be different versions of knowledge. This also will apply to the products. And in the presenting knowledge and products cases, persistence is not a concern as these services are not meant to change knowledge or the products repository.

[ploeh]

Wouldn't it be possible to keep separation of concerns even if we remove the agent infrastructure?

[halcwb]

Did some digging into how tightly the agents are actually wired in. Good news: the server already has a clean ports/adapters split, so the domain-agent question is largely decoupled from everything else.

ServerApi.Ports.fs defines AppEnv (a record of FormularyPort, OrderContextPort, OrderPlanPort, NutritionPlanPort, InteractionPort, LogAnalyzerPort). There are two adapters implementing it, both with the identical signature IResourceProvider -> AppEnv:

• ServerApi.AgentAdapters.fs — the 5 MailboxProcessor agents (current)
• ServerApi.Adapters.fs — direct service calls, already written and compiled (178 lines)

Everything downstream (Command.processCmd, ApiImpl) depends only on AppEnv, not on agents. The choice is a single line in CompositionRoot.compose:

let env = AgentAdapters.makeAppEnv provider // → Adapters.makeAppEnv provider

So to @ploeh's point — yes, separation of concerns lives in the ports, not the agents. Removing the agents keeps it intact. I'd suggest making this config/env-driven rather than a hard delete (for now), so we can A/B and revert cheaply if a real use case of Agents arises.

Actually, the whole agent per domain makes no sense when considering persistence. In that case we would need an agent per aggregate (patient), or a CQRS approach. In I would like the latter. But needs more work.

One claim in ADR-0008 doesn't hold in the current code. It says the agent "removes the need for the explicit lock inside CachedResourceProvider" — but Resources.fs:441/451 still lock lockObj. The provider is already thread-safe on its own, so the agents are serialising on top of an already-safe component. That removes the main stated justification and means the direct adapter path is safe for concurrent reads today.

• The 5 domain agents are entirely behind AppEnv → covered by the one-line swap.
• The only other agent usage anywhere is logging: the Logging.Lib MailboxProcessor logger + FileWriterAgent, and FileDirectoryAgent for log-file pruning in the server. Both adapters already use these regardless, so they're orthogonal to this decision.
• Informedica.MCP.Lib has zero agent references, despite ADR-0008/0009 saying MCP handlers wrap Agent.postAndAsyncReply — that integration goes through services directly. So MCP is not a hidden second call-site.

Consequences:

1. Flip the composition root (1 line).
2. Optionally delete AgentAdapters.fs (497 lines) + the per-library Command/Response DUs that only served it.
3. Informedica.Agents.Lib stays — still needed by the logging infra.

The logging agents are a defensible case (serialising writes to a single file / directory pruning), and whether even those are warranted is really the #416 question — separate from, and not blocking, this one.

TL;DR: the read-concurrency concern here is real, and thanks to the existing adapter design, addressing it is a one-line switch to an adapter that already exists — plus verification that the stateful ports (orderPlan/nutrition) don't hold unsynchronised mutable state outside the provider.

[ploeh]

I'll be happy to do this once I'm back from vacation, since I think this may teach me an extra thing or two about the currently implemented architecture.