Agent-Bindungen für Python in Azure Functions

Agentenbindungen für Python-Funktions-Apps ermöglichen es, agentische Verhaltensweisen zu bestehenden Funktionen hinzuzufügen. Wenn die Funktion ausgeführt wird, konstruiert die Erweiterung eine Agent aus Markdown-Anweisungen und injiziert sie als typisierten Parameter in deinen Handler. Dein Code entscheidet, wann und wie der Agent zusammen mit deiner deterministischen Anwendungslogik aufgerufen wird.

Important

Agent-Bindungen für Funktions-Apps für Python sind derzeit als Vorschau verfügbar. Funktionen, Paketnamen und Konfigurationen können sich vor der allgemeinen Verfügbarkeit ändern.

Um Agentenbindungen mit anderen KI-bezogenen Funktionen wie Azure Functions gehosteten Fähigkeiten und Model Context Protocol (MCP)-Tools zu vergleichen, siehe AI-Integrationsoptionen für Azure Functions.

Eine Agentenbindung ist eine erweiterungseigene Eingabebindung, die ein vollständig konstruiertes Agent Objekt für eine Python-Funktion bereitstellt. Die Erweiterung liest die Agentenbefehle als Rohtext aus einer .agent.md Datei aus. Ihr Anwendungscode behält clients- und anbieterspezifische Werkzeugkonfigurationen bei, während das Funktions-App-Projekt dateibasierte Agentenfähigkeiten und entfernte MCP-Server entdecken kann.

Die Agentenbindungsarchitektur unterstützt Agent-Objekte aus verschiedenen SDKs über anbieterspezifische Erweiterungspakete. Das Microsoft Agent Framework ist das einzige Agent-SDK, das in der aktuellen Vorschau unterstützt wird. Um es zu verwenden, installiere das azurefunctions-agents-extensions-agent-framework Paket.

Wann man Agentenbindungen verwenden sollte

Verwenden Sie Agentenbindungen, wenn eine Azure-Funktion für einen Teil eines Workflows agentisches Reasoning benötigt, Ihre Anwendung jedoch die Kontrolle über ihren Trigger, Validierung, Verzweigung, Fehlerbehandlung und Antwort behalten muss. Zu den gängigen Szenarien gehören:

Bewerten Sie eine HTTP-Anfrage. Validiere eine Bestellung mit deterministischem Code, lasse einen Agenten das Fulfillment-Risiko bewerten und nutze das Ergebnis, um die HTTP-Antwort zu erstellen.
Bereichern oder klassifizieren Sie Ereignisse. Erhalten Sie eine Warteschlangennachricht, ein Event Grid-Ereignis oder eine andere Trigger-Nutzlast und verwenden Sie einen Agenten, um die Daten zu klassifizieren, zusammenzufassen oder zu bereichern, bevor Ihre Funktion das Ergebnis schreibt.
Fügen Sie einem nachhaltigen Arbeitsablauf Vernunft hinzu. Rufen Sie einen Agenten von einem Durable Functions-Orchestrator über die wiederholungssichere context.call_agent() API auf und verwenden Sie das Ergebnis dann in späteren Orchestrierungsschritten.

Agentenbindungen passen gut, wenn der deterministische Code der Funktion der Koordinator bleiben sollte. Der Agent führt eine begrenzte Schlussfolgerungsaufgabe aus und gibt die Kontrolle an den Handler oder die Orchestrierung zurück.

Warum Agentenbindungen verwenden?

Viele Produktionsworkflows kombinieren Schritte, die deterministisch sein müssen, mit Schritten, die vom Modelldenken profitieren. Agentenbindungen bieten folgende Vorteile für diese hybriden Arbeitsabläufe:

Fügen Sie existierenden Funktionen agentisches Verhalten hinzu. Verwenden Sie Agenten-Argumentation aus HTTP-, Timer-, Warteschlange-, Event Grid-, Service Bus- und anderen ausgelösten Funktionen.
Steuern Sie den Aufruf des Agenten sicher im Code. Entscheiden Sie, wann der Agent aufgerufen wird, inspizieren Sie seine Antwort und bestimmen Sie die Funktionsausgabe. Die Erweiterung schließt die einer Invocation zugeordneten Ressourcen nach erfolgreicher Ausführung, bei einem Fehler oder bei Abbruch.
Reduziere den Agenten-Setup-Code. Erhalten Sie einen konfigurierten Agent als typisierten Handlerparameter, anstatt ihn für jeden Aufruf zu konstruieren und einzubinden.
Getrennte Anweisungen von der Laufzeitkonfiguration. Speichern Sie natürliche Sprachbefehle in einer .agent.md Datei und konfigurieren Sie Clients und anbieterspezifische Tools explizit in Python.
Nutze die Funktionen der gemeinsamen Agenten. Die Erweiterung entdeckt dateibasierte Agentenfähigkeiten und HTTP-basierte MCP-Server aus der Anwendungswurzel und stellt sie jeder Agentenbindung zur Verfügung.
Rufen Sie Agenten von dauerhaften Orchestrierungen an. Die Erweiterung führt die Arbeit des Agents in einer versteckten Aktivität aus, sodass die erneute Ausführung der Orchestrierung deterministisch bleibt.
Debugge lokal mit vertrauten Werkzeugen. Führe die App lokal aus und debugge sie wie jede andere Python-Funktions-App. Man kann Breakpoints setzen und sowohl die deterministische Funktionslogik als auch den Code, der den Agenten aufruft, durchlaufen.

Wie eine Agentenbindung funktioniert

AgentFunctionApp erbt von azure.functions.FunctionApp, und hat daher die gleichen Fähigkeiten wie FunctionApp. Der Dekorator markdown_agent fügt einer Funktion einen Eingabeparameter für einen Agenten hinzu.

Für jede Agentenbindung führt die Erweiterung folgende Operationen durch:

Sucht die angeforderte .agent.md-Datei im Stammverzeichnis der Funktions-App oder in ihrem agents/-Verzeichnis.
Lädt die vollständige Datei als rohe UTF-8-Befehle.
Kombiniert die Anweisungen mit der konfigurierten Clientfactory, den explizit konfigurierten Provider-Tools sowie den entdeckten Agentenfähigkeiten und MCP-Servern.
Erzeugt eine frische Agent und öffnet Invocation-eigene Ressourcen.
Injiziert das Agent in den Handler-Parameter.
Schließt die einer Invocation zugeordneten Ressourcen, wenn die Ausführung endet.

Die Erweiterung kann Provider-Discovery- und kompilierte Bindungsdefinitionen cachen. Ressourcen aktiver Aufrufe werden zwischen Funktionsaufrufen weder zwischengespeichert noch wiederverwendet.

Definieren Sie eine Agentenbindung

Das folgende Beispiel verwendet den derzeit unterstützten Microsoft Agent Framework-Anbieter, um ein Agent zu einer HTTP-ausgelösten Funktion hinzuzufügen. Die Funktion konstruiert die Aufgabe im Code, ruft den Agenten auf und gibt die Agentenantwort zurück:

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)

Der Wert arg_name muss mit dem eingespritzten Handlerparameter übereinstimmen. Um mehrere Agenten in dieselbe Funktion einzufügen, stapeln Sie markdown_agent-Decorators und verwenden Sie für jede Agentenbindung einen eindeutigen arg_name- und Handler-Parameter. Der agent_name Wert identifiziert die Anweisungsdatei. In diesem Beispiel muss order-fulfillment zu genau einer dieser Stellen aufgelöst werden:

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

Wenn beide Dateien existieren, ist die Definition mehrdeutig und der App-Start schlägt fehl. Agentennamen können keine absoluten Pfade, Pfadtrenner oder Durchlaufkomponenten enthalten. Dateien, die außerhalb der Anwendungswurzel aufgelöst werden, sind nicht erlaubt.

