Entwicklerhandbuch für in Azure Functions gehostete Skills

In Azure Functions gehostete Skills verwenden ein Markdown-First-Programmiermodell auf der Azure Functions Python-Laufzeit. Du definierst jede gehostete Fähigkeit in einer .agent.md Datei. YAML-Front-Matter legt die Konfiguration fest. Der Markdown-Körper gibt dem Modell Anweisungen.

Die meiste Entwicklungsarbeit ändert diese Definitionen sowie ihre Tool- und Konfigurationsdateien. In der Regel muss man den generierten Startcode von Functions nicht ändern. Die App benötigt jedoch weiterhin die richtigen Host-Einstellungen, Python-Abhängigkeiten, Modellzugriff und Service-Berechtigungen.

Dieser Leitfaden verwendet das öffentliche Vorschau-Paket azurefunctions-agents-runtime. Für eine vollständige lokale Einrichtung beginne mit dem Canvas-Quickstart. Um Azure-Ressourcen zu erstellen und ein Beispiel bereitzustellen, verwenden Sie den Azure Developer CLI Quickstart.

Projektstruktur

Verwenden Sie die folgende Struktur im Funktions-App-Projektroot. Füge die optionalen Dateien nur dann hinzu, wenn deine App sie braucht.

<project_root>/
├── function_app.py
├── host.json
├── requirements.txt
├── local.settings.json
├── summarize.agent.md
├── agents.config.yaml
├── mcp.json
├── skills/
│   └── report-writing/
│       ├── SKILL.md
│       ├── references/
│       │   └── report-format.md
│       └── assets/
│           └── example-report.md
└── tools/
    └── get_policy.py

Der Startcode in function_app.py kann so kompakt sein wie in folgendem Beispiel:

from azure_functions_agents import create_function_app

app = create_function_app()

Die Laufzeit entdeckt gehostete Skills und deren konfigurierte Fähigkeiten, wenn der Functions-Host die App lädt. Behalte die Host- und Abhängigkeitsdateien aus deinem Starterprojekt. Für die Standarddateien der Python-App siehe den Python-Entwicklerleitfaden.

Definieren eines gehosteten Skills

Erstellen Sie summarize.agent.md im Projektstammverzeichnis:

---
name: Request summary
description: Summarize a request and identify missing information.
trigger:
  type: http_trigger
  args:
    route: summarize
    methods: [POST]
    http_auth: function
builtin_endpoints:
  debug_chat_ui: true
  http_auth: function
---

Summarize the request supplied in the HTTP request body.

Return these sections:

- Summary: State the purpose of the request.
- Missing information: List the facts needed to complete the request.
- Questions: Ask specific questions for the missing facts.

Use only the supplied facts. Do not invent names, dates, or approvals.
If the request is empty or unclear, explain what information is needed.

Diese Definition akzeptiert HTTP-POST-Anfragen auf der Route summarize . In Azure http_auth: function wird eine Funktion oder ein Host-Schlüssel benötigt. Das Standard-Funktionen-Routenpräfix ist api, also ist die Route normalerweise /api/summarize. Verwenden Sie keinen lokalen Test, um die bereitgestellte Authentifizierung zu verifizieren. Details finden Sie unter HTTP-Trigger-Autorisierung.

Der Dateiname liefert die Identität des gehosteten Skills. Für summarize.agent.mdist der generierte Name der Azure-Funktion summarize, und das eingebaute Endpunkt-Routensegment ist summarize. Das Feld name ist ein Anzeigename. Eine Änderung dieses Feldes benennt die Funktion nicht um. Ein explizites HTTP route, wie in diesem Beispiel, legt die HTTP-Triggerroute fest.

Der Block builtin_endpoints aktiviert das Chatfenster und seine unterstützenden Chat-APIs für lokale Tests. Für verfügbare Endpunkte und Authentifizierungseinstellungen siehe vordefinierte Endpunkte.

Schreibe klare Anweisungen

Geben Sie das Ziel, die Eingabe, die verwendeten Werkzeuge und die erforderliche Ausgabe an. Erklären Sie, was zu tun ist, wenn Daten fehlen oder ein Tool ausfällt. Gib an, welche Aktionen der gehostete Skill nicht ausführen darf.

Anweisungen sind keine Autorisierungsmechanismen. Überprüfen Sie genaue Geschäftsregeln, Berechtigungen und erforderliche Genehmigungen im Code oder im Service, der die Aktion ausführt. Zum Beispiel ersetzt eine Aufforderung mit der Aufforderung "nur genehmigte Berichte senden" keine Genehmigungsprüfung im Tool, das den Bericht sendet.

