Référence d’exécution des agents serverless

Cet article fournit la référence de configuration pour l’exécution des agents serverless Azure Functions. Pour un aperçu du runtime et des conseils sur le moment de son utilisation, voir Runtime des agents serverless dans Azure Functions.

Important

L’exécution des agents serverless 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.

Informations de référence sur les fichiers de l’agent

Un fichier agent (.agent.md) utilise le front matter YAML pour configurer l’agent, suivi d’instructions markdown.

Champs front-matière

Utilisez ces champs front matter pour configurer un agent :

Champ Obligatoire Description
name Oui Nom affiché pour l’agent.
description Oui Brève description de ce que fait l’agent et quand il doit être utilisé.
trigger Oui (sauf si builtin_endpoints c’est activé) Définit la façon dont l’agent est appelé. Un seul déclencheur est autorisé par fichier d’agent.
builtin_endpoints Non Active les points de terminaison de débogage et de composition intégrés. Permet true d’activer tous les points de terminaison intégrés, ou de configurer debug_chat_ui, chat_apiet mcp individuellement. debug_chat_ui: true active également les routes de backing chat et chatstreamde point de terminaison car l’interface intégrée appelle ces API.
input_schema Non Schéma JSON utilisé pour valider les corps de requête HTTP pour les agents déclenchés par HTTP.
logger Non Contrôle si la journalisation du runtime est activée pour l’agent. La valeur par défaut est true.
mcp Non Contrôle l’accès aux serveurs MCP découverts à partir de mcp.json. Permet false de désactiver les serveurs MCP pour cet agent ou d’utiliser exclude pour supprimer des serveurs spécifiques.
metadata Non Métadonnées personnalisées pour votre organisation ou vos outils.
model Non Remplace le modèle par défaut configuré dans agents.config.yaml ou dans les paramètres de l’application.
response_example Non Exemple de forme de réponse utilisée pour guider les réponses structurées à partir d’agents déclenchés par HTTP.
response_schema Non Schéma JSON utilisé pour valider les réponses structurées retournées par les agents déclenchés par HTTP.
skills Non Contrôle l’accès aux compétences découvertes. Permet false de désactiver les compétences de cet agent ou exclude de supprimer des compétences spécifiques.
substitute_variables Non Contrôle si la substitution des variables d’environnement est appliquée à la matière et aux instructions de départ. La valeur par défaut est true.
system_tools Non Cela permet à un agent de se retirer des outils système configurés, comme l’exécution en mode bac à sable.
timeout Non Remplace le délai d’attente d’exécution par défaut, en secondes.
tools Non Contrôle l’accès aux outils Python personnalisés découverts. Permet false de désactiver des outils personnalisés pour cet agent ou d’utiliser exclude pour supprimer des outils spécifiques.

Configuration de déclencheur

Chaque fichier agent prend en charge un déclencheur, défini dans l’objet trigger dans la matière de départ.

Champ Obligatoire Description
type Oui Le type de blocage de détente. Voir le tableau des types pris en charge pour les valeurs autorisées.
args Dépend du type Paramètres spécifiques au déclencheur qui déterminent quel événement lance l’agent.

Types de déclencheurs pris en charge

Le tableau suivant liste les valeurs prises en charge trigger.type , leurs exigences args, ainsi que les liens vers la référence complète par type :

trigger.type Obligatoire args Reference
http_trigger route Déclencheur HTTP
timer_trigger schedule Déclencheur du minuteur
queue_trigger queue_name, connection Déclencheur de file d’attente
blob_trigger path, connection Déclencheur d’objet blob
event_grid_trigger (aucun) Déclencheur Event Grid
event_hub_message_trigger event_hub_name, connection Déclencheur du Event Hub
service_bus_queue_trigger queue_name, connection Déclencheur de file d’attente Service Bus
service_bus_topic_trigger topic_name, subscription_name, connection Déclencheur de sujet Service Bus
cosmos_db_trigger connection, database_name, container_name Déclencheur Cosmos DB
cosmos_db_trigger_v3 database_name, collection_name, connection_string_setting Déclencheur de base de données Cosmos v3
sql_trigger table_name, connection_string_setting Déclencheur SQL
mysql_trigger table_name, connection_string_setting Déclencheur MySQL
kafka_trigger topic, broker_list Déclencheur de Kafka
dapr_binding_trigger binding_name Détente de liaison Dapr
dapr_service_invocation_trigger method_name Déclencheur d’invocation de service Dapr
dapr_topic_trigger pub_sub_name, topic Déclencheur thématique Dapr
generic_trigger type (nom du type de liaison) Déclencheur générique
connector_trigger configuré dans l’espace de noms Connecteur. Détente de connecteur

