Foundry által üzemeltetett ügynökök

Az Microsoft Foundry Agent Service üzemeltetett ügynökei lehetővé teszik tárolóalapú ügynökalkalmazások üzembe helyezését Microsoft felügyelt infrastruktúrában. 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 Hosted Agents általánosan elérhető, és támogatja a saját kóddal vagy előnyben részesített ügynök-keretrendszerrel létrehozott ügynököket. Ez a cikk kifejezetten az Agent Framework üzemeltetési integrációját ismerteti.

Az Agent Framework üzemeltetési integrációjával minimális kóddal teheti elérhetővé a Agent elemet a Foundry Responses vagy az Invocations protokollon keresztül. A Python a natív Workflow szolgáltatás közvetlen üzemeltetését is támogatja anélkül, hogy ügynökké konvertálná.

Megjegyzés:

Más keretrendszerekkel készült ügynökkódokat is üzembe helyezhet a Foundry által üzemeltetett ügynökökben Azure fejlesztői parancssori felület (azd) munkafolyamataival. A keretrendszer-agnosztikus fogalmakról és az üzembe helyezési útmutatóról lásd: Mik azok a üzemeltetett ügynökök? A cikk további része az Agent Framework integrációjával foglalkozik.

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.
  • Valós idejű hangügynökök esetén használja az üzemeltetett ügynököket a Azure Speech in Foundry Tools (Voice Live) használatával a kiszolgálóoldali hangtevékenység-észleléshez, a visszhanglemondáshoz és a zajcsökkentéshez. A részletekért lásd: A Voice Live használata hosztolt ügynökökkel.

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

A Python által üzemeltetett ügynökök esetében a korán befejeződő válasz incomplete állapotú. A streaming ügyfelek response.incomplete termináleseményt kapnak, míg a nem streaming ügyfelek esetében a incomplete értéke status. A content_filter befejezési ok leképeződik a content_filter elemre, amelynek értéke incomplete_details.reason, és a length leképeződik a max_output_tokens elemre. A létrehozott kimeneti vagy elutasítási tartalmak továbbra is elérhetők maradnak a válaszban.

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("FOUNDRY_MODEL")
    ?? 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.get("FOUNDRY_MODEL") or 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é. A hívó store mezője határozza meg, hogy a külső válasz, valamint a gazdagép által kezelt munkamenet és a jóváhagyás állapota mentésre kerül-e. A history_source beállítás egymástól függetlenül választja ki, hogy ki adja meg a modellelőzményeket:

history_source Modellelőzmények viselkedése
"agent_server" (alapértelmezett) A hoszt rekonstruálja a tárolt külső Responses-átiratot, és letiltja a downstream szolgáltatás általi tárolást a duplikált előzmények elkerülése érdekében.
"service" A gazdarendszer csak az aktuális bemenetet küldi el, és saját maga számára menti a tároló modellszolgáltatás folytatási azonosítóját. A tárolt szolgáltatói beszélgetések nem ágazhatnak el egy korábbi válaszból.
"agent" A gazda csak az aktuális bemenetet küldi. Az ügynök HistoryProvider vagy a lejjebb lévő szolgáltatás tárolási alapértelmezett beállításai kezelik az előzményeket.

Ne kombinálja a(z) "agent_server" vagy "service" elemet terhelésre engedélyezett HistoryProvider elemmel. Az alapértelmezett mód elutasítja az olyan rögzített alsóbb rétegbeli folytatási beállításokat is, mint a conversation_id, previous_response_idés conversation. Használja a SupportsAgentRun elemet egyéni history_source="agent" megvalósításhoz.

A response_store konstruktorparaméter kiválasztja a külső válaszok megőrzésének háttérrendszerét. A régebbi konstruktorparaméter store egy elavult alias a következőhöz response_store: egyik paraméter sem állítja be a hívó kérésenkénti store mezőjét. A(z) store=false-val rendelkező kérés egyszer használatos: nem menti a gazdagép által kezelt állapotot, letiltja a támogatott alsóbb rétegbeli tárolást, és nem használhatja a(z) background=true elemet.

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.

A Responses-gazdagép megőrzi a natív rendszerhívásokat, a képernyőképeket és a biztonsági ellenőrzéseket. Az alkalmazásnak végre kell hajtania a kért műveleteket, és kifejezetten el kell fogadnia a biztonsági ellenőrzéseket. A teljes folyamatért tekintse meg a natív számítógéphasználatot.

