Foundry által üzemeltetett ügynökök

Hosted ügynökök lehetővé teszi a Microsoft Foundry Agent Service-ben az Ügynök-keretrendszer ügynökeinek containerizált alkalmazásként való üzembe helyezését a Microsoft által felügyelt infrastruktúrán. A platform kezeli a skálázást, a munkamenet-állapot megőrzését, a biztonságot és az életciklus kezelését, hogy az ügynök logikájára összpontosíthasson. Microsoft Foundry által üzemeltetett ügynökök általánosan elérhetők.

Az Agent Framework hosztolási integrációjával minimális kóddal elérhetővé tehet egy Agent-t, beleértve egy Workflow.as_agent() használatával becsomagolt munkafolyamatot is, a Foundry Responses vagy az Invocations protokollon keresztül.

Mikor érdemes üzemeltetett ügynököket használni?

Válassza a Foundry által üzemeltetett ügynököket, ha szeretné:

  • Felügyelt infrastruktúra – nincs szükség tárolók, webkiszolgálók vagy skálázási szabályok konfigurálására.
  • Beépített munkamenet-kezelés – a platform folyamatosan megőrzi a munkameneteket és a feltöltött fájlokat a fordulók között és a tétlenségi időszakok alatt.
  • Dedikált ügynökidentitás – minden üzembe helyezett ügynök saját Entra-identitást kap a modellekhez, eszközökhöz és alsóbb rétegbeli szolgáltatásokhoz való biztonságos hozzáférés érdekében.
  • OpenAI-kompatibilis végpontok – az ügyfelek bármilyen OpenAI-kompatibilis SDK-val kommunikálhatnak az ügynökkel a Responses protokollon keresztül.

Megjegyzés:

A Python agent-framework-foundry-hosting integráció előzetes kiadású. Microsoft Foundry Hosted Agents, a felügyelt üzemeltetési szolgáltatás általánosan elérhető.

Prerequisites

A helyi teszteléshez a következőkre is szüksége van:

Telepítse a tárhelyhez kapcsolódó NuGet-csomagot:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 vagy újabb verzió

Telepítse a prerelease üzemeltetési csomagot, a Foundry-ügyfelet és Azure hitelesítési csomagot:

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

A Foundryben a platform biztosítja a hívó felhasználói környezetét és hívási környezetét; az üzemeltetési infrastruktúra arra használja őket, hogy felhasználónként elkülönítsék az állapotot, és továbbítsák a kéréskörnyezetet az Foundry-szolgáltatásoknak. A helyi futtatások nem kapják meg ezt a platformkörnyezetet, ezért az alkalmazásoknak szükség esetén saját identitás- és állapotvezérlőket kell biztosítaniuk.

Válaszprotokoll

A Válaszok protokoll a legtöbb ügynök számára ajánlott kiindulópont. Egy OpenAI-kompatibilis /responses végpontot tesz elérhetővé, és a platform automatikusan kezeli a beszélgetési előzményeket, a streamelést és a munkamenetek életciklusát.

using Azure.AI.AgentServer.Core;
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";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

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

A AgentHost.CreateBuilder rendszer létrehoz egy előre konfigurált alkalmazás-gazdagépet az Foundry üzemeltetési környezethez. AddFoundryResponses regisztrálja az ügynököt a Responses protokollkezelővel, és MapFoundryResponses leképezi a /responses HTTP-végpontot.

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

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 helpful AI assistant.",
)

server = ResponsesHostServer(agent)
server.run()

A ResponsesHostServer rendszer becsomagolja az ügynököt, és a Foundry Responses protokollon keresztül teszi elérhetővé. Nem munkafolyamat-ügynök esetén az alapértelmezett history_source="agent_server" beállítás a konfigurált Ügynökkiszolgáló válaszszolgáltatót használja a modell előzményforrásaként. A hoszt megakadályozza, hogy a későbbi modellszolgáltatás egy második példányt tároljon, amikor a kliens alapértelmezés szerint tárolja az előzményeket.

Ne kombinálja az alapértelmezett előzményforrást olyan HistoryProvider elemmel, amely load_messages=True tartalmaz. Ne adja meg a , previous_response_idvagy conversation az conversation_idalsóbb rétegbeli szolgáltatás folytatási beállításait sem. A gazdagép elutasítja ezeket a konfigurációkat a duplikált előzmények elkerülése érdekében.

