Agentbindingen voor Python in Azure Functions

Agentbindings voor Python-functie-apps laten je agentisch gedrag toevoegen aan bestaande functies. Wanneer de functie draait, construeert de extensie een Agent uit Markdown-instructies en injecteert deze in je handler als een getypeerde parameter. Je code bepaalt wanneer en hoe de agent wordt aangeroepen, samen met je deterministische applicatielogica.

Important

Agent-bindings voor Python-functie-apps staan momenteel in preview. Functies, pakketnamen en configuratie kunnen veranderen voordat ze algemeen beschikbaar zijn.

Om agentbindings te vergelijken met andere AI-gerelateerde functies, zoals Azure Functions gehoste vaardigheden en Model Context Protocol (MCP)-tools, zie AI-integratieopties voor Azure Functions.

Een agentbinding is een door extensie beheerde invoerbinding die een volledig geconstrueerd Agent object aan een Python-functie biedt. De extensie leest agentinstructies als ruwe tekst uit een .agent.md bestand. Je applicatiecode behoudt client- en provider-specifieke toolconfiguratie, terwijl het functionele app-project bestandsgebaseerde agentvaardigheden en externe MCP-servers kan ontdekken.

De agent binding-architectuur ondersteunt agentobjecten van verschillende SDK's via provider-specifieke extensiepakketten. Microsoft Agent Framework is de enige agent SDK die in de huidige preview wordt ondersteund. Om het te gebruiken, installeer je het azurefunctions-agents-extensions-agent-framework pakket.

Wanneer gebruik je agentbindingen

Gebruik agentbindings wanneer een Azure-functie agentische redenering nodig heeft voor een deel van een workflow, maar je applicatie moet de controle behouden over de trigger, validatie, branching, foutafhandeling en respons. Veelvoorkomende scenario's zijn onder andere:

  • Beoordeel een HTTP-verzoek. Valideer een bestelling met deterministische code, vraag een agent om het fulfillment-risico te beoordelen en gebruik het resultaat om de HTTP-respons te construeren.
  • Verrijk of classificeer gebeurtenissen. Ontvang een wachtrijbericht, Event Grid-gebeurtenis of een andere triggerpayload en gebruik een agent om de data te classificeren, samen te vatten of te verrijken voordat je functie het resultaat schrijft.
  • Voeg redenering toe aan een duurzame workflow. Roep een agent aan van een Durable Functions-orchestrator via de replay-safe context.call_agent() API, en gebruik het resultaat vervolgens in latere orkestratiestappen.

Agentbindingen passen goed wanneer de deterministische code van de functie de coördinator zou moeten blijven. De agent voert een begrensde redeneertaak uit en geeft de controle terug aan de handler of orkestratie.

Waarom agentbindingen gebruiken?

Veel productieworkflows combineren stappen die deterministisch moeten zijn met stappen die profiteren van modelredenering. Agentbindings bieden de volgende voordelen voor deze hybride workflows:

  • Voeg agentisch gedrag toe aan bestaande functies. Gebruik het redeneervermogen van agenten in HTTP-, timer-, queue-, Event Grid-, Service Bus- en andere geactiveerde functies.
  • Beheer het aanroepen van de agent veilig in code. Bepaal wanneer je de agent aanroept, inspecteer de respons en bepaal de functie-uitvoer. De extensie sluit resources die eigendom zijn van de aanroep na succes, mislukking of annulering.
  • Verminder de code voor de agentinstallatie. Ontvang een geconfigureerde Agent handlerparameter als een getypeerde handlerparameter in plaats van deze voor elke aanroep te construeren en te bedraden.
  • Apart instructies van runtime-configuratie. Sla natuurtaalinstructies op in een .agent.md bestand en configureer clients en provider-specifieke tools expliciet in Python.
  • Gebruik gedeelde agentmogelijkheden. De extensie ontdekt bestandsgebaseerde agentvaardigheden en HTTP-gebaseerde MCP-servers vanaf de applicatiewortel en maakt deze beschikbaar voor elke agentbinding.
  • Agenten aanroepen vanuit Durable Orchestrations. De extensie voert het werk van de agent uit in een verborgen activiteit, zodat orkestratie-replay deterministisch blijft.
  • Debug lokaal met bekende tools. Start en debug de app lokaal zoals elke andere Python-functie-app. Je kunt breakpoints instellen en zowel de deterministische functielogica als de code die de agent oproept stapsgewijs uitvoeren.

