Table of Contents

🇬🇧 English version

Interop Microsoft Agent Framework

Orkeon.Interop.AgentFramework relie Orkeon et Microsoft Agent Framework (MAF, Microsoft.Agents.AI) dans les deux sens : une crew Orkeon s'exécute comme un AIAgent MAF, et un AIAgent MAF travaille à l'intérieur d'une crew Orkeon — comme modèle d'un agent ou comme l'un de ses outils. La décision et ses limites sont consignées dans l'ADR-010.

Paquet Orkeon.Interop.AgentFramework — dépend du parapluie Orkeon et de Microsoft.Agents.AI.Abstractions (voir la matrice de publication)
Espaces de noms Orkeon.Interop.AgentFramework, Orkeon.Interop.AgentFramework.DependencyInjection
Exemple examples/interop/agent-framework — les deux sens sur un même hôte et un même modèle

Installer et enregistrer

dotnet add package Orkeon.Interop.AgentFramework
dotnet add package Microsoft.Agents.AI   # seulement pour construire vous-mĂŞme des agents MAF (ChatClientAgent, AsAIAgent)

Le paquet apporte Orkeon et Microsoft.Agents.AI.Abstractions avec lui. Le pont a besoin d'un hôte Orkeon — la crew s'exécute par son ICrewOrchestrationService — il se pose donc par-dessus les enregistrements habituels :

services.AddOrkeonApplication();
services.AddOrkeonInfrastructure(configuration);
// … les suites d'outils qu'utilisent vos crews …
services.AddOrkeonAgentFramework();   // Orkeon -> MAF seulement ; MAF -> Orkeon ne demande aucun enregistrement

Ce qui traverse le pont

Sens Entre Sort Reste de son côté
Crew Orkeon → MAF (CrewAgent) la conversation MAF, comme contexte initial de la crew la sortie finale de la crew en un message assistant, son usage de jetons les outils, montages, budget, mémoire et orchestration de la crew — MAF voit un agent qui répond
Agent MAF → modèle d'un agent Orkeon (WithAgentFrameworkAgent) les prompts de l'agent Orkeon, rôles projetés, chaque message une fois sur la session MAF le texte de la réponse MAF et son usage, compté une fois le LlmConfig de l'agent Orkeon (chaque option déclarée produit un avertissement) ; aucun outil Orkeon — refusés ; les outils propres de MAF restent utilisables de son côté
Agent MAF → outil Orkeon (WithAgentFrameworkTool) la chaîne request answer et agent les outils, la session et la mémoire de l'agent MAF

Une crew Orkeon comme agent MAF — CrewAgent

