Liaisons d’agents pour Python dans Azure Functions

Les liaisons d’agents pour les applications de fonctions Python permettent d’ajouter des comportements agents à des fonctions existantes. Lorsque la fonction s’exécute, l’extension construit un Agent à partir d’instructions Markdown et l’injecte dans votre fonction de traitement en tant que paramètre typé. Votre code décide quand et comment invoquer l’agent en parallèle de votre logique d’application déterministe.

Important

Les liaisons d’agents pour les applications de fonctions Python sont actuellement en version préliminaire. Les fonctionnalités, les noms de paquets et la configuration peuvent changer avant la disponibilité générale.

Pour comparer les liaisons d’agents avec d’autres fonctionnalités liées à l’IA, telles que les compétences hébergées par Azure Functions et les outils Model Context Protocol (MCP), consultez les options d’intégration IA pour Azure Functions.

Une liaison d’agent est une liaison d’entrée appartenant à une extension qui fournit un objet entièrement construit Agent à une fonction Python. L’extension lit les instructions de l’agent sous forme de texte brut provenant d’un .agent.md fichier. Votre code d’application conserve la configuration d’outils spécifique au client et au fournisseur, tandis que le projet d’application de fonctions peut découvrir les compétences des agents basés sur des fichiers et des serveurs MCP distants.

L’architecture de liaison d’agents prend en charge les objets agents provenant de différents SDK via des extensions spécifiques à chaque fournisseur. Microsoft Agent Framework est le seul SDK agent pris en charge dans la version preview actuelle. Pour l’utiliser, installez le azurefunctions-agents-extensions-agent-framework paquet.

Quand utiliser les liaisons d’agent

Utilisez des liaisons d’agents lorsqu’une fonction Azure nécessite un raisonnement agent pour une partie d’un workflow, mais votre application doit conserver le contrôle sur son déclencheur, sa validation, son branchement, sa gestion des erreurs et sa réponse. Les scénarios courants sont les suivants :

  • Évaluez une requête HTTP. Validez une commande avec du code déterministe, demandez à un agent d’évaluer le risque de livraison, et utilisez le résultat pour construire la réponse HTTP.
  • Enrichir ou classifier les événements. Recevez un message de file d’attente, un événement de grille d’événements ou une autre charge utile de déclenchement et utilisez un agent pour classer, résumer ou enrichir les données avant que votre fonction n’écrive le résultat.
  • Ajoutez un raisonnement à un flux de travail durable. Appelez un agent depuis un orchestrateur Durable Functions via l’API replay-safecontext.call_agent(), puis utilisez le résultat dans les étapes d’orchestration ultérieures.

Les liaisons d’agent sont bien adaptées lorsque le code déterministe de la fonction doit continuer à jouer le rôle de coordinateur. L’agent effectue une tâche de raisonnement borné et renvoie le contrôle au gestionnaire ou à l’orchestration.

Pourquoi utiliser des liaisons d’agent ?

De nombreux flux de travail de production combinent des étapes qui doivent être déterministes avec des étapes bénéficiant du raisonnement du modèle. Les liaisons d’agents offrent les avantages suivants pour ces flux de travail hybrides :

  • Ajoutez un comportement agent aux fonctions existantes. Utilisez le raisonnement d’agent dans les fonctions déclenchées par HTTP, minuteur, file d’attente, Event Grid, Service Bus et d’autres déclencheurs.
  • Invocation de l’agent de contrôle en toute sécurité dans le code. Décidez quand invoquer l’agent, inspectez sa réponse et déterminez la sortie de la fonction. L’extension ferme les ressources appartenant à l’invocation en cas de réussite, d’échec ou d’annulation.
  • Réduisez le code de configuration de l’agent. Recevez un paramètre de gestionnaire typé Agent au lieu de le construire et de le câbler pour chaque invocation.
  • Séparez les instructions de la configuration à l’exécution. Stockez les instructions en langage naturel dans un .agent.md fichier et configurez explicitement les clients et les outils spécifiques au fournisseur en Python.
  • Utilisez les capacités d’agent partagé. L’extension découvre les compétences d’agent basées sur des fichiers et les serveurs MCP basés sur HTTP à partir de la racine de l’application et les met à disposition de chaque liaison d’agent.
  • Des agents d’appel issus d’orchestrations durables. L’extension exécute les tâches de l’agent dans une activité masquée afin que la relecture de l’orchestration reste déterministe.
  • Débogue localement avec des outils familiers. Exécutez et déboguez l’application localement comme n’importe quelle autre application de fonctions Python. Vous pouvez définir des points d’arrêt et passer à travers à la fois la logique des fonctions déterministes et le code qui invoque l’agent.

