Hostuj agentów Microsoft Agent Framework jako agentów hostowanych w Foundry

Użyj pakietów hostingowych platformy Microsoft Agent Framework, aby udostępnić agenta Agent Framework za pośrednictwem protokołów dla agentów hostowanych w Foundry. Pakiety hostingu umożliwiają zachowanie logiki agenta w kodzie, podczas gdy platforma Foundry zarządza hostowanym środowiskiem uruchomieniowym, sesjami, skalowaniem, tożsamością i punktami końcowymi protokołu.

W tym artykule utworzysz minimalnego agenta platformy Agent Framework, uwidaczniasz go za pomocą protokołu Responses lub Invocations, przetestujesz go za pośrednictwem protokołu HTTP i wdrożysz go w narzędziu Foundry za pomocą interfejsu wiersza polecenia dewelopera Azure.

Microsoft Foundry Skill może pomóc zaimplementować adapter, przetestować protokoły i wdrożyć za pomocą azd.

Wymagania wstępne

• Subskrypcja platformy Azure. Utwórz je bezpłatnie.
• Projekt Foundry.
• Wdrożony model czatu, taki jak gpt-4.1 lub gpt-4o.
• Rola Menedżer projektu Foundry w projekcie służąca do wdrożenia hostowanego agenta. Aby uzyskać szczegółowe informacje, zobacz Wdrażanie hostowanego agenta.
• Azure CLI jest zalogowane (az login), więc DefaultAzureCredential może się uwierzytelnić.

• Python 3.10 lub nowszy.

• SDK platformy .NET 10 lub nowszy.

Instalowanie pakietów

Zainstaluj platformę Agent Framework i pakiet hostingu foundry:

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

Pakiet agent_framework_foundry_hosting udostępnia serwery hosta dla protokołów Foundry:

• ResponsesHostServer dla zgodnego z OpenAI punktu końcowego /responses.
• InvocationsHostServer dla ogólnego /invocations punktu końcowego.

Dodaj pakiety hostingowe Agent Framework i Foundry do projektu:

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

W przypadku protokołu Invocations dodaj również pakiet serwera Invocations:

dotnet add package Azure.AI.AgentServer.Invocations

Te pakiety udostępniają rozszerzenia hosta dla protokołów Foundry:

• AddFoundryResponses i MapFoundryResponses dla punktu końcowego zgodnego z platformą /responses OpenAI.
• AddInvocationsServer i MapInvocationsServer dla ogólnego punktu końcowego /invocations.

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.

Protocol	Endpoint	Użyj, gdy
Responses	/responses	Chcesz czatu kompatybilnego z OpenAI, strumieniowania, historii odpowiedzi i wątkowania rozmów.
Wywołania	/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 AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

W programie PowerShell:

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

Gdy ten sam kod jest uruchamiany jako hostowany agent w narzędziu Foundry, platforma wprowadza FOUNDRY_PROJECT_ENDPOINT i AZURE_AI_MODEL_DEPLOYMENT_NAME w czasie wykonywania.

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 platformy Agent Framework, który korzysta z modelu foundry.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Co robi ten fragment kodu: Tworzy agenta platformy Agent Framework opartego na modelu Foundry za pośrednictwem FoundryChatClient, a następnie przekazuje agenta do ResponsesHostServer. Host uruchamia serwer HTTP i uwidacznia agenta za pomocą polecenia POST /responses. Domyślnie serwer jest powiązany z portem 8088.

Dokumentacja programu Microsoft Agent Framework

Uruchom aplikację lokalnie:

python main.py

Utwórz plik Program.cs z minimalnym agentem Agent Framework, korzystającym z modelu Foundry przy użyciu protokołu Responses.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(
    Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));

var deployment =
    Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? "gpt-4o";

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Co robi ten fragment kodu: Tworzy obiekt AIAgent na podstawie klienta projektu Foundry, rejestruje go jako host odpowiedzi Foundry za pomocą AddFoundryResponses i mapuje punkt końcowy POST /responses za pomocą MapFoundryResponses. Domyślnie host obsługuje port 8088.

Dokumentacja: AIProjectClient | DefaultAzureCredential

Uruchom aplikację lokalnie:

dotnet run

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"

Serwer odpowiada za pomocą obiektu JSON zawierającego tekst odpowiedzi i identyfikator odpowiedzi. 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.

Konwersacje wieloetapowe

Aby kontynuować konwersację, przekaż poprzedni identyfikator odpowiedzi w previous_response_id polu następnego żądania:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"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 hostowanych agentów.

