Przewodnik dla programistów umiejętności hostowanych w Azure Functions

Hostowane umiejętności Azure Functions wykorzystują model programowania Markdown-first w środowisku uruchomieniowym Python usługi Azure Functions. Definiujesz każdą hostowaną umiejętność w pliku .agent.md . Blok metadanych YAML określa swoją konfigurację. Treść Markdown daje instrukcje dla modelu.

Większość prac programistycznych wiąże się ze zmianami tych definicji oraz ich narzędzia i plików konfiguracyjnych. Zazwyczaj nie musisz zmieniać wygenerowanego kodu startowego Functions. Jednak aplikacja nadal wymaga poprawnych ustawień hosta, zależności Python, dostępu do modelu oraz uprawnień do usług.

Ten przewodnik korzysta z pakietu azurefunctions-agents-runtimepublicznego podglądu. Aby uzyskać kompletne lokalne ustawienie, zacznij od szybkiego startu canvas. Aby utworzyć zasoby Azure i wdrożyć przykład, użyj szybkiego startu Azure Developer CLI.

struktura projektu

Użyj następującej struktury w katalogu głównym projektu function app. Dodawaj opcjonalne pliki tylko wtedy, gdy aplikacja ich potrzebuje.

<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

Kod startowy w function_app.py może być tak krótki:

from azure_functions_agents import create_function_app

app = create_function_app()

Runtime wykrywa hostowane umiejętności i ich skonfigurowane funkcje podczas ładowania aplikacji przez hosta Functions. Zachowaj pliki hosta i zależności z projektu początkowego. Standardowe pliki aplikacji Python znajdziesz w przewodniku dla deweloperów Python.

Zdefiniuj umiejętność hostowaną

Stwórz summarize.agent.md w korzeniu projektu:

---
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.

Ta definicja akceptuje żądania HTTP POST na trasie summarize . W Azure element http_auth: function wymaga funkcji lub klucza hosta. Standardowy prefiks trasy Functions to api, więc trasa to zazwyczaj /api/summarize. Nie używaj lokalnego testu do potwierdzenia wdrożonego uwierzytelniania. Szczegóły można znaleźć w artykule autoryzacja wyzwalaczy HTTP.

Nazwa pliku określa tożsamość hostowanej umiejętności. Dla summarize.agent.md, wygenerowana nazwa funkcji Azure to summarize, a wbudowany segment trasy końcowej to summarize. Pole name to nazwa wyświetlana. Zmiana tego pola nie powoduje zmiany nazwy funkcji. Jawny HTTP route, jak w tym przykładzie, wyznacza trasę wyzwalacza HTTP.

Blok builtin_endpoints włącza okno czatu i obsługujące je interfejsy API czatu do lokalnych testów. Informacje o dostępnych punktach końcowych i ustawieniach uwierzytelniania znajdziesz w sekcji wbudowane punkty końcowe.

Pisz jasne instrukcje

Określ cel, dane wejściowe, narzędzia do wykorzystania oraz wymagane rezultaty. Wyjaśnij, co robić, gdy brakuje danych lub narzędzie zawodzi. Określ, których akcji umiejętność hostowana nie może wykonywać.

Instrukcje nie są mechanizmami kontroli autoryzacji. Weryfikuj dokładne reguły biznesowe, uprawnienia i wymagane zatwierdzenia w kodzie lub w usłudze wykonującej daną akcję. Na przykład prompt "wyślij tylko zatwierdzone raporty" nie zastępuje sprawdzania aprobaty w narzędziu, które wysyła raport.

Skonfiguruj wspólne ustawienia domyślne i przesłonięcia

Ustaw domyślne modele współdzielone i timeouty w agents.config.yaml:

model: $FOUNDRY_MODEL
timeout: 900

Ustaw FOUNDRY_MODEL na wdrożenie modelu dostępne przez skonfigurowanego dostawcę. Pełny przykład ustawień aplikacji Foundry można znaleźć w artykule Konfiguruj ustawienia lokalne. W przypadku innych dostawców zobacz konfigurację dostawcy modelu.

Dodaj obsługiwane nadpisania dla domyślnych ustawień zdefiniowanych w agents.config.yaml do sekcji wstępnej, gdy hostowana funkcja wymaga innych ustawień:

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

Ten przykład ustawia 120-sekundowy limit czasu działania, usuwa jeden serwer MCP i wyłącza umiejętności wielokrotnego użytku dla tej hostowanej umiejętności. Nazwa wykluczonego serwera musi być zgodna z kluczem w mcp.json.

Użyj $SETTING_NAME, aby wstawić ustawienie aplikacji do obsługiwanej wartości typu string. Na przykład model: $FOUNDRY_MODEL odczytuje ustawienie modelu. Ta składnia nie jest pełną składnią wyrażeń powłoki. Informacje o regułach podstawiania znajdziesz w podstawianiu zmiennych.

