Développement avec CopilotKit + AG-UI + Azure AI Foundry Hosted Agents

Utilisez cette skill pour les tâches de développement dans une application EXISTANTE construite sur cette stack : un frontend React/Next.js utilisant CopilotKit, connecté via le protocole AG-UI à un agent Microsoft Agent Framework (MAF) (Python ou .NET) qui s'exécute en tant qu'agent hébergé Azure AI Foundry — ou est en cours de développement contre celui-ci (service Azure payant ; l'utilisation peut entraîner des frais).

N'utilisez PAS cette skill pour scaffolder un nouveau projet. Des scaffoldeurs dédiés existent (le CopilotKit CLI, azd ai agent init) ; utilisez-les, puis revenez ici pour tout ce qui suit : ajouter des tools, les gater derrière des approbations, UI générative, état partagé, débogage, mises à jour de dépendances et déploiement des mises à jour d'agent.

Modèle mental

CopilotKit hooks (React)            useFrontendTool / useHumanInTheLoop /
        │                           useRenderToolCall / useCoAgent
        ▼
CopilotKit Runtime (route handler)  agents: { <name>: new HttpAgent({ url }) }
        │  AG-UI events over SSE
        ▼
AG-UI endpoint                      ← WHERE this lives defines your architecture
        │
        ▼
MAF Agent (tools, approval modes)   → model deployment

Le fait le plus important : un endpoint d'agent Foundry déployé ne parle pas AG-UI par défaut. Il expose un endpoint OpenAI Responses (.../protocols/openai/responses) et/ou un endpoint brut .../protocols/invocations. AG-UI doit être produit quelque part, et le lieu de sa production détermine le comportement de chaque feature (surtout human-in-the-loop). Les trois configurations sont décrites dans references/architecture.md.

Workflow

Suivez ces étapes pour chaque tâche sur cette stack :

1. Identifiez d'abord la configuration. Inspectez la base de code avant de rien modifier :
   • add_agent_framework_fastapi_endpoint(...) (Python) ou MapAGUI(...) (.NET) wrappant un agent in-process → Architecture A (endpoint AG-UI in-process).
   • Un agent hébergé dont le propre conteneur sert AG-UI, déclaré avec protocol: invocations dans agent.yaml → Architecture B.
   • Un service séparé traduisant entre l'endpoint AG-UI et l'endpoint /responses d'un agent hébergé (recherchez previous_response_id, mcp_approval_response, ou un objet Foundry conversation dans le code) → Architecture C (pont de traduction).
   • Confirmez le nom de l'agent frontend : la clé dans la config agents du runtime, la prop agent sur le provider <CopilotKit>, et le nom de l'agent hébergé dans agent.yaml doivent tous correspondre.
2. Ancrez-vous dans la documentation en direct. Chaque couche ici est en pré-1.0 ou en preview et évolue entre les versions mineures. Ne faites jamais confiance à des APIs mémorisées :
   • MAF et agents hébergés Foundry : utilisez les outils MCP Microsoft Docs quand disponibles, sinon learn.microsoft.com (/agent-framework/integrations/ag-ui/, /azure/foundry/).
   • CopilotKit : docs.copilotkit.ai (section Microsoft Agent Framework). Vérifiez les noms des hooks et de l'API runtime par rapport aux déclarations TypeScript packagées dans les packages @copilotkit/* installés — les noms ont changé (useCopilotAction est legacy ; les noms actuels incluent useFrontendTool, useHumanInTheLoop, useRenderToolCall, useCoAgent).
   • Protocole AG-UI : docs.ag-ui.com (référence événements, patterns dojo).
3. Exécutez la tâche en utilisant la référence correspondante ci-dessous.
4. Vérifiez de manière adversariale. Une build compilée, un dev server démarré, ou une réponse de chat réussie ne sont PAS des preuves. Appliquez les critères d'achèvement à la fin de cette skill.

Références

Chargez à la demande ; chacune est auto-contenue :

Playbooks de tâches

Ajouter ou modifier une tool d'agent

1. Définissez la tool sur l'agent (@tool en Python ; AIFunctionFactory.Create en .NET) avec des paramètres typés et décrits.
2. Gardez les docstrings sûrs pour le grounding : ne mettez pas de valeurs d'exemple concrètes dans les descriptions de paramètres pour les champs que le modèle doit dériver de données réelles — les modèles copient les exemples littéraux. Utilisez des placeholders et validez à l'intérieur de la tool.
3. Retournez des valeurs compactes et consommables par le modèle ; le formatage riche appartient au rendu de l'UI, pas au résultat de la tool.
4. Décidez du mode d'approbation maintenant : les tools ayant des effets secondaires obtiennent approval_mode="always_require" (voir references/hitl.md) ; les tools en lecture seule restent sans restriction.
5. Si l'appel à la tool doit s'afficher dans l'UI, ajoutez une entrée useRenderToolCall/render (references/patterns.md).
6. Vérifiez en direct : déclenchez la tool via l'UI de chat, confirmez l'appel et le résultat streamant comme événements TOOL_CALL_*, et vérifiez que les paramètres renommés ou ré-typés n'ont pas cassé un composant frontend qui parse les arguments.

Câbler human-in-the-loop sur une tool existante

Suivez references/hitl.md d'un bout à l'autre. Résumé : marquez la tool (approval_mode="always_require" / ApprovalRequiredAIFunction), activez la confirmation sur le wrapper AG-UI, enregistrez le hook d'UI d'approbation sur le frontend, et faites correspondre la forme du payload de réponse avec ce que la détection du serveur attend. Ensuite testez approuver ET rejeter ET un tour de suivi après approbation (voir le risque de double exécution).

Construire une UI générative ou un état partagé

Suivez le tableau de patterns dans references/patterns.md. Connaître la caveat d'honnêteté : les patterns de synchronisation d'état sont natifs quand l'adaptateur AG-UI wraps un agent in-process (Architecture A/B) ; via un pont du protocole Responses (Architecture C) ils nécessitent un travail de synthèse explicite — vérifiez ce que la base de code implémente réellement avant de promettre la feature.

Déboguer un flux cassé

1. Reproduisez à la couche la plus basse d'abord : curl -N l'endpoint AG-UI avec un corps JSON RunAgentInput minimal et lisez les événements SSE bruts. Si le bug se reproduit là, le frontend est innocent.
2. Pour les agents hébergés, allez une couche plus bas : appelez directement l'endpoint /responses de l'agent. C'est comme le bug de ré-exécution connu a été isolé au framework plutôt qu'à la stack UI.
3. Comparez le symptôme contre references/troubleshooting.md — les chaînes d'erreur exactes sont listées.
4. Redémarrez un agent hébergé exécuté localement (azd ai agent run) entre les passes de vérification si l'agent maintient l'état en mémoire ; l'état obsolète fait passer ou échouer les tests pour la mauvaise raison.

Mettre à jour les dépendances

Suivez references/upgrading.md. Ne bumpez jamais un seul package en isolation : les règles de relation de version là (runtime ↔ client AG-UI, cohérence de la ligne agent-framework, protocole d'hébergement ↔ version du manifest) doivent tenir simultanément, et n'importe quel workaround local doit être re-validé contre son problème upstream suivi avant suppression.

Déployer une mise à jour d'agent

Suivez references/deploy-loop.md : itérez localement contre l'agent réel avec azd ai agent run, puis azd deploy (chaque déploiement crée une nouvelle version d'agent), puis vérifiez l'agent déployé — y compris la pause d'approbation — avant de déclarer le succès.

Critères d'achèvement

Un changement sur cette stack est terminé seulement quand TOUS ceux-ci tiennent :

1. Le chemin de lecture/requête fonctionne via l'UI réelle (pas seulement via curl).
2. Chaque tool gatée par approbation a été testée des deux façons : approuver → la tool s'exécute côté serveur et l'état change visiblement ; rejeter → la tool ne s'exécute pas et l'agent reconnaît.
3. Au moins un tour de suivi a été envoyé dans le même thread après une approbation, et la tool gatée N'a PAS silencieusement exécuté à nouveau (references/hitl.md, risque de double exécution).
4. Les appels de tools s'affichent correctement à la fin du stream, pas seulement pendant le streaming (les snapshots de messages peuvent différer des événements en direct).
5. Pour les changements déployés : les vérifications ci-dessus ont été exécutées contre l'endpoint déployé, pas seulement localement — le succès du déploiement n'est pas une preuve de comportement.