Hostuj agentów LangGraph jako agentów hostowanych w usłudze Foundry

Użyj pakietu langchain_azure_ai.agents.hosting, aby udostępnić skompilowany graf LangGraph za pośrednictwem protokołów używanych przez hostowanych agentów Microsoft Foundry . Pakiet hostingowy umożliwia zachowanie logiki agenta LangChain i LangGraph w kodzie, podczas gdy narzędzie Foundry zarządza hostowanym środowiskiem uruchomieniowym, sesjami, skalowaniem, tożsamością i punktami końcowymi protokołu.

W tym artykule utworzysz minimalnego agenta LangGraph, uwidaczniasz go za pośrednictwem protokołu Responses lub Invocations, przetestujesz go za pośrednictwem protokołu HTTP i wdrożysz go w rozwiązaniu Foundry za pomocą interfejsu wiersza polecenia dewelopera Azure lub rozszerzenia Visual Studio Code zestawu narzędzi Foundry Toolkit.

Dowiesz się również, jak migrować istniejący projekt LangGraph bez zmiany jego kodu lub konfiguracji.

Wymagania wstępne

Subskrypcja platformy Azure. Utwórz je bezpłatnie.
Projekt Foundry.
Wdrożony model czatu, taki jak gpt-4.1 lub gpt-5-mini.
Python 3.10 lub nowszy.
Azure CLI jest zalogowane (az login), więc DefaultAzureCredential może się uwierzytelnić.

Instalowanie pakietu

Zainstaluj langchain-azure-ai wersję 1.2.9 lub nowszą z dodatkowym hostingiem:

pip install -U "langchain-azure-ai[hosting]>=1.2.9" azure-identity

Dodatek hosting instaluje biblioteki protokołu Foundry używane przez serwery hosta:

azure-ai-agentserver-responses dla zgodnego z OpenAI punktu końcowego /responses.
azure-ai-agentserver-invocations dla ogólnego /invocations punktu końcowego.

Wybieranie protokołu hostingu

Hostowani agenci mogą uwidaczniać jeden lub więcej protokołów. Zacznij od Responses w przypadku większości agentów konwersacyjnych.

Protokół	Klasa hosta	Punkt końcowy	Użyj, gdy
Responses	`ResponsesHostServer`	`/responses`	Chcesz czatu kompatybilnego z OpenAI, strumieniowania, historii odpowiedzi i wątkowania rozmów.
Wywołania	`InvocationsHostServer`	`/invocations`	Potrzebujesz niestandardowej struktury JSON, punktu końcowego typu webhook lub przetwarzania niezwiązanego z konwersacją.

Aby zapoznać się z zachowaniem protokołu i sesjami, zobacz Hostowani agenci i Zarządzanie sesjami hostowanych agentów.

Konfigurowanie zmiennych środowiskowych

Ustaw nazwę punktu końcowego projektu i wdrożenia modelu na potrzeby programowania lokalnego:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="gpt-4.1"

Gdy ten sam kod jest uruchamiany jako hostowany agent w narzędziu Foundry, platforma wprowadza element FOUNDRY_PROJECT_ENDPOINT. Jeśli używasz azd ai agent init z przykładem azure.yaml, wygenerowany projekt również używa FOUNDRY_MODEL_NAME dla wybranego wdrożenia modelu.

Protokół odpowiedzi

Użyj protokołu Responses, jeśli potrzebujesz punktu końcowego czatu zgodnego z OpenAI z obsługą strumieniowania, historią odpowiedzi i wątkowaniem rozmów.

Tworzenie hosta odpowiedzi

Utwórz plik o nazwie main.py z minimalnym agentem LangGraph, który używa modelu Foundry. Ten wzorzec jest zgodny z podstawowym przykładem Odpowiedzi w repozytorium źródłowym langchain-azure-ai .

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

from langchain_azure_ai.agents.hosting import ResponsesHostServer