Exemples de déclencheurs

Les exemples suivants montrent des configurations de déclencheurs courantes :

Déclencheur de minuterie (fonctionne tous les jours à 15h00 UTC) :

trigger:
  type: timer_trigger
  args:
    schedule: "0 0 15 * * *"

Déclencheur HTTP :

trigger:
  type: http_trigger
  args:
    route: summarize
    auth_level: FUNCTION

Déclencheur de file d’attente :

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

Déclencheur de blob :

trigger:
  type: blob_trigger
  args:
    path: uploads/{name}
    connection: AzureWebJobsStorage

Configuration à l’échelle de l’application (agents.config.yaml)

Utilisez agents.config.yaml pour les valeurs par défaut du runtime à l’échelle de l’application que chaque agent peut hériter. Le runtime peut charger une application sans ce fichier. Ajoutez-le si vous avez besoin de paramètres partagés tels que le déploiement d’un modèle, un délai d’expiration ou un point de terminaison d’exécution en bac à sable.

Ce fichier est une entrée au niveau de l’application. Le runtime découvre également les serveurs MCP de mcp.json, les compétences de skills/ et les outils de Python personnalisés de tools/. Ces fonctionnalités sont activées sur les agents par défaut. Les métadonnées d’en-tête de l’agent peuvent remplacer les paramètres par défaut d’exécution ou filtrer les serveurs MCP, les compétences et les outils hérités.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Les agents individuels peuvent remplacer les paramètres d’exécution pris en charge dans leurs propres métadonnées d’en-tête.

Champs de configuration

Utilisez ces champs de niveau supérieur dans agents.config.yaml:

Champ Obligatoire Description
model Non Modèle ou déploiement de modèle par défaut utilisé par les agents qui ne définissent pas model dans leur propre en-tête.
timeout Non Délai d’expiration d’exécution par défaut, en secondes. La valeur par défaut du runtime est de 900 secondes.
system_tools.dynamic_sessions_code_interpreter.endpoint Lors de l’utilisation d’une exécution isolée Point de terminaison de gestion pour le pool dynamique de sessions Azure Container Apps utilisé par les outils de sandbox.
system_tools.dynamic_sessions_code_interpreter.client_id Non ID client de l’identité managée utilisée pour appeler le pool de sessions.
tools.exclude Non Liste d’exclusion globale pour les outils de Python personnalisés découverts à partir du dossier tools/.

Ordre de résolution

Le runtime résout d’abord les valeurs du front matter de l’agent, puis agents.config.yaml, puis les paramètres de l’application et les valeurs par défaut du runtime. Les valeurs de chaîne dans agents.config.yaml peuvent référencer les paramètres d’application, tels que $AZURE_OPENAI_DEPLOYMENT ou $ACA_SESSION_POOL_ENDPOINT.

Conservez les valeurs par défaut de modèle, de délai d’attente et d’outil système dans agents.config.yaml. Conservez les définitions de serveurs MCP distants, y compris les points de terminaison de serveurs MCP issus des espaces de noms de connecteur, dans mcp.json.

Substitution de variable

Le runtime peut remplacer les paramètres d’application et les variables d’environnement en valeurs de chaîne dans le front matter de l’agent, les corps d’instructions de l’agent, agents.config.yamlet mcp.json.

Pour les substitutions, vous pouvez utiliser soit $SETTING_NAME%SETTING_NAME%, soit , qui sont gérés de la même manière par l’exécution à l’exécution. Les noms de variables doivent commencer par une lettre ou un trait de soulignement et peuvent contenir des lettres, des chiffres et des traits de soulignement.

model: $FOUNDRY_MODEL
system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: %ACA_SESSION_POOL_ENDPOINT%

Email the summary to $TO_EMAIL.

{
  "servers": {
    "office365": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL"
    }
  }
}