Ustaw regułę wyzwalającą

Użyj jednego jawnego wyzwalacza w każdym pliku .agent.md, który zaczyna się od zdarzenia. Aby przetwarzać komunikaty Azure Storage Queue zamiast żądań HTTP, zastąp blok:trigger

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

Zmień także instrukcje tak, aby opisywały wiadomość wejściową do kolejki zamiast ciała żądania HTTP.

Wartość connection ta to nazwa ustawienia aplikacji lub prefiks dla kolekcji ustawień opartej na tożsamości, a nie osadzony sekret. Skonfiguruj połączenie z magazynem i uprawnienia osobno. Aby uzyskać więcej informacji, zobacz Połączenia wyzwalające kolejkę.

Wybierz wyzwalacz dla źródła zdarzenia:

Pełną listę i wymagane argumenty można znaleźć w artykule Obsługiwane typy wyzwalaczy.

Opcjonalny wbudowany czat i endpointy MCP są oddzielone od jawnego wyzwalacza. Zobacz wbudowane punkty końcowe, aby uzyskać więcej informacji. Definicja zdalnego serwera MCP w mcp.json nie udostępnia twojej hostowanej umiejętności jako serwera MCP.

Podłącz serwer MCP

Korzystaj ze zdalnego serwera MCP, gdy inna usługa już dostarcza potrzebne narzędzia. Dodaj mcp.json do root projektu function app:

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

Środowisko uruchomieniowe obsługuje zdalne transporty http i streamable-http. Nie uruchamia lokalnych ani opartych na poleceniach serwerów MCP stdio

Hostowane umiejętności dziedziczą odkryte serwery MCP, chyba że je wykluczysz. Aby wykluczyć serwer z hostowanego skilla, zdefiniuj mcp.exclude w pliku .agent.md. Aby ograniczyć serwer do konkretnych narzędzi, dodaj tablicę tools do jego wpisu w mcp.json. Używaj dokładnych nazw narzędzi publikowanych przez ten serwer. Ten wybór dotyczy definicji serwera.

W przypadku uwierzytelniania Microsoft Entra ustaw wartość auth.scope na zakres tokenu serwera. Możesz także ustawić auth.client_id, aby wybrać zarządzaną tożsamość przypisaną przez użytkownika. Wybrana tożsamość musi mieć uprawnienie do nawiązania połączenia z serwerem. Nie wkładaj sekretów do mcp.json. Szczegóły można znaleźć w sekcji konfiguracji serwera MCP.

Wykonywanie hostowane jest nieinteraktywne. Ta konfiguracja oparta na tożsamości nie wykonuje automatycznie interaktywnego przepływu użytkownika OAuth. Jeśli usługa biznesowa wymaga delegowanej autoryzacji użytkownika, rozważ obsługiwany konektor i jego połączenie zarządzane. Potwierdź, że złącze obsługuje wymagany model autoryzacji usługi. Zobacz Korzystanie z łączników platformy Azure.

Ponowne wykorzystanie instrukcji ze skills

Używaj umiejętności wielokrotnego użytku do wskazówek, których potrzebuje kilka hostowanych umiejętności, lub do materiałów referencyjnych, które nie są potrzebne przy każdym żądaniu.

Utwórz 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.

W references/report-format.md, definiuj wymagane sekcje raportu. W assets/example-report.md, podaj przykładowy raport pokazujący format.

Nazwa umiejętności musi odpowiadać katalogowi, który ją zawiera, na przykład report-writing. Runtime dostarcza nazwy i opisy umiejętności do odkrywania oraz ładuje pełne instrukcje i zasoby na żądanie. Wspomnij o zasobach pomocniczych w SKILL.md, aby umiejętność hostowana wiedziała, kiedy je przeczytać.

Trzymaj każdą umiejętność w osobnym folderze bezpośrednio pod skills/. Wytyczne dotyczące pisania znajdziesz w sekcji Umiejętności.

Pliki umiejętności nie rejestrują automatycznie narzędzi wykonywalnych. Użyj skonfigurowanego narzędzia do wykonywalnego zachowania. Nie zakładaj, że skrypt w umiejętności daje modelowi pozwolenie lub sposób na jego uruchomienie.

Dodawanie narzędzi

Po pierwsze, użyj zdalnego narzędzia MCP lub narzędzia systemu wykonawczego, jeśli spełnia ten wymóg. Dodaj niestandardowe narzędzia Python do logiki specyficznej dla aplikacji.

Narzędzia systemowe uruchomieniowe

Środowisko uruchomieniowe domyślnie włącza narzędzie systemowe web_request. Wysyła żądania wychodzące na publiczne adresy internetowe. HTTPS jest domyślnie wymagany. Aby ograniczyć żądania do dokładnej nazwy hosta, dodaj tę konfigurację do agents.config.yaml:

