Azure Functions hosted skills reference

Den här artikeln tillhandahåller konfigurationsreferensen för Azure Functions-hostade färdigheter. För en översikt av runtime och vägledning om när den ska användas, se Azure Functions hostade färdigheter.

Agentfilreferens

En agentfil (.agent.md) använder YAML-frontmaterial för att konfigurera agenten, följt av markdown-instruktioner.

Frontmateriefält

Använd dessa front matter-fält för att konfigurera en agent:

Utlösarkonfiguration

Varje agentfil stöder en trigger, definierad i objektet trigger i frontmaterien.

Utlösartyper som stöds

Följande tabell listar de stödda trigger.type värdena, deras krav args, samt länkar till hela referensen per typ:

Exempel på triggers

Följande exempel visar vanliga triggerkonfigurationer:

• Timer-trigger (körs dagligen kl. 15:00 UTC)

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

• HTTP-utlösare

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

• Köutlösare

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

• Blob-utlösare

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

App-bred konfiguration (agents.config.yaml)

Använd agents.config.yaml för programomfattande körningsstandarder som varje agent kan ärva. Körmiljön kan ladda en app utan den här filen. Lägg till den när du behöver delade inställningar, till exempel en modelldistribution, tidsgräns eller slutpunkt för sandbox-körning.

Den här filen är en indatafil på applikationsnivå. Körmiljön upptäcker även MCP-servrar från mcp.json, färdigheter från skills/, och anpassade Pythonverktyg från tools/. Dessa funktioner är aktiverade på agenter som standard. Agentens inledande metadata kan åsidosätta standardvärden vid körning eller filtrera ärvda MCP-servrar, färdigheter och verktyg.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Enskilda agenter kan åsidosätta körningsinställningarna som stöds i sina egna inledande metadata.

Konfigurationsfält

Använd de här fälten på den översta nivån i agents.config.yaml:

Upplösningsordning

Körmiljön hämtar först värden från agentens front matter, sedan agents.config.yaml, och därefter från appinställningarna och körmiljöns standardvärden. Strängvärden i agents.config.yaml kan referera till appinställningar, till exempel $AZURE_OPENAI_DEPLOYMENT eller $ACA_SESSION_POOL_ENDPOINT.

Behåll standardinställningarna för modell-, timeout- och systemverktyg i agents.config.yaml. Behåll definitioner av fjärr-MCP-servrar, inklusive MCP-serverändpunkter från connector-namnområden, i mcp.json.

Variabel ersättning

Körmiljön kan substituera appinställningar och miljövariabler i strängvärden i agentens inledande metadata, brödtexten i agentinstruktioner, agents.config.yaml och mcp.json.

För substitutioner, använd antingen $SETTING_NAME eller %SETTING_NAME%. Runtimen hanterar dessa två format på samma sätt. Variabelnamn måste börja med en bokstav eller understreck och kan innehålla bokstäver, siffror och understreck.

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

Substitutionsregler:

• Gäller strängvärden, inklusive strängar som är nästlade i objekt eller listor. Gäller inte objektnycklar.
• Inhägnade kodblock i agentinstruktioner ersätts inte, så exempel kan innehålla literal $VALUE eller %VALUE% text.
• Använd $$SETTING_NAME eller %%SETTING_NAME%% för bokstavliga platshållare i ersatta innehåll.
• Saknade variabler lämnas oförändrade. Tomma värden upplöses till tomma strängar.
• Byte är en enkel passning. Syntaxen ${SETTING_NAME} stöds inte.
• För att inaktivera substitution för en agent, ställ substitute_variables: false in i agentfilen. Den här inställningen inaktiverar inte ersättning i agents.config.yaml eller mcp.json.

MCP-serverkonfiguration (mcp.json)

När en app använder fjärranslutna MCP-servrar lägger du till mcp.json i roten för funktionsappprojektet. Körmiljön upptäcker fjärr-HTTP-servrar eller strömmande HTTP-MCP-servrar i den här filen och gör deras verktyg tillgängliga för agenter, med förbehåll för eventuella filter per agent.

Serverinmatningsfält

Använd följande fält i varje servers post:

Autentisering

Använd omfånget Azure API Hub när agenten använder en hanterad MCP-server från ett namnområde för anslutningsappen. Lagra inte användarhemligheter i 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"
      }
    }
  }
}

Inställningen auth.client_id väljer vilken hanterad identitet som autentiserar med MCP-servern. Ange det till klient-ID för en användartilldelad hanterad identitet. Utelämna den om du vill använda funktionsappens systemtilldelade hanterade identitet i Azure. Den valda identiteten, eller din lokala utvecklaridentitet när du kör lokalt, måste tillåtas att anropa MCP-servern.