Válasszon ügynökpéldányt vagy gyárat

Mind a InvocationsHostServer, mind a ResponsesHostServer elfogad egy ügynökpéldányt vagy egy nulla argumentumú, szinkron vagy aszinkron hívható objektumot a agent paraméteren keresztül. A gazdagép élettartama alatt újrafelhasznál egy példányt. Egy hívható objektum kérésenként egyszer fut le, és a visszaadott ágens az adott kéréshez tartozik.

Akkor használjon hívhatót, ha egy normál ügynök a módosítható állapotot a(z) AgentSession elemen kívül tartja fenn. A gazdagépek csak a támogatott munkamenet-, ellenőrzőpont- és függvény-jóváhagyási tárolókat őrzik meg, nem pedig egy kérés hatókörű ügynök tetszőleges mezőit.

Warning

A WorkflowAgent, például a workflow.as_agent(), agent= használatával történő üzemeltetése elavult. A WorkflowAgent munkafolyamat állapota a futtatások között memóriában marad, ezért egy példánynak soha nem szabad különböző felhasználók vagy beszélgetések kéréseit kiszolgálnia. A munkafolyamat natív módon hosztolható a workflow= és egy kéréstudatos factory használatával.

Amíg nem migrál egy Responses hostot, a minden kéréshez friss munkafolyamatot, végrehajtókat, burkolt ügynököket, ügyfeleket, szolgáltatókat és eszközöket létrehozó gyár a biztonságos, örökölt megoldás. A munkafolyamat nevének és a végrehajtóazonosítóknak stabilnak kell maradnia, hogy a gazdagép visszaállíthassa az ellenőrzőpontokat. Az Invocations-gazdagépek esetében ez az örökölt gyártómetódus-forma csak az állapot nélküli, egyfordulós munkafolyamatoknak felel meg, mivel az ügynök üzemeltetése nem állítja vissza a munkafolyamat ellenőrzőpontjait.

Akkor is használjon gyárat, ha egy integráció kérési identitást hordoz, vagy kérésspecifikus erőforrásokkal rendelkezik. Hozzon létre például MCP-kapcsolatokat, eszközkészleteket, készségszolgáltatókat, Search-klienseket, memóriaszolgáltatókat és azok hitelesítő adatait a factoryn belül, ha azok az aktuális platformhívást vagy felhasználói kontextust használják. A folyamatszintű MCP-kapcsolat újbóli használata megőrizheti a megnyitott kérés identitását.

A hoszt minden kérés esetén belép a gyárilag létrehozott ágensekbe, majd kilép belőlük. Agent környezet által felügyelt ügyfeleket és MCP-eszközöket kezel, de a gyárnak be kell zárnia az általa létrehozott egyéb szolgáltatót, szállítást vagy hitelesítő adatokat. Ne zárja be azokat a megosztott objektumokat, amelyeket az alkalmazás a gyáron kívülről adott meg.

Natív munkafolyamat futtatása a Responses használatával

A Python közvetlenül futtathat egy létrehozott munkafolyamatot a(z) workflow= használatával. A natív munkafolyamat parse_response visszahívást igényel, amely az aktuális Responses-kérést egy tipizált kezdő bemenetre vagy a függőben lévő válaszok teljes kötegére képezi le:

from pydantic import BaseModel

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    HostedResponseRequest,
    ResponsesHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    text: str


def build_workflow(request: HostedResponseRequest):
    return build_fresh_workflow()


async def parse_response(request: HostedResponseRequest) -> WorkflowTurn[Ticket]:
    items = await request.get_input_items()
    if any(item.get("type") in ("function_call_output", "mcp_approval_response") for item in items):
        return WorkflowTurn(responses=await request.get_workflow_responses())

    text = await request.get_input_text()
    return WorkflowTurn(input=Ticket.model_validate_json(text or ""))


server = ResponsesHostServer(
    workflow=build_workflow,
    parse_response=parse_response,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[f"{Ticket.__module__}:{Ticket.__qualname__}"],
    ),
)

A háttérmunka szüneteltetésére, folytatására vagy helyreállítására képes munkafolyamatokhoz használjon kérésérzékeny szinkron vagy aszinkron gyármetódust. A gyárnak egy frissen összeállított gráfot kell visszaadnia friss módosítható végrehajtókkal, ügynökökkel, ügyfelekkel, szolgáltatókkal és eszközökkel. A munkafolyamat nevének és a végrehajtóazonosítóknak stabilnak kell maradnia, hogy a gazdagép visszaállíthassa a külső válaszhoz társított pontos ellenőrzőpontot.

