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. Po uruchomieniu funkcji rozszerzenie tworzy element Agent na podstawie instrukcji w języku Markdown i wstrzykuje go do procedury obsługi jako parametr o określonym typie. Twój kod decyduje, kiedy i jak wywołać agenta, wraz z deterministyczną logiką aplikacji.

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.

Wiązanie agenta to powiązanie wejściowe należące do rozszerzenia, które zapewnia w pełni skonstruowany Agent obiekt dla funkcji Python. Rozszerzenie odczytuje instrukcje agenta jako surowy tekst z pliku .agent.md . Kod aplikacji zachowuje specyficzną konfigurację narzędzi dla klienta i dostawcy, podczas gdy projekt aplikacji funkcjonalnej może odkrywać umiejętności agentów opartych na plikach oraz zdalne serwery MCP.

Architektura wiązania agentów obsługuje obiekty agentów z różnych SDK poprzez specyficzne dla dostawcy pakiety rozszerzeniowe. Microsoft Agent Framework jest jedynym zestawem SDK agenta obsługiwanym w bieżącej wersji zapoznawczej. Aby go używać, zainstaluj azurefunctions-agents-extensions-agent-framework pakiet.

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.

Wiązania agentów dobrze pasują, gdy deterministyczny kod funkcji powinien pozostać koordynatorem. Agent wykonuje zadanie rozumowania ograniczonego i oddaje kontrolę obsłudcy lub orkiestracji.

Dlaczego warto używać powiązań z agentami?

Wiele procesów produkcyjnych łączy kroki, które muszą być deterministyczne, z krokami korzystającymi z rozumowania modelowego. Powiązania agentów zapewniają następujące korzyści dla tych hybrydowych przepływów pracy:

• Dodaj zachowanie agentowe do istniejących funkcji. Używaj rozumowania agentów z HTTP, timer-, queue-, Event Grid-, Service Bus- oraz innych wyzwalanych funkcji.
• Wywołanie agenta sterowania bezpiecznie w kodzie. Zdecyduj, kiedy wywołać agenta, sprawdź jego odpowiedź i określ wyjście funkcji. Rozszerzenie zamyka zasoby będące własnością wywołania po pomyślnym zakończeniu, niepowodzeniu lub anulowaniu.
• Ogranicz kod konfiguracyjny agenta. Otrzymuj skonfigurowany obiekt Agent jako parametr procedury obsługi typizowanej, zamiast konstruować go i konfigurować połączenia przy każdym wywołaniu.
• Oddziel instrukcje od konfiguracji w czasie działania. Przechowuj instrukcje w języku naturalnym w pliku .agent.md i jawnie konfiguruj klientów oraz narzędzia specyficzne dla dostawcy w Pythonie.
• Korzystaj z możliwości udostępnionego agenta. Rozszerzenie wykrywa umiejętności agentów opartych na plikach oraz serwery MCP oparte na HTTP z root aplikacji i udostępnia je dla każdego powiązania agenta.
• Wywoływanie agentów w trwałych orkiestracjach. Rozszerzenie wykonuje zadania agenta w ukrytej aktywności, dzięki czemu ponowne odtwarzanie orkiestracji pozostaje deterministyczne.
• Debuguj lokalnie za pomocą znanych narzędzi. Uruchamiaj i debuguj aplikację lokalnie jak każdą inną aplikację z funkcjami Python. Możesz ustawić punkty przerwania i przejść przez logikę deterministycznej funkcji oraz kod wywołujący agenta.

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 ze skonfigurowaną fabryką klienta, jawnie skonfigurowanymi narzędziami dostawcy oraz wykrytymi umiejętnościami agentów i serwerami MCP.
4. Tworzy nowe Agent i otwiera zasoby należące do wywołania.
5. Wstrzykuje parametr Agent do handlera.
6. Zamyka zasoby przypisane do wywołania po zakończeniu wykonywania.

Rozszerzenie może buforować wykrywanie dostawców oraz skompilowane definicje wiązań. Nie buforuje ani nie wykorzystuje zasobów aktywnych wywołań między funkcjami.

Zdefiniuj powiązanie agenta