Azure-anslutningar

Med anslutningsappar kan agenter arbeta med externa tjänster utan anpassad API-klientkod. En Microsoft 365 Outlook-anslutning kan till exempel skicka e-post, en Teams-anslutningsapp kan fungera med meddelanden och andra anslutningsappar kan anropa åtgärder i system som Salesforce, SAP eller SQL. Ett namnområde för anslutningsappen är värd för de anslutningar, utlösare och MCP-servrar som gör dessa integreringar tillgängliga för din app.

För att använda connector-funktioner i en hostad färdighetsapp, skapa först en Connector Namespace-resurs, skapa en anslutning till tjänsten och auktorisera den anslutningen. Välj sedan hur uppgiften använder kopplingen:

• Anslutningsappen utlöser startagenter när något händer i en ansluten tjänst, till exempel ett nytt e-postmeddelande, Teams-meddelande eller kalenderhändelse. Om du vill använda en skapar du en utlösare i anslutningsprogrammets namnområde som använder den auktoriserade anslutningen och konfigurerar sedan agenten med utlösarnamnet och argumenten från den anslutningsutlösardefinitionen.
• Med MCP-verktyg för anslutningsprogram kan agenter anropa tjänståtgärder, till exempel att skicka e-post eller uppdatera en post. Om du vill använda dem skapar du en MCP-server i anslutningsprogrammets namnområde som använder den auktoriserade anslutningen och lägger sedan till MCP-serverslutpunkten i mcp.json.

För mer information, se Använd anslutningsprogram i Azure Functions.

Färdigheter

Lagra återanvändbara promptresurser under skills/. De hjälper till att hålla basagentinstruktionerna små samtidigt som domänspecifika instruktioner blir tillgängliga när det behövs. Körmiljön använder formatet Agent Skills.

Färdighetsformat

Runtime-systemet skannar skills/ i funktionsappens projektrot och upptäcker rekursivt mappar som innehåller SKILL.md.

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

Filen SKILL.md innehåller YAML-framsida följt av markdown-instruktioner.

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

Författarregler

Följ dessa riktlinjer när du skapar dina agentfiler och andra projektresurser:

• Varje färdighetsmapp måste innehålla en fil av typen SKILL.md.
• Fälten name och description krävs.
• Använd gemener, siffror och enkla bindestreck för färdighetsnamn. Använd inte blanksteg, understreck, versaler, inledande bindestreck, avslutande bindestreck eller upprepade bindestreck.
• Kunskapsnamn måste vara unika i hela appen.
• Beskrivningen bör förklara både vad kunskapen gör och när agenten ska använda den. Körmiljön läser först in färdighetsnamn och beskrivningar så att agenten kan avgöra när hela färdigheten ska läsas in.
• Färdigheter kan innehålla flera markdown-filer i samma färdighetsmapp. Referera till Markdown-filer som stöds från SKILL.md med hjälp av relativa länkar.
• Azure Functions hostade färdigheter stöder endast markdown-filer som färdighetsinnehåll. Om en färdighet behöver körbart beteende, paketera koden som ett eget Python-verktyg och hänvisa till verktyget vid namn från färdighetsinstruktionerna.

Filtreringsfärdigheter per agent

Agenter ärver alla identifierade kunskaper som standard. Inaktivera eller exkludera kunskaper i en agentfil när en specifik agent inte ska använda dem:

skills: false

skills:
  exclude:
    - incident-response

Körning i sandbox

För kodkörning eller webbläsarautomatisering kan körmiljön använda dynamiska sessioner i Azure Container Apps. Dynamiska sessioner ger isolerade miljöer med hjälp av sessionpooler. Körtiden använder sessioner för kodtolken för att ge agenter tillgång till verktyget execute_python.

Configuration

Konfigurera körning i begränsat läge i agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Krav

• Sessionspoolen måste vara en Python kodtolksessionspool, till exempel en pool som skapats med --container-type PythonLTS.
• Värdet endpoint är sessionspoolens hanteringsslutpunkt.
• I Azure måste den hanterade identitet som används av funktionsappen ha de rolltilldelningar som krävs för att köra kod i sessionspoolen. Azure Container Apps kodtolksessioner kräver Azure ContainerApps Session Executor och Contributor roller i sessionspoolen.
• När du kör lokalt måste utvecklaridentiteten ha samma nödvändiga åtkomst till sessionspoolen.
• Om du vill använda en användartilldelad hanterad identitet för körning i begränsat läge anger du system_tools.dynamic_sessions_code_interpreter.client_id till klient-ID för den identitet som har de nödvändiga rolltilldelningarna. Om den här inställningen inte har angetts använder körningen först AZURE_CLIENT_ID och sedan standardkedjan för autentiseringsuppgifter.