A Trusted Platform User és a Foundry tesztkörnyezet elkülöníti a natív munkafolyamat állapotát. A gazdagép ellenőrzi a teljes függőben lévő válaszköteget, mielőtt bármilyen válaszjogosultságot használ. Az elavult, részleges, duplikált, visszajátszott, felhasználóközi és tesztkörnyezetközi válaszok a munkafolyamat végrehajtása előtt meghiúsulnak. Egy store=false tartalmazó kérés nem menti a munkafolyamat állapotát, és nem tud folytatható szünetet visszaadni.

Az örökölt munkafolyamatok esetében, amelyek elfogadják list[Message], az aktuális Responses-forduló konvertálásához használja a(z) response_input_messages(request) elemet. Nem tölti be a korábbi külső előzményeket, és nem dekódolja a függőben lévő munkafolyamat-válaszokat. A hosztolás agent=workflow.as_agent() a jelenlegi bétaverzióban továbbra is elérhető marad, de elavulási figyelmeztetést ad ki. A teljes példák megtekintéséhez tekintse meg a natív válaszok munkafolyamat-mintáit.

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

ResponsesHostServer és InvocationsHostServer alapértelmezés szerint konfigurálja az állandó munkamenet-tárolókat. AgentSessionStoreProvider egy FoundryAgentSessionStore biztosít; a Responses-munkamenetek a agent_sessions logikai tárolót használják, míg az Invocations-munkamenetek a különálló invocation_sessions tárolót használják. Ezek az adattárak hosztolt környezetben a Foundry State Store-t, helyi futtatáskor pedig az SDK fájlalapú tárolását használják.

A Responses munkafolyamat-ügynökök esetében a CheckpointStoreProvider egy FoundryCheckpointStore biztosít. A natív válaszok és hívások munkafolyamatai ugyanazt a providert használják a pontos folytatási ellenőrzőpontjaikhoz. FunctionApprovalStoreProvider egy lehetőséget biztosít a függőben lévő ügynökeszköz-jóváhagyásokhoz. A natív munkafolyamat-kérelmek és jóváhagyási válaszok ehelyett munkafolyamat-ellenőrzőpontokhoz vannak kötve.

Az Foundryben való futtatáskor az alapértelmezett Python a névtér állapotát a platform felhasználói azonosítója és az Foundry tesztkörnyezet munkamenet-azonosítója alapján tárolja. Az egyes állapotműveletekhez platformhívás-azonosítót is igényelnek. A hívásazonosító engedélyezi és korrelálja a műveletet; ez nem beszélgetésazonosító, és nem része a tárkulcsnak.

A Responses esetében a platform által konfigurált FOUNDRY_AGENT_SESSION_ID azonosítja a sandbox-környezetet, és a rendszer elutasít egy ettől eltérő, a hívó által megadott agent_session_id-t. Az Invocations esetén a gazdagép a(z) agent_session_id útválasztott lekérdezési paramétert a kérelem kontextusával összevetve ellenőrzi. Ha a(z) FOUNDRY_AGENT_SESSION_ID nincs konfigurálva, a lekérdezési paraméternek jelen kell lennie, nem lehet üres, és meg kell egyeznie a kérés kontextusával. A hiányzó, ismétlődő vagy ütköző értékek SDK-tartalékazonosító használata helyett elutasításra kerülnek.

Ezek a garanciák az alapértelmezett üzemeltetett üzletekre vonatkoznak. Az egyéni tárolószolgáltatóknak egyenértékű felhasználói és sandbox-elkülönítést kell megvalósítaniuk, a belső AgentSession.session_id elemet a gazdagép-keresési kulcsoktól elkülönítve kell megőrizniük, és feltételes írásokat kell alkalmazniuk, hogy az elavult kérések ne írhassák felül az újabb pillanatképeket. Új kulcsok esetén a feltétel nélküli beszúrás vagy frissítés helyett kizárólag létrehozásra szolgáló írásokat kell használni. Tekintse meg az ETag által védett írásokkal és törlésekkel rendelkező Cosmos DB-implementáció egyéni tárolási mintáját .

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.

