Guide développeur de compétences hébergées sur Azure Functions

Les compétences hébergées Azure Functions utilisent un modèle de programmation Markdown-first sur l’environnement d’exécution Python d’Azure Functions. Vous définissez chaque compétence hébergée dans un fichier .agent.md. Les métadonnées YAML (front matter) définissent sa configuration. Le corps Markdown donne les instructions au modèle.

La plupart des travaux de développement modifient ces définitions ainsi que leurs outils et fichiers de configuration. En général, vous n’avez pas besoin de modifier le code de démarrage de Functions généré. Cependant, l’application a toujours besoin des bons réglages hôtes, des dépendances Python, de l’accès aux modèles et des permissions de service.

Important

Azure Functions Hosted Skills est actuellement en aperçu. Les fonctionnalités, les noms de configuration et les connecteurs pris en charge peuvent changer avant la disponibilité générale.

Ce guide utilise le package de préversion publique azurefunctions-agents-runtime. Pour une installation locale complète, commencez par le canvas quickstart. Pour créer des ressources Azure et déployer un exemple, utilisez le guide de démarrage rapide d’Azure Developer CLI.

Note

Un .agent.md fichier définit une compétence hébergée, qui peut s’exécuter lorsqu’un événement se produit. Un SKILL.md fichier définit un skill réutilisable, qui fournit des instructions et du matériel de référence à un skill hébergé. Ces fichiers ont des objectifs différents.

Structure du projet

Utilisez la structure suivante à la racine du projet de l'application de fonction. Ajoutez les fichiers optionnels uniquement lorsque votre application en a besoin.

<project_root>/
├── function_app.py
├── host.json
├── requirements.txt
├── local.settings.json
├── summarize.agent.md
├── agents.config.yaml
├── mcp.json
├── skills/
│   └── report-writing/
│       ├── SKILL.md
│       ├── references/
│       │   └── report-format.md
│       └── assets/
│           └── example-report.md
└── tools/
    └── get_policy.py
Fichier ou dossier Purpose
function_app.py Crée l’application Fonctions et lance la découverte à l’exécution.
host.json Définit les options hôtes d’Azure Functions, telles que les bundles d’extension et le délai d’attente de la fonction.
requirements.txt Liste l’environnement d’exécution des compétences hébergées et d’autres dépendances Python.
local.settings.json Maintient les paramètres locaux de l’application. Ne validez pas de secrets dans ce fichier.
summarize.agent.md Définit une compétence hébergée, son déclencheur et ses instructions.
agents.config.yaml Paramètres par défaut d’exécution facultatifs à l’échelle de l’application.
mcp.json Définitions optionnelles de serveurs MCP distants.
skills/ Compétences réutilisables optionnelles et leurs ressources Markdown.
tools/ Outils Python personnalisés optionnels.

Le code function_app.py de démarrage peut être aussi petit que ceci :

from azure_functions_agents import create_function_app

app = create_function_app()

L’environnement d’exécution découvre les compétences hébergées et leurs capacités configurées lorsque l’hôte Functions lance l’application. Conservez les fichiers hôte et de dépendances de votre projet de départ. Pour les fichiers standards de l’application Python, consultez le guide développeur Python.

Définir une compétence hébergée

Créez summarize.agent.md à la racine du projet :

---
name: Request summary
description: Summarize a request and identify missing information.
trigger:
  type: http_trigger
  args:
    route: summarize
    methods: [POST]
    http_auth: function
builtin_endpoints:
  debug_chat_ui: true
  http_auth: function
---

Summarize the request supplied in the HTTP request body.

Return these sections:

- Summary: State the purpose of the request.
- Missing information: List the facts needed to complete the request.
- Questions: Ask specific questions for the missing facts.

Use only the supplied facts. Do not invent names, dates, or approvals.
If the request is empty or unclear, explain what information is needed.

Cette définition accepte les requêtes HTTP POST sur la summarize route. Dans Azure, http_auth: function nécessite une clé de fonction ou d'hôte. Le préfixe standard de la route Functions est api, donc la route est normalement /api/summarize. N’utilisez pas un test local pour confirmer l’authentification déployée. Pour plus de détails, voir autorisation de déclenchement HTTP.

Le nom du fichier fournit l’identité de la compétence hébergée. Pour summarize.agent.md, le nom de la fonction Azure générée est summarize, et le segment de route de terminaison intégré est summarize. Le champ name est un nom affiché. Un changement de ce champ ne renomme pas la fonction. Un déclencheur HTTP route explicite, comme dans cet exemple, définit la route de déclenchement HTTP.