Poniższy przykład używa obecnie obsługiwanego dostawcy Microsoft Agent Framework do dodania elementu Agent do funkcji wyzwalanej żądaniem HTTP. Funkcja konstruuje zadanie w kodzie, wywołuje agenta i zwraca odpowiedź agenta:

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)

Wartość arg_name musi odpowiadać parametrowi wtryskiwanego handlera. Aby wstrzyknąć wiele agentów do tej samej funkcji, nałóż dekoratory markdown_agent jeden na drugi i użyj unikalnego arg_name oraz parametru programu obsługi dla każdego powiązania z agentem. agent_name Wartość ta identyfikuje plik z instrukcjami. W tym przykładzie element order-fulfillment musi wskazywać dokładnie jedną z tych lokalizacji:

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

Jeśli oba pliki istnieją, definicja jest niejednoznaczna i uruchamianie aplikacji się nie udaje. Nazwy agentów nie mogą zawierać ścieżek absolutnych, separatorów ścieżek ani komponentów przechodzenia. Pliki, które rozwiązują się poza root aplikacji, nie są dozwolone.

Konfiguruj klienta i narzędzia agenta

Skonfiguruj konstruktor bezargumentowy client_factory podczas tworzenia obiektu AgentFunctionApp. Fabryka zwraca świeżego klienta wspieranego przez pakiet dostawcy. Możesz też przekazywać obiekty narzędzi Microsoft Agent Framework lub obiekty wywoływalne Pythona za pomocą parametru tools na poziomie aplikacji. Powiązanie może zastąpić fabrykę klienta i narzędzia na poziomie aplikacji, jeśli wymaga innego działania.

Na przykład następująca funkcja wyzwalana przez protokół HTTP używa powiązania agenta, które udostępnia lookup_inventory jako narzędzie tylko dla order_agent:

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)

Weź na uwadze następujące kwestie podczas konfiguracji klienta i narzędzi agenta:

• Rozszerzenie agenta bazowego jest neutralne względem dostawcy. Pakiet dostawcy integruje konkretne SDK agenta i definiuje obsługiwane typy klienta i agenta.
• Obecnie wspierany pakiet dostawców Microsoft Agent Framework nie wybiera ani nie konfiguruje dostawcy modelu dla Twojej aplikacji. Fabryka klienta określa, którego obsługiwanego klienta czatu i którego modelu platformy Microsoft Agent Framework używa agent.
• Rozszerzenie przekazuje cały .agent.md plik skonfigurowanemu dostawcy jako instrukcje agenta. Nie parsuje z pliku ustawień modelu, narzędzi, nagłówka YAML ani innej konfiguracji środowiska uruchomieniowego.

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

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

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

Powiązania agentów wspierają hybrydowe, długotrwałe procesy dzięki opcjonalnej integracji z Durable Functions. Orkiestrator synchronicznego generatora wywołuje context.call_agent() i zwraca wynikowe zadanie:

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() zaplanowuje ukrytą aktywność, która rozwiązuje definicję agenta i wykonuje wszystkie operacje modelowania, systemu plików, poświadczeń uwierzytelniających, narzędzi i sieci. Orkiestrator tworzy jedynie deterministyczne żądanie schema-v1 serializowalne do formatu JSON. W rezultacie ponowne odtwarzanie orkiestracji nie powoduje ponownego wykonywania niedeterministycznych operacji wykonywanych przez agentów.

Trwałe wywołania agentów wykorzystują dostawcę i współdzielone możliwości skonfigurowane przez AgentFunctionApp. Wejścia i wyjścia muszą być serializowane przez JSON.

Wsparcie Durable Functions jest opcjonalne. Aplikacje, które go nie używają, nie muszą instalować ani importować Durable Functions. Aby użyć orchestration_trigger i context.call_agent(), zainstaluj pakiet wspieranego dostawcy z dodatkiem Durable dependency extra.

pliki projektu

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

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

Artykuły pokrewne

• Opcje integracji AI dla Azure Functions
• Użyj agenta Microsoft Agent Framework w funkcji Python
• Użyj powiązania agenta platformy Microsoft Agent Framework w orkiestracji Durable
• Omówienie programu Microsoft Agent Framework