Powiązania agenta dla języka Python w usłudze Azure Functions

Powiązania agentów dla aplikacji funkcyjnych w Python pozwalają dodawać zachowania agenticzne do istniejących funkcji. Gdy funkcja się uruchamia, rozszerzenie konstruuje agenta lub sesję specyficzną dla SDK z instrukcji Markdown i wstrzykuje ją do handlera jako parametr określonego typu. Twój kod decyduje, kiedy i jak wywołać agenta, wraz z deterministyczną logiką aplikacji.

Ważna

Powiązania agentów dla aplikacji funkcji w języku Python są obecnie dostępne w wersji zapoznawczej. Funkcje, nazwy pakietów i konfiguracja mogą się zmieniać przed ogólną dostępnością.

Aby porównać powiązania agentów z innymi funkcjami związanymi z AI, takimi jak umiejętności hostowane w Azure Functions oraz narzędzia Model Context Protocol (MCP), zobacz opcje integracji AI dla Azure Functions.

Czym jest powiązanie agenta?

Wiązanie agenta to wiązanie wejściowe, które udostępnia skonfigurowanego agenta lub sesję jako parametr typowany funkcji Python. Rozszerzenie łączy instrukcje Markdown z konfiguracją i narzędziami dostawcy aplikacji, dzięki czemu Twój handler nie musi budować i konfigurować agenta dla każdego wywołania.

Powiązanie nie zastępuje twojej funkcji ani jej trigera. Twój kod nadal waliduje wejścia, decyduje, kiedy wywołać agenta, obsługuje błędy i generuje wyjście. Instrukcje znajdują się w pliku .agent.md , natomiast konfiguracja klienta, modelu i narzędzia pozostaje w kodzie aplikacji i ustawieniach. Pakiety dostawców łączą ten model współdzielonego wiązania z różnymi SDK agentów.

Kiedy używać wiązań agentowych

Używaj wiązań agentów, gdy funkcja Azure potrzebuje rozumowania agentycznego dla części workflow, ale aplikacja musi zachować kontrolę nad wyzwalaczem, walidacją, rozgałęzieniem, obsługą błędów i odpowiedzią. Typowe scenariusze obejmują:

  • Oceń żądanie HTTP. Zweryfikować zamówienie za pomocą kodu deterministycznego, poproś agenta o ocenę ryzyka realizacji i wykorzystać wynik do skonstruowania odpowiedzi HTTP.
  • Wzbogacaj lub klasyfikuj wydarzenia. Odbierz komunikat kolejki, zdarzenie usługi Event Grid lub inne dane wejściowe wyzwalacza i użyj agenta, aby sklasyfikować, podsumować lub wzbogacić dane, zanim funkcja zapisze wynik.
  • Dodaj mechanizm wnioskowania do trwałego przepływu pracy. Wywołaj agenta z programu orchestratora Durable Functions za pośrednictwem interfejsu API context.call_agent(), który jest bezpieczny przy odtwarzaniu, a następnie użyj wyniku w kolejnych etapach orkiestracji.

Funkcja pozostaje koordynatorem: przygotowuje zadanie, wywołuje agenta i decyduje, co zrobić z wynikiem. Bindingi redukują kod inicjalizacyjny, oddzielają instrukcje Markdown od konfiguracji w czasie działania i działają z dobrze znanymi wyzwalaczami Azure Functions oraz lokalnymi narzędziami do debugowania.

Jeśli wolisz definiować zachowanie i wyzwalacze głównie przez Markdown i konfigurację deklaratywną zamiast za pomocą procedury obsługi w Pythonie, rozważ umiejętności hostowane w Azure Functions.

Dostępne pakiety

Pakiety rozszerzeń specyficzne dla dostawcy łączą wspólny model powiązań z SDK agenta. Następujące pakiety są dostępne w wersji podglądowej i wymagają Python 3.13 lub nowszy:

SDK Package Wprowadzenie
Microsoft — Struktura agentów azurefunctions-agents-extensions-agent-framework Przewodnik Szybki start dotyczący funkcji w języku Python · Przewodnik Szybki start dotyczący trwałej aranżacji
GitHub Copilot SDK azurefunctions-agents-extensions-copilot-sdk Szybki start funkcji Python · HTTP i próbka kolejki · Przykład trwałej orkiestracji