Konfigurieren von gemeinsamen Standardeinstellungen und Überschreibungen

Setze gemeinsames Modell und Timeout-Standardeinstellungen in agents.config.yaml:

model: $FOUNDRY_MODEL
timeout: 900

Legen Sie für FOUNDRY_MODEL eine Modellbereitstellung fest, die über Ihren konfigurierten Anbieter verfügbar ist. Ein vollständiges Beispiel der Foundry-App-Einstellungen finden Sie unter Lokale Einstellungen konfigurieren. Informationen zu anderen Anbietern finden Sie unter Konfiguration des Modellanbieters.

Fügen Sie der Front Matter unterstützte Overrides für in agents.config.yaml definierte Standardeinstellungen hinzu, wenn die gehostete Fähigkeit andere Einstellungen benötigt:

timeout: 120
mcp:
  exclude:
    - office365-outlook
skills: false

Dieses Beispiel setzt einen 120-sekündigen Laufzeit-Timeout, entfernt einen MCP-Server und deaktiviert wiederverwendbare Skills für diesen gehosteten Skill. Der ausgeschlossene Servername muss mit einem Schlüssel in mcp.jsonübereinstimmen.

Verwenden Sie $SETTING_NAME , um eine App-Einstellung in einen unterstützten String-Wert einzufügen. Zum Beispiel liest model: $FOUNDRY_MODEL die Modelleinstellung. Diese Syntax ist keine vollständige Shell-Ausdruckssyntax. Informationen über Substitutionsregeln finden Sie unter Variablenersetzung.

Trigger einstellen

Verwenden Sie in jeder .agent.md Datei einen expliziten Trigger, der mit einem Ereignis beginnt. Um Azure Storage Queue-Nachrichten statt HTTP-Anfragen zu verarbeiten, ersetzen Sie den trigger Block:

trigger:
  type: queue_trigger
  args:
    queue_name: work-items
    connection: AzureWebJobsStorage

Ändere außerdem die Anweisungen so, dass sie die Eingabe der Warteschlangennachricht anstelle eines HTTP-Anforderungskörpers beschreiben.

Der connection Wert ist ein Name der App-Einstellung oder das Präfix für eine identitätsbasierte Einstellungssammlung, kein eingebettetes Geheimnis. Konfigurieren Sie die Speicherverbindung und die Berechtigungen separat. Weitere Informationen finden Sie unter Verbindungen für Warteschlangentrigger.

Wählen Sie einen Trigger für die Ereignisquelle:

Für die vollständige Liste und die erforderlichen Argumente siehe Unterstützte Triggertypen.

Optionale integrierte Chat- und MCP-Endpunkte sind vom expliziten Trigger getrennt. Weitere Informationen finden Sie unter Integrierte Endpunkte. Eine Remote-MCP-Server-Definition in mcp.json stellt Ihren gehosteten Skill nicht als MCP-Server bereit.

Verbindung zu einem MCP-Server herstellen

Nutze einen entfernten MCP-Server, wenn ein anderer Dienst bereits die benötigten Tools bereitstellt. Fügen Sie mcp.json dem Stammverzeichnis des Function-App-Projekts hinzu:

{
  "servers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

Die Laufzeit unterstützt Remote-http- und -streamable-http-Transporte. Sie startet weder lokale stdio noch befehlsbasierte MCP-Server.

Gehostete Fähigkeiten erben entdeckte MCP-Server, es sei denn, man schließt sie aus. Um den Server von einem gehosteten Skill auszuschließen, definieren Sie mcp.exclude in der .agent.md-Datei. Um einen Server auf bestimmte Werkzeuge zu beschränken, fügen Sie seinem tools Eintrag in mcp.jsonein Array hinzu. Verwenden Sie die genauen Werkzeugnamen, die von diesem Server veröffentlicht wurden. Diese Auswahl gilt für die Serverdefinition.

Für die Microsoft Entra-Authentifizierung setzen Sie auth.scope auf den Tokenbereich des Servers. Sie können auch auth.client_id festlegen, um eine benutzerseitig zugewiesene verwaltete Identität zu verwenden. Die ausgewählte Identität muss die Berechtigung haben, den Server aufzurufen. Steck keine Geheimnisse in mcp.json. Details finden Sie unter MCP-Serverkonfiguration.

Die gehostete Ausführung ist nicht interaktiv. Diese identitätsbasierte Konfiguration führt nicht automatisch einen interaktiven Benutzer-OAuth-Flow aus. Wenn ein Geschäftsdienst eine delegierte Benutzerautorisierung benötigt, sollten Sie einen unterstützten Connector und dessen verwaltete Verbindung in Betracht ziehen. Bestätigen Sie, dass der Connector das erforderliche Autorisierungsmodell des Dienstes unterstützt. Siehe Azure-Konnektoren verwenden.

Wiederverwenden von Anweisungen mit Skills

Nutzen Sie einen wiederverwendbaren Skill als Anleitung, die mehrere gehostete Skills benötigen, oder als Referenzmaterial, das nicht bei jeder Anforderung benötigt wird.

Erstellen Sie skills/report-writing/SKILL.md:

---
name: report-writing
description: Write a review report from supplied facts. Use when a task requests a review report.
---

Read [the report format](references/report-format.md) before you write.
Use [the example report](assets/example-report.md) as a format example,
not as a source of facts.

State the result, the supporting facts, and the questions that remain.
If required facts are missing, list them. Do not invent a result.

In references/report-format.mddefinieren Sie die erforderlichen Berichtsabschnitte. In assets/example-report.md zeige einen Musterbericht, der das Format zeigt.

Der name des Skills muss mit seinem übergeordneten Verzeichnis übereinstimmen, zum Beispiel report-writing. Die Laufzeit liefert Skill-Namen und Beschreibungen für die Auffindung und lädt vollständige Anweisungen und Ressourcen auf Abruf. Erwähne unterstützende Ressourcen in SKILL.md, damit der gehostete Skill weiß, wann er sie lesen muss.

Bewahre jeden Skill in einem eigenen Ordner direkt unter skills/. Informationen zu Erstellungsrichtlinien finden Sie unter Skills.

Skill-Dateien registrieren ausführbare Tools nicht automatisch. Verwenden Sie ein konfiguriertes Tool für ausführbares Verhalten. Geh nicht davon aus, dass ein Skript in einem Skill dem Modell die Erlaubnis oder eine Möglichkeit gibt, es auszuführen.

Hinzufügen von Tools

Verwenden Sie zunächst ein entferntes MCP-Tool oder ein Laufzeitsystem-Tool, wenn es die Anforderungen erfüllt. Füge benutzerdefinierte Python-Tools für app-spezifische Logik hinzu.

Werkzeuge für das Laufzeitsystem

Die Laufzeit stellt das web_request Systemwerkzeug standardmäßig bereit. Es stellt ausgehende Anfragen an öffentliche Webadressen. HTTPS ist standardmäßig erforderlich. Um Anfragen auf einen exakten Hostnamen zu beschränken, fügen Sie diese Konfiguration hinzu:agents.config.yaml

system_tools:
  web_request:
    allowed_hosts:
      - example.com

Legen Sie system_tools.web_request: false fest, um das Tool anwendungsweit oder für einen gehosteten Skill zu deaktivieren. Eine Zulassungsliste schränkt Ziele ein. Es erteilt keine Berechtigung, einen Dienst zu nutzen oder vertrauliche Daten zu senden.

Für isolierte Python-Ausführung konfigurieren Sie einen Azure Container Apps dynamic sessions Python-Code-Interpreter-Pool:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Setze ACA_SESSION_POOL_ENDPOINT auf den Management-Endpunkt des Pools. Erteile der App-Identität vor der Nutzung die erforderlichen Pool-Berechtigungen. Informationen zu Identitätseinstellungen und Anforderungen finden Sie unter Sandbox-Ausführung.

Benutzerdefinierte Python-Tools

Erstellen Sie tools/get_policy.py:

from azure_functions_agents import tool


@tool
def get_policy_version() -> str:
    """Return the version of the sample review policy."""
    return "2026-10"

Verwenden Sie ein öffentliches Tool pro .pyDatei unter tools/. Die Laufzeit registriert das erste unterstützte gewöhnliche Werkzeug, das sie in jeder Datei findet. Verwenden Sie Typhinweise und eine klare Docstring, damit das Modell den Zweck und die Eingaben des Tools versteht. Fügen Sie erforderliche Pakete zu requirements.txt hinzu.

Ein benutzerdefiniertes Python-Tool läuft im Functions-Python-Worker. Es ist nicht automatisch in einer Sandbox isoliert. Eingaben validieren, Berechtigungen durchsetzen und Fehler explizit melden. Für Werkzeuge, die den externen Zustand ändern, machen Sie wiederholte Aufrufe sicher, zum Beispiel durch Verwendung eines Idempotenzschlüssels.

Durable Workflow-Tools verwenden einen separaten @workflow_tool Vertrag. Zu jenem Modell, siehe Dynamische Workflows.

Konfiguration verwalten

Lokale Einstellungen werden nicht automatisch in die Azure-App-Einstellungen kopiert. Konfigurieren Sie beide Umgebungen. Speichern Sie keine Geheimnisse in Git, verwenden Sie eine verwaltete Identität, wo sie unterstützt wird, und verwenden Sie geeigneten Geheimnisspeicher für Zugangsdaten, die weiterhin benötigt werden. Sieh dir lokale Einstellungen an und verwalte die App-Einstellungen.

Der timeout des gehosteten Skills und der functionTimeout des Functions-Hosts sind getrennte Grenzwerte. Legen Sie beide für Ihre Workload fest. Ein gehosteter Skill-Timeout setzt weder die Hosting-Plan-Limits noch HTTP-Response-Limits außer Kraft. Weitere Informationen finden Sie unter Funktions-App-Timeoutdauer.

Azure-Konnektoren verwenden

Azure-Connectors ermöglichen es gehosteten Skills, autorisierte externe Operationen aufzurufen und Serviceereignisse ohne benutzerdefinierten Client- und Authentifizierungscode zu empfangen. Dieser Abschnitt setzt voraus, dass die Connector-Ressourcen bereits existieren.

Um einen MCP-Server und seine Verbindung einzurichten, siehe Erstellen eines MCP-Server-Connectors.

Für einen bestehenden Microsoft 365 Outlook MCP-Server fügen Sie einen Eintrag in mcp.json hinzu:

{
  "servers": {
    "office365-outlook": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL",
      "auth": {
        "scope": "https://apihub.azure.com/.default"
      }
    }
  }
}