CrewAgent : AIAgent enveloppe une crew Orkeon. Chaque RunAsync est un kickoff de crew (ICrewOrchestrationService.KickoffAsync) :

  • EntrĂ©e — la conversation devient le contexte initial de la crew : un message seul tel quel ; plusieurs messages sous la forme Conversation so far: (les tours prĂ©cĂ©dents, une ligne rĂ´le: texte chacun) suivie de Request: et du dernier message.
  • Sortie — un message assistant portant la sortie finale de la crew, signĂ© du nom de l'agent. FinishReason vaut Stop, ou error quand la crew n'a pas rĂ©ussi. Usage porte les jetons de prompt, de complĂ©tion et le total quand le run les a mesurĂ©s, et il est absent sinon.
  • Streaming — RunStreamingAsync fonctionne, mais une crew rĂ©pond quand elle a fini : le flux est la rĂ©ponse finale, pas un flux de jetons.
  • Session — ne contient rien. Une crew ne garde aucun Ă©tat de conversation entre deux kickoffs (la mĂ©moire, quand elle est activĂ©e, est l'affaire de la crew) ; la session se sĂ©rialise en objet vide et se dĂ©sĂ©rialise depuis n'importe quoi, si bien que les appelants qui persistent leurs sessions continuent de fonctionner.
  • IdentitĂ© — l'identifiant de l'agent est orkeon-crew-<name> pour un agent construit par la fabrique, et orkeon-crew-<crewId> (aussi son nom par dĂ©faut) pour un agent construit sur un orchestrateur. Les AgentRunOptions ne sont pas lues.
  • Scope — un agent construit par la fabrique exĂ©cute chaque tour dans un scope Ă  lui : l'orchestrateur et les dĂ©pĂ´ts de crews, d'agents et de tâches sont des services scopĂ©s, si bien que deux tours, ou deux agents, ne les partagent jamais, et la fabrique se rĂ©sout sur un hĂ´te qui valide les scopes.
services.AddOrkeonAgentFramework();   // enregistre ICrewAgentFactory

var factory = host.Services.GetRequiredService<ICrewAgentFactory>();
AIAgent crewAgent = factory.Create(
    async (services, ct) =>           // le scope du tour : y enregistrer la crew, rendre son id
    {
        await services.GetRequiredService<IAgentRepository>().AddAsync(summariser, ct);
        await services.GetRequiredService<ITaskRepository>().AddAsync(summarise, ct);
        await services.GetRequiredService<ICrewRepository>().AddAsync(crew, ct);
        return crew.Id;
    },
    "orkeon-summariser",
    "Summarises text in two sentences");

var answer = await crewAgent.RunAsync("Summarise last week's incidents");

Le chargeur peut aussi bien charger un fichier de crew par l'ICrewFactory du scope (CreateFromFileAsync) et rendre l'identifiant de ce qu'il a chargé. AddOrkeonAgentFramework() n'enregistre que le singleton ICrewAgentFactory (TryAdd), sur l'IServiceScopeFactory de l'hôte ; new CrewAgent(scopeFactory, loadCrew, name, description?) fait de même sans la fabrique, et new CrewAgent(orchestrator, crewId, name?, description?) / new CrewAgent(orchestrator, crew) exécutent une crew enregistrée par un orchestrateur que l'appelant possède, avec le scope où il vit. Le résultat s'insère dans n'importe quel workflow, orchestration ou chaîne AsAIFunction() de MAF.

Un agent MAF à l'intérieur d'une crew Orkeon

Comme modèle d'un agent — WithAgentFrameworkAgent

var reviewer = new AgentBuilder()
    .Role("Reviewer").Goal("Find the biggest risk of a change")
    .WithAgentFrameworkAgent(mafAgent, logger)   // logger facultatif : il entend les options non transmises
    .Build();

WithAgentFrameworkAgent(agent, logger?) équivaut à WithLlm(new AIAgentLlmProvider(agent, logger)) : l'agent MAF devient le fournisseur propre de l'agent Orkeon (Agent.Llm). L'agent Orkeon garde son rôle, son objectif et ses tâches ; ce qui répond, c'est l'agent MAF.

  • Ce qui tourne sur lui — les tours des tâches de l'agent et leur correction de sortie, son rĂ´le de manager hiĂ©rarchique (il assigne et relit), son bulletin dans un vote consensuel. Un autre agent peut toujours lui dĂ©lĂ©guer du travail (delegate_work_to_coworker). L'agent MAF reçoit le prompt qu'Orkeon a composĂ© — le message système (rĂ´le, objectif, backstory, garde-fous, gabarit de rĂ©ponse) et le message utilisateur (la tâche, son rĂ©sultat attendu, son plan, les variables, les sorties prĂ©cĂ©dentes, les souvenirs rappelĂ©s, la connaissance), examinĂ© d'abord par le Guardian — et y ajoute ses propres instructions et fournisseurs de contexte.
  • L'ordre — le profil que nomme le llm_override d'une tâche l'emporte pour cette tâche, default compris ; sinon l'agent tourne sur son propre fournisseur. Un agent tourne sur son propre fournisseur ou sur un profil de l'hĂ´te, jamais les deux : Build() et Agent.Create refusent le fournisseur accompagnĂ© de WithLlmConfig(LlmConfig.OnProfile(nom)). Le WithManagerLlm d'une crew l'emporte toujours sur le fournisseur propre de son agent manager.
  • Aucun outil Orkeon — un agent MAF appelle les outils qu'il porte, jamais ceux d'Orkeon : AIAgentLlmProvider dĂ©clare LlmProviderCapabilities.RunsOwnTools. Un tel agent se voit refuser WithTool, WithTools et AllowDelegation Ă  sa construction (BuilderValidationException), et AddTool ensuite ; une tâche qui tombe sur un fournisseur qui fait ses propres outils — celui de l'agent, celui d'un profil ou le dĂ©faut de l'hĂ´te — avec des outils Ă  tenir (ses propres tools:, human_input, les delegate_work_to_coworker et ask_question_to_coworker d'un agent qui permet la dĂ©lĂ©gation, comme le fait un agent YAML qui n'Ă©crit pas allowDelegation: false) Ă©choue avant tout appel. Le message nomme les outils et les deux remèdes : donner l'outil Ă  l'agent MAF, ou donner l'agent MAF Ă  un agent Orkeon comme outil (WithAgentFrameworkTool, ci-dessous) — et, pour les outils de dĂ©lĂ©gation, couper la dĂ©lĂ©gation. Un mĂŞme agent Orkeon ne peut pas tenir le mĂŞme agent MAF des deux façons.
  • Limites de dĂ©bit — chaque tour qu'Orkeon envoie Ă  l'agent MAF compte pour l'agent Orkeon et sa crew, face Ă  leur maxRpm. Pour le RateLimiting de l'hĂ´te, comptent les appels que l'agent MAF fait au modèle d'Orkeon, pas ceux qu'il fait ailleurs : le pont lui-mĂŞme ne prend pas de bail.
  • Une session, chaque message une fois, un appel Ă  la fois — le fournisseur garde une seule session MAF pour toute sa durĂ©e de vie, créée au premier usage, si bien qu'un agent MAF dotĂ© de mĂ©moire ou de fournisseurs de contexte voit une conversation continue. La boucle d'agent renvoie toute la conversation Ă  chaque tour ; un appel qui prolonge la conversation que tient la session — les messages de l'appel prĂ©cĂ©dent, puis la rĂ©ponse que le fournisseur y a faite — n'envoie Ă  la session que la suite, et tout autre appel — une nouvelle tâche — envoie tous ses messages, la session gardant la tâche prĂ©cĂ©dente. Les appels passent un Ă  la fois : les tâches d'un mĂŞme agent MAF passent l'une après l'autre, mĂŞme dans une vague parallèle ou Ă  cĂ´tĂ© d'une tâche asyncExecution. La session grandit Ă  chaque tâche, et la sortie d'une tâche prĂ©cĂ©dente atteint le modèle deux fois — par la session et par les sorties prĂ©cĂ©dentes du prompt ; un ChatReducer cĂ´tĂ© MAF la borne.
  • ComptĂ© une fois — le run construit un client sur le fournisseur, une fois par instance, et le compte comme le travail de l'agent (operation: agent, manager pour les appels d'un manager). Un agent MAF bâti sur le modèle comptĂ© d'Orkeon est comptĂ© une fois, par le compteur de ce modèle, au nom du vrai fournisseur et du vrai modèle : le compteur le plus proche du modèle compte. Un agent MAF sur un client qu'Orkeon ne compte pas est comptĂ© sous agent-framework:<nom>, avec l'usage que porte sa rĂ©ponse (estimĂ© quand elle n'en porte pas).
  • Streaming — un tour diffusĂ© (--stream, KickoffStreamingAsync) reçoit la rĂ©ponse MAF en un seul fragment, comptĂ© une fois.
  • Options — le pont n'envoie Ă  l'agent MAF que des messages : les options du LlmConfig d'un appel (modèle, tempĂ©rature, jetons max, top-p, format de rĂ©ponse, rĂ©flexion, grammaire…) ne l'atteignent jamais. Chacune qu'un appel dĂ©clare — une tempĂ©rature ou un top-p quelle que soit sa valeur — produit un avertissement structurĂ© — Option '<nom>' was declared but agent-framework:<nom> does not support it — it was not sent (Ă©vĂ©nement 110, celui des fournisseurs HTTP) —, une fois par run d'une crew et par option, par le logger passĂ© Ă  WithAgentFrameworkAgent, sinon par l'ILoggerFactory qu'expose l'agent MAF (GetService), sinon nulle part. Une sortie structurĂ©e attendue d'un agent MAF n'a pour garde que la validation de sortie et sa correction.
  • Il projette les rĂ´les system, assistant et tool, et tout autre rĂ´le sur user, dĂ©clare Name = agent-framework:<nom ou id>, et relaie l'usage MAF comme dĂ©compte de jetons de la rĂ©ponse.

