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ő.

Előfeltételek

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.",
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

A ResponsesHostServer rendszer becsomagolja az ügynököt, és a Foundry Responses protokollon keresztül teszi elérhetővé. store beállítása False-re a default_options beszélgetési előzmények duplikálását akadályozza meg, mivel az üzemeltetési infrastruktúra automatikusan kezeli az előzményeket.

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

Figyelmeztetés

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.

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.

Tipp

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>

Tipp

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:

Változó 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