Protokół wywołań

Użyj protokołu Invocations, gdy klienci wywołujący nie mogą używać formatu żądania interfejsu Responses API lub gdy dany scenariusz nie jest rozmową na czacie. Host wywołań zarządza stanem sesji za pomocą parametru agent_session_id zapytania i nagłówka odpowiedzi.

Tworzenie hosta wywołań

Użyj tej samej konfiguracji agenta co przykład Odpowiedzi, ale uruchom InvocationsHostServer zamiast ResponsesHostServer.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        default_options={"store": False},
    )

    server = InvocationsHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Co robi ten fragment kodu: Hostuje agenta programu Agent Framework za pośrednictwem programu POST /invocations. Host zarządza stanem sesji za pośrednictwem parametru zapytania i nagłówka agent_session_id odpowiedzi.

Dokumentacja programu Microsoft Agent Framework

Protokół wywołań używa implementowanego przez Ciebie elementu InvocationHandler do przetwarzania każdego żądania. Zarejestruj serwer wywołań i program obsługi, a następnie przypisz punkty końcowe.

using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

Co robi ten fragment kodu: Rejestruje usługi serwera Invocations oraz implementację InvocationHandler, a następnie mapuje endpointy /invocations. Zaimplementowana jest implementacja MyInvocationHandler w celu zdefiniowania sposobu przetwarzania każdego żądania. Aby zapoznać się z kompletnym przykładem procedury obsługi, zobacz przykład wywołania .NET.

Dokumentacja: AddInvocationsServer

Testowanie punktu końcowego wywołań

Wyślij żądanie do serwera lokalnego:

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

W przypadku wieloetapowych rozmów użyj ponownie wartości agent_session_id z nagłówka odpowiedzi jako parametru zapytania agent_session_id w następnym żądaniu:

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

Platforma nie przechowuje historii konwersacji dla protokołu Invocations. Użyj parametru zapytania agent_session_id, aby kierować kolejne wywołania do tego samego hostowanego środowiska testowego.

Deploy

Wdrażanie przy użyciu interfejsu wiersza polecenia dewelopera Azure (azd). Ten proces wykorzystuje przykładowe manifesty i platformę Docker do tworzenia obrazu kontenera agenta oraz wdrażania go w hostowanym środowisku uruchomieniowym agenta Foundry.

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

Instalowanie rozszerzenia interfejsu wiersza polecenia dla deweloperów platformy Azure

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 manifestu

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

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/agent.manifest.yaml

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.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.

Aprowizuj zasoby platformy Azure

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

azd provision

To polecenie tworzy grupę zasobów, która zawiera między innymi wystąpienie usługi Foundry, projekt Foundry z wdrożeniem modelu, wystąpienie usługi Application Insights oraz rejestr kontenerów dla hostowanych obrazów agentów.

Uruchamianie kontenera w środowisku lokalnym

Uruchom hosta agenta lokalnie za pomocą polecenia azd:

azd ai agent run

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

azd ai agent invoke --local "Hello!"

Punkt końcowy można również wywołać bezpośrednio za pomocą polecenia curl:

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

Wdróż do Foundry

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

Rozwiązywanie problemów

Ta lista kontrolna służy do diagnozowania typowych problemów podczas opracowywania hostowanych agentów za pomocą platformy Agent Framework.

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

Upewnij się, że hostowana wersja programu agenta zawiera AZURE_AI_MODEL_DEPLOYMENT_NAME oraz ż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.

Stan konwersacji nie jest kontynuowany

W przypadku protokołu Responses przekaż previous_response_id lub identyfikator conversation w kolejnych turach.

W przypadku protokołu Wywołania platforma nie przechowuje historii konwersacji. Użyj parametru zapytania agent_session_id, aby kierować kolejne wywołania do tego samego hostowanego środowiska testowego.

Niezgodność wersji protokołu

Jeśli żądania kończą się niepowodzeniem po uaktualnieniu, upewnij się, że manifest i pakiet hostingowy używają protokołu w wersji 2.0.0. Wersje protokołu 1.0.0 i 2.0.0 są niezgodne.

Następny krok

Wdrażanie hostowanego agenta

Treści powiązane

• Co to jest usługa agenta programu Foundry?
• Agenci hostowani
• Zarządzanie sesjami hostowanych agentów
• Hostowanie agentów LangGraph jako agentów hostowanych w usłudze Foundry