Règles de remplacement :

  • S’applique aux valeurs de chaînes, y compris les chaînes imbriquées dans des objets ou des listes. Cela ne s’applique pas aux clés objet.
  • Les blocs de code délimités dans les corps d’instructions de l’agent ne sont pas remplacés, de sorte que les exemples peuvent inclure le texte littéral $VALUE ou %VALUE%.
  • Utiliser $$SETTING_NAME ou %%SETTING_NAME%% pour des substituts significatifs dans le contenu substitutif.
  • Les variables manquantes restent inchangées. Les valeurs vides se résolvent en chaînes vides.
  • La substitution est un passage simple. La ${SETTING_NAME} syntaxe n’est pas prise en charge.
  • Pour désactiver la substitution pour un agent, il faut définir substitute_variables: false dans le fichier agent. Cela ne désactive pas la substitution dans agents.config.yaml ou mcp.json.

Configuration du serveur MCP (mcp.json)

Lorsqu’une application utilise des serveurs MCP distants, ajoutez mcp.json à la racine du projet d’application de fonction. Le runtime découvre les serveurs HTTP distants ou HTTP MCP streamables à partir de ce fichier et met leurs outils à la disposition des agents, soumis à tous les filtres par agent.

Champs d’entrée serveur

Utilisez ces champs dans chaque servers entrée :

Champ Obligatoire Description
type Oui Utilisez http ou streamable-http. Les serveurs MCP locaux stdio ne sont pas pris en charge par le runtime.
url Oui Point de terminaison de serveur MCP distant. La substitution de variable d’environnement est prise en charge.
headers Non En-têtes statiques pour un serveur MCP distant générique. Ne stockez pas de secrets statiques dans mcp.json.
auth.scope Lors de l’utilisation de l’authentification Microsoft Entra Microsoft Entra étendue de jeton utilisée pour authentifier les appels au serveur MCP.
auth.client_id Non ID client de l’identité managée à utiliser lors de l’authentification auprès de ce serveur MCP. Omettez ce champ pour utiliser l’identité managée attribuée par le système de votre application de fonction dans Azure.

Authentication

Utilisez l’étendue du hub d’API Azure lorsque l’agent consomme un serveur MCP managé à partir d’un espace de noms de connecteur. Ne stockez pas les secrets utilisateur dans mcp.json.

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

Le auth.client_id paramètre sélectionne l’identité managée qui s’authentifie auprès du serveur MCP. Définissez-la sur l’ID client d’une identité managée attribuée par l’utilisateur. Omettez ce paramètre pour utiliser l’identité managée attribuée par le système de l’application de fonction dans Azure. L’identité sélectionnée ou votre identité de développeur local lorsque vous exécutez localement doit être autorisée à appeler le serveur MCP.

connecteurs Azure

Les connecteurs permettent aux agents d’utiliser des services externes sans code client d’API personnalisé. Par exemple, un connecteur Microsoft 365 Outlook peut envoyer des e-mails, un connecteur Teams peut utiliser des messages et d’autres connecteurs peuvent appeler des actions dans des systèmes tels que Salesforce, SAP ou SQL. Un espace de noms de connecteur héberge les connexions, les déclencheurs et les serveurs MCP qui rendent ces intégrations disponibles pour votre application.

Pour utiliser les capacités de connecteurs dans une application agents serverless, créez d’abord une ressource Connector Namespace, créez une connexion au service, puis autorisez cette connexion. Choisissez ensuite comment l’agent utilise la connexion :

  • Le connecteur déclenche des agents de démarrage lorsqu’un événement se produit dans un service connecté, tel qu’un nouvel e-mail, un message Teams ou un événement de calendrier. Pour en utiliser un, créez un déclencheur dans l’espace de noms du connecteur qui utilise la connexion autorisée, puis configurez l’agent avec le nom et les arguments du déclencheur à partir de cette définition de déclencheur de connecteur.
  • Les outils MCP du connecteur permettent aux agents d’appeler des actions de service, telles que l’envoi d’e-mails ou la mise à jour d’un enregistrement. Pour les utiliser, créez un serveur MCP dans l’espace de noms du connecteur qui utilise la connexion autorisée, puis ajoutez le point de terminaison du serveur MCP à mcp.json.

Pour plus d’informations, voir Utiliser les connecteurs dans Azure Functions.

Compétences

Enregistrez les ressources de prompt réutilisables dans skills/. Ils aident à réduire les instructions de l’agent de base tout en rendant les instructions spécifiques au domaine disponibles si nécessaire. Le runtime utilise le format Compétences de l’agent .