Sandlådeverktyget kör Python i en isolerad session. Variabler, importer och filer kan sparas mellan verktygsanrop i samma agentsession. När inget sessions-ID för agenten är tillgängligt använder körmiljön en ny sandlådesession så att orelaterade körningar inte delar tillstånd.

Inaktivera per agent

Agenter ärver sandlådeliknande körning när detta konfigureras globalt. Du kan inaktivera exekvering för en specifik agent genom att ställa in dynamic_sessions_code_interpreter i false agentfilen.

system_tools:
  dynamic_sessions_code_interpreter: false

Anpassade Python verktyg

Använd anpassade Python-verktyg när du behöver app-specifik logik som runtimens inbyggda funktioner inte täcker. Anpassade verktyg körs i funktionsappprocessen, inte i en sandboxad session.

Verktygsidentifiering

Lägg till verktygsfiler i tools/ mappen i funktionsappens projektrot:

tools/
  submit_ticket.py
  lookup_customer.py

Körningen identifierar .py filer i tools/ vars filnamn inte börjar med _. I den aktuella förhandsversionen registrerar körmiljön det första verktyg som stöds från varje fil. Använd ett verktyg per fil för att hålla identifieringen förutsägbar.

Definierande verktyg

Definiera ett verktyg genom att dekorera en funktion med @tool från runtime-paketet:

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

För mer omfattande parameterbeskrivningar och validering använder du en Pydantisk modell som verktygsschema:

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

Du kan också definiera en vanlig Python funktion utan dekoratören. Körmiljön omger den första vanliga funktionen som den hittar i filen, använder funktionsnamnet som namn på verktyget och använder dokumentationssträngen som beskrivning av verktyget.

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

Verktygsnamn, beskrivningar, typtips och pydantiska fältbeskrivningar hjälper modellen att avgöra när och hur verktyget ska anropas. Lägg till eventuella paketberoenden som används av anpassade verktyg i requirements.txt, precis som du skulle göra för annan Python-kod i en Azure Functions-app.

Filtreringsverktyg per agent

Agenter ärver identifierade anpassade verktyg som standard. Inaktivera eller exkludera anpassade verktyg i en agentfil när en specifik agent inte ska använda dem:

tools: false

tools:
  exclude:
    - submit_ticket

Konfiguration av modellleverantörer

Körmiljön använder Microsoft Agent Framework för att anropa modellleverantörer. Förhandsversionsstöd omfattar Azure OpenAI, Azure AI Foundry och OpenAI.

Leverantörsval

Du måste konfigurera minst en leverantörssignal för runtime för att skapa en chattklient. Du kan uttryckligen ställa in leverantören genom att använda inställningen AZURE_FUNCTIONS_AGENTS_PROVIDER eller låta runtimen härleda leverantören från dina andra appinställningar.

Använd dessa leverantörsinställningar:

När du inte sätter AZURE_FUNCTIONS_AGENTS_PROVIDER, upptäcker körtiden automatiskt leverantören i denna ordning:

1. AZURE_OPENAI_ENDPOINTselects Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINTväljer Azure AI Foundry.
3. OPENAI_API_KEY väljer OpenAI.

När du förlitar dig på auto-detektering måste den leverantörsspecifika inställningen som identifierade vårdgivaren fortfarande åtföljas av den förespråkade modellinställningen som vårdgivaren kräver. Till exempel FOUNDRY_PROJECT_ENDPOINT behöver FOUNDRY_MODELfortfarande , och AZURE_OPENAI_ENDPOINT behöver AZURE_OPENAI_DEPLOYMENTfortfarande .

AZURE_FUNCTIONS_AGENTS_MODEL är en runtime-omfattande reservmodell. Dess giltiga värden beror på den aktiva leverantören:

• För Azure AI Foundry, använd ett modelldistributionsnamn som finns i Foundry-projektet, såsom gpt-5.4.
• För Azure OpenAI, använd distributionsnamnet endast om du medvetet vill ha en runtime-täckande reservplan. I de flesta appar, sätt istället AZURE_OPENAI_DEPLOYMENT .
• För OpenAI, använd modellnamnet som accepteras av OpenAI API, såsom gpt-4o-mini.

Modellprioritet

Modellvalet följer denna allmänna prioritetsordning:

1. Den modell som begärs av agenten eller körningsanropet.
2. Providerspecifika inställningar, till exempel AZURE_OPENAI_DEPLOYMENT eller FOUNDRY_MODEL.
3. Modellen satte i AZURE_FUNCTIONS_AGENTS_MODEL.
4. Den aktiva leverantörens inbyggda standardmodell.