Le bloc builtin_endpoints active la fenêtre de chat et ses API de chat sous-jacentes pour des tests locaux. Pour les points de terminaison disponibles et les paramètres d’authentification, voir points de terminaison intégrés.

Rédigez des instructions claires

Indiquez l’objectif, l’entrée, les outils à utiliser et la sortie requise. Expliquez quoi faire lorsque des données manquent ou qu’un outil tombe en panne. Indiquez quelles actions la compétence hébergée ne doit pas effectuer.

Les instructions ne sont pas des contrôles d’autorisation. Validez les règles métier exactes, les autorisations et les approbations requises dans le code ou dans le service qui effectue l’action. Par exemple, une invite qui dit « envoyer uniquement les rapports approuvés » ne remplace pas une vérification d’approbation dans l’outil qui envoie le rapport.

Configurer les valeurs par défaut partagées et les substitutions

Définissez les valeurs par défaut partagées du modèle et du délai d'expiration dans agents.config.yaml :

model: $FOUNDRY_MODEL
timeout: 900

Définissez FOUNDRY_MODEL sur un déploiement de modèle disponible via votre fournisseur configuré. Pour un exemple complet des paramètres de l’application Foundry, voir Configurer les paramètres locaux. Pour les autres fournisseurs, consultez Configuration du fournisseur de modèles.

Ajouter des dérogations prises en charge pour les paramètres par défaut définis dans agents.config.yaml à l’en-tête lorsque la skill hébergée nécessite des réglages différents :

timeout: 120
mcp:
  exclude:
    - office365-outlook
skills: false

Cet exemple impose un délai d’exécution de 120 secondes, supprime un serveur MCP et désactive les compétences réutilisables pour cette compétence hébergée. Le nom du serveur exclu doit correspondre à une clé dans mcp.json.

Utilisez $SETTING_NAME pour insérer un paramètre d’application dans une valeur de chaîne prise en charge. Par exemple, model: $FOUNDRY_MODEL lit le réglage du modèle. Cette syntaxe n’est pas une syntaxe d’expression shell complète. Pour les règles de substitution, voir substitution de variables.

Définir un déclencheur

Utilisez un déclencheur explicite dans chaque .agent.md fichier qui commence par un événement. Pour traiter les messages de file d’attente stockage Azure au lieu des requêtes HTTP, remplacez le trigger bloc :

trigger:
  type: queue_trigger
  args:
    queue_name: work-items
    connection: AzureWebJobsStorage

Modifiez également les instructions pour décrire l’entrée du message de file d’attente au lieu d’un corps de requête HTTP.

La connection valeur correspond au nom d’un paramètre d’application ou au préfixe d’une collection de paramètres basée sur l’identité, et non à un secret intégré. Configurez séparément la connexion de stockage et les permissions. Pour plus d'informations, consultez Connexions aux déclencheurs de file d'attente.

Choisissez un déclencheur pour la source de l’événement :

Source de l'événement Utiliser
Demande HTTP http_trigger pour une requête et une réponse.
Schedule timer_trigger avec une planification de minuteur.
Queue ou Service Bus Un déclencheur de file d'attente ou de message pour les éléments de travail.
Changement de blob ou de base de données Le déclencheur du service de stockage ou de base de données.
Événement de service externe connector_trigger avec une source d’événement de connecteur configurée.

Pour la liste complète et les arguments requis, voir types de déclencheurs supportés.

Les points de terminaison de chat intégrés optionnels et MCP sont distincts du déclencheur explicite. Voir les points de terminaison intégrés pour plus d’informations. Une définition de serveur MCP distant dans mcp.json n'expose pas votre compétence hébergée en tant que serveur MCP.

Connectez-vous à un serveur MCP

Utilisez un serveur MCP distant lorsqu’un autre service fournit déjà les outils dont vous avez besoin. Ajoutez mcp.json à la racine du projet de l'application de fonction :

