π«π· Version franΓ§aise
See also: ADR-002 Β· ADR-005 Β· Back to the index
ADR-010 β Interoperability with Microsoft Agent Framework is a separate package, in both directions
Status: Accepted Β· Date: 2026-09-11
Β· Scope: src/interop/Orkeon.Interop.AgentFramework, src/packaging/Orkeon.Interop.AgentFramework, the NuGet lineup
Context
Microsoft Agent Framework (MAF, Microsoft.Agents.AI) has been GA since April 2026 and its
declarative YAML workflows since July. Its AIAgent abstraction is what a growing share of
.NET developers already have in their projects. The question was not whether to compete with
it on the promise the README used to open with β "describe your agents in YAML" β but how a
developer who has MAF code can try Orkeon without giving anything up, and how an Orkeon
crew can be one more agent in a MAF workflow.
Orkeon already carried two IChatClient adapters
(LlmProviderToChatClientAdapter, ChatClientToLlmProviderAdapter), so the model layer was
bridged. The agent layer was not: nothing turned a crew into an AIAgent, nothing let an
AIAgent answer for an Orkeon agent or be called by one.
Decision
- One package,
Orkeon.Interop.AgentFramework, depending onOrkeonand onMicrosoft.Agents.AI.Abstractionsonly. It is not folded into theOrkeonumbrella: the MAF dependency is a consumer's choice, and a consumer who never uses MAF must not restore it. The package follows the PUB-25 wrapper pattern (src/packaging/) and joins the NuGet.org lineup as its eighth id. - Both directions, three types, no new abstraction on the Orkeon side.
CrewAgent : AIAgentβ an Orkeon crew as a MAF agent.RunAsyncis one kickoff: the conversation becomes the crew's initial context, the final output the assistant message, token telemetry theUsage. Sessions hold nothing (a crew has no conversation state of its own between kickoffs) and serialise to an empty bag.AIAgentLlmProvider : ILlmProviderβ a MAF agent as the model of an Orkeon agent (AgentBuilder.WithAgentFrameworkAgent). The Orkeon agent keeps role, goal and tasks; the MAF agent answers, on one MAF session for the provider's lifetime.AIAgentTool : ToolBase<β¦>β a MAF agent as a tool of an Orkeon agent (AgentBuilder.WithAgentFrameworkTool), the mirror of MAF'sAsAIFunction(). The library builds on ports Orkeon already exposes (ICrewOrchestrationService,ILlmProvider,ToolBase); nothing in Domain, Application or Infrastructure changed for it β with one exception below, which was a bug.
- The initial context of a kickoff reaches the agents.
CrewInput.InitialContextwas mapped into the domain input and read by nothing:--initial-context, a client's field and every programmaticCrewInput.Empty("β¦")reached no prompt. The orchestrator now exposes it as theinitial_contextprompt variable (a caller-supplied variable of that name wins).CrewAgentrelies on it; so does every user who ever passed--initial-context.
Consequences
- A MAF workflow can call an Orkeon crew like any other agent; an Orkeon crew can delegate
to, or be answered by, a MAF agent. Verified end to end on a local model
(
examples/interop/agent-framework/, both directions,llama3.2:1bvia Ollama). - The interop tracks
Microsoft.Agents.AI.Abstractions1.x. A breaking change on the MAF side is absorbed in this package alone; the umbrella never sees it. Orkeon.Interop.AgentFrameworkis part of the scope freeze's interoperability exception (CONTRIBUTING): interop lowers the cost of trying Orkeon, it does not widen its surface.- Streaming from a crew is the final answer as one update: a crew has no token stream to forward. A streaming caller works; it does not see intermediate agent output.
Amendment β 2026-10-01 (GAP-25): one scope per turn
AddOrkeonAgentFramework() registered a singleton ICrewAgentFactory that captured the
host's scoped ICrewOrchestrationService: every CrewAgent of a host shared one
orchestrator, and its scoped repositories, for the life of the process, and a host validating
scopes (the default in Development) refused to resolve the factory. The orchestrator stays
scoped β its repositories are scoped by design β and the factory now holds the host's
IServiceScopeFactory only.
ICrewAgentFactory.Create(loadCrew, name, description?)replacesCreate(crewId, β¦)andCreate(crew). Every turn of the agent it returns opens a scope, callsloadCrewwith the scope's provider β it registers the crew there (adds its agents, tasks and crew to the scope's repositories, or loads it through the scope'sICrewFactory) and returns its id β kicks that crew off through the scope's orchestrator, and disposes the scope. A crew registered once in a root-resolved repository was the old contract; a scope never sees it.- The same form is public as
new CrewAgent(IServiceScopeFactory, loadCrew, name, description?); its agent id isorkeon-crew-<name>and itsCrewIdisnull(a fresh crew every turn).new CrewAgent(orchestrator, crewId|crew)stays, for a caller that owns the orchestrator and its scope.
Amendment β 2026-10-03 (GAP-34): the MAF agent answers
What was false. WithAgentFrameworkAgent set Agent.FunctionCallingLlm, a field nothing read:
an agent built with it ran its tasks on the host's default model (or its profile), with its Orkeon
tools, and the MAF agent heard nothing β neither its instructions, nor its tools, nor its memory
served. The interop test checked the field; the example exercised the tool form only. The
consequence "an Orkeon crew can β¦ be answered by a MAF agent" was never run end to end, and the
sentence of decision 2, "nothing in Domain, Application or Infrastructure changed for it", no longer
holds:
- Domain.
Agent.FunctionCallingLlmisAgent.Llm(AgentCreateOptions.Llm, thellmparameter ofAgent.Create): the provider the agent's turns run on, CrewAI'sllmgiven as an object. An agent runs on its own provider or on a host profile, never both βAgent.CreateandAgentBuilder.Build()refuse both.LlmProviderCapabilities.RunsOwnTools, declared byAIAgentLlmProvider: an agent whose own provider runs its own tools is refused Orkeon tools and delegation when it is created, andAddToolkeeps the rule. - Application.
ILlmProfileRegistry.ForProvider(provider)builds the client of an agent's own provider, once per instance, metered. The orchestrator runs on it the agent's turns, their correction round and its ballot, after the profile a task'sllm_overridenames and before the agent's profile. A task that falls on a provider running its own tools β the agent's own, a profile's, the default β with tools to hold (its own,human_input) fails before any call, naming the tools and the two remedies. - Infrastructure.
LlmProfileRegistry.ForProvideris a new entrance of the metered path.ManagerLlmResolverruns a hierarchical manager agent's own provider (provider:<name>), afterCrew.ManagerLlm.MeteredLlmProvidercounts a call once: an outer call during which a meter nearer the model counted reports nothing, so a MAF agent built over Orkeon's own model is counted under the real provider and model, and one on a client Orkeon does not meter underagent-framework:<name>.
The session. One per provider, as decision 2 chose, so a MAF agent's memory spans the Orkeon
agent's turns and tasks β but fed once: a call that extends the conversation the session holds (the
previous call's messages, then the provider's answer) sends only what is new, any other call β a new
task β sends everything, and calls run one at a time. The tasks of one MAF agent therefore run one
after another, even in a parallel wave; an earlier task's output reaches the model by the session and
by the prompt's previous outputs, and the session grows with each task (a MAF ChatReducer bounds it).
What the bridge does not send, it says. The options of a call's configuration (model, temperature, response format, thinkingβ¦) never reach a MAF agent; each one declared is a structured warning, once per crew run and option. Streaming is unchanged: a streamed turn receives the MAF answer as one fragment.
Verified. End to end in the interop suite (the MAF agent receives the composed prompt, the default
is not called, one usage event under the agent; counted once over Orkeon's model; tools refused at
build, at AddTool and at run), and by a third section of examples/interop/agent-framework/, run on
the echo provider; the campaign on a local model is the owner's.
Amendment (2026-10-29)
Decision 1 says the package depends on Orkeon and Microsoft.Agents.AI.Abstractions only. As built, Orkeon.Interop.AgentFramework.csproj references the Orkeon core projects Orkeon.Domain, Orkeon.Application and Orkeon.Tools.Abstractions, and the packages Microsoft.Agents.AI.Abstractions, Microsoft.Extensions.AI.Abstractions and Microsoft.Extensions.DependencyInjection.Abstractions.