Każdy pakiet definiuje obsługiwane typy, uwierzytelnianie, konfigurację modelu oraz API wywołań. Skorzystaj z przewodnika Szybki start lub przykładu, aby poznać wymagania dotyczące konfiguracji i wdrożenia specyficzne dla SDK.

Jak działa wiązanie agentowe

AgentFunctionApp dziedziczy po azure.functions.FunctionApp, więc ma takie same możliwości jak FunctionApp. Dekorator markdown_agent dodaje do funkcji parametr wejściowy agenta.

Dla każdego powiązania agentów rozszerzenie wykonuje następujące operacje:

  1. Rozwiązuje żądany .agent.md plik z root aplikacji function lub jej agents/ katalogu.
  2. Ładuje cały plik jako surowe instrukcje UTF-8.
  3. Łączy instrukcje z konfiguracją dostawcy, narzędziami explicitnymi oraz umiejętnościami odkrytych agentów i serwerami MCP.
  4. Tworzy świeżego agenta lub sesję specyficzną dla SDK i otwiera zasoby należące do wywołania.
  5. Wprowadza agenta lub sesję do parametru handlera.
  6. Zamyka zasoby przypisane do wywołania po zakończeniu wykonywania.

Dostawca zarządza własnym cyklem życia klienta. Zasoby należące do wywołania są zamykane po sukcesie, porażce lub anulacji.

Zdefiniuj powiązanie agenta

Aby dodać powiązanie do aplikacji funkcji w Python v2:

  1. Zainstaluj pakiet dostawcy i zaimportuj jego AgentFunctionApp.
  2. Konfiguruj klienta, model, uwierzytelnianie i narzędzia zgodnie z wymaganiami tego pakietu.
  3. Dodaj .agent.md plik instrukcji w katalogu głównym aplikacji lub w katalogu agents/. Plik to surowy tekst UTF-8; system nie analizuje sekcji nagłówkowej YAML ani konfiguracji uruchomieniowej.
  4. Dodaj markdown_agent do funkcji wyzwalanej. Ustaw arg_name tak, aby odpowiadała parametrowi procedury obsługi o określonym typie, a agent_name identyfikowała plik instrukcji.
  5. Wywołaj wstrzyknięty obiekt przez jego API SDK i obsłuż wynik w kodzie funkcji.

Na przykład można za pomocą agent_name="order-fulfillment" identyfikować element order-fulfillment.agent.md w jednym z obsługiwanych katalogów, ale nie w obu. Nazwy muszą jednoznacznie wskazywać lokalizację w katalogu głównym aplikacji i nie mogą zawierać separatorów ścieżek ani sekwencji przejścia katalogów. Aby wstrzyknąć wielu agentów, nakładaj dekoratory jeden na drugim z różnymi wartościami arg_name i dopasowanymi parametrami procedury obsługi.

Pełne przykłady kodu można znaleźć w pakietach szybkiego startu i przykładach.

Współdzielone umiejętności agenta i serwery MCP

Rozszerzenie automatycznie wykrywa możliwości współdzielonego agenta z rootu aplikacji:

Zdolność Lokalizacja Behavior
Umiejętności agenta skills/<skill-name>/SKILL.md lub Skills/<skill-name>/SKILL.md Pakiet dostawcy ładuje i weryfikuje umiejętność agenta opartą na plikach.
Zdalne serwery MCP mcp.json Rozszerzenie konfiguruje obsługiwane serwery HTTP lub serwery HTTP obsługujące strumieniowanie oraz opcjonalne listy dozwolonych narzędzi.
Narzędzia dostawców Konfiguracja aplikacji lub wiązania Narzędzia specyficzne dla SDK lub wywołania Python obsługiwane przez dostawcę są udostępniane jawnie zamiast być odkrywane.