{
  "servers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

Le runtime prend en charge les transports http et streamable-http distants. Il ne démarre pas les serveurs MCP locaux stdio ni ceux basés sur des commandes.

Les compétences hébergées héritent des serveurs MCP découverts à moins que vous ne les excluiez. Pour exclure le serveur d’une compétence hébergée, définissez mcp.exclude dans le .agent.md fichier. Pour limiter un serveur à des outils spécifiques, ajoutez un tableau tools à son entrée dans mcp.json. Utilisez les noms d’outils exacts publiés par ce serveur. Cette sélection s’applique à la définition du serveur.

Pour l'authentification Microsoft Entra, définissez auth.scope sur la portée du jeton du serveur. Vous pouvez également définir auth.client_id pour sélectionner une identité managée attribuée par l’utilisateur. L’identité sélectionnée doit avoir la permission d’appeler le serveur. Ne mets pas de secrets dans mcp.json. Pour plus de détails, voir la configuration du serveur MCP.

L’exécution hébergée est non interactive. Cette configuration basée sur l’identité n’exécute pas automatiquement un flux OAuth interactif de l’utilisateur. Si un service métier nécessite une autorisation utilisateur déléguée, considérez un connecteur pris en charge et sa connexion gérée. Confirmez que le connecteur prend en compte le modèle d’autorisation requis du service. Voir Utiliser les connecteurs Azure.

Réutiliser les instructions avec des skills

Utilisez une compétence réutilisable pour les conseils dont plusieurs compétences hébergées ont besoin, ou pour le matériel de référence qui n’est pas nécessaire à chaque demande.

Créez skills/report-writing/SKILL.md :

---
name: report-writing
description: Write a review report from supplied facts. Use when a task requests a review report.
---

Read [the report format](references/report-format.md) before you write.
Use [the example report](assets/example-report.md) as a format example,
not as a source of facts.

State the result, the supporting facts, and the questions that remain.
If required facts are missing, list them. Do not invent a result.

Dans references/report-format.md, définissez les sections de rapport requises. Dans assets/example-report.md, donnez un rapport d’exemple qui montre le format.

Le name de la compétence doit correspondre au nom de son répertoire parent, par exemple report-writing. L’environnement d’exécution fournit des noms de compétences et des descriptions pour la découverte et charge des instructions complètes et des ressources à la demande. Mentionnez les ressources SKILL.md de soutien afin que la compétence hébergée sache quand les lire.

Gardez chaque compétence dans son propre dossier directement sous skills/. Pour les directives d’écriture, voir Skills.

Les fichiers Skill n’enregistrent pas automatiquement les outils exécutables. Utilisez un outil configuré pour implémenter un comportement exécutable. Ne supposez pas qu’un script dans une compétence donne au modèle la permission ou un moyen de l’exécuter.

Ajouter des outils

Commencez par utiliser un outil MCP distant ou un outil système du runtime s'il répond à vos besoins. Ajoutez des outils Python personnalisés pour la logique spécifique à chaque application.

Outils système du runtime

L’environnement d’exécution active l’outil système web_request par défaut. Il effectue des requêtes sortantes vers des adresses web publiques. Le HTTPS est requis par défaut. Pour limiter les requêtes à un nom d'hôte exact, ajoutez cette configuration à agents.config.yaml :

system_tools:
  web_request:
    allowed_hosts:
      - example.com

Définissez system_tools.web_request: false pour désactiver l'outil à l'échelle de l'application ou pour une seule compétence hébergée. Une liste d’autorisations limite les destinations. Il n’autorise pas l’utilisation d’un service ni l’envoi de données confidentielles.

Pour l'exécution isolée de code Python, configurez un pool d'interpréteurs de code Python Sessions dynamiques Azure Container Apps :

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Réglez ACA_SESSION_POOL_ENDPOINT sur le point de terminaison de gestion du pool. Accordez à l’identité de l’application les autorisations de pool requises avant utilisation. Pour les paramètres et exigences d’identité, voir exécution en sandbox.

Outils de Python personnalisés

Créez tools/get_policy.py :

from azure_functions_agents import tool


@tool
def get_policy_version() -> str:
    """Return the version of the sample review policy."""
    return "2026-10"

Utilisez un outil public par fichier .py sous tools/. L’environnement d’exécution enregistre le premier outil ordinaire pris en charge qu’il trouve dans chaque fichier. Utilisez des indices de type et un docstring clair afin que le modèle puisse comprendre l’utilité et les entrées de l’outil. Ajoutez tous les paquets nécessaires à requirements.txt.

Un outil Python personnalisé s’exécute dans le processus worker Python Functions. L'exécution n'est pas automatiquement isolée dans un sandbox. Validez les entrées, faites respecter les permissions et signalez explicitement les échecs. Pour les outils qui modifient l’état externe, rendez les appels répétés sûrs, par exemple en utilisant une clé d’idempotence.

Les outils de workflow durables utilisent un contrat séparé @workflow_tool . Pour ce modèle, voir Flux de travail dynamiques.

Gérer la configuration

Les paramètres locaux ne sont pas automatiquement copiés dans les paramètres de l'application Azure. Configurez les deux environnements. Gardez les secrets hors de Git, utilisez l’identité gérée quand c’est pris en charge, et utilisez un stockage secret approprié pour les identifiants encore nécessaires. Consultez Paramètres locaux et Gérer les paramètres de l'application.

Les limites de la compétence hébergée timeout et de l’hôte Functions functionTimeout sont distinctes. Configurez les deux pour votre charge de travail. Un timeout de compétence hébergée ne remplace pas les limites du plan d’hébergement ni les limites de réponse HTTP. Voir la durée d’expiration de Function App.

Utilisez les connecteurs Azure

Les connecteurs Azure permettent aux compétences hébergées d’appeler des opérations externes autorisées et de recevoir des événements de service sans client personnalisé ni code d’authentification. Cette section suppose que les ressources du connecteur existent déjà.

Pour configurer un serveur MCP et sa connexion, voir Créer un connecteur serveur MCP.

Pour un serveur MCP Microsoft 365 Outlook existant, ajoutez une entrée dans mcp.json:

{
  "servers": {
    "office365-outlook": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL",
      "auth": {
        "scope": "https://apihub.azure.com/.default"
      }
    }
  }
}