Format de compétence

L’exécution scanne skills/ dans la racine du projet de l’application de fonction et découvre récursivement les dossiers contenant SKILL.md.

skills/
  incident-response/
    SKILL.md
    triage-checklist.md
    escalation-policy.md

Le fichier SKILL.md contient un en-tête YAML suivi d’instructions au format Markdown.

---
name: incident-response
description: Triage production incidents, summarize impact, and recommend next steps. Use when the task mentions incidents, outages, alerts, or severity levels.
---

Follow the incident response checklist in [triage-checklist.md](triage-checklist.md).

Règles d’auteur

Suivez ces directives lors de la création de vos fichiers d’agent et d’autres ressources de projet :

  • Chaque dossier de compétences doit contenir un SKILL.md fichier.
  • Les champs name et description sont obligatoires.
  • Utilisez des lettres minuscules, des chiffres et des traits d’union simples pour les noms de compétences. N’utilisez pas d’espaces, de traits de soulignement, de lettres majuscules, de traits d’union de début, de traits d’union de fin ou de traits d’union répétés.
  • Les noms de compétence doivent être uniques dans l’application.
  • La description doit expliquer à la fois ce que fait la compétence et quand l’agent doit l’utiliser. Le runtime charge d’abord les noms et descriptions des compétences afin que l’agent puisse décider quand charger la compétence complète.
  • Les compétences peuvent inclure plusieurs fichiers Markdown dans le même dossier de compétences. Faites référence aux fichiers Markdown associés depuis SKILL.md, à l’aide de liens relatifs.
  • L’environnement d’exécution des agents serverless prend uniquement en charge les fichiers Markdown en tant que contenu de compétence. Si une compétence nécessite un comportement exécutable, emballez ce code sous forme d’outil Python personnalisé et réfoncez-vous à l’outil par son nom dans les instructions de compétence.

Compétences de filtrage par agent

Les agents héritent de toutes les compétences découvertes par défaut. Désactivez ou excluez les compétences dans un fichier d’agent quand un agent spécifique ne doit pas les utiliser :

skills: false

skills:
  exclude:
    - incident-response

Exécution en bac à sable

Pour l’exécution du code ou l’automatisation du navigateur, le runtime peut utiliser Azure Container Apps sessions dynamiques. Les sessions dynamiques fournissent des environnements isolés à partir de pools de sessions. Le runtime utilise des sessions d’interpréteur de code pour fournir un execute_python outil aux agents.

Configuration

Configurer l’exécution en bac à sable dans agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Exigences

  • Le pool de sessions doit être un pool de sessions d’interpréteur de code Python, tel qu’un pool créé avec --container-type PythonLTS.
  • La valeur endpoint est le point de terminaison de gestion du pool de sessions.
  • Dans Azure, l’identité gérée utilisée par l’application de fonctions doit avoir les attributions de rôles nécessaires pour exécuter le code dans le pool de session. Les sessions d’interpréteur de code Azure Container Apps nécessitent les rôles Azure ContainerApps Session Executor et Contributor dans le pool de sessions.
  • Lors de l’exécution locale, votre identité de développeur doit avoir le même accès requis au pool de sessions.
  • Pour utiliser une identité managée attribuée par l’utilisateur pour l’exécution en bac à sable, définissez system_tools.dynamic_sessions_code_interpreter.client_id sur l’ID client de l’identité qui dispose des attributions de rôle nécessaires. Si ce paramètre n’est pas défini, le runtime utilise AZURE_CLIENT_ID, puis la chaîne d’informations d’identification par défaut.

L’outil sandbox exécute Python dans une session isolée. Les variables, les importations et les fichiers peuvent persister entre les appels d’outil dans la même session d’agent. Quand aucun ID de session de l’agent n’est disponible, le runtime utilise une nouvelle session de bac à sable afin que les exécutions non liées ne partagent pas l’état.

Désactivation par agent

Les agents héritent de l’exécution en bac à sable si celle-ci est configurée globalement. Vous pouvez désactiver l’exécution pour un agent spécifique en définissant dynamic_sessions_code_interpreter dans false le fichier de l’agent.

system_tools:
  dynamic_sessions_code_interpreter: false

Outils de Python personnalisés