Mindkét gazdagép elfogadja a StoreProvider[SessionStore] és agent_session_store_provider közötti tartományt. A munkamenet-állapotnak támogatnia kell a AgentSession szerializálását. Regisztrálja az egyéni állapottípusok kodekjeit a(z) register_state_type() használatával; a visszaállított állapot nem őrzi meg a Python-objektumok azonosságát. Az új alapértelmezett tárolók a munkameneteket az utolsó írást követően 30 nap után járatják le. Az egyéni szolgáltatók maguk szabályozzák a megőrzést.

A hatókörözött alapértelmezett tárolók nem olvassák a régi, hatókör nélküli agent_sessions, invocation_sessions, ellenőrzőpont- vagy függvényjóváhagyási adatokat. A régi previous_response_id vagy a beszélgetési azonosító újbóli használata helyett kezdjen új Válaszok beszélgetést. A meghívások egy üres Agent Framework-munkamenettel kezdődnek a hatókörrel rendelkező tárolóban.

A betöltött AgentSession rekordok ETag-feltételeket használnak. Ha egy másik kérés előbb előrébb viszi ugyanannak a munkamenetnek az állapotát, az elavult írási művelet meghiúsul, ahelyett hogy felülírná az újabb állapotot. Ez az ellenőrzés nem biztosít tranzakciókat vagy pontosan egyszeri végrehajtást ügynök- vagy eszközoldali hatások esetén, ezért az alkalmazásoknak továbbra is koordinálniuk kell az átfedésben lévő kéréseket.

Responses-specifikus tároláshoz adjon át egy StoreProvider elemet a function_approval_store_provider számára, vagy egy ContextScopedStoreProvider elemet a checkpoint_store_provider számára.

A külső háttérben futó feladat a lekérdezéshez a hívó számára látható response.id elemet használja. Az alapértelmezett background_source="agent_server" beállítás a hoszton hagyja a háttérben történő végrehajtást. A(z) history_source="service" elemet csak background_source="provider" és egy tárolást biztosító, folytatható Responses klienssel állítsa be. Ha a(z) ResponsesServerOptions(resilient_background=True) is be van állítva, a gazdagép csak a privát folytatási token mentése után tudja helyreállítani a szolgáltató lekérdezését. Tegye idempotenssé a helyi eszközműveletek mellékhatásait, mert ha a következő token mentése előtt összeomlás történik, a rendszer újra lefuttathatja azokat.

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
Munkafolyamat-ellenőrzőpont háttérbeli helyreállítása 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.
Szolgáltatói natív háttérválaszok Nem munkafolyamat jellegű Agent válaszokat tároló klienssel Állítsd be history_source="service" és background_source="provider". Állítsa be a(z) resilient_background=True értéket, ha azt szeretné, hogy a mentett szolgáltatói folytatási tokenek a gazdagép újraindítása után is megmaradjanak.
Irányítható beszélgetések Ideiglenesen nem érhető el Ne állítsa be a parancsot steerable_conversations=True. A gazda a létrehozás során mindaddig RuntimeError jelez, amíg az Agent Server SDK biztonságosan nem kezeli az elutasított vezérlési fordulókat.

A teljes implementációkért tekintse meg az egyéni tárterületet, az alapszintű válaszok előzményeit és hátterét, valamint a rugalmas, hosszú ideig futó munkafolyamat-mintákat .

Fájlok olvasása a üzemeltetett tesztkörnyezetből

Az üzemeltetett tesztkörnyezet állandóját $HOME ne általános fájlrendszerhatárként, hanem kérésvezérelt erőforrásként kezelje. Csak olyan fájlokat fogadjon el, amelyeket az alkalmazás explicit módon feltölt egy dedikált könyvtárba, ellenőrizze az aktuális tesztkörnyezeti identitást, és elutasítsa az abszolút elérési utakat, a bejárást, a hivatkozásokat, a nemreguláris fájlokat, valamint a túlméretezett vagy érvénytelen tartalmakat.

A Válaszok protokoll esetében irányítsa a kérést egy üzemeltetett munkamenetbe a agent_session_id törzsmezővel. A lekérdezési karakterlánc választója az Invocationshoz tartozik. A munkamenet-feltöltések és az Eszközkészlet kódértelmező fájljai különálló erőforrások; a feltöltött tesztkörnyezetfájl nem lesz automatikusan eszközkészlet-tárolóba csatlakoztatva. A korlátozott UTF-8-olvasásról, valamint a helyi és üzemeltetett feltöltésre vonatkozó útmutatásért tekintse meg a munkamenetfájl-mintát.