Réglez O365_MCP_SERVER_URL sur le point de terminaison serveur déployé dans les paramètres locaux ou de l’application Azure. Accordez à l’identité de l’application fonctionnelle l’accès à ce serveur MCP. Pour sélectionner une identité managée attribuée par l’utilisateur, ajoutez auth.client_id avec son identifiant client.

Configurez les deux limites d’autorisation :

Limite Configuration nécessaire
De l'application de fonction au serveur MCP du connecteur L’identité de l’application nécessite une autorisation pour appeler le serveur MCP.
Connexion par connecteur vers un service externe La connexion doit être autorisée pour l'utilisateur ou le service en amont, ainsi que pour les opérations requises.

Une autorisation à une frontière ne donne pas la permission à l’autre. L’autorisation de la connexion ne devient pas automatiquement l’identité de chaque appelant de votre compétence hébergée.

Pour démarrer une compétence hébergée à partir d’un événement connecteur, créez et autorisez d’abord une connexion. Utilisez ensuite le bloc de déclencheur suivant dans son fichier .agent.md :

trigger:
  type: connector_trigger

Vous devez également configurer l'événement en amont, le routage des rappels et l'authentification des rappels dans le Connector Namespace. Une définition de serveur dans mcp.json ne s’abonne pas aux événements. Pour les exigences d’extension et la configuration d’événements, voir Utiliser les connecteurs gérés dans Azure Functions.

Exécution locale

Utilisez Azure Functions Core Tools pour lancer l’application sur votre ordinateur. Vous avez également besoin de Python 3.13 ou version ultérieure et d'un accès à un déploiement de modèle.

Configurer les paramètres locaux

Créer local.settings.json à la racine du projet Function App. Pour un modèle Foundry et stockage Azure local, utilisez cette structure :

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "AZURE_FUNCTIONS_AGENTS_PROVIDER": "foundry",
    "FOUNDRY_PROJECT_ENDPOINT": "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
    "FOUNDRY_MODEL": "<model-deployment-name>"
  }
}

Remplacez les espaces réservés d’endpoint et de modèle par vos valeurs de déploiement. Utilisez un déploiement de modèle existant dans votre projet Foundry et accordez à votre identité de développeur local l’accès à celui-ci. Ajoutez tous les paramètres utilisés par vos serveurs MCP, vos outils ou vos déclencheurs. N’incluez pas local.settings.json dans le contrôle de version.

Utilisez un émulateur comme source de données lorsqu’un émulateur compatible est disponible. Par exemple, Azurite fournit du stockage local pour Blob, Queue et Table. Commencez Azurite avant l’hôte Fonctions lorsque vous utilisez UseDevelopmentStorage=true. Pour le Service Bus, voir l’émulateur Service Bus.

Les espaces de noms de connecteurs, les connexions et les serveurs MCP de connecteurs nécessitent de véritables ressources Azure. L’exécution locale appelle toujours ces ressources. Les appels de modèle et les sessions dynamiques Azure Container Apps utilisent également leurs services configurés et peuvent entraîner des frais.

Démarrer l'hôte Functions

Créez et activez un environnement virtuel Python comme décrit dans le guide de développement local Python. À la racine du projet de l'application de fonction, installez les packages à partir de requirements.txt :

python -m pip install -r requirements.txt