Utilisez des outils Python personnalisés lorsque vous avez besoin d'une logique spécifique à une application que les capacités intégrées du runtime ne couvrent pas. Les outils personnalisés s’exécutent dans le processus de l’application de fonctions, pas dans une session en bac à sable.

Découverte d’outils

Ajoutez des fichiers outils au tools/ dossier dans la racine du projet d’application de fonction :

tools/
  submit_ticket.py
  lookup_customer.py

L’environnement d’exécution découvre les fichiers .py dans tools/ dont le nom de fichier ne commence pas par _. Dans la préversion actuelle, le runtime inscrit le premier outil pris en charge à partir de chaque fichier. Utilisez un outil par fichier pour maintenir la découverte prévisible.

Définition des outils

Définissez un outil en décorant une fonction avec @tool du package d’exécution :

from azure_functions_agents import tool


@tool(name="submit_ticket", description="Create a support ticket with a title and summary.")
async def submit_ticket(title: str, summary: str) -> str:
    return f"Created ticket for {title}: {summary}"

Pour obtenir des descriptions et une validation de paramètres plus riches, utilisez un modèle Pydantic comme schéma d’outil :

from pydantic import BaseModel, Field
from azure_functions_agents import tool


class LookupCustomerParams(BaseModel):
    customer_id: str = Field(description="Customer identifier from the CRM system.")


@tool(schema=LookupCustomerParams, description="Look up customer details by customer ID.")
async def lookup_customer(params: LookupCustomerParams) -> str:
    return f"Customer details for {params.customer_id}"

Vous pouvez également définir une fonction Python simple sans décorateur. Le runtime encapsule la première fonction simple qu’il trouve dans le fichier, utilise le nom de la fonction comme nom d’outil et utilise la documentation comme description de l’outil.

def summarize_order(order_id: str) -> str:
    """Summarize an order by order ID."""
    return f"Summary for order {order_id}"

Les noms d’outils, les descriptions, les indicateurs de type et les descriptions de champs Pydantic aident le modèle à décider quand et comment appeler l’outil. Ajoutez à requirements.txt toutes les dépendances utilisées par les outils personnalisés, comme vous le feriez pour d’autre code Python dans une application Azure Functions.

Outils de filtrage par agent

Les agents héritent des outils personnalisés découverts par défaut. Désactivez ou excluez les outils personnalisés dans un fichier d’agent quand un agent spécifique ne doit pas les utiliser :

tools: false

tools:
  exclude:
    - submit_ticket

Configuration du fournisseur de modèles

Le runtime utilise Microsoft Agent Framework pour appeler des fournisseurs de modèles. La préversion inclut Azure OpenAI, Azure AI Foundry et OpenAI.

Sélection du fournisseur

Vous devez configurer au moins un signal fournisseur pour l’exécution afin de créer un client de chat. Vous pouvez définir explicitement le fournisseur en utilisant ce AZURE_FUNCTIONS_AGENTS_PROVIDER paramètre ou laisser l’exécution déduire le fournisseur à partir de vos autres paramètres d’application.

Utilisez ces paramètres du fournisseur :

Provider AZURE_FUNCTIONS_AGENTS_PROVIDER valeur Paramètres obligatoires Paramètres facultatifs Comportement de la configuration du modèle
Azure AI Foundry foundry FOUNDRY_PROJECT_ENDPOINT AZURE_CLIENT_ID Quand vous souhaitez une identité gérée attribuée à l’utilisateur Définissez FOUNDRY_MODEL le nom de déploiement du modèle que le projet Foundry doit utiliser.
Azure OpenAI azure_openai AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT AZURE_OPENAI_API_KEY, AZURE_OPENAI_API_VERSION, AZURE_CLIENT_ID lorsque vous souhaitez une identité managée attribuée par l’utilisateur Régler AZURE_OPENAI_DEPLOYMENT sur le nom de déploiement Azure OpenAI.
OpenAI openai OPENAI_API_KEY None Définissez AZURE_FUNCTIONS_AGENTS_MODEL le nom du modèle OpenAI lorsque vous ne passez pas un modèle en configuration agent ou runtime.

Lorsque vous ne définissez AZURE_FUNCTIONS_AGENTS_PROVIDERpas , l’exécution détecte automatiquement le fournisseur dans cet ordre :

  1. AZURE_OPENAI_ENDPOINTsélectionne Azure OpenAI.
  2. FOUNDRY_PROJECT_ENDPOINTsélectionne Azure AI Foundry.
  3. OPENAI_API_KEY sélectionne OpenAI.