Comme outil — WithAgentFrameworkTool

var planner = new AgentBuilder()
    .Role("Planner").Goal("Write a plan and have it reviewed")
    .WithAgentFrameworkTool(reviewer, "ask_reviewer", "Ask the reviewer for the biggest risk of a plan")
    .Build();

WithAgentFrameworkTool(agent, toolName?, description?) ajoute un AIAgentTool à côté des autres outils de l'agent — le miroir de l'AsAIFunction() de MAF :

Nom toolName, ou agent_<slug> du nom de l'agent MAF (en minuscules, tout autre caractère devient _, les _ de tête et de fin sont retirés ; l'id de l'agent sert de repli s'il n'a pas de nom)
Description description, ou celle de l'agent MAF, ou une phrase générée
Catégorie Delegation
Entrée request (requis, refusé s'il est vide) — envoyé comme un message utilisateur
Sortie answer (le texte de l'agent MAF), agent (son nom)
Session une par instance d'outil : les appels successifs poursuivent la mĂŞme conversation MAF

Ce que le pont ne fait pas

  • Il ne traduit pas les outils d'un cĂ´tĂ© Ă  l'autre : les outils d'un agent Orkeon restent ceux d'Orkeon — refusĂ©s sur un agent auquel rĂ©pond un agent MAF —, ceux d'un agent MAF restent ceux de MAF.
  • Il ne diffuse pas de jetons : CrewAgent renvoie la rĂ©ponse finale d'une crew, et un agent auquel rĂ©pond un agent MAF reçoit cette rĂ©ponse en un seul fragment.
  • Il n'envoie aucune option Ă  un agent MAF : chacune dĂ©clarĂ©e produit un avertissement, jamais un abandon silencieux.
  • Il n'enregistre rien dans les runners livrĂ©s : orkeon, orkeon-host et le REPL ne rĂ©fĂ©rencent pas le paquet. Un hĂ´te qui embarque l'ajoute — l'exemple le fait par le hook configureServices de RunnerHost.Build (hĂ©bergement).

Voir aussi : ADR-010 · Matrice de publication · Hébergement · Retour à l'index