Samouczek: zbuduj aplikację internetową opartą na agencie w Azure App Service przy użyciu LangGraph lub Foundry Agent Service (Python)

W tym samouczku pokazano, jak dodać funkcję agenta do istniejącej aplikacji FASTAPI CRUD opartej na danych. Robi to przy użyciu dwóch różnych podejść: LangGraph i Foundry Agent Service.

Jeśli aplikacja internetowa ma już przydatne funkcje, takie jak zakupy, rezerwacja hotelowa lub zarządzanie danymi, stosunkowo proste jest dodanie funkcji agenta do aplikacji internetowej przez opakowywanie tych funkcji w wtyczki (dla LangGraph) lub jako punkt końcowy OpenAPI (dla usługi Agenta Foundry). W tym samouczku zaczniesz od prostej aplikacji z listą zadań. Na koniec będziesz mieć możliwość tworzenia, aktualizowania i zarządzania zadaniami za pomocą agenta w aplikacji usługi App Service.

Zarówno LangGraph, jak i Foundry Agent Service umożliwiają tworzenie agentowych aplikacji internetowych z wykorzystaniem funkcji opartych na sztucznej inteligencji. LangGraph jest podobny do Microsoft Agent Framework i jest SDK. W poniższej tabeli przedstawiono niektóre zagadnienia i kompromisy:

W tym poradniku nauczysz się, jak:

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją — utwórz bezpłatne konto.
• Konto usługi GitHub do korzystania z usługi GitHub Codespaces — dowiedz się więcej o usłudze GitHub Codespaces.

Otwieranie przykładu za pomocą usługi Codespaces

Najprostszym sposobem rozpoczęcia pracy jest użycie usługi GitHub Codespaces, która udostępnia kompletne środowisko programistyczne ze wszystkimi wymaganymi wstępnie zainstalowanymi narzędziami.

1. Przejdź do repozytorium GitHub pod adresem https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.

2. Wybierz przycisk Kod , wybierz kartę Codespaces i wybierz pozycję Utwórz przestrzeń kodu w obszarze głównym.

3. Zaczekaj chwilę na zainicjowanie usługi Codespace. Gdy wszystko będzie gotowe, zobaczysz w przeglądarce w pełni skonfigurowane środowisko programistyczne.

4. Uruchom aplikację lokalnie:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

5. Gdy zobaczysz, że aplikacja uruchomiona na porcie 3000 jest dostępna, wybierz pozycję Otwórz w przeglądarce i dodaj kilka zadań.

   Agenci nie są w pełni skonfigurowani, więc jeszcze nie działają. Skonfigurujesz je później.

Przejrzyj kod agenta

Oba podejścia używają tego samego wzorca implementacji, w którym agent jest inicjowany podczas uruchamiania aplikacji i odpowiada na komunikaty użytkowników według żądań POST.

self.memory = InMemorySaver()
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation thread per worker process.
self.thread_id = "authenticated-conversation"

try:
    endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    deployment_name = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME")
    
    if not endpoint or not deployment_name:
        print("Azure OpenAI configuration missing for LangGraph agent")
        return
    
    # Initialize Azure OpenAI client
    credential = DefaultAzureCredential()
    azure_ad_token_provider = get_bearer_token_provider(
        credential, "https://cognitiveservices.azure.com/.default"
    )
    
    self.llm = AzureChatOpenAI(
        azure_endpoint=endpoint,
        azure_deployment=deployment_name,
        azure_ad_token_provider=azure_ad_token_provider,
        api_version="2024-10-21"
    )
    
    # Define tools
    tools = [
        self._create_task_tool(),
        self._get_tasks_tool(),
        self._get_task_tool(),
        self._update_task_tool(),
        self._delete_task_tool()
    ]
    
    # Create the agent
    self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)

config = {"configurable": {"thread_id": self.thread_id}}

# Process the message
result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Get the OpenAI client for conversation operations
self.openai_client = self.project_client.get_openai_client()

