Agentbindningar för Python i Azure Functions

Agentbindningar för Python-funktionsappar låter dig lägga till agentiska beteenden till befintliga funktioner. När funktionen körs konstruerar tillägget en SDK-specifik agent eller session från Markdown-instruktioner och injicerar den i din handler som en typad parameter. Din kod bestämmer när och hur agenten ska anropas tillsammans med din deterministiska applikationslogik.

Important

Agentbindningar för Python-funktionsappar är för närvarande i förhandsvisning. Funktioner, paketnamn och konfiguration kan ändras innan allmän tillgänglighet.

För att jämföra agentbindningar med andra AI-relaterade funktioner, såsom Azure Functions hostade färdigheter och Model Context Protocol (MCP)-verktyg, se AI-integrationsalternativ för Azure Functions.

Vad är en agentbindning?

En agent binding är en inmatningsbindning som tillhandahåller en konfigurerad agent eller session som en typad parameter till en Python-funktion. Tillägget kombinerar Markdown-instruktioner med appens leverantörskonfiguration och verktyg, så din hanterare behöver inte konstruera och koppla agenten för varje anrop.

Bindningen ersätter inte din funktion eller dess trigger. Din kod validerar fortfarande indata, bestämmer när agenten ska anropas, hanterar fel och producerar utdatan. Instruktioner finns i en .agent.md fil, medan klient-, modell- och verktygskonfiguration förblir i applikationskod och inställningar. Leverantörspaket kopplar denna delade bindningsmodell till olika agent-SDK:er.

När man ska använda agentbindningar

Använd agentbindningar när en Azure-funktion behöver agentisk resonemang för en del av ett arbetsflöde, men din applikation måste behålla kontrollen över dess trigger, validering, förgrening, felhantering och svar. Vanliga scenarier är:

  • Bedöm en HTTP-förfrågan. Validera en order med deterministisk kod, be en agent bedöma uppfyllelserisken och använd resultatet för att konstruera HTTP-svaret.
  • Berika eller klassificera händelser. Ta emot ett kömeddelande, Event Grid-händelse eller annan trigger-payload och använd en agent för att klassificera, sammanfatta eller berika datan innan din funktion skriver resultatet.
  • Lägg till resonemang i ett hållbart arbetsflöde. Anropa en agent från en Durable Functions-orkestrator via det replay-säkra context.call_agent() API:et, och använd sedan resultatet i senare orkestreringssteg.

Funktionen förblir koordinatoren: den förbereder uppgiften, anropar agenten och bestämmer vad som ska göras med resultatet. Bindningar minskar setup-koden, separerar Markdown-instruktioner från runtime-konfigurationen och fungerar med välbekanta Azure Functions-triggers och lokala felsökningsverktyg.

Om du föredrar att definiera beteende och triggers främst genom Markdown och deklarativ konfiguration istället för en Python-hanterare, överväg Azure Functions hosted skills.

Tillgängliga paket

Leverantörsspecifika tilläggspaket kopplar den delade bindningsmodellen till ett agent-SDK. Följande paket finns tillgängliga i förhandsvisning och kräver Python 3.13 eller senare:

SDK Package Get started
Microsoft Agent Framework azurefunctions-agents-extensions-agent-framework Snabbstart för Python-funktioner · Snabbstart för Durable-orchestrering
GitHub Copilot SDK azurefunctions-agents-extensions-copilot-SDK Python-funktion quickstart · HTTP och köexempel · exempel på varaktig orkestrering

Varje paket definierar sina stödda typer, autentisering, modellkonfiguration och anrops-API. Följ dess quickstart eller sample för SDK-specifika instruktioner för installation och distribution.

Hur en agentbindning fungerar

AgentFunctionApp Utvidgas azure.functions.FunctionApp, så den har samma möjligheter som FunctionApp. Dekoratören markdown_agent lägger till en agentinmatning till en funktion.

För varje agentbindning utför tillägget följande operationer:

  1. Lokaliserar den begärda .agent.md-filen från funktionsappens rotkatalog eller dess agents/-katalog.
  2. Laddar hela filen som råa UTF-8-instruktioner.
  3. Kombinerar instruktionerna med leverantörskonfiguration, explicita verktyg och upptäckta agentfärdigheter samt MCP-servrar.
  4. Skapar en ny SDK-specifik agent eller session och öppnar anropsägda resurser.
  5. Injicerar agenten eller sessionen i handlerparametern.
  6. Stänger invocation-ägda resurser när exekveringen avslutas.

Leverantören hanterar livscykeln för sina kunder. Invocation-ägda resurser stängs efter framgång, misslyckande eller avbrytning.

Definiera en bindning för en agent

För att lägga till en bindning till en Python v2-funktionsapp:

  1. Installera ett leverantörspaket och importera dess AgentFunctionApp.
  2. Konfigurera klienten, modellen, autentiseringen och verktygen så som krävs av det paketet.
  3. Lägg till en .agent.md instruktionsfil i appens rot eller katalogen agents/. Filen är rå UTF-8-text; systemet tolkar inte YAML front matter eller runtime-konfiguration.
  4. Lägg till markdown_agent i en utlöst funktion. Ställ arg_name in för att matcha den typade handlerparametern och agent_name för att identifiera instruktionsfilen.
  5. Anropa det injicerade objektet via dess SDK-API och hantera resultatet i din funktionskod.