Setze O365_MCP_SERVER_URL in den lokalen oder Azure-App-Einstellungen auf den bereitgestellten Serverendpunkt. Gewähren Sie der Identität der Funktions-App Zugriff auf diesen MCP-Server. Um eine vom Benutzer zugewiesene verwaltete Identität auszuwählen, fügen Sie auth.client_id mit seiner Client-ID hinzu.

Konfigurieren Sie beide Autorisierungsgrenzen:

Eine Berechtigung an einer Grenze gewährt keine Berechtigung an der anderen. Die Autorisierung der Verbindung wird nicht automatisch zur Identität jedes Anrufers deines gehosteten Skills.

Um einen gehosteten Skill aus einem Connector-Event zu starten, erstellen und autorisieren Sie zunächst eine Verbindung. Verwenden Sie diesen Triggerblock dann in seiner Datei .agent.md:

trigger:
  type: connector_trigger

Sie müssen außerdem das Upstream-Event, das Rückruf-Routing und die Rückruf-Authentifizierung im Connector-Namensraum konfigurieren. Eine Serverdefinition in mcp.json abonniert keine Events. Für Erweiterungsanforderungen und Ereigniseinrichtung siehe Use managed connectors in Azure Functions.

Lokal ausführen

Verwenden Sie Azure Functions Core Tools, um die App auf Ihrem Computer zu starten. Du brauchst außerdem Python 3.13 oder neuer und Zugang zu einer Modellbereitstellung.

Konfigurieren lokaler Einstellungen

Erstelle local.settings.json im Stammverzeichnis des Function-App-Projekts. Für ein Foundry-Modell und lokalen Azure Storage verwenden Sie diese Struktur:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "AZURE_FUNCTIONS_AGENTS_PROVIDER": "foundry",
    "FOUNDRY_PROJECT_ENDPOINT": "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
    "FOUNDRY_MODEL": "<model-deployment-name>"
  }
}

Ersetzen Sie die Endpunkt- und Modell-Platzhalter durch Ihre Bereitstellungswerte. Verwenden Sie ein Modell-Deployment, das in Ihrem Foundry-Projekt existiert, und gewähren Sie Ihrer lokalen Entwickleridentität Zugriff darauf. Füge alle Einstellungen hinzu, die von deinen MCP-Servern, Tools oder Triggern verwendet werden. local.settings.json aus der Versionsverwaltung heraushalten.

Verwenden Sie einen Emulator für eine Datenquelle, wenn ein kompatibler Emulator verfügbar ist. Zum Beispiel stellt Azurite lokalen Blob-, Warteschlangen- und Tabellenspeicher bereit. Starte Azurite vor dem Funktionshost, wenn du UseDevelopmentStorage=true verwendest. Für Service Bus siehe den Service Bus-Emulator.

