Foundry hostovaní agenti

Hostovaní agenti ve službě agenta Microsoft Foundry umožňují nasadit agenty Agent Framework jako kontejnerizované aplikace do Microsoft spravované infrastruktury. Platforma zpracovává škálování, trvalost stavu relace, zabezpečení a správu životního cyklu, abyste se mohli soustředit na logiku vašeho agenta. Agenti Microsoft Foundry Hosted Agents jsou nyní obecně dostupní.

Díky integraci hostování v rámci Agent Frameworku můžete s minimem kódu zpřístupnit Agent, včetně workflow zapouzdřeného pomocí Workflow.as_agent(), prostřednictvím protokolu Foundry Responses nebo Invocations.

Kdy použít hostované agenty

Zvolte agenty hostované v Foundry, pokud chcete:

  • Spravovaná infrastruktura – nemusíte konfigurovat kontejnery, webové servery ani pravidla škálování sami.
  • Integrovaná správa relací – platforma zachovává stav a nahrané soubory během přechodů mezi interakcemi a období nečinnosti.
  • Identita vyhrazeného agenta – každý nasazený agent získá vlastní identitu Entra pro zabezpečený přístup k modelům, nástrojům a podřízeným službám.
  • Koncové body kompatibilní s OpenAI – klienti můžou komunikovat s vaším agentem pomocí libovolné sady SDK kompatibilní s OpenAI prostřednictvím protokolu Odpovědi.

Poznámka:

Integrace jazyka Python agent-framework-foundry-hosting je ve verzi Preview. Hostovaní agenti Microsoft Foundry, spravovaná hostingová služba, jsou nyní obecně dostupní.

Prerequisites

  • Předplatné Azure
  • rozhraní příkazového řádku pro vývojáře Azure (azd) s rozšířením agenta AI: azd ext install azure.ai.agents

Pro místní testování potřebujete také:

Nainstalujte hostující balíček NuGet:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 nebo novější

Nainstalujte předem připravený balíček pro hostování, klienta Foundry a Azure ověřovací balíček:

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

V Foundry poskytuje platforma kontext uživatele volajícího a kontext volání; hostitelská infrastruktura je používá k izolaci stavu na uživatele a předávání kontextu žádosti do služeb Foundry. Při místním spuštění aplikace nezískají kontext dané platformy, takže si v případě potřeby musí zajistit vlastní mechanismy pro identitu a řízení stavu.

Protokol odpovědí

Protokol odpovědi je doporučeným výchozím bodem pro většinu agentů. Zpřístupní koncový bod kompatibilní /responses s OpenAI a platforma automaticky spravuje historii konverzací, streamování a životní cyklus relací.

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

Vytváří AgentHost.CreateBuilder server aplikace předkonfigurovaný pro hostitelské prostředí Foundry. AddFoundryResponses zaregistruje vašeho agenta pomocí obslužné rutiny protokolu Odpovědi a MapFoundryResponses mapuje /responses koncový bod HTTP.

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

Zabalí ResponsesHostServer agenta a zpřístupní ho prostřednictvím protokolu Foundry Responses. U agenta, který není agentem pracovního postupu, používá výchozí možnost history_source="agent_server" jako zdroj historie modelu nakonfigurovaného poskytovatele odpovědí serveru agenta. Hostitel zabraňuje službě podřízeného modelu zachovat druhou kopii, když klient ukládá historii ve výchozím nastavení.

Nekombinujte výchozí zdroj historie s hodnotou HistoryProvider , která obsahuje load_messages=True. Také nenastavujte možnosti pokračování navazující služby conversation_id, previous_response_id ani conversation. Hostitel tyto konfigurace odmítne, aby zabránil duplicitní historii.

Používá se ResponsesHostServer(agent, history_source="agent") , když poskytovatel historie agenta nebo služba podřízeného modelu musí spravovat historii konverzací. Tento režim předává pouze aktuální vstup požadavku ze serveru Agent Server a zachovává historii agenta a chování úložiště služby. Vlastní SupportsAgentRun implementace musí tento režim používat. Parametr store zůstane samostatný: vybere zprostředkovatele odpovědí, který zachovává vstupy a výstupy rozhraní API odpovědi v obou režimech.

Hostitel vlastní dodaného agenta a může přidat zprostředkovatele kontextu specifického pro hostování. Nepoužívejte agenta znovu s jiným hostem ani ho nevyvolávejte přímo po vytvoření hosta.

Zachování stavu a zpracování dlouhotrvajících konverzací

ResponsesHostServer nakonfiguruje úložiště s podporou Foundry ve výchozím nastavení. Pro agenty, které nejsou součástí pracovního postupu, AgentSessionStoreProvider poskytuje FoundryAgentSessionStore. Pro agenty pracovního postupu poskytuje CheckpointStoreProviderFoundryCheckpointStore. FunctionApprovalStoreProvider FoundryFunctionApprovalStore poskytuje žádost o schválení čekající na vyřízení. Tato úložiště používají při hostování Foundry State Store a při místním spuštění místní stav serveru Agent.

S history_source="agent" nakonfigurované úložiště relací uchovává stav poskytovatele přenášený pomocí AgentSession, včetně zpráv z InMemoryHistoryProvider.

Pokud chcete přizpůsobit úložiště, předejte StoreProvider do agent_session_store_provider nebo function_approval_store_provider. Předejte ContextScopedStoreProvider do checkpoint_store_provider. Například implementujte SessionStore a StoreProvider[SessionStore], abyste mohli používat vlastní úložiště relací agenta mimo pracovní postup.

Importujte ResponsesServerOptions z azure.ai.agentserver.responsesparametru a předejte ho ResponsesHostServer prostřednictvím parametru options . Dostupné možnosti dlouhotrvající konverzace závisí na typu agenta:

Schopnost Typ agenta Požadavky a chování
Odolné odpovědi na pozadí Pouze pracovní postup Nastavte ResponsesServerOptions(resilient_background=True). Odešlete žádost o odpovědi s store=true a background=true. Po restartu host obnoví nejnovější kontrolní bod trvalého pracovního postupu nebo znovu přehraje původní vstup, pokud žádný kontrolní bod neexistuje. Nekonfigurujte úložiště kontrolních bodů v pracovním postupu, protože ho hostitel spravuje. Zajistěte, aby externí vedlejší efekty byly idempotentní, protože operace po posledním perzistentním kontrolním bodu se mohou opakovat.
Řiditelné konverzace Pouze bez pracovního postupu Nastavte ResponsesServerOptions(steerable_conversations=True) a odešlete žádosti o odpovědi pomocí store=true. Zachovejte tahy v jednom lineárním řetězci opětovným použitím stejné hodnoty conversation. Případně odešlete bezprostředně předcházející previous_response_id a zachovejte vyhodnocené agent_session_id. Hostitel odmítne zastaralé předchůdce, kteří by vytvořili fork.

ResponsesHostServer vyvolá RuntimeError, pokud povolíte odolné odpovědi na pozadí pro agenta bez pracovního postupu nebo řiditelné konverzace pro agenta pracovního postupu. Úplné implementace najdete v ukázkách vlastního úložiště, odolného dlouhotrvajícího pracovního postupu a řiditelného dlouhotrvajícího agenta.

Pokud nástroj MCP hostovaný foundry vyžaduje souhlas uživatele, ResponsesHostServer vrátí neúplnou odpověď s výstupní položkou oauth_consent_request . Předložte uživateli jeho consent_link a poté pokračujte s ID neúplné odpovědi jako previous_response_id poté, co uživatel udělí souhlas. Hostitel uchovává relaci agenta pro tento opakovaný pokus a zpřístupňuje pouze absolutní odkazy HTTPS pro udělení souhlasu.

Protokol vyvolání

Protokol Vyvolání poskytuje úplnou kontrolu nad požadavkem a odpovědí HTTP. Použijte ho, pokud potřebujete vlastní datové části, nekoverzační zpracování nebo streamovací protokoly, které nejsou kompatibilní s OpenAI.

Při použití protokolu Invocations v jazyce C# implementujete vlastní InvocationHandler, abyste zpracovali příchozí požadavky.

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

Metoda AddInvocationsServer zaregistruje služby protokolu Invocations. Implementujete InvocationHandler , abyste definovali, jak agent zpracovává jednotlivé požadavky.

Pro odlehčenou instalaci použijte InvocationsHostServer z agent_framework_foundry_hosting balíčku. Zabalí vašeho agenta podobně jako ResponsesHostServer a automaticky spravuje relaci.

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

Pro úplnou kontrolu nad zpracováním požadavků použijte InvocationAgentServerHost přímo z balíčku a implementujte vlastní azure.ai.agentserver.invocations rutinu vyvolání:

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

Při restartování dojde ke ztrátě úložiště relací v paměti v příkladu vlastní obslužné rutiny. V produkčním prostředí používejte trvalé úložiště (například Cosmos DB).

Kompletní nasazení Invocations najdete v ukázce Telegramu hostované ve Foundry. Umístí službu API Management před webhook hostovaného agenta a používá spravované identity, Key Vault a Cosmos DB pro trvalou historii konverzací.

Poznámka:

Podpora Go pro agenty hostované v Foundry bude brzy k dispozici. Nejnovější stav najdete v úložišti Agent Framework Go .

Tip

Příklady hostovaného projektu agenta najdete v ukázkách Python nebo ukázkách C#. Nebo pomocí azd ai agent init příkazu vygenerujte nový projekt hostovaného agenta úplně od začátku. Podrobné pokyny najdete v této příručce pro rychlý start .

Lokální spuštění

Rozhraní příkazového řádku pro vývojáře Azure (azd) poskytuje nejjednodušší způsob, jak spustit a otestovat hostovaného agenta místně.

Inicializace projektu

Vytvořte novou složku a inicializujete ji z ukázkového manifestu:

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

Tip

Manifest může být cesta k místnímu souboru YAML nebo adrese URL vzdáleného manifestu.

Nastavení proměnných prostředí

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

Spusťte hostitele agenta

azd ai agent run

Hostitel agenta se spustí na http://localhost:8088.

Vyvolání agenta

azd ai agent invoke --local "Hello!"

Nebo použijte curl:

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

Nebo v PowerShellu:

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

Nasazení do Foundry

Jakmile agenta ověříte místně, nasaďte ho do služby Microsoft Foundry:

  1. Poskytnutí zdrojů (pokud ještě projekt Foundry nemáte):

    azd provision

    Tím se vytvoří skupina prostředků s instancí Foundry, projektem, nasazením modelu, Application Insights a registrem kontejneru.

  2. Nasazení agenta:

    azd deploy

    Tím se váš agent zabalí jako image kontejneru, odešle ji do Azure Container Registry a nasadí ji do služby Foundry Agent Service.

Infrastruktura hostování Foundry automaticky vloží následující proměnné prostředí do kontejneru agenta za běhu:

Proměnné Description
FOUNDRY_PROJECT_ENDPOINT Adresa URL koncového bodu pro projekt Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Název nasazení modelu (nakonfigurovaný během azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING Řetězec připojení Application Insights pro telemetrii.

Po nasazení je váš agent přístupný prostřednictvím vyhrazeného koncového bodu Foundry a dá se také otestovat z portálu Foundry.

Další kroky

Koncepty hostovaných agentů

  • Last updated on