Microsoft Foundry Ügynök Szolgáltatás

FoundryAgentaz Ügynök-keretrendszert a Microsoft Foundry Agent Service által felügyelt ügynökdefinícióhoz csatlakoztatja. Az ügynök modellje, utasításai, üzemeltetett eszközei és verziója a Foundryben van konfigurálva; az alkalmazás ehhez a definícióhoz csatlakozik, és a standard Agent Framework-futtatási, streamelési és munkamenet-API-kat használja.

Használja ezt az integrációt a következő célokra:

• A kiszolgálóoldali ügynökdefiníciók nevesített és verziószámozott ügynökdefiníciók kérése.
• Üzemeltetett ügynökök, amelyek ügynökspecifikus végponton keresztül elért üzembe helyezett ügynökalkalmazások.

Ha közvetlen modellkövetkeztetést keres, amelyben az alkalmazásé az ügynökdefiníció, tekintse meg Microsoft Foundry-modell szolgáltatóját. Az Agent Framework-alkalmazás üzemeltetett ügynökként való üzembe helyezéséhez lásd: Foundry Hosted Agents.

A csomagok telepítése

dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Csatlakozás parancssori ügynökhöz

Hozzon létre egy AIProjectClient elemet az Foundry-projekthez, és csomagolja be a AgentReference következőt FoundryAgent: . Rögzítse a verziót, amikor az alkalmazásnak egy adott Parancssori ügynök definíciót kell használnia.

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

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!),
    new DefaultAzureCredential());

FoundryAgent agent = projectClient.AsAIAgent(
    new AgentReference(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!,
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION")!));

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

Lekérheti ProjectsAgentRecord azt is, hogy a legújabb vagy a ProjectsAgentVersion kifejezetten lekért verziót használja, majd átadja az objektumot.projectClient.AsAIAgent(...)

A Prompt Agent legújabb verziójának lekérése

Akkor használható AgentAdministrationClient , ha az alkalmazásnak név alapján kell feloldania a legújabb regisztrált verziót.

ProjectsAgentRecord agentRecord =
    await projectClient.AgentAdministrationClient.GetAgentAsync(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!);

FoundryAgent latestAgent = projectClient.AsAIAgent(agentRecord);
Console.WriteLine(await latestAgent.RunAsync("What can you help me with?"));

Important

Az A FoundryAgent a Foundry definíciójában tárolt modellt, utasításokat és üzemeltetett eszközöket használja. Konfigurálja ezeket a képességeket a Foundryben; az ügyfél nem tudja lecserélni őket futásidőben.

Warning

DefaultAzureCredential a fejlesztéshez kényelmes. Éles környezetben előnyben részesítsen egy adott hitelesítő adatot, például ManagedIdentityCredential hogy elkerülje a nem szándékos hitelesítőadat-készítést.

Csatlakozás üzemeltetett ügynökhöz

Az üzemeltetett ügynökök egy ügynökspecifikus OpenAI-végpontot tehetnek közzé. Hozza létre a végpontot a projektvégpontból és a regisztrált ügynök nevéből, majd adja át neki AIProjectClient.AsAIAgent(...).

Env.TraversePath().Load();

// Port the Hosted-* samples listen on when run locally with `dotnet run`.
const int LocalAgentPort = 8088;

// AZURE_AI_AGENT_NAME is the registered server-side agent name.
string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");

// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
// exposes; with neither, ask at startup.
    ══════════════════════════════════════════════════════════
    """);
Console.ResetColor();
Console.WriteLine();

A végpont rendszergazda által vezérelt verzióválasztója határozza meg az aktív üzemeltetett ügynök verzióját.

A csomagok telepítése

pip install agent-framework-foundry

Configuration

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

A parancssori ügynökökhöz használható FOUNDRY_AGENT_VERSION . A üzemeltetett ügynökök kihagyhatják.

Csatlakozás parancssori ügynökhöz

Adja meg a projektvégpontot, az ügynök nevét és az ügynök verzióját. A szolgáltatás biztosítja a tárolt modellt, utasításokat és üzemeltetett eszközök konfigurációját.

async def main() -> None:
    agent = FoundryAgent(
        project_endpoint="https://your-project.services.ai.azure.com",
        agent_name="my-prompt-agent",
        agent_version="1.0",
        credential=AzureCliCredential(),
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

    # Streaming
    print("Agent (streaming): ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Ha egy parancssori ügynök helyi függvényeszközt deklarál, a konstruktálás FoundryAgent során adja át a megfelelő hívható eszközttools=, hogy az ügyfél igény szerint végrehajthassa. Tekintse meg a Prompt Agent közzétételi és csatlakozási mintáját.

Csatlakozás üzemeltetett ügynökhöz

A üzemeltetett ügynökök nem igényelnek agent_version. Csatlakozzon a projektvégponthoz és a regisztrált ügynök nevéhez.

async def main() -> None:
    # HostedAgents don't need agent_version
    agent = FoundryAgent(
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        agent_name=os.getenv("FOUNDRY_AGENT_NAME"),
        credential=AzureCliCredential(),
    )

    result = await agent.run("Summarize the latest news about AI.")
    print(f"Agent: {result}")

Mi működik és mi nem működik FoundryAgent

FoundryAgent olyan ügynökdefinícióhoz csatlakozik, amely már létezik a Foundryben. A tárolt utasítások és az eszközkonfiguráció mérvadó, ezért az ügyféloldali viselkedés eltér az alkalmazás tulajdonában lévőtől Agent(client=FoundryChatClient(...)).

Eszközök

A(z) FoundryAgent(...) részére átadott eszköztípus	Magatartás
FunctionToolhelyi Python hívható	Csak akkor támogatott, ha az egyező függvénydefiníció már létezik az Foundry-ügynökön. A hívható az alkalmazásfolyamatban fut, amikor a Foundry kéri.
Üzemeltetett eszközök, beleértve a webkeresést, a kódértelmezőt, a fájlkeresést, az MCP-t, a képgenerálást és a Microsoft Foundry Toolboxot	Konfigurálja ezeket az Foundry-ügynök definícióján. Az ügyféloldali átadás nem adja hozzá őket a szolgáltatás által felügyelt ügynökhöz.

Az eszközkészlet mellékletét és a közvetlen MCP-használati útmutatót az Microsoft Foundry Toolboxban találja.

Nem regisztrálhat új, modellen látható eszközt az építkezéskor. A hívható függvények átadása csak az Öntödei ügynök által már deklarált függvény helyi implementációját biztosítja.

Kontextus biztosítók

A kontextusszolgáltató működése	Működik a(z) FoundryAgent elemmel?
Üzeneteket ad hozzá, például lekért memóriát, RAG-kódrészleteket vagy felhasználói profiladatokat	Yes. Az injektált kontextus a kéréssel együtt továbbításra kerül.
Megőrzi vagy megfigyeli a beszélgetést	Yes. A szolgáltató helyileg fut a kérés és a válasz körül.
Eszközök dinamikus hozzáadása	Nem, kivéve, ha ezek az eszközök már deklarálva vannak az Foundry-ügynök definícióján.

Akkor használható Agent(client=FoundryChatClient(...)) , ha az alkalmazásnak dinamikus eszközválasztásra, képességbetöltésre vagy bármilyen olyan viselkedésre van szüksége, amely futásidőben módosítja a modellen látható eszközöket.

Futtatási beállítások

Mivel az Foundry-ügynök definíciója az igazság forrása, nem minden lehetőség halad át default_options vagy agent.run(...) van tiszteletben.

Option	Az ügynök viselkedésének kérése
model	Figyelmen kívül hagyott. A modell az Foundry-ügynök definíciójából származik.
\, \, \	El lett távolítva a kérelemből. Az eszközöket deklarálni kell az Foundry-ügynök definícióján.
instructions rendszer- vagy fejlesztői üzenetek	Figyelmen kívül hagyott. A tárolt öntödei utasítások mérvadóak.
conversation_id	Adott esetben az Öntödei ügynök munkamenete használható és leképezhető.
extra_body	Továbbítva és egyesítve a keretrendszer által biztosított ügynökreferenciával.
Mintavételezési paraméterek, metaadatok, user, storeés response_format	Továbbítva, de az Foundry-ügynök vagy a modell konfigurációja felülbírálhatja vagy korlátozhatja őket.

A üzemeltetett ügynökök ugyanazt az ügyféloldali szűrést kapják, de az üzembe helyezett ügynök bármilyen továbbított beállítást elfogadhat, figyelmen kívül hagyhat vagy újraértelmezhet. Ellenőrizze a viselkedést az adott üzemeltetett ügynökkel szemben.

Tip

Akkor használható Agent(client=FoundryChatClient(...)) , ha futtatásonkénti vezérlésre van szüksége az utasítások, a létrehozási beállítások vagy az eszközök felett.

Üzemeltetett ügynök szolgáltatás munkamenetének kezelése

A szolgáltatásoldali munkameneteket használó üzemeltetett ügynököknek az előzetes Válaszok felületre van szükségük:

Hozza létre explicit módon a szolgáltatási munkamenetet, amikor az alkalmazásnak egy bérlőhöz vagy felhasználóhoz kell kötnie, majd az azonosítóját ügynök-keretrendszer-munkamenetként kell burkolnia.

    queries = [
        "Hi!",
        "Your name is Javis. What can you do?",
        "What is your name?",
    ]
    for query in queries:
        print(f"\nUser: {query}")
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run(query, session=session, stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
    print()


async def run_service_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
) -> None:
    """Let Foundry create the hosted-agent session, then delete it when finished."""
    session = AgentSession()
    print("\nService-managed hosted-agent session")
    print(f"Before first request: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    try:
        await run_conversation(agent, session)
        print(f"After conversation: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    finally:
        hosted_session_id = session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)
        if isinstance(hosted_session_id, str) and hosted_session_id:
            await project_client.agents.delete_session(agent_name, hosted_session_id)
            print(f"Deleted session: {hosted_session_id}")


async def run_user_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
    agent_version: str | None,
) -> None:
    """Create, attach, and delete a hosted-agent session explicitly."""
    resolved_agent_version = agent_version
    if resolved_agent_version is None:
        agent_details = await project_client.agents.get(agent_name)
        resolved_agent_version = agent_details.versions.latest.version

    hosted_session = await project_client.agents.create_session(
        agent_name,
        version_indicator=VersionRefIndicator(agent_version=resolved_agent_version),
    )
    session = AgentSession()
    session.state[FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY] = hosted_session.agent_session_id

    print("\nUser-managed hosted-agent session")
    print(f"Created session: {hosted_session.agent_session_id}")
    try:
        await run_conversation(agent, session)
    finally:
        await project_client.agents.delete_session(agent_name, hosted_session.agent_session_id)
        print(f"Deleted session: {hosted_session.agent_session_id}")


async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(

Tip

A teljes példáért tekintse meg a using_deployed_agent.py mintát .

Egyéni HTTP-időtúllépés beállítása

FoundryAgent alapértelmezés szerint örökli az OpenAI SDK időtúllépését. Adja át timeout= másodpercek alatt, ha a többfordulós beszélgetések vagy a hálózati feltételek eltérő korlátot igényelnek.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,
)

Az időtúllépés a HTTP-ügyfél ügynökönkénti példányára van alkalmazva, és nem érinti az azonos elemet AIProjectClienthasználó többi ügynököt.

Megjegyzés:

FoundryAgent A parancssori és a üzemeltetett ügynökök integrációja jelenleg nem érhető el az Agent Framework Go-hoz. A legújabb állapotot az Agent Framework Go-adattárában tekinthet meg.

Beszélgetések futtatása, streamelése és folytatása

A csatlakozás után ugyanazokat az API-kat használja, mint a többi Agent Framework-ügynök:

• Kérelem futtatása a következővel vagy runa következővelRunAsync:
• Frissítések streamelése a vagy run(..., stream=True)a RunStreamingAsync .
• A beszélgetés folytatásához használja újra az ant AgentSession .
• Az Foundry kiszolgálóoldali beszélgetési API-kat akkor használja, ha a beszélgetésnek láthatónak és tartósnak kell lennie az Foundry-projektben.

Az Foundry-ügynök nevei, verziói, végpontjai és beszélgetésazonosítói megbízható kiszolgálóoldali állapotban maradnak. A meglévő beszélgetés folytatása előtt engedélyezze a hívót.

Következő lépések

Microsoft Foundry-modell szolgáltató áttekintése