system_tools:
  web_request:
    allowed_hosts:
      - example.com

Ustaw system_tools.web_request: false, aby wyłączyć narzędzie w całej aplikacji lub dla jednej hostowanej umiejętności. Lista dozwolonych adresów ogranicza adresy docelowe. Nie udziela zgody na korzystanie z usługi ani przesyłanie poufnych danych.

Aby skonfigurować izolowane wykonywanie kodu w języku Python, skonfiguruj pulę interpreterów kodu języka Python Azure Container Apps dynamic sessions:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Ustaw ACA_SESSION_POOL_ENDPOINT na endpoint zarządzania pulą. Nadaj tożsamości aplikacji wymagane uprawnienia do puli przed użyciem. Informacje o ustawieniach tożsamości i wymaganiach można znaleźć w sandboxed execution.

Niestandardowe narzędzia Python

Utwórz 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"

Użyj jednego publicznego narzędzia na każdy plik .py w obszarze tools/. Runtime rejestruje pierwsze obsługiwane narzędzie zwykłe, które znajduje w każdym pliku. Używaj podpowiedzi typów i przejrzystego docstringu, aby model mógł zrozumieć cel i dane wejściowe. Dodaj wymagane pakiety do requirements.txt.

Niestandardowe narzędzie Python działa w workerze Functions Python. Nie jest to automatycznie izolowane w sandboxie. Waliduj dane wejściowe, wymuszaj uprawnienia i raportuj awarie w sposób jawny. Dla narzędzi zmieniających stan zewnętrzny zapewnij bezpieczeństwo powtarzających się wywołań, na przykład używając klucza idempotentnego.

Trwałe narzędzia do zarządzania przepływem pracy wykorzystują osobną @workflow_tool umowę. Informacje o tym modelu znajdują się w Dynamic workflows.

Zarządzanie konfiguracją

Ustawienia lokalne nie są automatycznie kopiowane do ustawień aplikacji Azure. Konfiguruj oba środowiska. Trzymaj sekrety z dala od Gita, używaj tożsamości zarządzanej tam, gdzie jest to obsługiwane, oraz odpowiedniego magazynu sekretów dla poświadczeń, które nadal są wymagane. Zobacz ustawienia lokalne i zarządzaj ustawieniami aplikacji.

Limity hostowanej umiejętności timeout i hosta Functions functionTimeout są oddzielne. Ustaw oba dla swojego obciążenia roboczego. Limit czasu hostowanej umiejętności nie nadpisuje limitów planów hostingowych ani limitów odpowiedzi HTTP. Zobacz limit czasu aplikacji funkcji.

Użyj łączników platformy Azure

Złącza Azure pozwalają hostowanym umiejętnościom wywoływać autoryzowane operacje zewnętrzne i otrzymywać zdarzenia serwisowe bez niestandardowego kodu klienta i uwierzytelniania. Ta sekcja zakłada, że zasoby konektora już istnieją.

Aby skonfigurować serwer MCP i jego połączenie, zobacz Utworzenie złącza serwera MCP.

Dla istniejącego serwera Microsoft 365 Outlook MCP dodaj wpis do mcp.json:

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

Ustaw O365_MCP_SERVER_URL na wdrożony endpoint serwera w ustawieniach lokalnych lub w ustawieniach aplikacji Azure. Przyznaj tożsamości aplikacji funkcji dostęp do tego serwera MCP. Aby wybrać zarządzaną tożsamość przypisaną przez użytkownika, dodaj auth.client_id z jej identyfikatorem klienta.

Konfiguruj obie granice autoryzacji:

Uprawnienie w jednym obszarze nie oznacza uprawnienia w drugim. Autoryzacja połączenia nie staje się automatycznie tożsamością każdego wywołującego hostowanego skilla.

Aby uruchomić hostowaną umiejętność ze zdarzenia konektora, najpierw utwórz i autoryzuj połączenie. Następnie użyj tego bloku wyzwalającego w jego pliku .agent.md:

trigger:
  type: connector_trigger

Musisz także skonfigurować zdarzenie upstream, routing callback oraz uwierzytelnianie callback w przestrzeni nazw Connector. Definicja serwera w mcp.json nie zapisuje się na zdarzenia. Aby uzyskać wymagania dotyczące rozszerzenia i konfigurację zdarzeń, zobacz Użyj zarządzanych konektorów w Azure Functions.

Uruchamianie lokalne

Użyj Azure Functions Core Tools, aby uruchomić aplikację na komputerze. Potrzebujesz też Python 3.13 lub nowszy oraz dostęp do wdrożenia modelu.

Konfigurowanie ustawień lokalnych