Hoe een agentbinding werkt

AgentFunctionApp Uitbreidt azure.functions.FunctionApp, zodat het dezelfde mogelijkheden heeft als FunctionApp. De markdown_agent decorateur voegt een agentinvoer toe aan een functie.

Voor elke agentbinding voert de extensie de volgende bewerkingen uit:

  1. Lost het gevraagde .agent.md bestand op vanuit de root van de functie-app of de map daarvan agents/ .
  2. Laadt het volledige bestand als ruwe UTF-8 instructies.
  3. Combineert de instructies met de geconfigureerde clientfabriek, expliciet geconfigureerde providertools en ontdekte agentvaardigheden en MCP-servers.
  4. Maakt een nieuwe Agent en opent resources die eigendom zijn van de invocatie.
  5. Injecteert de Agent in de handlerparameter.
  6. Sluit resources die eigendom zijn van de aanroep wanneer de uitvoering eindigt.

De extensie kan provider-ontdekking en gecompileerde bindingsdefinities cachen. Het cachet of hergebruikt geen live aanroepbronnen over functie-aanroepen heen.

Definieer een agentbinding

Het volgende voorbeeld gebruikt de momenteel ondersteunde Microsoft Agent Framework-provider om een Agent toe te voegen aan een HTTP-getriggerde functie. De functie construeert de taak in code, roept de agent aan en geeft het agentantwoord terug:

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)

De arg_name waarde moet overeenkomen met de geïnjecteerde handlerparameter. Om meerdere agenten in dezelfde functie te injecteren, stapel de markdown_agent-decorators en gebruik voor elke agentbinding een unieke arg_name en een handlerparameter. De agent_name waarde identificeert het instructiebestand. In dit voorbeeld moet order-fulfillment precies naar een van deze locaties verwijzen:

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

Als beide bestanden bestaan, is de definitie dubbelzinnig en mislukt het opstarten van de app. Agentnamen mogen geen absolute paden, padscheiders of doorloopcomponenten bevatten. Bestanden die buiten de applicatieroot worden opgelost, zijn niet toegestaan.

Configureer de agentclient en de hulpprogramma's

Configureer een nul-argument client_factory wanneer je construeert AgentFunctionApp. De fabriek stuurt een verse client terug die wordt ondersteund door het providerpakket. Je kunt ook Microsoft Agent Framework-toolobjecten of Python-callables via de tools parameter op app-niveau doorgeven. Een binding kan de clientfabriek en tools op app-niveau overschrijven wanneer dit ander gedrag vereist.

Bijvoorbeeld gebruikt de volgende HTTP-getriggerde functie een agentbinding die lookup_inventory alleen beschikbaar maakt als hulpprogramma voor 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)

Houd deze overwegingen in gedachten bij het configureren van de agentclient en tools:

  • De basisagent-extensie is provider-neutraal. Een providerpakket integreert een specifieke agent SDK en definieert de ondersteunde client- en agenttypes.
  • Het momenteel ondersteunde Microsoft Agent Framework providerpakket selecteert of configureert geen modelprovider voor jouw applicatie. Je client factory bepaalt welke ondersteunde Microsoft Agent Framework chatclient en model de agent gebruikt.
  • De extensie geeft het hele .agent.md bestand door aan de geconfigureerde provider als agentinstructies. Het verwerkt geen modelinstellingen, hulpmiddelen, YAML front matter of andere runtimeconfiguraties uit het bestand.

Gedeelde agentvaardigheden en MCP-servers

De extensie ontdekt automatisch de gedeelde agentmogelijkheden vanaf de applicatieroot:

Vermogen Location Gedrag
Agentvaardigheden skills/<skill-name>/SKILL.md of Skills/<skill-name>/SKILL.md Het providerpakket laadt en valideert de op bestanden gebaseerde agentskill.
Externe MCP-servers mcp.json De extensie configureert ondersteunde HTTP-servers of HTTP-servers die streaming ondersteunen, en optionele toelatingslijsten voor tools.
Hulpmiddelen voor aanbieders Applicatie- of bindingsconfiguratie Microsoft Agent Framework toolobjecten of Python callables worden expliciet geleverd in plaats van ontdekt.

