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, erstellt die Erweiterung einen SDK-spezifischen Agent oder eine Sitzung aus Markdown-Anweisungen und injiziert es in Ihren Handler als typisierten Parameter. 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.

Was ist eine Agentzuordnung?

Eine Agentenbindung ist eine Eingabebindung, die einen konfigurierten Agenten oder eine Sitzung als typisierten Parameter für eine Python-Funktion bereitstellt. Die Erweiterung kombiniert Markdown-Anweisungen mit der Provider-Konfiguration und den Tools der App, sodass dein Handler den Agenten nicht für jede Aufrufung erstellen und verdrahten muss.

Die Bindung ersetzt weder deine Funktion noch ihren Auslöser. Dein Code validiert weiterhin Eingaben, entscheidet, wann der Agent aufgerufen wird, behandelt Fehler und erzeugt die Ausgabe. Anweisungen befinden sich in einer .agent.mdDatei, während Client-, Modell- und Werkzeugkonfigurationen im Anwendungscode und in den Einstellungen verbleiben. Provider-Pakete verbinden dieses Shared-Binding-Modell mit verschiedenen Agent-SDKs.

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.

Die Funktion bleibt der Koordinator: Sie bereitet die Aufgabe vor, ruft den Agenten auf und entscheidet, was mit dem Ergebnis geschieht. Bindings reduzieren Setup-Code, trennen Markdown-Anweisungen von der Laufzeitkonfiguration und funktionieren mit bekannten Azure Functions-Triggern und lokalen Debugging-Tools.

Wenn du Verhalten und Trigger hauptsächlich über Markdown und deklarative Konfiguration definieren möchtest, statt über einen Python-Handler, solltest du in Azure Functions gehostete Skills in Betracht ziehen.

Verfügbare Pakete

Anbieterspezifische Erweiterungspakete verbinden das Shared-Binding-Modell mit einem Agent-SDK. Die folgenden Pakete sind in der Vorschau verfügbar und erfordern Python 3.13 oder neuer:

SDK Paket Get started
Microsoft Agent Framework azurefunctions-agents-extensions-agent-framework Python-Funktion Quickstart · Durable-Orchestrierung – Schnellstart
GitHub Copilot SDK azurefunctions-agents-extensions-copilot-SDK Python-Funktion Quickstart · HTTP- und Warteschlangenbeispiel · Durable-Orchestrierungsbeispiel

Jedes Paket definiert seine unterstützten Typen, Authentifizierung, Modellkonfiguration und Aufruf-API. Folgen Sie dem entsprechenden Quickstart oder Sample für SDK-spezifische Setup- und Deployment-Anforderungen.

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:

  1. Löst die angeforderte .agent.md-Datei vom Stammverzeichnis der Funktions-App oder in ihrem agents/-Verzeichnis auf.
  2. Lädt die vollständige Datei als rohe UTF-8-Befehle.
  3. Kombiniert die Anweisungen mit Provider-Konfiguration, expliziten Tools sowie entdeckten Agenten-Fähigkeiten und MCP-Servern.
  4. Erstellt einen frischen, SDK-spezifischen Agenten oder eine Sitzung und öffnet aufrufeigene Ressourcen.
  5. Injiziert den Agent oder die Sitzung in den Handler-Parameter.
  6. Schließt die einer Invocation zugeordneten Ressourcen, wenn die Ausführung endet.

Der Anbieter verwaltet seinen Client-Lifecycle. Ressourcen, die der Invocation gehören, werden nach Erfolg, Misserfolg oder Abbruch geschlossen.

Definieren Sie eine Agentenbindung

Um eine Bindung zu einer Python v2-Funktions-App hinzuzufügen:

  1. Installiere ein Provider-Paket und importiere dessen AgentFunctionApp.
  2. Konfigurieren Sie den Client, das Modell, die Authentifizierung und die Werkzeuge wie von diesem Paket benötigt.
  3. Füge eine .agent.md Anleitungsdatei in der App-Wurzel oder im Verzeichnis agents/ hinzu. Die Datei ist roher UTF-8-Text; das System analysiert weder YAML-Frontmatter noch die Laufzeitkonfiguration.
  4. Fügen Sie markdown_agent zu einer ausgelösten Funktion hinzu. Legen Sie arg_name so fest, dass es mit dem typisierten Handler-Parameter übereinstimmt, und agent_name so, dass es die Anweisungsdatei identifiziert.
  5. Rufen Sie das eingeschleuste Objekt über dessen SDK-API auf und verarbeiten Sie das Ergebnis in Ihrem Funktionscode.

Zum Beispiel kann agent_name="order-fulfillment"order-fulfillment.agent.md in einem der unterstützten Verzeichnisse identifizieren, aber nicht in beiden. Namen müssen innerhalb der App-Wurzel eindeutig aufgelöst werden und dürfen keine Pfadtrenner oder Pfadtraversierungskomponenten enthalten. Um mehrere Agenten einzuschleusen, stapeln Sie Dekoratoren mit unterschiedlichen arg_name Werten und passenden Handler-Parametern.

Für vollständige Codebeispiele siehe die Paket-Quickstarts und Beispiele.

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 SDK-spezifische Tools oder Python-Callables, die vom Anbieter unterstützt werden, werden explizit bereitgestellt, anstatt automatisch erkannt zu werden.

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

Wenn Sie die optionale Durable Functions-Integration eines Anbieters installieren, liefert ein synchroner Generator-Orchestrator context.call_agent(agent_name, input_). Die Erweiterung führt Agentenarbeit in einer versteckten Aktivität aus und hält Modellaufrufe, Tools und andere nichtdeterministische Operationen außerhalb der Orchestrator-Wiedergabe.

Ein- und Ausgänge müssen JSON-serialisierbar sein. Anrufe nutzen den Anbieter und freigegebene Funktionen, die von der App konfiguriert sind. Siehe Quickstarts und Samples des Pakets für Installations- und Orchestrierungsbeispiele.

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 Beinhaltet ein Provider-Paket und die erforderlichen Abhängigkeiten. Optionale Extras können Durable Functions und MCP-Unterstützung aktivieren.
*.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 Agentdefinitionen vor oder während der Bindungskompilierung, sodass Konfigurationsprobleme mit verwertbaren Fehlern fehlschlagen. 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.

  • Zuletzt aktualisiert um