Pour Foundry avec un accès basé sur l’identité, connectez-vous avec un identité ayant la permission d’utiliser le modèle :

az login

Démarrez l’hôte depuis le même répertoire :

func start

L’hôte liste la summarize fonction et les points de terminaison intégrés activés par l’exemple. Avec le préfixe de route par défaut 7071 et le port api, la sortie est similaire à :

Functions:

    agent_summarize_builtin_chat: [POST] http://localhost:7071/api/agents/summarize/chat

    agent_summarize_builtin_chatstream: [POST] http://localhost:7071/api/agents/summarize/chatstream

    agent_summarize_builtin_chat_page: [GET] http://localhost:7071/api/agents/summarize/

    agent_summarize_builtin_history: [GET] http://localhost:7071/api/agents/summarize/history

    summarize: [POST] http://localhost:7071/api/summarize

Laissez l'hôte en cours d'exécution pendant les tests. Lisez la sortie du terminal pour détecter les erreurs de configuration et les URL de fonction enregistrées. Pour plus d’informations, consultez Exécuter des fonctions localement.

Tester avec la fenêtre de conversation

L’exemple summarize.agent.md active déjà la fenêtre de chat intégrée et les API de chat sous-jacentes associées.

Ouvrez http://localhost:7071/api/agents/summarize/ dans votre navigateur lorsque host.json utilise le préfixe de route par défaut api. Si votre projet de départ définit extensions.http.routePrefix sur une chaîne vide, utilisez http://localhost:7071/agents/summarize/ à la place. Utilisez le port hôte réel s’il diffère de 7071.

Saisissez une requête d’exemple, envoyez-la et inspectez la réponse et le journal de l’hôte. Par exemple, demandez à la compétence hébergée de résumer une demande avec une date de livraison manquante. Vérifiez que la réponse identifie la date manquante au lieu d’en inventer une. Testez aussi l’absence de saisie et les défaillances des outils.

L’exécution par Local Core Tools saute normalement les vérifications des touches de fonction. Conservez http_auth: function dans la définition et testez séparément l'authentification dans Azure. Pour une fenêtre de conversation déployée, fournissez la clé de fonction lorsqu'elle vous est demandée. Activez les points de terminaison de débogage uniquement lorsque cela est nécessaire. Pour les routes et la récupération des clés, consultez Points de terminaison intégrés.

Déployer sur Azure

Choisissez une méthode de déploiement pour votre projet :

Method Conseils
Exemple avec un modèle de Bicep Utilisez le dépôt d’exemples de compétences hébergé. Son modèle d’infrastructure crée les ressources nécessaires. Suivez le démarrage rapide de la CLI pour développeurs Azure afin de configurer et exécuter azd up.
Canevas Azure Functions Hosted Skills Utilisez le canevas pour créer et tester une application, puis sélectionnez Déployer sur Azure. Consultez le guide de démarrage rapide du canevas des compétences hébergées.
Azure Functions Skills Installez Azure Functions Skills. Sa compétence de créationazure-functions-hosted-skills aide votre agent de codage à créer une application et à préparer son déploiement. Demandez à l’agent de codage de déployer l’application, puis examinez les ressources proposées, les permissions et le coût avant d’approuver le déploiement.

Après le déploiement, vérifiez que les paramètres de l’application Azure contiennent les valeurs requises, que l’identité de l’application a accès au modèle et aux outils, et que chaque connexion de connecteur est autorisée. Testez le déclencheur déployé et son authentification avec une requête contrôlée avant d’utiliser les données de production.

Explorez des exemples de bout en bout

Utilisez ces exemples pour voir comment les compétences hébergées combinent déclencheurs, outils et services Azure dans une application complète. Chaque dépôt comprend des instructions d’installation et de déploiement.

Sample Ce qu’il montre
Examen des polices d'assurance Démarrez un flux de travail durable à partir d’un message de file d’attente, examinez les documents en parallèle, puis enregistrez un rapport dans Stockage Blob pour une relecture humaine.
Processeur de notes de frais Traitez les notes de frais à partir d'une file d'attente, lisez les documents de stratégie via un serveur MCP de connecteur et acheminez les résultats vers des files d'attente de sortie. Les appels de modèle utilisent une passerelle Gestion des API Azure AI.
Résumé quotidien du blog Utilisez des déclencheurs de conversation et de minuteur pour résumer des billets de blog à l'aide d'un interpréteur de code dans les sessions dynamiques Azure Container Apps. Si vous le souhaitez, envoyez le résumé via un connecteur Microsoft 365 Outlook.