Konfigurieren Sie den Agenten-Client und die Werkzeuge

Konfigurieren Sie beim Erstellen von AgentFunctionApp ein parameterloses client_factory. Die Fabrik liefert einen frischen Client zurück, der vom Provider-Paket unterstützt wird. Du kannst auch Microsoft Agent Framework Tool-Objekte oder Python-Callables auf App-Ebene durch den tools Parameter leiten. Ein Binding kann die Client Factory und die Tools auf Anwendungsebene außer Kraft setzen, wenn für sie ein anderes Verhalten erforderlich ist.

Zum Beispiel verwendet die folgende durch HTTP ausgelöste Funktion eine Agentenbindung, die lookup_inventory nur für order_agent als Werkzeug verfügbar macht:

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)

Behalte diese Überlegungen im Hinterkopf, wenn du den Agenten-Client und die Tools konfigurierst:

Die Erweiterung des Basisagenten ist anbieterneutral. Ein Provider-Paket integriert ein spezifisches Agent-SDK und definiert die unterstützten Client- und Agententypen.
Das derzeit unterstützte Microsoft Agent Framework Provider-Paket wählt oder konfiguriert keinen Modellanbieter für Ihre Anwendung. Deine Client-Fabrik bestimmt, welchen unterstützten Microsoft Agent Framework Chat-Client und Modell der Agent verwendet.
Die Erweiterung übergibt die gesamte .agent.md Datei als Agent-Anweisungen an den konfigurierten Anbieter. Es analysiert keine Modelleinstellungen, Tools, YAML-Frontmatter oder andere Laufzeitkonfiguration aus der Datei.

Shared Agent Skills und MCP-Server

Die Erweiterung entdeckt automatisch die Funktionen des gemeinsamen Agenten aus der Anwendungswurzel:

Capability	Ort	Behavior
Agent-Fähigkeiten	`skills/<skill-name>/SKILL.md` oder `Skills/<skill-name>/SKILL.md`	Das Provider-Paket lädt und validiert die dateibasierte Agentenfähigkeit.
Fern-MCP-Server	`mcp.json`	Die Erweiterung konfiguriert unterstützte HTTP- oder streamfähige HTTP-Server sowie optionale Allowlists für Tools.
Anbieter-Tools	Anwendungs- oder Bindungskonfiguration	Microsoft Agent Framework Tool-Objekte oder Python-Callables werden explizit bereitgestellt statt entdeckt.

Behalte diese Überlegungen im Hinterkopf, wenn du Shared-Agent-Funktionen nutzt:

Jede Agentenbindung in der Funktions-App erhält alle entdeckten Agentenfähigkeiten und MCP-Server.
Dateibasierte Agentenfähigkeiten sind Fähigkeiten, die ein Agent laden kann. Sie sind keine von Azure Functions gehosteten Skills, die ein separates Ausführungsmodell verwenden.
Die aktuelle Vorschau der Agent-Erweiterung unterstützt es nicht, für eine App oder eine einzelne Bindung eine Untermenge von Funktionen auszuwählen.
Agentenfähigkeiten und MCP-Tools können privilegierte Operationen ausführen. Setze nur Fähigkeiten ein, die jeder Agent in der App nutzen darf, und nutze separate Funktions-Apps, wenn Agenten unterschiedliche Fähigkeitsgrenzen benötigen.

Die MCP-Konfiguration kann für URLs, Header, Authentifizierungs-Scopes und Client-IDs auf Umgebungsvariablen verweisen. Referenzen werden für jeden Aufruf aufgelöst, bevor sich die Erweiterung mit dem Server verbindet. Speichere Geheimnisse nicht direkt in einer quellcode-kontrollierten mcp.json Datei.

