Microsoft Agent Framework-ügynökök üzemeltetése Foundry által üzemeltetett ügynökökként

A Microsoft Agent Framework hosztolási csomagjaival elérhetővé tehet egy Agent Framework-ügynököt a Foundry hosztolt ügynökeihez készült protokollokon keresztül. Az üzemeltetési csomagok lehetővé teszik az ügynöklogika kódban tartását, míg a Foundry kezeli az üzemeltetett futtatókörnyezetet, a munkameneteket, a méretezést, az identitást és a protokollvégpontokat.

Ebben a cikkben létrehoz egy minimális Agent Framework-ügynököt, elérhetővé teszi a Válaszok vagy az Invocations protokollon keresztül, teszteli a HTTP-vel, és üzembe helyezi azt a Foundryben a Azure fejlesztői parancssori felülettel.

A Microsoft Foundry Skill segíthet az adapter implementálásában, a protokollok tesztelésében és a telepítésbenazd.

Prerequisites

• Azure-előfizetés. Készíts egyet ingyen.
• Egy Foundry-projekt.
• Üzembe helyezett csevegőmodell, például gpt-4.1 vagy gpt-4o.
• A Foundry Project Manager szerepkör az üzemeltetett ügynök üzembe helyezését célzó projektben. További információ: Üzemeltetett ügynök üzembe helyezése.
• Azure CLI bejelentkezett (az login), hogy DefaultAzureCredential hitelesíthesse magát.

• Python 3.10 vagy újabb verzió.

• .NET 10 SDK vagy újabb.

A csomagok telepítése

Telepítse az Agent Frameworkt és az Foundry üzemeltetési csomagját:

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

A agent_framework_foundry_hosting csomag tartalmazza a Foundry protokollok kiszolgálóit:

• ResponsesHostServer az OpenAI-kompatibilis /responses végponthoz.
• InvocationsHostServer az általános /invocations végpont számára.

Adja hozzá az Agent Framework és a Foundry üzemeltetési csomagokat a projekthez:

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

Az Invocations protokollhoz adja hozzá az Invocations kiszolgálócsomagot is:

dotnet add package Azure.AI.AgentServer.Invocations

Ezek a csomagok a Foundry protokollokhoz készült gazdagép-bővítményeket biztosítják:

• AddFoundryResponses és MapFoundryResponses az OpenAI-kompatibilis /responses végponthoz.
• AddInvocationsServer és MapInvocationsServer az általános /invocations végpont esetében.

Üzemeltetési protokoll kiválasztása

A üzemeltetett ügynökök egy vagy több protokollt tehetnek közzé. Kezdje a legtöbb beszélgetési ügynök válaszaival.

Protocol	Endpoint	Használja amikor
Responses	/responses	OpenAI-kompatibilis csevegést, streamelést, válaszelőzményeket és beszélgetési szálkezelést szeretne.
Meghívások	/invocations	Egyéni JSON-alakzatot, webhookstílusú végpontot vagy nem beszélgetési feldolgozást szeretne.

A protokoll működésével és munkamenetekkel kapcsolatos háttérrel kapcsolatban lásd: Üzemeltetett ügynökök és Üzemeltetett ügynök munkamenetek kezelése.

Környezeti változók konfigurálása

Adja meg a projektvégpont és a modell üzembe helyezésének nevét a helyi fejlesztéshez:

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

A PowerShellben:

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

Amikor ugyanaz a kód üzemeltetett ügynökként fut a Foundryben, a platform futásidőben beszúrja a FOUNDRY_PROJECT_ENDPOINT és AZURE_AI_MODEL_DEPLOYMENT_NAME elemeket.

Válaszprotokoll

A Válasz protokollt akkor használja, ha egy OpenAI-kompatibilis csevegési végpontot szeretne streameléssel, válaszelőzményekkel és beszélgetési szálkezeléssel.

Responses-kiszolgáló létrehozása

Hozzon létre egy main.py nevű fájlt, amely egy Foundry-modellt használó minimális Agent Framework-ügynököt tartalmaz.

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()

Mit csinál ez a kódrészlet: Létrehoz egy Foundry-modellre épülő Agent Framework-ügynököt a FoundryChatClient használatával, majd átadja az ügynököt a ResponsesHostServer számára. A gazdagép elindít egy HTTP-kiszolgálót, és a POST /responses használatával elérhetővé teszi az ügynököt. Alapértelmezés szerint a kiszolgáló a porthoz 8088kapcsolódik.