_AZURE_AI_SCOPE = "https://ai.azure.com/.default"


def build_chat_model() -> ChatOpenAI:
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
    deployment = os.environ.get("FOUNDRY_MODEL_NAME", "gpt-4.1")
    credential = DefaultAzureCredential()
    project = AIProjectClient(endpoint=project_endpoint, credential=credential)
    openai_client = project.get_openai_client()
    token_provider = get_bearer_token_provider(credential, _AZURE_AI_SCOPE)

    return ChatOpenAI(
        model=deployment,
        base_url=str(openai_client.base_url),
        api_key=token_provider,
    )


def main() -> None:
    graph = create_agent(build_chat_model(), tools=[])
    port = int(os.environ.get("PORT", "8088"))
    ResponsesHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

Co robi ten fragment kodu: Tworzy agenta LangGraph za pomocą create_agent z biblioteki LangChain, łączy go z punktem końcowym modelu projektu Foundry zgodnym z OpenAI i przekazuje skompilowany graf do ResponsesHostServer. Host uruchamia serwer HTTP i uwidacznia graf za pomocą polecenia POST /responses. Domyślnie serwer wiąże się z portem 8088lub z wartością zmiennej środowiskowej PORT po ustawieniu.

Note

Deep Agents są hostowane w taki sam sposób jak inne agenty LangGraph. Przekaż agenta bezpośrednio do ResponsesHostServer.

agent = create_deep_agent(...)
ResponsesHostServer(agent).run(port=port)

Uruchom aplikację lokalnie:

python main.py

Testowanie punktu końcowego odpowiedzi

Wyślij żądanie odpowiedzi spoza przesyłania strumieniowego do serwera lokalnego.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

W przypadku odpowiedzi strumieniowych ustaw stream na true. Host emituje zdarzenia przesyłane przez serwer z interfejsu Responses API, takie jak response.created, response.output_text.delta i response.completed.

Rozmowy

ResponsesHostServer obsługuje dwa wzorce stanu konwersacji. Wzorzec, którego używa, zależy od tego, czy skompilowany graf ma checkpointer LangGraph.

Konfiguracja programu Graph	Źródło konwersacji	Co host wysyła do grafu w kolejnych turach
Graf bez punktu kontrolnego	Historia odpowiedzi ze środowiska uruchomieniowego protokołu	Poprzednia historia odpowiedzi oraz bieżące dane wejściowe żądania
Graf skompilowany z użyciem mechanizmu tworzenia punktów kontrolnych	Stan punktu kontrolnego LangGraph indeksowany według rozmowy lub wątku odpowiedzi	Tylko dane wejściowe bieżącego żądania

Użyj checkpointera, gdy Twój graf potrzebuje stanu środowiska wykonawczego LangGraph, przerwań lub lokalnego stanu węzła między turami. W przypadku testowania lokalnego można użyć modułu kontrolnego w pamięci:

from langgraph.checkpoint.memory import MemorySaver

graph = create_agent(
    build_chat_model(),
    tools=[],
    checkpointer=MemorySaver(),
)

W przypadku produkcyjnych agentów hostowanych należy użyć trwałego mechanizmu punktów kontrolnych zamiast mechanizmu punktów kontrolnych w pamięci operacyjnej, aby stan grafu był zachowany po ponownym uruchomieniu kontenera.

Klienci kontynuują konwersację w Responses, podając previous_response_id lub identyfikator conversation. W przypadku testowania lokalnego należy połączyć poprzedni identyfikator odpowiedzi w następnym żądaniu:

POST http://localhost:8088/responses
Content-Type: application/json

{
  "input": "Can you make that more concise?",
  "previous_response_id": "<previous-response-id>",
  "stream": false
}

Gdy agent działa w rozwiązaniu Foundry, ten sam wzorzec działa za pośrednictwem punktu końcowego Odpowiedzi hostowanego agenta. Jeśli w kolejnych krokach również będzie potrzebny ten sam system plików hostowanego sandboxa, uwzględnij agent_session_id lub użyj identyfikatora conversation. Aby uzyskać szczegółowe informacje, zobacz Zarządzanie sesjami hostowanego agenta.

