Foundry Hostade Agenter

Hosted-agenter i Microsoft Foundry Agent Service kan du distribuera Agent Framework-agenter som containerbaserade program till Microsoft hanterad infrastruktur. Plattformen hanterar skalning, sessionstillståndsbeständighet, säkerhet och livscykelhantering så att du kan fokusera på agentens logik. Microsoft Foundry Hosted Agents är allmänt tillgänglig.

Med agentramverkets värdintegrering kan du exponera ett Agent, inklusive ett arbetsflöde omslutet med Workflow.as_agent(), via protokollet Foundry Responses eller Invocations med minimal kod.

När värdbaserade agenter ska användas

Välj Foundry-värdbaserade agenter när du vill:

  • Hanterad infrastruktur – du behöver inte konfigurera containrar, webbservrar eller skalningsregler själv.
  • Inbyggd sessionshantering – plattformen bevarar $HOME och uppladdade filer över omgångar och inaktiva perioder.
  • Dedikerad agentidentitet – varje distribuerad agent får sin egen Entra-identitet för säker åtkomst till modeller, verktyg och underordnade tjänster.
  • OpenAI-kompatibla slutpunkter – klienter kan interagera med din agent med valfri OpenAI-kompatibel SDK via protokollet Svar.

Anmärkning

Python-integreringen agent-framework-foundry-hosting är en förhandsversion. Microsoft Foundry Hosted Agents, den hanterade värdtjänsten, är allmänt tillgänglig.

Förutsättningar

För lokal testning behöver du också:

Installera NuGet-värdpaketet:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 eller senare

Installera värdpaketet för förhandsversion, Foundry-klienten och Azure autentiseringspaketet:

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

I Foundry tillhandahåller plattformen anroparens användarkontext och samtalskontext. värdinfrastrukturen använder dem för att isolera tillstånd per användare och vidarebefordra begärandekontext till Foundry-tjänster. Lokala körningar får inte den plattformskontexten, så applikationer måste tillhandahålla egna kontroller för identitet och tillstånd vid behov.

Svarsprotokoll

Protokollet Svar är den rekommenderade startpunkten för de flesta agenter. Den exponerar en OpenAI-kompatibel /responses slutpunkt och plattformen hanterar konversationshistorik, strömning och sessionslivscykel automatiskt.

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

AgentHost.CreateBuilder skapar ett programvärd som är förkonfigurerat för värdmiljön Foundry. AddFoundryResponses registrerar din agent med svarsprotokollhanteraren och MapFoundryResponses mappar /responses HTTP-slutpunkten.

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

Omsluter ResponsesHostServer din agent och exponerar den via protokollet Foundry Responses. Om du anger storeFalse i default_options undviks duplicering av konversationshistorik eftersom värdinfrastrukturen hanterar historiken automatiskt.

Anropsprotokoll

Protokollet Anrop ger dig fullständig kontroll över HTTP-begäran och -svaret. Använd den när du behöver anpassade nyttolaster, icke-konversationsbearbetning eller direktuppspelningsprotokoll som inte är OpenAI-kompatibla.

Med protokollet Anrop i C# implementerar du en anpassad InvocationHandler för att bearbeta inkommande begäranden:

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

Metoden AddInvocationsServer registrerar protokolltjänsterna för anrop. Du implementerar InvocationHandler för att definiera hur din agent bearbetar varje begäran.

För en enkel installation använder du InvocationsHostServer från agent_framework_foundry_hosting paketet. Den omsluter din agent på samma sätt som ResponsesHostServer och hanterar sessionshantering automatiskt:

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

För fullständig kontroll över hanteringen av förfrågningar, använder du InvocationAgentServerHost från azure.ai.agentserver.invocations-paketet direkt och implementerar din egen anroparhanterare.

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

Varning

Minnesinternt sessionsarkiv i exemplet med anpassad hanterare går förlorat vid omstart. Använd varaktig lagring (till exempel Cosmos DB) i produktion.

Anmärkning

Go-stöd för värdbaserade agenter i Foundry blir snart tillgängligt. Se Agent Framework Go-lagringsplatsen för den senaste statusen.

Tips/Råd

Se exemplen Python eller C# för exempel på ett värdbaserat agentprojekt. Eller använd azd ai agent init kommandot för att skapa ett nytt värdbaserat agentprojekt från grunden. I den här snabbstartsguiden finns stegvisa instruktioner.

Körs på lokal nivå

AZURE Developer CLI (azd) är det enklaste sättet att köra och testa din värdbaserade agent lokalt.

Initiera ett projekt

Skapa en ny mapp och initiera från ett exempelmanifest:

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

Tips/Råd

Manifestet kan vara en sökväg till en lokal YAML-fil eller en URL till ett fjärrmanifest.

Ange miljövariabler

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

Kör agentvärden

azd ai agent run

Värddator för agenten startar och körs på http://localhost:8088.

Anropa agenten

azd ai agent invoke --local "Hello!"

Eller använd curl:

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

Eller i PowerShell:

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

Distribuera till Foundry

När du har verifierat din agent lokalt distribuerar du den till Microsoft Foundry:

  1. Etablera resurser (om du inte redan har ett Foundry-projekt):

    azd provision

    Då skapas en resursgrupp med en Foundry-instans, ett projekt, en modelldistribution, Application Insights och ett containerregister.

  2. Distribuera agenten:

    azd deploy

    Detta paketerar din agent som en containeravbildning, push-överför den till Azure Container Registry och distribuerar den till Foundry Agent Service.

Foundry-värdinfrastrukturen matar automatiskt in följande miljövariabler i din agentcontainer vid körning:

Variabel Description
FOUNDRY_PROJECT_ENDPOINT Slutpunkts-URL:en för Foundry-projektet.
AZURE_AI_MODEL_DEPLOYMENT_NAME Namnet på modelldistributionen (konfigurerades under azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING Anslutningssträng för Application Insights-telemetri.

När agenten har distribuerats är den tillgänglig via sin dedikerade Foundry-slutpunkt och kan även testas från Foundry-portalen.

Nästa steg

Begrepp för värdbaserade agenter

  • Last updated on