Referencia: Microsoft Agent Framework dokumentációja

Futtassa az alkalmazást helyileg:

python main.py

Hozzon létre egy Program.cs fájlt, amely egy minimális Agent Framework-ügynököt tartalmaz, és a Responses protokollon keresztül egy Foundry-modellt használ.

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();

Mit tesz ez a kódrészlet: Létrehoz egy AIAgent elemet a Foundry-projekt ügyfeléből, regisztrálja Foundry Responses-gazdagépként a(z) AddFoundryResponses használatával, és leképezi a POST /responses végpontot a(z) MapFoundryResponses használatával. Alapértelmezés szerint a gazda a(z) 8088 porton figyel.

Referencia: AIProjectClient | DefaultAzureCredential

Futtassa az alkalmazást helyileg:

dotnet run

A Válaszok végpont tesztelése

Küldjön egy nem streamelő Responses-kérést a helyi kiszolgálóra.

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"

A kiszolgáló válaszszöveget és válaszazonosítót tartalmazó JSON-objektummal válaszol. Streamelési válaszok esetén állítsa a következőre streamtrue: . A gazdagép a Responses API által küldött szerveroldali eseményeket küld, például response.created, response.output_text.delta és response.completed.

Többfordulós beszélgetések

A beszélgetés folytatásához adja meg az előző válaszazonosítót a previous_response_id következő kérés mezőjében:

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}'

Amikor az ügynök a Foundry-ben fut, ugyanez a minta a hosztolt ügynök Responses végpontján keresztül működik. Ha a későbbi körökben is ugyanarra a hosztolt sandbox fájlrendszerre van szükség, foglalja bele a(z) agent_session_id elemet, vagy használjon conversation azonosítót. További részletekért lásd: Üzemeltetett ügynök munkameneteinek kezelése.

Meghívások protokollja

Használja az Invocations protokollt, ha a hívó felek nem tudják használni a Responses API kérésformátumát, vagy ha a használati eset nem csevegési jellegű. Az Invocations-gazda a munkamenet-állapotát egy agent_session_id lekérdezési paraméteren és egy válaszfejlécken keresztül kezeli.

Invocations-gazdagép létrehozása

Használja ugyanazt az ügynökbeállítást, mint a Responses-példában, de InvocationsHostServer helyett ResponsesHostServer-val kezdje.

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()

A kódrészlet leírása: Az Agent Framework-ügynököt a segítségével üzemelteti POST /invocations. A gazda a munkamenetenkénti állapotot a agent_session_id lekérdezési paraméteren és a válaszfejlécen keresztül kezeli.

Referencia: Microsoft Agent Framework dokumentációja

Az Invocations protokoll egy InvocationHandler használ, amelyet Ön valósít meg az egyes kérések feldolgozásához. Regisztrálja az Invocations-kiszolgálót és a kezelőjét, majd képezze le a végpontokat.

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();

A kódrészlet leírása: Regisztrálja az Invocations kiszolgálói szolgáltatásokat és az implementációt InvocationHandler , majd leképezi a /invocations végpontokat. Az egyes kérések feldolgozási módjának meghatározásához a(z) MyInvocationHandler elemet valósítja meg. A teljes kezelőpéldáért lásd a .NET Meghívások mintapéldáját.

Hivatkozás: AddInvocationsServer

Az Invocations végpont tesztelése

Kérés küldése a helyi kiszolgálónak:

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

Többfordulós beszélgetések esetén használja újra a agent_session_id válaszfejléc értékét lekérdezési agent_session_id paraméterként a következő kérelemben:

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

A platform nem tárolja az Invocations protokoll beszélgetési előzményeit. agent_session_id A lekérdezési paraméterrel a későbbi hívásokat ugyanahhoz a üzemeltetett tesztkörnyezethez irányíthatja.

Deploy

Telepítés az Azure Developer CLI (azd) használatával. A folyamat mintafájlokat azure.yaml és Dockert használ az ügynökkonténerképének létrehozásához és a Foundry által üzemeltetett ügynök-futtatókörnyezetbe való telepítéséhez.

A hosztolt ügynök telepítéséhez a projektben a Foundry Project Manager szerepkör szükséges. További információ: Üzemeltetett ügynök üzembe helyezése.

Az Azure Developer CLI bővítmény telepítése

Telepítse az AI-ügynök bővítményét, és jelentkezzen be a minta inicializálása előtt:

azd ext install azure.ai.agents
azd auth login