Człowiek w pętli sterowania

Jeśli graf używa wywołań LangGraph interrupt() , ResponsesHostServer wyświetla oczekujące przerwy za pośrednictwem standardowych elementów wyjściowych interfejsu API odpowiedzi:

Element function_call o nazwie __hosted_agent_adapter_interrupt__.
Element mcp_approval_request z ustawioną server_label wartością langgraph.

Klienci mogą wznowić graf, wysyłając albo element function_call_output, którego call_id odpowiada identyfikatorowi przerwania, albo element mcp_approval_response, którego approval_request_id odpowiada identyfikatorowi przerwania. Użyj function_call_output, gdy musisz wysłać rozbudowany ładunek Command LangGraph z polami resume, update lub goto. Użyj mcp_approval_response do prostego przepływu zatwierdzania lub odrzucania.

Protokół wywołań

Użyj InvocationsHostServer, gdy wywołujący nie mogą używać formatu żądania interfejsu Responses API lub gdy Twój scenariusz nie jest rozmową na czacie. Domyślny host Invocations akceptuje ciąg message i opcjonalną flagę stream.

Tworzenie hosta wywołań

Użyj tej samej funkcji tworzenia modelu z przykładu Odpowiedzi, ale uruchom InvocationsHostServer zamiast ResponsesHostServer.

import os

from langchain.agents import create_agent
from langgraph.checkpoint.memory import MemorySaver

from langchain_azure_ai.agents.hosting import InvocationsHostServer


def main() -> None:
    graph = create_agent(
        build_chat_model(),
        tools=[],
        checkpointer=MemorySaver(),
    )
    port = int(os.environ.get("PORT", "8088"))
    InvocationsHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

Co robi ten fragment kodu: Hostuje agenta LangGraph za pośrednictwem programu POST /invocations. Mechanizm MemorySaver zapisywania punktów kontrolnych zapewnia lokalną ciągłość wieloturową dla danego identyfikatora sesji. W środowisku produkcyjnym należy użyć trwałego mechanizmu zapisywania stanu, aby stan przetrwał ponowne uruchomienia kontenera.

Note

Agenci Deep są hostowani w ten sam sposób co inni agenci LangGraph. Przekaż agenta bezpośrednio do InvocationsHostServer.

agent = create_deep_agent(...)
InvocationsHostServer(agent).run(port=port)

Testowanie punktu końcowego wywołań

Wyślij żądanie bez przesyłania strumieniowego:

curl -i -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

Żądania spoza przesyłania strumieniowego zwracają kod JSON w tym kształcie:

{
  "response": "Assistant text"
}

W przypadku rozmów wieloetapowych użyj ponownie nagłówka odpowiedzi x-agent-session-id jako parametru zapytania agent_session_id w następnym żądaniu:

curl -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

Żądania strumieniowe zwracają zdarzenia text/event-stream zawierające tokeny:

curl -N -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"Count to 5.","stream":true}'

Strumień zawiera zdarzenia tokenów, po których następuje końcowe zdarzenie done:

data: {"token": "..."}

event: done
data: {}

Dostosowywanie schematu żądania

Aby dostosować treść żądania, utwórz klasę pochodną klasy InvocationsHostServer i przesłoń parse_request. Możesz również przeciążyć build_input, aby mapować przeanalizowane dane na niestandardowy stan grafu.

from starlette.requests import Request

from langchain_azure_ai.agents.hosting import InvocationsHostServer


class TicketHostServer(InvocationsHostServer):
    async def parse_request(self, request: Request) -> tuple[str, bool]:
        data = await request.json()
        ticket_id = data["ticket_id"]
        description = data["description"]
        stream = bool(data.get("stream", False))
        return f"Summarize ticket {ticket_id}: {description}", stream