Connector-Namensräume, Verbindungen und Connector-MCP-Server benötigen tatsächliche Azure-Ressourcen. Die lokale Ausführung ruft diese Ressourcen weiterhin auf. Modellaufrufe und dynamische Sitzungen von Azure Container Apps nutzen ebenfalls ihre konfigurierten Dienste und können Kosten verursachen.

Starte den Functions-Host

Erstellen und aktivieren Sie eine virtuelle Python-Umgebung, wie im lokalen Entwicklungsleitfaden von Python beschrieben. Im Funktions-App-Projektroot installieren Sie die Pakete aus requirements.txt:

python -m pip install -r requirements.txt

Für Foundry mit identitätsbasiertem Zugriff melden Sie sich mit einer Identität an, die die Berechtigung zur Nutzung des Modells hat:

az login

Starte den Host aus demselben Verzeichnis:

func start

Der Host listet die summarize Funktion und die im Beispiel aktivierten Endpunkte auf. Mit dem Standard-Routenpräfix api und Port 7071ist die Ausgabe ähnlich zu:

Functions:

    agent_summarize_builtin_chat: [POST] http://localhost:7071/api/agents/summarize/chat

    agent_summarize_builtin_chatstream: [POST] http://localhost:7071/api/agents/summarize/chatstream

    agent_summarize_builtin_chat_page: [GET] http://localhost:7071/api/agents/summarize/

    agent_summarize_builtin_history: [GET] http://localhost:7071/api/agents/summarize/history

    summarize: [POST] http://localhost:7071/api/summarize

Lass den Host laufen, während du testest. Lesen Sie die Terminalausgabe auf Konfigurationsfehler und die URLs der registrierten Funktionen. Weitere Informationen finden Sie unter Ausführen einer lokalen Funktion.

Testen Sie mit dem Chatfenster

Das summarize.agent.md-Beispiel ermöglicht bereits das integrierte Chatfenster und dessen zugrundeliegenden Chat-APIs.

Öffnen Sie http://localhost:7071/api/agents/summarize/ im Browser, wenn host.json das Standard-Routenpräfix api verwendet. Wenn dein Starterprojekt extensions.http.routePrefix auf eine leere Zeichenkette setzt, verwende stattdessen http://localhost:7071/agents/summarize/. Verwenden Sie den eigentlichen Host-Port, falls dieser sich von 7071 unterscheidet.

Geben Sie eine Beispielanfrage ein, senden Sie sie ab und überprüfen Sie die Antwort und das Host-Log. Bitten Sie zum Beispiel den gehosteten Skill, eine Anforderung mit fehlendem Lieferdatum zusammenzufassen. Überprüfen Sie, ob die Antwort das fehlende Datum als fehlend identifiziert, anstatt eines zu erfinden. Teste auch fehlende Eingaben und Werkzeugfehler.

Die Ausführung lokaler Core Tools überspringt normalerweise Funktionsschlüsselprüfungen. Behalten Sie http_auth: function in der Definition bei und testen Sie die Authentifizierung separat in Azure. Für ein bereitgestelltes Chatfenster geben Sie den Funktionsschlüssel an, wenn Sie dazu aufgefordert werden. Aktiviere Debug-Endpunkte nur dort, wo es nötig ist. Für Routen und Schlüsselabruf siehe vordefinierte Endpunkte.

In Azure bereitstellen

Wählen Sie eine Bereitstellungsmethode für Ihr Projekt:

Stellen Sie nach der Bereitstellung sicher, dass die Azure-App-Einstellungen die erforderlichen Werte enthalten, die App-Identität Zugriff auf das Modell und die Tools hat und jede Connector-Verbindung autorisiert ist. Teste den bereitgestellten Trigger und seine Authentifizierung mit einer kontrollierten Anfrage, bevor du Produktionsdaten verwendest.

Entdecken Sie End-to-End-Beispiele

Nutzen Sie diese Beispiele, um zu sehen, wie gehostete Skills Trigger, Tools und Azure-Dienste in einer vollständigen App kombinieren. Jedes Repository enthält Einrichtungs- und Bereitstellungsanweisungen.

Verwandte Inhalte

• Überblick über in Azure Functions gehostete Skills
• Konfigurationsreferenz für gehostete Fähigkeiten
• Bauen und testen Sie mit dem gehosteten Skills-Canvas
• Stellen Sie eine ereignisgesteuerte, gehostete Skills-App bereit
• Dynamische Workflows erstellen
• Leitfaden zur Laufzeitbeobachtbarkeit
• Beispiele für gehostete Fähigkeiten