# Find the existing agent by name
self.agent = self.project_client.agents.get(agent_name)

if not self.agent:
    print(f"Agent with name '{agent_name}' not found in project.")
    return
            
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation per worker process.
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

# Add user message to the conversation
await asyncio.to_thread(
    self.openai_client.conversations.items.create,
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

# Create response using the agent
response = await asyncio.to_thread(
    self.openai_client.responses.create,
    conversation=self.conversation_id,
    extra_body={"agent": {"name": self.agent.name, "type": "agent_reference"}},
    input="",
)

Wdrażanie przykładowej aplikacji

Przykładowe repozytorium zawiera szablon Azure Developer CLI (AZD), który tworzy aplikację App Service i wdraża Twoją przykładową aplikację. Tożsamość zarządzana przypisana przez system usługi App Service jest zachowana na potrzeby wychodzących wywołań do usługi Azure AI. Oddzielna zarządzana tożsamość przypisana przez użytkownika oraz federacja tożsamości pozwalały uwierzytelniać App Service jako wygenerowana aplikacja Microsoft Entra bez tajemnicy klienta.

1. W terminalu zaloguj się do Azure, używając Azure Developer CLI:

   azd auth login
   

   Postępuj zgodnie z instrukcjami, aby ukończyć proces uwierzytelniania.

2. Wdrożenie aplikacji Azure App Service za pomocą szablonu AZD:

   azd up
   

3. Po wyświetleniu monitu podaj następujące odpowiedzi:

   Question	Odpowiedź
   Wprowadź nową nazwę środowiska:	Wpisz unikatową nazwę.
   Wybierz subskrypcję platformy Azure do użycia:	Wybierz subskrypcję.
   Wybierz grupę zasobów do użycia:	Wybierz pozycję Utwórz nową grupę zasobów.
   Wybierz lokalizację, w ramach których chcesz utworzyć grupę zasobów:	Wybierz pozycję Szwecja Środkowa.
   Wprowadź nazwę nowej grupy zasobów:	Wpisz Enter.

4. W danych wyjściowych usługi AZD znajdź adres URL aplikacji i przejdź do niej w przeglądarce. Skopiuj też wartość „audience” tożsamości zarządzanej Foundry OpenAPI do późniejszego użycia. Dane wyjściowe wyglądają następująco:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
   
    Foundry OpenAPI managed identity audience:
        api://<generated-client-id>
    

5. Gdy Microsoft cię o to poprosi, zaloguj się, używając konta w tenantzie wdrożenia i sprawdź, czy lista zadań się ładuje.

6. W tej samej uwierzytelnionej przeglądarce dodaj /openapi.json na końcu punktu końcowego usługi App Service. Skopiuj lub zapisz wygenerowany schemat OpenAPI na później.

   Uwaga / Notatka

   Uwierzytelnianie usługi App Service zwraca przekierowanie HTTP 302 dla nieuwierzytelnionych żądań z przeglądarki. Ten przykład zawiera zarówno interfejs przeglądarki, jak i API, dzięki czemu przekierowanie zapewnia użyteczne doświadczenie logowania. Aplikacje oparte wyłącznie na API często korzystają z HTTP 401.

Tworzenie i konfigurowanie zasobu rozwiązania Microsoft Foundry

Przypisywanie wymaganych uprawnień

Konfigurowanie zmiennych połączenia w przykładowej aplikacji

1. Otwórz plik env. Korzystając z wartości skopiowanych wcześniej z portalu Foundry, skonfiguruj następujące zmienne:

   • LangGraph
   • Usługa agenta programu Foundry

   Variable	Description
   AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint (skopiowany ze strony głównej portalu Foundry).
   AZURE_OPENAI_DEPLOYMENT_NAME	Nazwa modelu we wdrożeniu (skopiowana z obszaru roboczego modelu w nowym portalu Foundry).

   Uwaga / Notatka

   Aby zachować prostotę samouczka, użyjesz tych zmiennych w pliku env zamiast zastępowania ich ustawieniami aplikacji w usłudze App Service.

   Uwaga / Notatka

   Aby zachować prostotę samouczka, użyjesz tych zmiennych w pliku env zamiast zastępowania ich ustawieniami aplikacji w usłudze App Service.

   Wartości w .env konfigurują połączenie wychodzące aplikacji z Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID konfiguruje oddzielne przychodzące połączenie OpenAPI z Foundry do App Service i jest przechowywane w środowisku AZD.

2. Zaloguj się do platformy Azure przy użyciu interfejsu wiersza polecenia platformy Azure:

   az login
   

   Dzięki temu biblioteka klienta tożsamości platformy Azure w przykładowym kodzie może odbierać token uwierzytelniania dla zalogowanego użytkownika. Pamiętaj, że wcześniej dodano wymaganą rolę dla tego użytkownika.

3. Uruchom aplikację lokalnie:

   source venv/bin/activate
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

4. Gdy zobaczysz, że aplikacja uruchomiona na porcie 3000 jest dostępna, wybierz pozycję Otwórz w przeglądarce.

5. Walidacja obu pivotów osobno:

   • LangGraph: Wybierz Agenta LangGraph i poproś agenta o utworzenie zadania. LangGraph wywołuje narzędzie zadań działające w tym samym procesie.
   • Usługa agenta Foundry: Wybierz Foundry Agent i poproś agenta o utworzenie zadania. Zdalny agent Foundry wywołuje wdrożony, chroniony /api/tasks punkt końcowy przy użyciu tożsamości zarządzanej.

   Zadanie tworzone przez agenta Foundry pojawia się w wdrożonej instancji App Service, a nie w lokalnej bazie danych SQLite. Narzędzie Foundry OpenAPI zawsze korzysta z adresu URL serwera osadzonego w schemacie OpenAPI.

6. W usłudze GitHub codespace wdróż zmiany aplikacji.

   azd up
   

7. Przejdź ponownie do wdrożonej aplikacji i przetestuj obu agentów czatu. Przeglądarka wysyła jedynie tekst wiadomości; nie wysyła identyfikatora sesji ani identyfikatora rozmowy dla żadnego z agentów.

Często zadawane pytania

• Jak dodać generowanie wspomagane wyszukiwaniem (RAG) do agenta Foundry?

Jak dodać generowanie wspomagane wyszukiwaniem (RAG) w agencie Foundry?

Te wskazówki dotyczą ścieżki Foundry Agent Service w tym samouczku. Nie zmienia to implementacji LangGraph, Semantic Kernel ani Microsoft Agent Framework pokazanych w drugiej karcie.

Stwórz lub wybierz bazę wiedzy Foundry IQ, a następnie połącz tę bazę z agentem Foundry Agent Service. Połączenie jest udostępniane agentowi jako zarządzane narzędzie wiedzy MCP.

Kod usługi App Service nadal wywołuje tego samego agenta po nazwie za pośrednictwem istniejącego klienta Foundry oraz agent_reference. Aplikacja webowa nie potrzebuje bezpośredniej integracji z Wyszukiwanie AI platformy Azure ani własnego klienta MCP. Jeśli interfejs wyświetla źródła, przetworz adnotacje cytowań zwrócone przez agenta.

Uprzątnij zasoby

Po zakończeniu pracy z aplikacją możesz usunąć zasoby usługi App Service, aby uniknąć ponoszenia dodatkowych kosztów:

azd down --purge

Hak AZD postdown usuwa także aplikację Microsoft Entra na poziomie dzierżawcy stworzoną do uwierzytelniania App Service.

Następnie usuń zasób Foundry, jeśli utworzyłeś go osobno.

Więcej zasobów

• Integrowanie sztucznej inteligencji z aplikacjami usługi Azure App Service
• Co to jest usługa agenta programu Foundry?
• LangGraph — Szybki start
• Biblioteka klienta usługi Azure AI Projects dla języka Python