if __name__ == "__main__":
    TicketHostServer(graph).run()

Co robi ten fragment kodu: Akceptuje niestandardowe dane zgłoszenia i przekształca je w pojedynczy komunikat użytkownika, zanim host wywoła graf. W przypadku bardziej złożonego stanu grafu nadpisz build_input zamiast spłaszczać żądanie do postaci tekstowej.

Deploy

Możesz wdrożyć za pomocą interfejsu wiersza polecenia Azure Developer CLI lub rozszerzenia Foundry Toolkit dla programu Visual Studio Code. Przepływ pracy Azure Developer CLI wykorzystuje przykładowe pliki azure.yaml i Docker. Proces rozszerzenia zapewnia wdrażanie krok po kroku w programie Visual Studio Code.

Wdrożenie agenta hostowanego wymaga roli Foundry Project Manager w projekcie. Aby uzyskać szczegółowe informacje, zobacz Wdrażanie hostowanego agenta.

Wdrażanie przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure

Repozytorium langchain-azure-ai źródłowe zawiera przykłady hostowanych agentów, które można uruchamiać i wdrażać przy użyciu interfejsu wiersza polecenia platformy Azure Developer. Przepływ wykorzystuje azure.yaml, Dockerfile i main.py każdej próbki. Aby uzyskać szczegółowe informacje o konfiguracji agentów hostowanych w azure.yaml, zobacz Tworzenie pliku azure.yaml dla agentów hostowanych.

Przed zainicjowaniem przykładu zainstaluj rozszerzenie agenta sztucznej inteligencji i zaloguj się:

azd ext install azure.ai.agents
azd auth login

Platforma Docker musi działać lokalnie, ponieważ azd ai agent run kompiluje obraz kontenera zadeklarowany w pliku Dockerfile przykładu. Szczegółowe informacje o poleceniach zawiera dokumentacja referencyjna usługi Azure Developer CLI.

Inicjowanie z przykładowego pliku azure.yaml

Utwórz nowy folder i zainicjuj go na podstawie przykładu azure.yaml. Zastąp azure.yaml adres URL przykładem, którego chcesz użyć.

mkdir my-langchain-agent
cd my-langchain-agent

azd ai agent init -m https://github.com/langchain-ai/langchain-azure/blob/main/samples/hosting/langgraph-hosted-agents/responses/01_basic/azure.yaml

Postępuj zgodnie z monitami z witryny azd ai agent init. Jeśli nie masz jeszcze projektu Foundry ani wdrożenia modelu, proces inicjalizacji może przeprowadzić Cię przez proces ich tworzenia.

Uruchamianie kontenera w środowisku lokalnym

Uruchom hosta agenta lokalnie za pomocą polecenia azd:

azd ai agent run

Host działa na http://127.0.0.1:8088. W innym terminalu bezpośrednio wywołaj punkt końcowy protokołu lokalnego:

curl -X POST http://127.0.0.1:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

Odpowiednik programu PowerShell:

(Invoke-WebRequest -Uri http://127.0.0.1:8088/responses `
  -Method POST -ContentType 'application/json' `
  -Body '{"input": "Hello!"}').Content

Agenta lokalnego można również wywołać przez azd:

azd ai agent invoke --local "Hello!"

Wdróż do Foundry

Jeśli zainicjowany projekt korzysta z nowego projektu Foundry i wdrożenia modelu, najpierw utwórz zasoby platformy Azure:

azd provision

Wdróż agenta:

azd deploy

Wdrożenie pakuje agenta do obrazu kontenera, przesyła go do udostępnionego rejestru kontenerów i wdraża do środowiska uruchomieniowego hostowanego agenta Foundry.

Infrastruktura hostingu usługi Foundry wprowadza zmienne środowiskowe środowiska uruchomieniowego do agenta, w tym:

FOUNDRY_PROJECT_ENDPOINT: adres URL punktu końcowego projektu Foundry, w którym wdrożono agenta.
FOUNDRY_MODEL_NAME: Nazwa wdrożenia modelu wybrana podczas azd ai agent init.
APPLICATIONINSIGHTS_CONNECTION_STRING: Parametry połączenia wystąpienia usługi Application Insights dla projektu.

Aby uzyskać pełne pojęcia dotyczące wdrażania, uprawnienia i szczegóły zarządzania, zobacz Wdrażanie hostowanego agenta i Zarządzanie cyklem życia hostowanego agenta.

Wdrażanie za pomocą rozszerzenia Foundry Toolkit dla programu Visual Studio Code

Aby uzyskać informacje na temat wdrażania opartego na rozszerzeniach, zobacz Szybki start: wdrażanie pierwszego hostowanego agenta.

Hostowanie istniejącego agenta

Jeśli aplikacja już współpracuje z językiem LangSmith lub interfejsem wiersza polecenia LangGraph, użyj modułu langchain_azure_ai.agents.hosting.run , aby bezproblemowo hostować agenta na platformie Foundry bez zmieniania kodu lub konfiguracji.

W katalogu głównym projektu uruchom host Responses:

python -m langchain_azure_ai.agents.hosting.run --protocol responses

Aby udostępnić ten sam graf za pomocą protokołu Invocations, ustaw --protocol na invocations. Jeśli langgraph.json definiuje wiele grafów, przekaż nazwę grafu jako pierwszy argument. Użyj --config <path>, jeśli plik konfiguracji nie znajduje się w domyślnej ścieżce langgraph.json. Przykład:

python -m langchain_azure_ai.agents.hosting.run agent --protocol invocations

Użyj tego samego polecenia modułu co punkt wejścia kontenera podczas wdrażania istniejącej aplikacji w usłudze Foundry.

Na przykład skonfiguruj polecenie w pliku azure.yaml. Kluczowe ustawienie to punkt wyjścia.

services:
  my-agent:
    host: azure.ai.agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint: '-m langchain_azure_ai.agents.hosting.run --protocol responses'
      ...
    ...

Troubleshooting

Ta lista kontrolna służy do diagnozowania typowych problemów podczas opracowywania hostowanych agentów za pomocą polecenia langchain_azure_ai.agents.hosting.

Sprawdzanie poprawności schematu grafu kończy się niepowodzeniem

Hosty domyślne oczekują skompilowanego grafu LangGraph, którego stan ma messages pole, takie jak MessagesState. Jeśli graf używa niestandardowego schematu stanu, utwórz podklasę hosta i przesłoń build_input. W przypadku Responses zastąp handle_create, gdy potrzebujesz pełnej kontroli nad analizowaniem żądań, wykonywaniem grafu i emitowaniem zdarzeń Responses.

Stan konwersacji nie jest kontynuowany

W przypadku protokołu Responses przekaż previous_response_id lub identyfikator conversation w kolejnych turach. Jeśli graf używa modułu kontrolnego, upewnij się, że moduł kontrolny jest skonfigurowany i trwały dla środowiska, w którym działa agent.

W przypadku protokołu Wywołania platforma nie przechowuje historii konwersacji. Użyj parametru agent_session_id zapytania, aby kierować późniejsze wywołania do tej samej hostowanej piaskownicy i używać własnego magazynu stanów lub modułu kontrolnego LangGraph dla stanu konwersacji.

Nie można uzyskać dostępu do modelu w hostowanym kontenerze

Upewnij się, że wersja agenta hostowanego zawiera FOUNDRY_MODEL_NAME, a także że tożsamość agenta ma uprawnienia do wywoływania projektu Foundry. Platforma ustawia FOUNDRY_PROJECT_ENDPOINT; kod powinien odczytać tę zmienną podczas działania w Foundry.

Następny krok

Wdrażanie hostowanego agenta

Opinia

Czy ta strona była pomocna?

Last updated on 2026-08-31