Konfiguration av hanterad identitet

Körningen använder hanterade identiteter när den ansluter till Azure-resurser som stödjer Microsoft Entra-autentisering. Använd AZURE_CLIENT_ID som appens standardidentitetsväljare, eller använd funktionsspecifika inställningar för finare kontroll:

1. När du inte konfigurerar en identitetsinställning använder runtimen DefaultAzureCredential, som löser till den systemtilldelade hanterade identiteten i Azure och din utvecklaridentitet (Azure CLI eller Visual Studio) lokalt.
2. När du konfigurerar en API-nyckel i Azure OpenAI (med hjälp av AZURE_OPENAI_API_KEY), använder modellleverantören nyckeln istället för en hanterad identitet. För mer information, se Azure OpenAI-tillägget för Azure Functions.
3. Sessionshistoriken använder samma standardkonfiguration för värdens lagringsidentitet som Azure Functions-värden. Använd AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUrioch AzureWebJobsStorage__clientId för att konfigurera identitetsbaserad lagring för blobbackad historik. Körtidsmiljön använder inte en separat agentspecifik identitetsinställning för sessionshistorik. För mer information, se Definiera kopplingar i utvecklarguiden för funktioner.

Inbyggda slutpunkter

Runtimen exponerar valfria inbyggda endpoints när en agent väljer in via inställningarna builtin_endpoints i dess frontmatter. Dessa endpoints är användbara för utveckling, testning och diagnostik. De är inte designade som det primära produktionsapplikationsgränssnittet.

Aktivera inbyggda endpoints i agentens frontmaterial:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

Inställningen debug_chat_ui: true möjliggör chat också och chatstream API:erna eftersom användargränssnittet är beroende av dem. Ställ chat_api: true in själv när du vill ha programmatisk chattåtkomst utan debug-gränssnittet.

Slutpunktsvägar

Ruttsegmentet <AGENT_NAME> kommer från filnamnet .agent.md, inte från fältet name display. Till exempel använder main.agent.md/agents/main/.

Hämta nycklar

När du hostar chattgränssnittet i Azure ber det om en funktionstangent innan meddelandena skickas. Du kan använda nyckeln när du anropar HTTP-chatt-API:erna direkt.

Använd följande az functionapp keys list kommando för att hämta standardfunktionstangenten för din app:

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

I det här exemplet, ersätt <RESOURCE_GROUP> och <FUNCTION_APP_NAME> med dina grupp- och appnamn. Du kan inkludera den returnerade nyckeln i x-functions-key headern eller en code frågesträngsparameter i HTTP-förfrågan till endpointen.

När du ansluter till en MCP-klient, begär istället MCP-tilläggssystemet med följande kommando:

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

MCP-ändpunkten kräver denna systemnyckel.

Chatt-API-förfrågningsflöde

Båda inbyggda chatt-API:er förväntar sig en JSON-kropp med ett prompt fält:

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

Använd POST /agents/<AGENT_NAME>/chat när du vill ha ett JSON-svar. Responskroppen inkluderar session_id, response, och tool_calls. Körtiden speglar också samma sessions-ID i x-ms-session-id svarshuvudet.

Använd POST /agents/<AGENT_NAME>/chatstream när du vill Server-Sent Events (SSE). Strömmen börjar med en session händelse som innehåller den lösta sessions-ID:t, följt av noll eller fler delta, intermediate, tool_start, och tool_end händelser, och slutar med antingen done eller error.

För att fortsätta en konversation med flera turer, skicka sessions-ID:t från det tidigare svaret i x-ms-session-id begäransökan, senare chat eller chatstream anrop. Om du utelämnar den headern skapar runtimen automatiskt en ny 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."}

Sessioner och tillstånd

Interaktioner med flera turer kräver sessionshistorik. Runtime hanterar sessionslagring automatiskt baserat på miljön:

Runtime-systemet kräver inte en separat sessionsdatabas. Sandboxad exekvering är också sessionmedveten: när inget explicit sessions-ID finns tillgängligt använder runtimen en ny isolerad sandlådesession så att orelaterade anrop inte delar tillstånd.

Stödda värdplaner

Azure Functions hosted skills stöder dessa Azure Functions hostingplaner:

Alla abonnemang stödjer hanterad identitet, virtuell nätverksintegration och Application Insights.

Relaterat innehåll

• Azure Functions hosted skills
• Bygg en händelsedriven AI-app med Azure Functions hostade färdigheter
• Värdtjänst för Flex Consumption-plan