Kérelmek beállításainak szabályozása

A gazda a natív válaszgenerálási mezőket az Agent Framework futtatási beállításaihoz képezi le. Például lesz max_output_tokens, max_tokens és parallel_tool_calls leszallow_multiple_tool_calls. A(z) extra_body egyszerűsített értékei felülbírálják a lefordított natív értékeket.

A szinkron vagy aszinkron prepare_options(request, options) horoggal eltávolíthatja vagy lecserélheti a hívómodell beállításait a normál ügynök futtatása előtt. A kapcsolódási pont nem képes beállítani a gazdagép által vezérelt identitás-, tárolási, folytatási vagy átviteli mezőket. Olyan egyéni SupportsAgentRun-implementáció esetén, amely nem képes fogadni a futásidejű modellbeállításokat, állítsa a(z) unsupported_options értékét a következők egyikére: "warn" (alapértelmezett), "ignore" vagy "error".

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

Ha a kiszolgáló ismeri az elvárt engedélyezési forrásokat, korlátozza a beleegyezési hivatkozásokat ezzel: allowed_oauth_consent_origins

server = ResponsesHostServer(
    agent,
    allowed_oauth_consent_origins=[
        "https://logic-region.consent.azure-apihub.net",
        "https://auth.partner.example",
    ],
)

Ha kihagyja az engedélyezési listát, az abszolút HTTPS-ellenőrzést a célhely korlátozása nélkül is megőrzi. Ha üres listát ad meg, az elutasít minden hozzájárulási hivatkozást. Csak pontos HTTPS-forrásokat konfiguráljon; az elérési úttal, lekérdezéssel vagy töredékkel rendelkező bejegyzések elutasításra kerülnek.

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.get("FOUNDRY_MODEL") or 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()

InvocationsHostServer elfogadja a Responses-gazdagéphez ismertetett példány- vagy kérés hatókörű gyári formákat. Visszaállítja a szerializált munkameneteket a konfigurált tárolóból, így a befejezett beszélgetések folytatódhatnak a gazdagép újraindítása után. A tárolási viselkedésről, a megőrzésről és a testreszabásról az Állapot megőrzése és a hosszan futó beszélgetések kezelése című témakörben olvashat.

Hosztolt környezetben az Invocations a Az állapot megőrzése és a hosszan futó beszélgetések kezelése című részben ismertetett ellenőrzött kérési hatókört használja. Kezelje a(z) AgentSession.session_id elemet egy átlátszatlan értékként; ne értelmezze, és ne támaszkodjon a belső ábrázolására. A helyi futtatások megtartják a meglévő egyfelhasználós tárolási viselkedésüket.

Hosztoljon natív munkafolyamatot az Invocations használatával

Natív munkafolyamat üzemeltetéséhez adjon át workflow= és egy explicit parse_request visszahívást. A visszahívás az alkalmazás JSON-sémáját kezeli, és egy WorkflowTurn tipizált bemenetet vagy a teljes függőben lévő válaszköteget ad vissza:

from pydantic import BaseModel
from starlette.requests import Request

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    InvocationsHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    ticket_id: str
    question: str


class TicketDecision(BaseModel):
    approved: bool


def build_workflow(_request: Request):
    return build_fresh_workflow()


async def parse_request(request: Request) -> WorkflowTurn[Ticket]:
    payload = await request.json()
    stream = payload.get("stream", False)

    if "responses" in payload:
        decisions = {
            request_id: TicketDecision.model_validate(value)
            for request_id, value in payload["responses"].items()
        }
        return WorkflowTurn(responses=decisions, stream=stream)

    ticket = Ticket.model_validate(payload)
    return WorkflowTurn(input=ticket, stream=stream)


server = InvocationsHostServer(
    workflow=build_workflow,
    parse_request=parse_request,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[
            f"{Ticket.__module__}:{Ticket.__qualname__}",
            f"{TicketDecision.__module__}:{TicketDecision.__qualname__}",
        ],
    ),
)

Minden egyéni alkalmazástípust foglaljon bele, amelyet a munkafolyamat ment az ellenőrzőpont-szolgáltató allowed_checkpoint_types listájába.

Az üzemeltetett munkafolyamatokhoz egy kéréstudatos factoryra van szükség, amely egy friss, felépített gráfot ad vissza stabil munkafolyamat- és végrehajtóazonosítókkal. A közvetlen beépített munkafolyamat csak olyan helyi, egyszeri futtatáshoz érhető el, amely nem áll le.

