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 Agent från Markdown-instruktioner och injicerar den i din hanterare som en typad parameter. Din kod bestämmer när och hur agenten ska anropas tillsammans med din deterministiska applikationslogik.

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.

En agentbindning är en tilläggsägd inmatningsbindning som tillhandahåller ett fullt konstruerat Agent objekt till en Python-funktion. Fixelsen läser agentinstruktioner som råtext från en .agent.md fil. Din applikationskod behåller klient- och leverantörsspecifik verktygskonfiguration, medan funktionsappprojektet kan upptäcka filbaserade agentfärdigheter och fjärr-MCP-servrar.

Agent binding-arkitekturen stödjer agentobjekt från olika SDK:er via leverantörsspecifika tilläggspaket. Microsoft Agent Framework är det enda agent-SDK:t som stöds i den nuvarande förhandsvisningen. För att använda det, installera paketet azurefunctions-agents-extensions-agent-framework .

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.

Agentbindningar passar bra när funktionens deterministiska kod bör förbli koordinator. Agenten utför en begränsad resonemangsuppgift och återlämnar kontrollen till hanteraren eller orkestreringen.

Varför använda agentbindningar?

Många produktionsarbetsflöden kombinerar steg som måste vara deterministiska med steg som gynnas av modellresonemang. Agentbindningar ger följande fördelar för dessa hybrida arbetsflöden:

• Lägg till agentiskt beteende till befintliga funktioner. Använd agentresonemang från HTTP-, timer-, kö-, Event Grid-, Service Bus- och andra utlösta funktioner.
• Styr agentanrop på ett säkert sätt i kod. Bestäm när agenten ska anropas, inspektera dess svar och bestäm funktionsutdata. Förlängningen stänger invocation-ägda resurser efter framgång, misslyckande eller avbokning.
• Minska koden för agentuppsättning. Ta emot en konfigurerad Agent som en typad handlerparameter istället för att konstruera och koppla den för varje anrop.
• Separata instruktioner från runtime-konfigurationen. Lagra instruktioner för naturligt språk i en .agent.md fil och konfigurera klienter och leverantörsspecifika verktyg explicit i Python.
• Använd delade agentfunktioner. Tillägget upptäcker filbaserade agentfärdigheter och HTTP-baserade MCP-servrar från applikationens rot och gör dem tillgängliga för varje agentbindning.
• Anropa agenter från varaktiga orkestreringar. Tillägget kör agentens arbete i en dold aktivitet så att återkörning av orkestreringen förblir deterministisk.
• Felsök lokalt med välbekanta verktyg. Kör och felsök appen lokalt som vilken annan Python-funktionsapp som helst. Du kan sätta brytpunkter och stegvisa igenom både den deterministiska funktionslogiken och koden som anropar agenten.

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 den konfigurerade klientfabriken, explicit konfigurerade leverantörsverktyg samt upptäckta agentfärdigheter och MCP-servrar.
4. Skapar en ny Agent källa och öppnar invocation-ägda resurser.
5. Injicerar Agent i parametern för hanteraren.
6. Stänger invocation-ägda resurser när exekveringen avslutas.

Tillägget kan cachelagra leverantörsupptäckt och kompilerade bindningsdefinitioner. Den cachar eller återanvänder inte levande anropsresurser över funktionsanrop.

Definiera en bindning för en agent

Följande exempel använder den för närvarande stödda Microsoft Agent Framework-leverantören för att lägga till en Agent i en HTTP-utlöst funktion. Funktionen konstruerar uppgiften i kod, anropar agenten och returnerar agentens svar:

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

Värdet arg_name måste matcha den injicerade handlerparametern. För att injicera flera agenter i samma funktion, stapla markdown_agent-dekoratorer och använd en unik arg_name och en hanterarparameter för varje agentbindning. Värdet agent_name identifierar instruktionsfilen. I det här exemplet måste order-fulfillment motsvara exakt en av dessa platser:

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

Om båda filerna finns är definitionen oklar och appstart misslyckas. Agentnamn kan inte innehålla absoluta vägar, vägseparatorer eller traverseringskomponenter. Filer som löses utanför applikationsroten är inte tillåtna.

Konfigurera agentklienten och verktygen

Konfigurera ett nollargument client_factory när du konstruerar AgentFunctionApp. Fabriken returnerar en ny klient som stöds av leverantörspaketet. Du kan också skicka Microsoft Agent Framework-verktygsobjekt eller Python-callables genom parametern tools på appnivå. En binding kan åsidosätta app-nivåns klientfabrik och verktyg när det kräver annat beteende.

Till exempel använder följande HTTP-utlösta funktion en agentbindning som gör lookup_inventory tillgängligt som ett verktyg endast för order_agent:

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

Tänk på dessa överväganden när du konfigurerar agentklienten och verktygen:

• Basagentens förlängning är leverantörsneutral. Ett leverantörspaket integrerar ett specifikt agent-SDK och definierar de stödda klient- och agenttyperna.
• Det nuvarande stödda Microsoft Agent Framework-paketet väljer eller konfigurerar inte en modellleverantör för din applikation. Din klientfabrik avgör vilken stödd Microsoft Agent Framework-chattklient och modell agenten använder.
• Tillägget skickar hela .agent.md filen till den konfigurerade leverantören som agentinstruktioner. Den tolkar inte modellinställningar, verktyg, YAML-frontmaterial eller annan runtime-konfiguration från filen.

Delade agentfärdigheter och MCP-servrar

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

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

Agentbindningar stödjer hybrida, långvariga arbetsflöden via en valfri Durable Functions-integration. En synkron generator-orchestrator anropar context.call_agent() och ger den resulterande uppgiften:

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() schemalägger en dold aktivitet som löser agentdefinitionen och utför alla modell-, filsystem-, legitimations-, verktygs- och nätverksoperationer. Orkestratören skapar endast en deterministisk, JSON-serialiserbar schema-v1-förfrågan. Som ett resultat upprepar inte orkestreringen icke-deterministiska agentoperationer.

Varaktiga agentanrop använder leverantören och delade funktioner konfigurerade av AgentFunctionApp. In- och utdata måste vara JSON-serialiserbara.

Durable Functions-stöd är frivilligt. Applikationer som inte använder det behöver inte installera eller importera Durable Functions. För att använda orchestration_trigger och context.call_agent(), installera det stödda leverantörspaketet med dess tillägg för varaktigt beroende.

Projektfiler

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

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.

Relaterade artiklar

• AI-integreringsalternativ för Azure Functions
• Använd en Microsoft Agent Framework-agent i en Python-funktion
• Använd en Microsoft Agent Framework-agentbindning i en Durable-orkestrering
• Översikt över Microsoft Agent Framework