Houd deze overwegingen in gedachten wanneer je shared agent-mogelijkheden gebruikt:

  • Elke agentbinding in de function-app ontvangt alle gedetecteerde agentvaardigheden en MCP-servers.
  • Bestandsgebaseerde agentvaardigheden zijn functionaliteiten die een agent kan laden. Het zijn geen Azure Functions-gehoste vaardigheden, die een apart uitvoeringsmodel gebruiken.
  • De huidige preview van de agentextensie ondersteunt het selecteren van een subset van capabilities voor een app of individuele binding niet.
  • Agentvaardigheden en MCP-tools kunnen bevoorrechte operaties uitvoeren. Plaats alleen mogelijkheden die elke agent in de app mag gebruiken, en gebruik aparte functie-apps wanneer agenten verschillende capaciteitsgrenzen vereisen.

MCP-configuratie kan omgevingsvariabelen verwijzen voor URL's, headers, authenticatiescopes en client-ID's. Referenties worden voor elke aanroep opgelost voordat de extensie verbinding maakt met de server. Sla geheimen niet direct op in een bronbeheerd mcp.json bestand.

Local-process en standaard input/output (stdio) MCP-servers worden niet ondersteund. MCP-ondersteuning is een optionele afhankelijkheid en normale pakketimporten blijven veilig wanneer deze niet geïnstalleerd zijn.

Gebruik agentbindings met Durable Functions

Agentbindings ondersteunen hybride, langlopende workflows via een optionele integratie van Durable Functions. Een synchrone generator-orchestrator roept context.call_agent() aan en levert de resulterende taak op:

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() plant een verborgen activiteit die de agentdefinitie oplost en alle model-, bestandssysteem-, inloggegevens-, tool- en netwerkoperaties uitvoert. De orkestrator maakt alleen een deterministisch, JSON-serialiseerbaar schema-v1-verzoek. Daardoor worden niet-deterministische agentoperaties niet herhaald wanneer de orkestratie opnieuw wordt afgespeeld.

Duurzame agent-oproepen gebruiken de provider en gedeelde mogelijkheden die zijn geconfigureerd door AgentFunctionApp. Inputs en outputs moeten JSON-serialiseerbaar zijn.

Durable Functions-ondersteuning is optioneel. Applicaties die het niet gebruiken, hoeven geen Durable Functions te installeren of importeren. Om te gebruiken orchestration_trigger en context.call_agent(), installeer het ondersteunde providerpakket met de Duurzame afhankelijkheidsbonus.

Projectbestanden

Een agent-enabled applicatie is een standaard Python v2-functieapp met afhankelijkheden van agentextensies en één of meer instructiebestanden:

Bestand of map Purpose
function_app.py Definieert AgentFunctionApp, standaard Functions-triggers, agentbindings, client factories en expliciet geconfigureerde providertools.
host.json Hiermee configureert u de Azure Functions host.
requirements.txt Bevat een ondersteund agent provider-pakket en elk SDK-specifiek clientpakket. Voor de huidige preview gebruik azurefunctions-agents-extensions-agent-framework. Optionele extra's maken Durable Functions en MCP-ondersteuning mogelijk.
*.agent.md of agents/*.agent.md Bevat ruwe UTF-8-instructies voor een agent. Elke opgegeven naam moet naar precies één bestand verwijzen.
skills/ of Skills/ (Optioneel) Bevat bestandsgebaseerde agentvaardigheden die gedeeld worden door alle agentbindingen.
mcp.json (Optioneel) Definieert externe HTTP-gebaseerde MCP-servers die door alle agentbindingen worden gedeeld.

Voor de standaard Python projectstructuur, zie de Azure Functions Python ontwikkelaarsgids.

Validatie en diagnostiek

De extensie valideert agentdefinities vóór of tijdens de compilatie van bindings, zodat configuratieproblemen leiden tot bruikbare foutmeldingen. Validatie dekt:

  • Ontbrekende of ambigu .agent.md bestanden.
  • Ongeldige handlerhandtekeningen, inclusief een ontbrekende of niet overeenkomende geïnjecteerde parameter.
  • Opties of mogelijkheden voor niet-ondersteunde aanbieders.
  • Ongeldige vaardigheidsgidsen en misvormde MCP-configuratie.
  • Niet-ondersteunde MCP-transporten en ontbrekende omgevingswaarden.
  • Ongeldige duurzame payloads of waarden die niet JSON-serialiseerbaar zijn.

Waar beschikbaar, bewaart de extensie de naam van de Azure Functie, de aanroep-ID en de Duurzame instantie-ID aan de providergrens om correlatie en diagnostiek te ondersteunen.

  • Last updated on