Comment fonctionne une liaison d’agent

AgentFunctionApp étend azure.functions.FunctionApp, donc il a les mêmes capacités que FunctionApp. Le décorateur markdown_agent ajoute un paramètre d’agent à une fonction.

Pour chaque liaison d’agent, l’extension effectue les opérations suivantes :

  1. Résout le fichier .agent.md demandé à partir de la racine de l’application de fonction ou depuis son répertoire agents/.
  2. Charge le fichier complet sous forme d’instructions brutes UTF-8.
  3. Combine les instructions avec l’usine client configurée, les outils fournisseurs explicitement configurés, ainsi que les compétences d’agent et serveurs MCP découverts.
  4. Crée un nouveau Agent et ouvre les ressources appartenant à l’invocation.
  5. Injecte le Agent dans le paramètre du manipulateur.
  6. Ferme les ressources appartenant à l’invocation à la fin de l’exécution.

L’extension peut mettre en cache la découverte du fournisseur et les définitions de liaison compilées. Il ne met pas en cache ni ne réutilise les ressources d’invocation en temps réel entre les invocations de fonctions.

Définir une liaison d’agent

L’exemple suivant utilise le fournisseur Microsoft Agent Framework actuellement pris en charge pour ajouter un Agent à une fonction déclenchée par HTTP. La fonction construit la tâche en code, invoque l’agent, et renvoie la réponse de l’agent :

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

La arg_name valeur doit correspondre au paramètre du gestionnaire injecté. Pour injecter plusieurs agents dans la même fonction, empilez les décorateurs markdown_agent et utilisez un paramètre arg_name unique ainsi qu’un paramètre de gestionnaire pour chaque liaison d’agent. La agent_name valeur identifie le fichier d’instructions. Dans cet exemple, order-fulfillment doit correspondre à un et un seul de ces emplacements :

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

Si les deux fichiers existent, la définition est ambiguë et le démarrage de l’application échoue. Les noms d’agents ne peuvent pas contenir de chemins absolus, de séparateurs de chemin ou de composants de traversée. Les fichiers qui se résolvent en dehors de la racine de l’application ne sont pas autorisés.

Configurez le client agent et les outils

Configurez un argument client_factory zéro lorsque vous construisez AgentFunctionApp. L’usine renvoie un client neuf soutenu par le package fournisseur. Vous pouvez aussi passer des objets de l’outil Microsoft Agent Framework ou des appelables Python via le tools paramètre au niveau de l’application. Une liaison peut prendre le dessus sur la chaîne client et les outils au niveau de l’application lorsqu’elle nécessite un comportement différent.

Par exemple, la fonction suivante déclenchée par HTTP utilise une liaison d’agent qui ne rend lookup_inventory disponible comme outil que pour order_agent:

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

Gardez ces éléments à l’esprit lorsque vous configurez le client agent et les outils :

  • L’extension de base de l’agent est indépendante du fournisseur. Un package fournisseur intègre un SDK d’agent spécifique et définit les types de client et d’agent pris en charge.
  • Le package de fournisseur Microsoft Agent Framework actuellement pris en charge ne sélectionne ni ne configure de fournisseur de modèle pour votre application. Votre fabrique de clients détermine le client de chat et le modèle pris en charge par Microsoft Agent Framework que l’agent utilise.
  • L’extension transmet l’intégralité .agent.md du fichier au fournisseur configuré sous forme d’instructions d’agent. Il n’analyse pas les paramètres de modèle, les outils, le front matter YAML, ni toute autre configuration d’exécution à partir du fichier.

Compétences d’agent partagé et serveurs MCP

L’extension découvre automatiquement les capacités d’agents partagés à partir de la racine de l’application :

Capacité Lieu Comportement
Compétences de l’agent skills/<skill-name>/SKILL.md ou Skills/<skill-name>/SKILL.md Le package du fournisseur charge et valide la compétence de l’agent basée sur un fichier.
Serveurs MCP distants mcp.json L’extension configure les serveurs HTTP pris en charge ou compatibles avec le streaming, ainsi que des listes d’autorisation d’outils facultatives.
Outils du fournisseur Application ou configuration de liaison Les objets de l’outil Microsoft Agent Framework ou les appelables Python sont explicitement fournis au lieu d’être découverts.