Local-Process- und Standard-Input/Output-(STDIO) MCP-Server werden nicht unterstützt. MCP-Unterstützung ist eine optionale Abhängigkeit und normale Paketimporte bleiben sicher, wenn sie nicht installiert ist.

Verwenden Sie Agentenbindungen mit Durable Functions

Agentenbindungen unterstützen hybride, langlaufende Workflows durch eine optionale Integration von Durable Functions. Ein synchroner Generator-Orchestrator ruft context.call_agent() auf und liefert die resultierende Aufgabe:

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 eine versteckte Aktivität, die die Agentendefinition auflöst und alle Modell-, Dateisystem-, Zugangs-, Werkzeug- und Netzwerkoperationen ausführt. Der Orchestrator erstellt nur eine deterministische, JSON-serialisierbare Schema-v1-Anfrage. Daher führt die erneute Ausführung der Orchestrierung nicht deterministische Agentenvorgänge nicht erneut aus.

Persistente Agentaufrufe verwenden den Anbieter und die gemeinsam genutzten Funktionen, die durch AgentFunctionApp konfiguriert sind. Ein- und Ausgänge müssen JSON-serialisierbar sein.

Durable Functions-Unterstützung ist optional. Anwendungen, die es nicht verwenden, müssen Durable Functions nicht installieren oder importieren. Um zu verwenden orchestration_trigger und context.call_agent(), installieren Sie das unterstützte Provider-Paket mit seinem Durable Dependency Extra.

Projektdateien

Eine agentenfähige Anwendung ist eine Standard-Python-v2-Funktionsanwendung mit Abhängigkeiten von Agentenerweiterungen und einer oder mehreren Befehlsdateien:

Datei oder Ordner	Purpose
`function_app.py`	Definiert `AgentFunctionApp`, Standardtrigger für Funktionen, Agentenbindungen, Client-Factorys und explizit konfigurierte Anbietertools.
`host.json`	Konfiguriert den Azure Functions-Host.
`requirements.txt`	Enthält ein unterstütztes Agent-Provider-Paket und jedes SDK-spezifische Client-Paket. Verwenden Sie für die aktuelle Vorschau `azurefunctions-agents-extensions-agent-framework`. Optionale Extras ermöglichen Durable Functions und MCP-Unterstützung.
`.agent.md` oder `agents/.agent.md`	Enthält rohe UTF-8-Anweisungen für einen Agenten. Jeder referenzierte Name muss genau auf eine Datei aufgelöst werden.
`skills/` oder `Skills/`	(Optional) Enthält dateibasierte Agentenfähigkeiten, die von allen Agentenbindungen geteilt werden.
`mcp.json`	(Optional) Definiert entfernte HTTP-basierte MCP-Server, die von allen Agentenbindungen gemeinsam genutzt werden.

Für die Standardstruktur Python Projekts siehe den Azure Functions Python Developer Guide.

Validierung und Diagnostik

Die Erweiterung validiert Agentendefinitionen vor oder während der Bindungskompilierung, sodass Konfigurationsprobleme mit verwertbaren Fehlern ausfallen. Validierung deckt ab:

Fehlende oder mehrdeutige .agent.md Dateien.
Ungültige Handler-Signaturen, einschließlich eines fehlenden oder nicht übereinstimmenden injizierten Parameters.
Nicht unterstützte Anbieteroptionen oder Funktionen.
Ungültige Fertigkeitsverzeichnisse und fehlerhafte MCP-Konfiguration.
Nicht unterstützte MCP-Transporte und fehlende Umweltwerte.
Ungültige dauerhafte Payloads oder Werte, die nicht JSON-serialisierbar sind.

Wo verfügbar, bewahrt die Erweiterung den Namen der Azure-Funktion, die Aufruf-ID und die Durable Instance ID an der Anbietergrenze, um Korrelation und Diagnostik zu unterstützen.

Feedback

War diese Seite hilfreich?

Last updated on 2026-09-24