Lorsque vous vous appuyez sur l’auto-détection, le paramètre spécifique au fournisseur qui a identifié le fournisseur doit toujours être accompagné du modèle requis par le prestataire. Par exemple, FOUNDRY_PROJECT_ENDPOINT a toujours besoin FOUNDRY_MODELde , et AZURE_OPENAI_ENDPOINT a toujours besoin AZURE_OPENAI_DEPLOYMENTde .

AZURE_FUNCTIONS_AGENTS_MODEL est un réglage de modèle de secours à l’échelle de l’exécution. Ses valeurs valides dépendent du fournisseur actif :

  • Pour Azure AI Foundry, utilisez un nom de déploiement de modèle existant dans le projet Foundry, tel que gpt-5.4.
  • Pour Azure OpenAI, utilisez le nom de déploiement uniquement si vous souhaitez intentionnellement le plan de secours à l’échelle de l’exécution. Dans la plupart des applications, il faut plutôt régler AZURE_OPENAI_DEPLOYMENT .
  • Pour OpenAI, utilisez le nom de modèle accepté par l’API OpenAI, tel que gpt-4o-mini.

Priorité du modèle

La sélection de modèle utilise cette priorité générale :

  1. Le modèle demandé par l’agent ou par l’appel du runtime.
  2. Paramètres spécifiques au fournisseur, tels que AZURE_OPENAI_DEPLOYMENT ou FOUNDRY_MODEL.
  3. Le modèle a défini dans AZURE_FUNCTIONS_AGENTS_MODEL.
  4. Le modèle par défaut intégré au fournisseur actif.

Configuration d’une identité managée

L’exécution utilise des identités gérées lors de la connexion aux ressources Azure qui prennent en charge l’authentification Microsoft Entra. Utilisez AZURE_CLIENT_ID comme sélecteur d’identité par défaut de l’application, ou utilisez des réglages spécifiques à chaque fonctionnalité pour un contrôle plus précis :

Fonctionnalité d’exécution Paramètres d’identité Solution de secours1
Azure OpenAI modelprovider 2 AZURE_CLIENT_ID DefaultAzureCredential
fournisseur de modèles Azure AI Foundry AZURE_CLIENT_ID DefaultAzureCredential
Azure Container Apps bac à sable pour sessions dynamiques system_tools.dynamic_sessions_code_interpreter.client_id AZURE_CLIENT_ID, alors DefaultAzureCredential
Serveurs MCP hébergés dans des espaces de noms de connecteur La valeur auth.client_id dans l’entrée du serveur dans mcp.json AZURE_CLIENT_ID, alors DefaultAzureCredential
Historique des sessions soutenus par desblobs 3 AzureWebJobsStorage__clientId AZURE_CLIENT_ID, alors DefaultAzureCredential
  1. Lorsqu’aucun paramètre d’identité n’est configuré, l’exécution utilise DefaultAzureCredential, qui résout à l’identité managée attribuée par le système dans Azure et à l’identité de votre développeur (Azure CLI ou Visual Studio) localement.
  2. Lorsqu’une clé API est configurée dans Azure OpenAI (en utilisant AZURE_OPENAI_API_KEY), le fournisseur du modèle utilise la clé au lieu d’une identité gérée. Pour plus d’informations, voir l’extension Azure OpenAI pour Azure Functions.
  3. L’historique des sessions utilise la même configuration par défaut d’identité de stockage hôte que l’hôte Azure Functions. Utilisez AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri et AzureWebJobsStorage__clientId pour configurer le stockage basé sur l’identité pour l’historique basé sur des blobs. Le runtime n’utilise pas de paramètre d’identité distinct propre à l’agent pour l’historique de session. Pour plus d’informations, voir Définir les connexions dans le guide développeur des fonctions.

Points de terminaison intégrés

L’exécution expose des terminaux intégrés optionnels lorsqu’un agent s’inscrit via les builtin_endpoints paramètres de son contenu principal. Ces points de terminaison sont utiles pour le développement, les tests et les diagnostics. Ils ne sont pas conçus comme l’interface principale de l’application en production.

Activez les points de terminaison intégrés dans le dossier de l’agent :

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

Le paramètre debug_chat_ui: true active aussi les chat API et chatstream car l’interface utilisateur en dépend. Configurez-le chat_api: true tout seul lorsque vous voulez un accès programmatique au chat sans l’interface de débogage.

Itinéraires de point de terminaison

Le <AGENT_NAME> segment de route provient du nom du .agent.md fichier, pas du champ d’affichage name . Par exemple, main.agent.md utilise /agents/main/.

Surface Itinéraire Exigence clé
Interface utilisateur de conversation /agents/<AGENT_NAME>/ Clé de fonction (demandée dans le navigateur).
API de conversation HTTP POST /agents/<AGENT_NAME>/chat Clé de fonction.
API de conversation en streaming POST /agents/<AGENT_NAME>/chatstream Clé de fonction.
Point de terminaison MCP /runtime/webhooks/mcp mcp_extension clé système.

Récupération des clés

Lorsque vous hébergez l’interface de chat sur Azure, elle vous demande une touche de fonction avant d’envoyer des messages. Vous pouvez utiliser la clé en appelant directement les API de chat HTTP.

Utilisez la commande suivante az functionapp keys list pour récupérer la touche de fonction par défaut de votre application :

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "functionKeys.default" \
  --output tsv

Dans cet exemple, remplacez <RESOURCE_GROUP> et <FUNCTION_APP_NAME> par vos noms de groupe et d’application. Vous pouvez inclure la clé retournée dans l’en-tête x-functions-key ou un code paramètre de chaîne de requête dans la requête HTTP vers le point d’extrémité.

Lors de la connexion à un client MCP, demandez plutôt le système d’extension MCP à l’aide de la commande suivante :

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "systemKeys.mcp_extension" \
  --output tsv

Le point d’extrémité MCP nécessite cette clé système.

Flux de requêtes API de chat

Les deux API de chat intégrées s’attendent à un corps JSON avec un prompt champ :

{
  "prompt": "Summarize today's failures."
}

Utilisez-les POST /agents/<AGENT_NAME>/chat quand vous voulez une réponse JSON. Le corps de réponse comprend session_id, response, et tool_calls. L’exécution fait également écho au même ID de session dans l’en-tête x-ms-session-id de la réponse.

Utilisez-les POST /agents/<AGENT_NAME>/chatstream quand vous voulez Server-Sent événements (SSE). Le flux commence par un session événement contenant l’ID de session résolu, suivi de zéro ou plus delta, intermediate, tool_start, et tool_end événements, et se termine par soit done .error

Pour poursuivre une conversation multi-tours, envoyez l’ID de session de la réponse précédente dans l’en-tête x-ms-session-id de requête sur les appels ultérieurs chat ou (plus tard).chatstream Si vous omettez cet en-tête, l’exécution crée automatiquement une nouvelle session.

POST /agents/main/chatstream HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
x-ms-session-id: <SESSION_ID_FROM_A_PREVIOUS_RESPONSE>

{"prompt":"Continue the last summary and add blockers."}

Sessions et état

Les interactions multi-tours avec les agents nécessitent l’historique des sessions. L’exécution gère automatiquement le stockage de session en fonction de l’environnement :

Environnement Stockage Configuration
Azure Stockage Blob dans le compte de stockage hôte par défaut (AzureWebJobsStorage) Chaîne de connexion ou basée sur l’identité (préférée). Voir Configuration de l’identité managée.
Développement local Basé sur des fichiers dans le répertoire de configuration des agents locaux Aucune configuration nécessaire.

L’exécution ne nécessite pas de base de données de session séparée. L’exécution en mode bac à sable est également consciente de la session : lorsqu’aucun identifiant de session explicite n’est disponible, l’exécution utilise une session bac à sable isolée afin que les invocations non liées ne partagent pas d’état.

Plans d’accueil soutenus

L’exécution des agents serverless prend en charge les plans d’hébergement Azure Functions suivants :

Plan Mise à l’échelle sans serveur Notes
Consommation flexible Oui Échelle à zéro, facturation par seconde et mise à l’échelle automatique. Recommandé pour la plupart des charges de travail des agents.
Dédié (App Service) Non Des instances toujours activées avec une mise à l’échelle manuelle ou basée sur des règles. Utilisez-les quand vous avez déjà des instances de plan App Service avec une capacité disponible.

Les deux plans prennent en charge l’identité gérée, l’intégration réseau virtuel et l’application Insight.

Contenu connexe

  • Last updated on