Utwórz local.settings.json w katalogu głównym projektu aplikacji funkcji. Dla modelu Foundry i lokalnego Azure Storage użyj tej struktury:

{
  "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>"
  }
}

Zamień symbole zastępcze punktu końcowego i modelu na wartości wdrożenia. Użyj wdrożenia modelu, które istnieje w Twoim projekcie Foundry, i przyznaj lokalnej tożsamości dewelopera dostęp do niego. Dodaj dowolne ustawienia używane przez serwery MCP, narzędzia MCP lub wyzwalacze MCP. Nie przechowuj local.settings.json w kontroli wersji.

Używaj emulatora jako źródła danych, gdy dostępny jest kompatybilny emulator. Na przykład Azurite dostarcza lokalne przechowywanie blobów, kolejek i tabel. Uruchom Azurite przed hostem Funkcji, gdy używasz UseDevelopmentStorage=true. Informacje o usłudze Service Bus: zobacz emulator Service Bus.

Przestrzenie nazw łączników, połączenia i serwery MCP łączników wymagają rzeczywistych zasobów Azure. Wykonywanie lokalne nadal wywołuje te zasoby. Wywołania modeli oraz sesje dynamiczne Azure Container Apps również korzystają z ich skonfigurowanych usług i mogą wiązać się z opłatami.

Uruchom hosta Functions

Stwórz i aktywuj wirtualne środowisko Python, jak opisano w lokalnym przewodniku programistycznym Python. W katalogu głównym projektu aplikacji funkcji zainstaluj pakiety z requirements.txt:

python -m pip install -r requirements.txt

W przypadku Foundry z dostępem opartym na tożsamości zaloguj się za pomocą tożsamości posiadającej uprawnienia do korzystania z modelu:

az login

Rozpocznij hosta z tego samego katalogu:

func start

Host wymienia summarize funkcję oraz wbudowane punkty końcowe włączone w tym przykładzie. Z domyślnym api prefiksem trasy i portem 7071, wyjście jest podobne do:

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

Utrzymuj host włączony podczas testowania. Odczytaj wyjście terminala pod kątem błędów konfiguracji oraz zarejestrowanych adresów URL funkcji. Aby uzyskać więcej informacji, zobacz Uruchamianie funkcji lokalnej.

Test z użyciem okna czatu

Przykład już summarize.agent.md umożliwia wbudowane okno czatu i powiązane interfejsy API czatu.

Otwórz http://localhost:7071/api/agents/summarize/ w przeglądarce, gdy host.json używa domyślnego prefiksu trasy api. Jeśli Twój projekt startowy ustawia extensions.http.routePrefix na pusty ciąg znaków, użyj http://localhost:7071/agents/summarize/ zamiast tego. Użyj faktycznego portu hosta, jeśli różni się od 7071.

Wprowadź przykładowe żądanie, wyślij je i sprawdź odpowiedź oraz log hosta. Na przykład poproś hostowaną umiejętność o podsumowanie żądania z brakującą datą dostawy. Sprawdź, czy odpowiedź wskazuje, że brakuje daty, a nie ją wymyśla. Testuj też brak danych wejściowych i awarie narzędzi.

Wykonanie narzędzia Local Core Tools zazwyczaj pomija sprawdzanie klawiszy funkcyjnych. Zachowaj http_auth: function w definicji i testuj uwierzytelnianie osobno w Azure. W przypadku wdrożonego okna czatu podaj klucz funkcji, gdy pojawi się pytanie. Włączaj punkty końcowe debugowania tylko tam, gdzie jest to konieczne. O trasach i pobieraniu kluczy zobacz wbudowane endpointy.

Wdrażanie na platformie Azure

Wybierz metodę wdrożenia dla swojego projektu:

Po wdrożeniu poupewnij się, że ustawienia aplikacji Azure zawierają wymagane wartości, tożsamość aplikacji ma dostęp do modelu i narzędzi, a każde połączenie konektora jest autoryzowane. Przetestowaj wdrożony wyzwalacz i jego uwierzytelnienie za pomocą kontrolowanego żądania, zanim użyjesz danych produkcyjnych.

Poznaj kompleksowe przykłady

Wykorzystaj te przykłady, aby zobaczyć, jak hostowane funkcje łączą wyzwalacze, narzędzia i usługi Azure w kompletnej aplikacji. Każde repozytorium zawiera instrukcje dotyczące konfiguracji i wdrożenia.

Treści powiązane

• Przegląd umiejętności hostowanych w Azure Functions
• Referencyjna konfiguracja umiejętności hostowanych
• Buduj i testuj na hostowanej kanwie umiejętności
• Wdrażanie hostowanej aplikacji umiejętności opartej na zdarzeniach
• Buduj dynamiczne przepływy pracy
• Wskazówki dotyczące obserwowalności środowiska uruchomieniowego
• Przykłady hostowanych umiejętności