Akkor használható ResponsesHostServer(agent, history_source="agent") , ha az ügynök előzményszolgáltatójának vagy az alsóbb rétegbeli modellszolgáltatásnak kezelnie kell a beszélgetési előzményeket. Ez a mód csak az ügynökkiszolgáló aktuális kérésbemenetét adja át, és megőrzi az ügynök előzményeit és szolgáltatástárolási viselkedését. Az egyéni SupportsAgentRun implementációknak ezt a módot kell használniuk. A store paraméter külön marad: kiválasztja azt a válaszszolgáltatót, amely mindkét módban megőrzi a Responses API bemeneteit és kimeneteit.

A gazdagép a megadott ügynök tulajdonosa, és tárhelyspecifikus környezetszolgáltatókat vehet fel. Ne használja újra az ügynököt másik hosttal, és a host létrehozása után közvetlenül ne hívja meg.

Állapot megőrzése és hosszan futó beszélgetések kezelése

ResponsesHostServer Alapértelmezés szerint az Foundry által támogatott tárolókat konfigurálja. A nem munkafolyamat-ügynökök esetében a(z) AgentSessionStoreProvider egy FoundryAgentSessionStore biztosít. A munkafolyamat-ügynökök számára CheckpointStoreProvider egy FoundryCheckpointStore biztosít. FunctionApprovalStoreProvider biztosít egy FoundryFunctionApprovalStore a függőben lévő jóváhagyásokhoz. Ezek az adattárak üzemeltetett környezetben a Foundry State Store-t, helyi futtatáskor pedig az Agent Server helyi állapotát használják.

A(z) history_source="agent" használatával a konfigurált munkamenet-tároló megőrzi a AgentSession által továbbított szolgáltatói állapotot, beleértve a InMemoryHistoryProvider üzeneteit is.

A tárolás testreszabásához adjon át egy agent_session_store_provider elemet a function_approval_store_provider vagy a StoreProvider számára. Adjon át egy ContextScopedStoreProvider-t a checkpoint_store_provider számára. Például valósítsa meg a(z) SessionStore és StoreProvider[SessionStore] elemet úgy, hogy a saját, nem munkafolyamathoz tartozó ügynök munkamenettárolóját használja.

Importálja a(z) ResponsesServerOptions elemet a(z) azure.ai.agentserver.responses helyről, és adja át a(z) ResponsesHostServer számára a(z) options paraméteren keresztül. A hosszú ideig futó beszélgetési lehetőségek az ügynök típusától függenek:

Képesség Ügynök típusa Követelmények és viselkedés
Rugalmas háttérválaszok Csak munkafolyamat Beállítás ResponsesServerOptions(resilient_background=True). Küldje el a Válasz kérést a következővel store=true : és background=true. Újraindítás után a gazdagép a legutóbbi tartós munkafolyamat-ellenőrzőponttól folytatja a végrehajtást, vagy ellenőrzőpont hiányában újrajátssza az eredeti bemenetet. Ne konfigurálja az ellenőrzőpont-tárolót a munkafolyamaton, mert a gazdagép kezeli. Külső mellékhatások idempotenssé tétele, mert az utolsó tartós ellenőrzőpont utáni munka ismétlődhet.
Irányítható beszélgetések Csak nem munkafolyamathoz Állítsa be a ResponsesServerOptions(steerable_conversations=True) elemet, és küldjön Responses-kéréseket a(z) store=true használatával. Tartsa a fordulókat egyetlen lineáris láncon ugyanannak a(z) conversation értéknek az újbóli felhasználásával. Alternatívaként küldje el a közvetlenül megelőző previous_response_id címkét, és tartsa meg a feloldott agent_session_id címkét. A gazdagép elutasítja az elavult elődöket, amelyek elágazásokat hoznak létre.

ResponsesHostServer akkor jelentkezik, ha rugalmas háttérválaszokat RuntimeError engedélyez egy nem munkafolyamat-ügynökhöz vagy egy munkafolyamat-ügynök irányítható beszélgetéseihez. A teljes implementációkhoz tekintse meg az egyéni tárolót, a rugalmas, hosszú ideig futó munkafolyamatot és a irányítható, hosszú ideig futó ügynökmintákat .

Ha egy Foundry által hosztolt MCP-eszköz felhasználói hozzájárulást igényel, a ResponsesHostServer egy oauth_consent_request kimeneti elemmel rendelkező hiányos választ ad vissza. Jelenítse meg a felhasználónak a consent_link-t, majd a felhasználó hozzájárulásának megadása után folytassa a műveletet a befejezetlen válasz azonosítójával, previous_response_id-ként. A gazda megőrzi az ügynök munkamenetét ehhez az újrapróbálkozáshoz, és csak abszolút HTTPS-es beleegyezési hivatkozásokat tesz elérhetővé.