A Dockernek helyileg kell futnia, mert azd ai agent run a minta Docker-fájljában deklarált tárolórendszerképet hozza létre. A parancs részleteiért lásd a Azure fejlesztői parancssori felületre vonatkozó referenciát.

Inicializálás mintajegyzékből

Hozzon létre egy új mappát, és inicializálja azt egy minta azure.yaml alapján. Ezek a parancsok inicializálják az aktuális könyvtárat, és az útmutatónak megfelelő konténeres telepítést választják ki.

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

azd ai agent init -t https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml --src . --deploy-mode container

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

azd ai agent init -t https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/azure.yaml --src . --deploy-mode container

Kövesse a(z) azd ai agent init utasításait. A Python minta létrehozhat egy Foundry-projektet és üzembe helyezhet egy modellt. A C#-minta egy meglévő Foundry-projektet és modelltelepítést igényel.

Azure-erőforrások kiépítése

Ha az inicializált projekt egy új Foundry-projektet és modelltelepítést használ, először a Azure erőforrásokat építse ki:

azd provision

Ez a parancs létrehoz egy erőforráscsoportot, amely többek között egy Foundry-példányt, egy Modelltelepítéssel rendelkező Foundry-projektet, egy Application Insights-példányt és egy tárolóregisztrációs adatbázist tartalmaz az üzemeltetett ügynök lemezképeihez.

Helyileg futtassa a konténert

Futtassa helyileg az ügynökgazdát a azd használatával:

azd ai agent run

A gazdagép a következőre http://localhost:8088szolgál: . Egy másik terminálban hívja meg a helyi protokollvégpontot:

azd ai agent invoke --local "Hello!"

A végpontot közvetlenül is meghívhatja a következővel curl:

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

Telepítés a Foundryba

Az ügynök telepítése

azd deploy

Az üzembe helyezés egy tárolórendszerképbe csomagolja az ügynököt, leküldi a kiépített tárolóregisztrációs adatbázisba, és a Foundry által üzemeltetett ügynök futtatókörnyezetébe helyezi.

A Foundry üzemeltetési infrastruktúrája futtatókörnyezeti környezeti változókat injektál az ügynökbe, beleértve a következőket:

• FOUNDRY_PROJECT_ENDPOINT: Annak az Foundry-projektnek a végponti URL-címe, amelyben az ügynök telepítve van.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: A(z) azd ai agent init során kiválasztott modelltelepítés neve.
• APPLICATIONINSIGHTS_CONNECTION_STRING: A projekt Application Insights-példányának kapcsolati karakterlánc.

Az üzembe helyezéssel kapcsolatos fogalmak, engedélyek és felügyeleti részletekért tekintse meg a üzemeltetett ügynök üzembe helyezését és az üzemeltetett ügynök életciklusának kezelését ismertető cikket.

Troubleshooting

Ezzel az ellenőrzőlistával diagnosztizálhatja a gyakori problémákat, miközben üzemeltetett ügynököket fejleszt az Agent Framework használatával.

A modell nem érhető el a üzemeltetett tárolóban

Győződjön meg arról, hogy a hosztolt ügynök verziója tartalmazza a(z) AZURE_AI_MODEL_DEPLOYMENT_NAME elemet, és hogy az ügynök identitása rendelkezik jogosultsággal a Foundry-projekt eléréséhez. A platform beállítja a FOUNDRY_PROJECT_ENDPOINT változót; a kódodnak ki kell olvasnia ezt a változót, amikor a Foundryben fut.

A beszélgetés állapota nem marad fenn

A Responses protokoll esetében a későbbi fordulókban adja át a previous_response_id vagy egy conversation azonosítót.

Az Invocations protokoll esetében a platform nem tárolja a beszélgetési előzményeket. Lekérdezési paraméterrel agent_session_id átirányíthatja a későbbi hívásokat ugyanahhoz a üzemeltetett tesztkörnyezethez.

A protokollverzió nem egyezik

Ha a kérések a frissítés után meghiúsulnak, győződjön meg arról, hogy a jegyzékfájl és az üzemeltetési csomag egyaránt a 2.0.0-s protokollverziót használja. A protokoll 1.0.0-s verziója már nem támogatott.

Következő lépés

Üzemeltetett ügynök üzembe helyezése

Kapcsolódó tartalom

• Mi az a Foundry Agent Service?
• Hosztolt ügynökök
• Üzemeltetett ügynök munkameneteinek kezelése
• LangGraph-ügynökök üzemeltetése Foundry által üzemeltetett ügynökökként