Pamiętaj o tych kwestiach, korzystając z funkcji współdzielonego agenta:

  • Każde powiązanie agenta w aplikacji funkcyjnej otrzymuje wszystkie odkryte umiejętności agenta oraz serwery MCP.
  • Umiejętności agenta opartego na plikach to zdolności, które agent może załadować. To nie są umiejętności hostowane w Azure Functions, które korzystają z osobnego modelu wykonywania.
  • Obecna wersja zapoznawcza rozszerzenia agenta nie obsługuje wybierania podzbioru możliwości dla aplikacji lub pojedynczego powiązania.
  • Umiejętności agenta i narzędzia MCP mogą wykonywać operacje uprzywilejowane. Umieszczaj tylko funkcje, które każdy agent w aplikacji może używać, a osobne aplikacje funkcyjne używaj, gdy agenci wymagają różnych granic możliwości.

Konfiguracja MCP może odwoływać się do zmiennych środowiskowych dla adresów URL, nagłówków, zakresów uwierzytelniania i identyfikatorów klientów. Referencje są ustalane dla każdego wywołania, zanim rozszerzenie połączy się z serwerem. Nie przechowuj poufnych danych bezpośrednio w pliku mcp.json znajdującym się pod kontrolą wersji.

Serwery MCP z procesem lokalnym oraz standardowym wejściem/wyjściem (stdio) nie są obsługiwane. Wsparcie dla MCP jest opcjonalną zależnością, a normalne importy pakietów pozostają bezpieczne, gdy nie są zainstalowane.

Używaj wiązań agentów z Durable Functions

Gdy instalujesz opcjonalną integrację Durable Functions dostawcy, synchroniczny generator koordynatora zwraca context.call_agent(agent_name, input_). Rozszerzenie wykonuje pracę agenta w ukrytej aktywności, zachowując wywołania modelu, narzędzia i inne niedeterministyczne operacje poza odtwarzaniem orchestratora.

Wejścia i wyjścia muszą być serializowane przez JSON. Połączenia wykorzystują dostawcę i współdzielone możliwości skonfigurowane przez aplikację. Zobacz przewodniki szybkiego startu pakietu oraz przykłady kodu instalacji i orkiestracji.

pliki projektu

Aplikacja z agentem to standardowa aplikacja funkcjonalna Python v2 z zależnościami rozszerzenia agenta oraz jednym lub więcej plikami instrukcji:

Plik lub folder Purpose
function_app.py Definiuje AgentFunctionApp, standardowe wyzwalacze Funkcji, powiązania agentów, fabryki klientów oraz wyraźnie skonfigurowane narzędzia dostawców.
host.json Konfiguruje hosta Azure Functions.
requirements.txt Zawiera pakiet dostawcy oraz wymagane zależności. Opcjonalne dodatki mogą umożliwić wsparcie Durable Functions i MCP.
*.agent.md lub agents/*.agent.md Zawiera surowe instrukcje UTF-8 dla agenta. Każda nazwa, do której istnieje odwołanie, musi wskazywać dokładnie jeden plik.
skills/ lub Skills/ (Opcjonalne) Zawiera umiejętności agenta oparte na plikach, współdzielone przez wszystkie powiązania agentów.
mcp.json (Opcjonalnie) Definiuje zdalne serwery MCP oparte na HTTP współdzielone przez wszystkie powiązania agentów.

Standardową strukturę projektu Python można znaleźć w Azure Functions Python przewodniku dla deweloperów.

Walidacja i diagnostyka

Rozszerzenie sprawdza poprawność definicji agentów przed kompilacją powiązań lub w jej trakcie, dzięki czemu problemy z konfiguracją są zgłaszane w postaci błędów zawierających wskazówki do działania. Walidacja obejmuje:

  • Brakujące .agent.md lub niejednoznaczne pliki.
  • Nieprawidłowe sygnatury handlera, w tym brakujący lub niedopasowany parametr wstrzykiwany.
  • Nieobsługiwane opcje lub możliwości dostawcy.
  • Nieprawidłowe katalogi umiejętności i zdeformowana konfiguracja MCP.
  • Nieobsługiwane metody transportu MCP i brakujące wartości zmiennych środowiskowych.
  • Nieprawidłowe trwałe ładunki danych lub wartości, których nie można serializować do formatu JSON.

Tam, gdzie jest dostępne, rozszerzenie zachowuje nazwę funkcji Azure, identyfikator wywołania oraz trwały identyfikator instancji na granicy dostawcy, aby wspierać korelację i diagnostykę.

  • Ostatnia aktualizacja o