Gardez ces considérations à l’esprit lorsque vous utilisez des capacités d’agent partagé :

  • Chaque liaison d’agent dans l’application de fonction reçoit toutes les compétences d’agent détectées ainsi que tous les serveurs MCP.
  • Les compétences d’agent basées sur des fichiers sont des capacités qu’un agent peut charger. Ce ne sont pas des compétences hébergées par Azure Functions, qui utilisent un modèle d'exécution séparé.
  • L’aperçu actuel de l’extension agent ne permet pas de sélectionner un sous-ensemble de capacités pour une application ou un lien individuel.
  • Les compétences de l’agent et les outils MCP peuvent effectuer des opérations privilégiées. Ne placez que les capacités que chaque agent dans l’application est autorisé à utiliser, et utilisez des applications de fonctions séparées lorsque les agents nécessitent des limites de capacités différentes.

La configuration MCP peut référencer les variables d’environnement pour les URLs, les en-têtes, les champs d’authentification et les identifiants clients. Les références sont résolues pour chaque invocation, avant que l’extension ne se connecte au serveur. Ne stockez pas les secrets directement dans un fichier contrôlé mcp.json par la source.

Les serveurs MCP à processus locaux et les serveurs MCP standard d’entrée/sortie (stdio) ne sont pas pris en charge. Le support MCP est une dépendance optionnelle et les importations normales de paquets restent sûres lorsqu’il n’est pas installé.

Utilisez des liaisons d’agents avec des fonctions durables

Les liaisons d’agent prennent en charge des flux de travail hybrides à longue durée d’exécution grâce à une intégration facultative à Durable Functions. Un orchestrateur générateur synchrone appelle context.call_agent() et produit la tâche résultante :

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() planifie une activité cachée qui résout la définition de l’agent et effectue toutes les opérations de modèle, système de fichiers, identifiants, outils et réseau. L’orchestrateur ne crée qu’une requête schéma v1 déterministe et sérialisable en JSON. En conséquence, la relecture d’orchestration ne répète pas les opérations d’agent non déterministes.

Les appels d’agent durables utilisent le fournisseur ainsi que les fonctionnalités partagées configurées par AgentFunctionApp. Les entrées et sorties doivent être sérialisables en JSON.

Le support Durable Functions est optionnel. Les applications qui ne l'utilisent pas n'ont pas besoin d'installer ou d'importer Durable Functions. Pour utiliser orchestration_trigger et context.call_agent(), installez le package fournisseur pris en charge avec son supplément de dépendance durable.

Fichiers projet

Une application activée par agent est une application standard de fonctions Python v2 avec des dépendances d’extension d’agent et un ou plusieurs fichiers d’instructions :

Fichier ou dossier Purpose
function_app.py Définit AgentFunctionApp, déclencheurs de fonctions standard, liaisons d’agents, usines clients et outils fournisseurs explicitement configurés.
host.json Configure l’hôte Azure Functions.
requirements.txt Inclut un package d’agent provider pris en charge ainsi que tout package client spécifique au SDK. Pour l’aperçu actuel, utilisez azurefunctions-agents-extensions-agent-framework. Des options supplémentaires permettent la prise en charge des Durable Functions et du MCP.
*.agent.md ou agents/*.agent.md Contient des instructions brutes UTF-8 pour un agent. Chaque nom référencé doit se résoudre à exactement un fichier.
skills/ ou Skills/ (Optionnel) Contient les compétences d’agent basées sur des fichiers partagées par toutes les liaisons d’agent.
mcp.json (Optionnel) Définit les serveurs MCP distants basés sur HTTP partagés par toutes les liaisons d’agents.

Pour la structure standard Python de projet, consultez le guide développeur Azure Functions Python.

Validation et diagnostic

L’extension valide les définitions d’agents avant ou pendant la compilation de liaison afin que les problèmes de configuration échouent avec des erreurs actionnables. La validation couvre :

  • Fichiers manquants ou ambigus .agent.md .
  • Signatures de gestionnaire invalides, y compris un paramètre injecté manquant ou mal correspondant.
  • Options ou capacités de fournisseurs non supportées.
  • Répertoires de compétences invalides et configuration MCP déformée.
  • Transports MCP non pris en charge et valeurs d’environnement manquantes.
  • Des charges utiles durables invalides ou des valeurs qui ne sont pas sérialisables en JSON.

Lorsque disponible, l’extension conserve le nom de fonction Azure, l’ID d’invocation et l’ID d’instance durable à la frontière du fournisseur afin de soutenir la corrélation et le diagnostic.

  • Last updated on