Meghívások protokollja

Az Invocations protokoll teljes körű vezérlést biztosít a HTTP-kérések és -válaszok felett. Akkor használja, ha olyan egyéni hasznos adatokra, nem beszélgetési feldolgozási vagy streamelési protokollokra van szüksége, amelyek nem OpenAI-kompatibilisek.

A C#-ban az Invocations protokollal egyéni InvocationHandler módon dolgozhatja fel a bejövő kéréseket:

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

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

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

A AddInvocationsServer metódus regisztrálja az Invocations protokollszolgáltatásokat. Használja a InvocationHandler-t annak meghatározására, hogyan dolgozza fel az ügynök az egyes kéréseket.

Az egyszerű beállításhoz használja InvocationsHostServer a agent_framework_foundry_hosting csomagból. Az ügynököt hasonlóan körülveszi, mint a ResponsesHostServer, és automatikusan kezeli a munkamenetet.

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

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

A kérések kezelésének teljes körű vezérléséhez használja InvocationAgentServerHost közvetlenül a azure.ai.agentserver.invocations csomagból, és implementálja a saját híváskezelőt:

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

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},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


if __name__ == "__main__":
    app.run()

Warning

Az egyéni kezelő példában található memóriabeli munkamenet-tároló megszakad az újraindítás során. Használjon tartós tárolást (például Cosmos DB-t) éles környezetben.

Az Invocations teljes üzembe helyezéséhez tekintse meg az Foundry által üzemeltetett Telegram-mintát. Az API Managementet az üzemeltetett ügynök webhookja elé helyezi, és felügyelt identitásokat, Key Vault és Cosmos DB-t használ a tartós beszélgetési előzményekhez.

Megjegyzés:

A Foundry által üzemeltetett ügynökök Go nyelvű támogatása hamarosan elérhető lesz. A legújabb állapotot az Agent Framework Go-adattárában tekinthet meg.

Tip

Tekintse meg a Python-mintákat vagy a C#-mintákat a hostolt ügynökprojekt példáiért. Vagy használhatja a azd ai agent init parancsot egy új üzemeltetett ügynökprojekt létrehozásához az alapoktól. Részletes útmutatásért tekintse meg ezt a rövid útmutatót .

Helyi futtatás

A Azure fejlesztői parancssori felület (azd) biztosítja a üzemeltetett ügynök helyi futtatásának és tesztelésének legegyszerűbb módját.

Projekt inicializálása

Hozzon létre egy új mappát, és inicializáljon egy mintajegyzékből:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Tip

A jegyzék lehet egy helyi YAML-fájl elérési útja, vagy egy távoli jegyzék URL-címe.

Környezeti változók beállítása

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

Az ügynök gazdagépének futtatása

azd ai agent run

Az ügynök gazdagép a következőn indul el: http://localhost:8088.

Az ügynök meghívása

azd ai agent invoke --local "Hello!"

Vagy használja a következőt curl:

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

Vagy a PowerShellben:

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

Üzembe helyezés az Foundryben

Miután helyben ellenőrizte az ügynökprogramot, helyezze üzembe a Microsoft Foundry-ba.

  1. Erőforrások kiépítése (ha még nem rendelkezik Foundry-projektel):

    azd provision

    Ez létrehoz egy erőforráscsoportot egy Foundry-példány, projekt, modelltelepítés, Application Insights és tárolóregisztrációs adatbázis használatával.

  2. Az ügynök üzembe helyezése:

    azd deploy

    Ez konténerképként csomagolja az ügynököt, feltölti az Azure Container Registry-be, és üzembe helyezi a Foundry Agent Service-ben.

Az Foundry üzemeltetési infrastruktúrája futásidőben automatikusan injektálja a következő környezeti változókat az ügynöktárolóba:

Variable Leírás
FOUNDRY_PROJECT_ENDPOINT Az Foundry-projekt végponti URL-címe.
AZURE_AI_MODEL_DEPLOYMENT_NAME A modell üzembehelyezési neve (a azd ai agent init során konfigurálva).
APPLICATIONINSIGHTS_CONNECTION_STRING Az Application Insights kapcsolati lánca a telemetria számára.

Az üzembe helyezést követően az ügynök a dedikált Foundry-végponton keresztül érhető el, és az Foundry portálról is tesztelhető.

Következő lépések

Üzemeltetett ügynökökkel kapcsolatos fogalmak

  • Last updated on