Till exempel kan agent_name="order-fulfillment" identifiera order-fulfillment.agent.md i någon av de två kataloger som stöds, men inte i båda. Namn måste lösas entydigt inom appens rot och kan inte innehålla vägseparatorer eller traverseringskomponenter. För att injicera flera agenter, stapla dekoratörer med distinkta arg_name värden och matchande handlerparametrar.

För kompletta kodexempel, se paketets snabbstartsguider och exempel.

Delade agentfärdigheter och MCP-servrar

Tillägget upptäcker automatiskt delade agentfunktioner från applikationens rot:

Förmåga Location Behavior
Agentkunskaper skills/<skill-name>/SKILL.md eller Skills/<skill-name>/SKILL.md Leverantörspaketet laddar in och validerar den filbaserade agentfärdigheten.
Fjärr-MCP-servrar mcp.json Tillägget konfigurerar HTTP-servrar som stöds eller streamningsbara HTTP-servrar som stöds samt valfria tillåtelselistor för verktyg.
Leverantörsverktyg Applikations- eller bindningskonfiguration SDK-specifika verktyg eller Python-callables som stöds av leverantören tillhandahålls uttryckligen istället för att upptäckas.

Tänk på dessa överväganden när du använder delade agentfunktioner:

  • Varje agentbindning i funktionsappen får alla identifierade agentfunktioner och MCP-servrar.
  • Filbaserade agentfärdigheter är funktioner som en agent kan ladda. De är inte Azure Functions-hostade färdigheter, som använder en separat exekveringsmodell.
  • Den nuvarande förhandsgranskningen av agenttillägget stöder inte att välja en delmängd av funktioner för en app eller individuell bindning.
  • Agentfärdigheter och MCP-verktyg kan utföra privilegierade operationer. Placera endast funktioner som varje agent i appen får använda, och använd separata funktionsappar när agenter kräver olika kapabilitetsgränser.

MCP-konfiguration kan hänvisa till miljövariabler för URL:er, rubriker, autentiseringsomfattningar och klient-ID:n. Referenser löses för varje anrop innan tillägget ansluter till servern. Lagra inte hemligheter direkt i en källkodskontrollerad mcp.json fil.

MCP-servrar för lokala processer och standardindata/-utdata (stdio) stöds inte. MCP-stöd är ett valfritt beroende och normala paketimporter förblir säkra när det inte är installerat.

Använd agentbindningar med Durable Functions

När du installerar en leverantörs valfria Durable Functions-integration ger en synkron generator-orchestrator context.call_agent(agent_name, input_). Tillägget kör agentarbete i en dold aktivitet, och behåller modellanrop, verktyg och andra icke-deterministiska operationer utanför orchestrator-replay.

In- och utdata måste vara JSON-serialiserbara. Anrop använder leverantören och delade funktioner som har konfigurerats av appen. Se paketets snabbstarter och exempel för exempel på installation och orkestrering.

Projektfiler

En agentaktiverad applikation är en standard Python v2-funktionsapp med agentförlängningsberoenden och en eller flera instruktionsfiler:

Fil eller mapp Purpose
function_app.py Definierar AgentFunctionApp, standard-Functions-triggers, agentbindningar, klientfabriker och explicit konfigurerade leverantörsverktyg.
host.json Konfigurerar Azure Functions-värden.
requirements.txt Inkluderar ett leverantörspaket och dess nödvändiga beroenden. Valfria tillägg kan möjliggöra stöd för Durable Functions och MCP.
*.agent.md eller agents/*.agent.md Innehåller råa UTF-8-instruktioner för en agent. Varje refererat namn måste resolveras till exakt en fil.
skills/ eller Skills/ (Valfritt) Innehåller filbaserade agentfärdigheter som delas av alla agentbindningar.
mcp.json (Valfritt) Definierar fjärrbaserade HTTP-baserade MCP-servrar som delas av alla agentbindningar.

För den standardiserade Python projektstrukturen, se Azure Functions Python utvecklarguiden.

Validering och diagnostik

Tillägget validerar agentdefinitioner före eller under bindningskompilering, så konfigurationsproblem misslyckas med åtgärdsbara fel. Valideringen omfattar:

  • Saknade eller otydliga .agent.md filer.
  • Ogiltiga handlersignaturer, inklusive en saknad eller omatchad injicerad parameter.
  • Alternativ eller funktioner för leverantörer som inte stöds.
  • Ogiltiga färdighetskataloger och felaktig MCP-konfiguration.
  • Icke-stödda MCP-transporter och saknade miljövärden.
  • Ogiltiga varaktiga payloads eller värden som inte är JSON-serialiserbara.

Där det finns tillgängligt bevarar tillägget Azure Function-namnet, anrops-ID och Durable instans-ID vid leverantörsgränsen för att stödja korrelation och diagnostik.

  • Uppdaterades senast