A nem streamelő munkafolyamat-válaszok application/json formátumot használnak, és output eseménylistát tartalmaznak. A streamelés során keretezett output és request_info eseményeket küld, majd a done eseményt csak az egzakt munkafolyamat-kurzor mentése után küldi. A streamelt kimenetet ideiglenesnek kell tekinteni, amíg done. A natív munkafolyamatok nem támogatják a(z) legacy_wire_format=True elemet.

A hoszt a megbízhatófelhasználó- és a tesztkörnyezet-hatókörben a pontos függőben lévő ellenőrzési ponttal szemben ellenőrzi a válaszokat. Ha egy munkafolyamat több függőben lévő kéréssel rendelkezik, válaszoljon a teljes kötegre egyetlen lépésben. Futtatható elemző, típussal ellátott ticket-munkafolyamat, ellenőrzőponttípus engedélyezési listája és JSON/SSE-példák esetén tekintse meg a native Invocations workflow sample-t.

Híváskérések és válaszok testreszabása

Alapértelmezés szerint POST /invocations elfogad egy JSON-objektumot egy sztringgel message, egy opcionális options objektummal és egy opcionális logikai stream értékkel. Az alkalmazásspecifikus adattartalom elfogadásához adjon át egy szinkron vagy aszinkron parse_request visszahívási függvényt, amely InvocationRun(messages, options, stream) értéket ad vissza. Használja a prepare_options elemet a hívásgenerálási beállítások egy példányának szűrésére vagy cseréjére, mielőtt az ügynök futása megkezdődik.

A gazdagép ellenőrzi a hook kimenetét, és elutasítja a platformazonossági, tárolási, folytatási és ügynökvégrehajtási vezérlőket. Azon ügynökök esetén, amelyek nem fogadnak el futásidejű beállításokat, állítsa a unsupported_options értékét "warn"-re (ez az alapértelmezett), "ignore"-re vagy "error"-ra. A teljes megvalósításhoz tekintse meg az Invocations elemzőmintát .

A nem streamelt sikeres válasz a(z) {"response": "..."} formátumú JSON-t adja vissza. A streamelés kiszolgáló által küldött eseményeket használ: egy vagy több event: delta képkockát, amelyet event: done sikeres vagy event: error sikertelen események követnek. Az adatfolyam a hiba előtt is kibocsáthat deltafrissítéseket, ezért az ügyfeleknek a sikeres befejezés jeleként a(z) done elemet kell értelmezniük, nem pedig egy deltát. A gazdagép csak azután bocsát ki done , hogy véglegesíti a válaszfolyamot, és megőrzi a AgentSession. A session_id platform tesztkörnyezetének útvonalazonosítója, nem a szerializált AgentSession.session_id.

A legacy_wire_format=True beállítását csak olyan meglévő ügyfelek áttelepítésekor végezze el, amelyek az előző egyszerű szöveges választ és a nyers szövegrészlet-folyamot igénylik. Ez a kompatibilitási mód elavult, és nem konvertálja a hibákat sikeres szöveggé. A gazdagép csak egy folyamaton belül szerializálja az azonos munkamenet-kérelmeket; a folyamatközi összehasonlítási és felcserélési ütközés a külső eszközeffektusok után is előfordulhat.

Az Invocations protokoll nem folytatja a függőben lévő vagy megszakított munkafolyamat-futtatásokat. Használja az egyéni kezelőmintát a következő szakaszban, ha eltérő munkafolyamat-folytatási viselkedésre van szüksége.

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.get("FOUNDRY_MODEL") or 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

Az üzemeltetett ügynökprojektek példáiért tekintse meg a Python vagya C#-mintákat. 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álja azt egy minta azure.yaml fájljából. Az útmutatóhoz használja a tároló üzembe helyezését:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -t <path-to-azure.yaml> --src . --deploy-mode container

Tip

Cserélje le a(z) <path-to-azure.yaml> elemet a minta azure.yaml projektdokumentumának helyi elérési útjára vagy támogatott GitHub URL-címére.

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

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL="<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 Az azd által felügyelt modell üzembe helyezési neve a(z) azd ai agent init során van konfigurálva. A Python-kód helyben ezt részesítheti előnyben FOUNDRY_MODEL, és visszatérhet ehhez az üzemeltetett értékhez.
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

  • Utolsó frissítés időpontja: