Azure Functions hosted skills reference

Dit artikel biedt de configuratiereferentie voor door Azure Functions gehoste vaardigheden. Voor een overzicht van de runtime en richtlijnen over wanneer deze te gebruiken, zie Azure Functions hosted skills.

Agentbestandreferentie

Een agentbestand (.agent.md) gebruikt YAML front matter om de agent te configureren, gevolgd door markdown-instructies.

Frontmaterievelden

Gebruik deze frontmatter-velden om een agent te configureren:

Triggerconfiguratie

Elk agentbestand ondersteunt één trigger, gedefinieerd in het trigger object in de voorste content.

Ondersteunde triggertypen

De volgende tabel geeft een overzicht van de ondersteunde trigger.type waarden, hun vereiste args, en links naar de volledige referentie per type:

Triggervoorbeelden

De volgende voorbeelden tonen veelvoorkomende triggerconfiguraties:

• Timer trigger (draait dagelijks om 15:00 uur UTC)

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

• HTTP-trigger

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

• Wachtrijtrigger

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

• Blobtrigger

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

App-brede configuratie (agents.config.yaml)

Gebruiken agents.config.yaml voor runtime-standaardinstellingen voor de hele app die elke agent kan overnemen. De runtime kan een app laden zonder dit bestand. Voeg deze toe wanneer u gedeelde instellingen nodig hebt, zoals een modelimplementatie, time-out of eindpunt voor sandbox-uitvoering.

Dit bestand is één invoer op app-niveau. De runtime detecteert ook MCP-servers van mcp.json, vaardigheden van skills/ en aangepaste Python-hulpprogramma's van tools/. Deze mogelijkheden zijn standaard ingeschakeld voor agents. De front matter van de agent kan de standaardinstellingen van de runtime overschrijven of geërfde MCP-servers, vaardigheden en hulpprogramma's filteren.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Afzonderlijke agents kunnen de ondersteunde runtime-instellingen in hun eigen front matter overschrijven.

Configuratievelden

Gebruik deze velden op het hoogste niveau in agents.config.yaml:

Resolutievolgorde

De runtime lost eerst waarden op van agentfront matter, vervolgens agents.config.yamlen vervolgens app-instellingen en runtime-standaardwaarden. Tekenreekswaarden in agents.config.yaml kunnen verwijzen naar app-instellingen, zoals $AZURE_OPENAI_DEPLOYMENT of $ACA_SESSION_POOL_ENDPOINT.

Behoud de standaardwaarden voor model, time-out en systeemtools in agents.config.yaml. Behoud externe MCP-serverdefinities, inclusief MCP-servereindpunten uit connectornaamruimten, in mcp.json.

Variabele vervanging

De runtime kan app-instellingen en omgevingsvariabelen vervangen door tekenreekswaarden in agentfront matter, agentinstructieteksten en agents.config.yaml.mcp.json

Voor substituties gebruik ofwel $SETTING_NAME of.%SETTING_NAME% De runtime behandelt deze twee formaten op dezelfde manier. Variabelenamen moeten beginnen met een letter of onderstrepingsteken en kunnen letters, cijfers en onderstrepingstekens bevatten.

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"
    }
  }
}

Substitutieregels:

• Gilt voor stringwaarden, inclusief strings die genest zijn in objecten of lijsten. Dat geldt niet voor objectsleutels.
• Omheinde codeblokken in agentinstructieteksten worden niet vervangen, dus voorbeelden kunnen letterlijke $VALUE tekst of %VALUE% tekst bevatten.
• Gebruik $$SETTING_NAME of %%SETTING_NAME%% voor letterlijke plaatsvervangers in vervangen inhoud.
• Ontbrekende variabelen blijven ongewijzigd. Lege waarden worden opgelost in lege strings.
• Substitutie is een enkele pass. De ${SETTING_NAME} syntaxis wordt niet ondersteund.
• Om substitutie voor één agent uit te schakelen, zet substitute_variables: false je in het agentbestand. Met deze instelling wordt vervanging niet uitgeschakeld in agents.config.yaml of mcp.json.

MCP-serverconfiguratie (mcp.json)

Wanneer een app externe MCP-servers gebruikt, voegt u mcp.json toe aan de hoofdmap van het project van de functie-app. De runtime detecteert externe HTTP- of streambare HTTP MCP-servers uit dit bestand en maakt hun hulpprogramma's beschikbaar voor agents, afhankelijk van eventuele filters per agent.

Serverinvoervelden

Gebruik deze velden in elke servers vermelding:

Authenticatie

Gebruik het Azure API Hub-bereik wanneer de agent een beheerde MCP-server uit een connectornaamruimte verbruikt. Sla geen gebruikersgeheimen op in 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"
      }
    }
  }
}

De auth.client_id instelling selecteert welke beheerde identiteit wordt geverifieerd bij de MCP-server. Stel deze in op de client-id van een door de gebruiker toegewezen beheerde identiteit. Laat deze weg om de door het systeem toegewezen beheerde identiteit van de functie-app in Azure te gebruiken. De geselecteerde identiteit, of uw lokale ontwikkelaarsidentiteit wanneer u lokaal werkt, moet gemachtigd zijn om de MCP-server aan te roepen.

Azure connectoren

Met connectors kunnen agents met externe services werken zonder aangepaste API-clientcode. Een Microsoft 365 Outlook-connector kan bijvoorbeeld e-mail verzenden, een Teams-connector kan werken met berichten en andere connectors kunnen acties aanroepen in systemen zoals Salesforce, SAP of SQL. Een connectornaamruimte fungeert als host voor de verbindingen, triggers en MCP-servers die deze integraties beschikbaar maken voor uw app.

Om connectormogelijkheden te gebruiken in een gehoste vaardighedenapp, maak je eerst een Connector Namespace-resource, maak je een verbinding met de service en autoriseer je die verbinding. Kies vervolgens hoe de taak de verbinding gebruikt:

• Connector activeert agents wanneer er iets gebeurt in een verbonden service, zoals een nieuw e-mailbericht, Teams-bericht of agendagebeurtenis. Als u er een wilt gebruiken, maakt u een trigger in de connectornaamruimte die gebruikmaakt van de geautoriseerde verbinding en configureert u vervolgens de agent met de triggernaam en argumenten van die connectortriggerdefinitie.
• Met MCP-hulpprogramma's voor connectors kunnen agents serviceacties aanroepen, zoals het verzenden van e-mail of het bijwerken van een record. Als u deze wilt gebruiken, maakt u een MCP-server in de connectornaamruimte die gebruikmaakt van de geautoriseerde verbinding en voegt u vervolgens het MCP-servereindpunt toe aan mcp.json.

Voor meer informatie, zie Gebruik connectoren in Azure Functions.

Skills

Bewaar herbruikbare prompt-assets onder skills/. Ze helpen de basisagentinstructies klein te houden en domeinspecifieke instructies beschikbaar te maken wanneer dat nodig is. De runtime maakt gebruik van de indeling Agent Skills .

Vaardigheidsformaat

De runtime scant skills/ in de hoofdmap van het Function App-project en detecteert vervolgens recursief mappen die SKILL.md bevatten.

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

Het SKILL.md-bestand bevat YAML front matter, gevolgd door Markdown-instructies.

---
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).

Auteursregels

Volg deze richtlijnen bij het aanmaken van je agentbestanden en andere projectbronnen:

• Elke vaardigheidsmap moet een SKILL.md bestand bevatten.
• De name velden en description velden zijn vereist.
• Gebruik kleine letters, cijfers en enkele koppeltekens voor vaardigheidsnamen. Gebruik geen spaties, onderstrepingstekens, hoofdletters, koppeltekens aan het begin, koppeltekens aan het einde of opeenvolgende koppeltekens.
• Namen van vaardigheden moeten uniek zijn in de app.
• In de beschrijving moet worden uitgelegd wat de vaardigheid doet en wanneer de agent deze moet gebruiken. De runtime laadt eerst namen en beschrijvingen van vaardigheden, zodat de agent kan bepalen wanneer de volledige vaardigheid moet worden geladen.
• Vaardigheden kunnen meerdere markdownbestanden bevatten in dezelfde vaardigheidsmap. Verwijzen naar ondersteunende Markdown-bestanden SKILL.md met behulp van relatieve koppelingen.
• De door Azure Functions gehoste vaardigheden ondersteunen alleen markdown-bestanden als vaardigheidsinhoud. Als een vaardigheid uitvoerbaar gedrag nodig heeft, pak die code dan als een aangepaste Python-tool en verwijs naar de tool bij naam uit de vaardigheidsinstructies.

Filtervaardigheden per agent

Agents nemen standaard alle gedetecteerde vaardigheden over. Vaardigheden in een agentbestand uitschakelen of uitsluiten wanneer een specifieke agent deze niet mag gebruiken:

skills: false

skills:
  exclude:
    - incident-response

Uitvoering in een sandbox

Voor code-uitvoering of browserautomatisering kan de runtime gebruikmaken van Azure Container Apps dynamische sessies. Dynamische sessies bieden geïsoleerde omgevingen van sessiegroepen. De runtime maakt gebruik van code-interpretersessies om agents een execute_python hulpprogramma te bieden.

Configuration

Uitvoering in sandbox configureren in agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Vereisten

• De sessiegroep moet een Python code-interpretersessiegroep zijn, zoals een pool die is gemaakt met --container-type PythonLTS.
• De endpoint waarde is het eindpunt voor sessiegroepbeheer.
• In Azure moet de beheerde identiteit die door de functie-app wordt gebruikt, de roltoewijzingen hebben die nodig zijn om code uit te voeren in de sessiepool. voor Azure Container Apps code-interpretersessies zijn de rollen Azure ContainerApps Session Executor en Contributor in de sessiegroep vereist.
• Wanneer u lokaal werkt, moet uw ontwikkelaarsidentiteit dezelfde vereiste toegangsrechten hebben tot de sessiepool.
• Als u een door de gebruiker toegewezen beheerde identiteit wilt gebruiken voor uitvoering in een sandbox, stelt u system_tools.dynamic_sessions_code_interpreter.client_id in op de client-id van de identiteit die over de vereiste roltoewijzingen beschikt. Als deze instelling niet is geconfigureerd, gebruikt de runtime AZURE_CLIENT_ID en vervolgens de standaardketen met aanmeldingsgegevens.

Het sandbox-hulpprogramma voert Python uit in een geïsoleerde sessie. Variabelen, importbewerkingen en bestanden kunnen worden bewaard tussen aanroepen van hulpprogramma's in dezelfde agentsessie. Wanneer er geen agentsessie-id beschikbaar is, gebruikt de runtime een nieuwe sandbox-sessie, zodat niet-gerelateerde uitvoeringen de status niet delen.

Uitschakelen per agent

Agents nemen de uitvoering van de sandbox over wanneer deze globaal is geconfigureerd. Je kunt de uitvoering voor een specifieke agent uitschakelen door in het agentbestand te dynamic_sessions_code_interpreter zettenfalse.

system_tools:
  dynamic_sessions_code_interpreter: false

Aangepaste hulpprogramma's voor Python

Gebruik aangepaste Python-tools wanneer je app-specifieke logica nodig hebt die de ingebouwde mogelijkheden van de runtime niet dekken. Aangepaste tools draaien in het functie-appproces, niet in een sandbox-sessie.

Ontdekking van tools

Voeg hulpprogrammabestanden toe aan de tools/ map in de hoofdmap van het functie-app-project:

tools/
  submit_ticket.py
  lookup_customer.py

De runtime detecteert .py bestanden in tools/ wiens bestandsnamen niet beginnen met _. In de huidige preview registreert de runtime het eerste ondersteunde hulpprogramma van elk bestand. Gebruik één hulpprogramma per bestand om detectie voorspelbaar te houden.

Definiërende hulpmiddelen

Definieer een tool door een functie te decoreren met @tool uit het runtime-pakket:

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}"

Voor uitgebreidere parameterbeschrijvingen en validatie gebruikt u een Pydantic-model als het hulpprogrammaschema:

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}"

U kunt ook een gewone Python functie definiëren zonder de decorator. De runtime verpakt de eerste gewone functie die in het bestand wordt gevonden, gebruikt de functienaam als de naam van het hulpprogramma en gebruikt de docstring als de beschrijving van het hulpprogramma.

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

Met hulpprogrammanamen, beschrijvingen, typehints en beschrijvingen van Pydantic-velden kan het model bepalen wanneer en hoe het hulpprogramma moet worden aangeroepen. Voeg pakketafhankelijkheden toe die door aangepaste hulpprogramma's worden gebruikt voor requirements.txt, net zoals voor andere Python code in een Azure Functions-app.

Filtertools per agent

Agents erven standaard ontdekte aangepaste hulpprogramma's. Schakel aangepaste hulpprogramma's uit of sluit deze uit in een agentbestand wanneer een specifieke agent deze niet mag gebruiken:

tools: false

tools:
  exclude:
    - submit_ticket

Configuratie van modelaanbieders

De runtime maakt gebruik van Microsoft Agent Framework om modelproviders aan te roepen. Preview-ondersteuning omvat Azure OpenAI, Azure AI Foundry en OpenAI.

Providerselectie

Je moet ten minste één provider-signaal configureren voor de runtime om een chatclient te maken. Je kunt de provider expliciet instellen door de AZURE_FUNCTIONS_AGENTS_PROVIDER instelling te gebruiken of de runtime de provider laten afleiden uit je andere app-instellingen.

Gebruik deze instellingen voor zorgverlener:

Wanneer je niet instelt AZURE_FUNCTIONS_AGENTS_PROVIDER, detecteert de runtime automatisch de provider in deze volgorde:

1. AZURE_OPENAI_ENDPOINTselects Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINTselects Azure AI Foundry.
3. OPENAI_API_KEY selecteert OpenAI.

Wanneer je op automatische detectie vertrouwt, moet de provider-specifieke instelling die de provider identificeerde nog steeds worden vergezeld door de vereiste modelinstelling van de provider. Bijvoorbeeld, FOUNDRY_PROJECT_ENDPOINT heeft nog steeds nodig FOUNDRY_MODEL, en AZURE_OPENAI_ENDPOINT heeft nog steeds .AZURE_OPENAI_DEPLOYMENT

AZURE_FUNCTIONS_AGENTS_MODEL is een runtime-brede fallback-modelinstelling. De geldige waarden hangen af van de actieve aanbieder:

• Voor Azure AI Foundry gebruik je een modelimplementatienaam die in het Foundry-project voorkomt, zoals gpt-5.4.
• Voor Azure OpenAI gebruik je de deployment name alleen als je bewust de runtime-brede fallback wilt. In de meeste apps kun je in plaats daarvan instellen AZURE_OPENAI_DEPLOYMENT .
• Voor OpenAI gebruik de modelnaam die door de OpenAI API wordt geaccepteerd, zoals gpt-4o-mini.

Modelprecedent

Modelselectie volgt deze algemene volgorde:

1. Het model dat door de agent of de runtime-aanroep is opgevraagd.
2. Providerspecifieke instellingen, zoals AZURE_OPENAI_DEPLOYMENT of FOUNDRY_MODEL.
3. Het model zette in AZURE_FUNCTIONS_AGENTS_MODEL.
4. Het ingebouwde standaardmodel van de actieve aanbieder.

Configuratie van beheerde identiteit

De runtime gebruikt beheerde identiteiten bij verbinding met Azure-bronnen die Microsoft Entra-authenticatie ondersteunen. Gebruik AZURE_CLIENT_ID het als standaard identiteitsselector van de app, of gebruik feature-specifieke instellingen voor fijnere controle:

1. Wanneer je geen identiteitsinstelling configureert, gebruikt de runtime DefaultAzureCredential, dat wordt opgelost naar de door het systeem toegewezen beheerde identiteit in Azure en je ontwikkelaarsidentiteit (Azure CLI of Visual Studio) lokaal.
2. Wanneer je een API-sleutel configureert in Azure OpenAI (met ), AZURE_OPENAI_API_KEYgebruikt de modelprovider de sleutel in plaats van een beheerde identiteit. Voor meer informatie, zie Azure OpenAI extensie voor Azure Functions.
3. De sessiegeschiedenis gebruikt dezelfde standaard opslagidentiteitsconfiguratie van de host als de Azure Functions-host. Gebruik AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri en AzureWebJobsStorage__clientId om op identiteit gebaseerde opslag te configureren voor geschiedenis op basis van blobs. De runtime gebruikt geen afzonderlijke agentspecifieke identiteitsinstelling voor sessiegeschiedenis. Voor meer informatie, zie Define connections in de Functions ontwikkelaarsgids.

Ingebouwde eindpunten

De runtime stelt optionele ingebouwde endpoints bloot wanneer een agent zich aanmeldt via de builtin_endpoints instellingen in zijn frontmatter. Deze eindpunten zijn nuttig voor ontwikkeling, testen en diagnostiek. Ze zijn niet ontworpen als de primaire productieapplicatie-interface.

Schakel ingebouwde eindpunten in de front-matter van de agent in:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

Instellen debug_chat_ui: true maakt ook de chat en chatstream API's mogelijk omdat de UI daarvan afhankelijk is. Stel het zelf in chat_api: true wanneer je programmatische chattoegang wilt zonder de debug-interface.

Eindpuntroutes

Het <AGENT_NAME> routesegment komt van de .agent.md bestandsnaam, niet van het weergaveveld name . Bijvoorbeeld, main.agent.md gebruikt /agents/main/.

Sleutels ophalen

Wanneer je de chatinterface in Azure host, vraagt deze om een functietoets voordat berichten worden verzonden. Je kunt de sleutel gebruiken bij het direct aanroepen van de HTTP-chat-API's.

Gebruik het volgende az functionapp keys list commando om de standaard functietoets voor je app op te halen:

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

In dit voorbeeld vervang <RESOURCE_GROUP> en <FUNCTION_APP_NAME> door je groeps- en appnamen. Je kunt de teruggegeven sleutel opnemen in de x-functions-key header of een code querystringparameter in het HTTP-verzoek naar het eindpunt.

Bij het verbinden met een MCP-client vraag dan in plaats daarvan het MCP-extensiesysteem aan met het volgende commando:

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

Het MCP-eindpunt vereist deze systeemsleutel.

Chat-API-verzoekflow

Beide ingebouwde chat-API's verwachten een JSON-body met een prompt veld:

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

Gebruik POST /agents/<AGENT_NAME>/chat wanneer je één JSON-respons wilt. Het responslichaam omvat session_id, response, en tool_calls. De runtime weerspiegelt ook dezelfde sessie-ID in de x-ms-session-id response header.

Gebruik POST /agents/<AGENT_NAME>/chatstream wanneer je wilt Server-Sent Events (SSE). De stream begint met een session gebeurtenis die de opgeloste sessie-ID bevat, gevolgd door nul of meer delta, intermediate, tool_start, en tool_end gebeurtenissen, en eindigt met ofwel done of error.

Om een multi-turn conversie voort te zetten, stuur je de sessie-ID van het eerdere antwoord in de x-ms-session-id request header op later chat of chatstream calls. Als je die header weglaat, maakt de runtime automatisch een nieuwe sessie aan.

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."}

Sessies en toestand

Interacties tussen meerdere beurten vereisen sessiegeschiedenis. De runtime beheert de sessieopslag automatisch op basis van de omgeving:

De runtime vereist geen aparte sessiedatabase. Sandbox-uitvoering is ook sessiebewust: wanneer er geen expliciete sessie-ID beschikbaar is, gebruikt de runtime een verse geïsoleerde sandbox-sessie zodat niet-gerelateerde aanroepen geen status delen.

Ondersteunde hostingplannen

Azure Functions hosted skills ondersteunen deze Azure Functions hostingplannen:

Alle plannen ondersteunen beheerde identiteit, virtuele netwerkintegratie en Application Insights.

Verwante onderwerpen

• Azure Functions hosted skills
• Bouw een event-gedreven AI-app met Azure Functions hosted skills
• Flex Consumption-abonnement hosting