Foundry Hostade Agenter

• .NET 10 SDK eller senare

Installera NuGet-värdpaketet:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --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

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

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

Omsluter ResponsesHostServer din agent och exponerar den via protokollet Foundry Responses. Anroparens store fält styr om det yttre svaret och värdhanterade sessionen och godkännandetillståndet sparas. Inställningen history_source väljer oberoende vem som tillhandahåller modellhistorik:

Kombinera inte "agent_server" eller "service" med en lastaktiverad HistoryProvider. Standardläget avvisar även fasta fortsättningsalternativ för nedströms, till exempel conversation_id, previous_response_idoch conversation. Använd history_source="agent" för en anpassad implementering av SupportsAgentRun.

Konstruktorparametern response_store väljer bakänden för beständig lagring av yttre svar. Den äldre konstruktorparametern store är ett inaktuellt alias för response_store. Ingen av parametrarna anger anroparens fält per begäran store . En begäran med store=false är en engångsbegäran: den sparar inte värdhanterat tillstånd, inaktiverar stödd nedströmslagring och kan inte använda background=true.

Värden äger den tillhandahållna agenten och kan lägga till värdspecifika kontextleverantörer. Återanvänd inte agenten med en annan värd eller anropa den direkt efter värdkonstruktionen.

Responses-värden bevarar inbyggda datoranrop, skärmbilder och säkerhetskontroller. Ditt program måste utföra de begärda åtgärderna och uttryckligen bekräfta eventuella säkerhetskontroller. Det fullständiga flödet finns i Intern datoranvändning.

Välj en agentinstans eller fabrik

Både ResponsesHostServer och InvocationsHostServer accepterar antingen en agentinstans eller ett nollargument synkront eller asynkront anrop via parametern agent . Värdprocessen återanvänder en instans under hela dess livstid. En anropsbar funktion körs en gång per begäran, och den returnerade agenten tillhör den aktuella begäran.

Använd en anropbar funktion när en vanlig agent har ett muterbart tillstånd utanför AgentSession. Värdarna bevarar endast de sessions-, kontrollpunkts- och funktionsgodkännandelager som stöds, inte godtyckliga fält i en agent med begärandeomfång.

Använd även en fabrik när en integrering bär begärandeidentitet eller äger begärandespecifika resurser. Du kan till exempel skapa MCP-anslutningar, verktygslådor, kompetensprovidrar, sökklienter, minnesprovidrar och deras autentiseringsuppgifter i fabriken när de använder det aktuella plattformsanropet eller användarkontexten. Om du återanvänder en processomfattande MCP-anslutning kan du behålla identiteten för den begäran som öppnade den.

Värden går in i och lämnar agenter som skapats av fabriken för varje begäran. Agent hanterar kontexthanterade klienter och MCP-verktyg, men din fabrik måste stänga alla andra leverantörer, transporter eller autentiseringsuppgifter som skapas. Stäng inte delade objekt som programmet levererade utanför fabriken.

Kör ett inbyggt arbetsflöde med Responses

Python kan köra ett skapat arbetsflöde direkt via workflow=. Ett nativt arbetsflöde kräver ett parse_response återanrop som mappar den aktuella Responses-begäran till antingen en typad startinmatning eller den fullständiga batchen med väntande svar:

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__}"],
    ),
)

Använd en begärandemedveten synkron eller asynkron fabrik för arbetsflöden som kan pausa, fortsätta eller återuppta bakgrundsarbete. Fabriken måste skapa och returnera en nybyggd graf med nya föränderliga exekverare, agenter, klienter, leverantörer och verktyg. Håll arbetsflödets namn och exekverar-ID:n stabila så att värden kan återställa den exakta kontrollpunkt som är associerad med det yttre svaret.

Den betrodda plattformsanvändaren och Foundry-sandbox-miljön isolerar det inbyggda arbetsflödets tillstånd. värden validerar en komplett väntande svarsbatch innan den förbrukar någon svarsbehörighet. Inaktuella, partiella, duplicerade, återspelade svar över användare och sandboxar misslyckas innan arbetsflödet körs. En begäran med store=false sparar inte arbetsflödestillståndet och kan inte returnera en återupptagbar paus.

För ett äldre arbetsflöde som accepterar list[Message] använder du response_input_messages(request) för att konvertera endast den aktuella svarsturen. Den läser inte in tidigare yttre historik eller avkodar väntande arbetsflödessvar. Hosting agent=workflow.as_agent() är fortfarande tillgängligt under den aktuella betaversionen, men genererar en utfasningsvarning. Fullständiga exempel finns i exemplen på arbetsflödet Native Responses.

Spara tillstånd och hantera långvariga konversationer

ResponsesHostServer och InvocationsHostServer konfigurera beständiga sessionslager som standard. AgentSessionStoreProvider tillhandahåller en FoundryAgentSessionStore. Svarssessioner använder det logiska arkivet agent_sessions , medan anropssessioner använder det separata invocation_sessions arkivet. Dessa lagringsplatser använder Foundry State Store när de körs i en värdmiljö och SDK:ns filbaserade lagring när du kör lokalt.

För agenter för arbetsflödet Responses tillhandahåller CheckpointStoreProvider en FoundryCheckpointStore. Arbetsflöden för inbyggda svar och anrop använder samma leverantör för sina exakta fortsättningskontrollpunkter. FunctionApprovalStoreProvider tillhandahåller ett FoundryFunctionApprovalStore för väntande godkännanden för agentverktyg. Svar på inbyggda arbetsflödesbegäranden och godkännanden är bundna till arbetsflödeskontrollpunkter i stället.

När den körs i Foundry lagrar standardversionen av Python namnrymdens tillstånd utifrån plattformsanvändar-ID:t och Foundry-sandlådesessions-ID:t. De kräver också ett plattformsanrops-ID för varje tillståndsåtgärd. Anrops-ID:t auktoriserar och korrelerar åtgärden. det är inte ett konversations-ID och är inte en del av lagringsnyckeln.

För svar identifierar den plattformskonfigurerade FOUNDRY_AGENT_SESSION_ID sandboxen, och ett annat agent_session_id som anges av anroparen avvisas. För anrop verifierar värden den dirigerade agent_session_id frågeparametern mot begärandekontexten. Om FOUNDRY_AGENT_SESSION_ID inte har konfigurerats måste frågeparametern finnas, inte vara tillgänglig och matcha begärandekontexten. Saknade, duplicerade eller motstridiga värden avvisas i stället för att använda ett SDK-återställnings-ID.

Dessa garantier gäller för de standardhostade butikerna. Anpassade butiksprovidrar måste implementera motsvarande användar- och sandbox-isolering, bevara det inre AgentSession.session_id separat från värdsökningsnycklarna och använda villkorliga skrivningar så att inaktuella begäranden inte kan skriva över nyare ögonblicksbilder. Nya nycklar bör använda skrivningar endast vid skapande i stället för villkorslösa upserts. Se det anpassade lagringsexemplet för en Cosmos DB-implementering med ETag-skyddade skrivningar och borttagningar.

Med history_source="agent" bevarar den konfigurerade sessionslagringen leverantörstillstånd som förmedlas av AgentSession, inklusive meddelanden från InMemoryHistoryProvider.

Båda värdarna accepterar en StoreProvider[SessionStore] via agent_session_store_provider. Sessionstillståndet måste ha stöd för AgentSession serialisering. Registrera codecs för anpassade tillståndstyper med register_state_type(); återställt tillstånd bevarar inte Python objektidentitet. Nya standarddatalager låter sessioner upphöra att gälla 30 dagar efter att de senast skrevs till. Anpassade leverantörer styr sin egen lagringstid.

Standardlagringsplatserna med omfång läser inte äldre data utan omfång, agent_sessions, invocation_sessions, kontrollpunktsdata eller data om funktionsgodkännande. Starta en ny svarskonversation i stället för att återanvända ett gammalt previous_response_id eller konversations-ID. Anrop börjar med en tom Agent Framework-session i det avgränsade lagret.

Inlästa AgentSession poster använder ETag-villkor. Om en annan begäran avancerar samma session först misslyckas den inaktuella skrivningen i stället för att skriva över nyare tillstånd. Den här kontrollen tillhandahåller varken transaktioner eller exakt en gång-exekvering för bieffekter på agent- eller verktygssidan, så applikationer måste fortfarande koordinera överlappande begäranden.

För Svarsspecifik lagring skickar du en StoreProvider till function_approval_store_provider eller en ContextScopedStoreProvider till checkpoint_store_provider.

Yttre bakgrundsarbete använder det response.id, som är synligt för anroparen, för pollning. Standardinställningen background_source="agent_server" behåller bakgrundskörningen i värden. Ange background_source="provider" endast med history_source="service" och en lagrande, återupptagbar Responses-klient. Om ResponsesServerOptions(resilient_background=True) också anges kan värdsystemet återuppta avsökningen av providern först efter att det har sparat den privata fortsättningstokenen. Gör lokala verktygsbieffekter idempotenta eftersom en krasch innan nästa token sparas kan upprepa dem.

Importera ResponsesServerOptions från azure.ai.agentserver.responsesoch skicka den till ResponsesHostServer via parametern options . Vilka alternativ för långvariga konversationer som är tillgängliga beror på agenttypen:

Fullständiga implementeringar finns i anpassad lagring, grundläggande svarshistorik och bakgrund samt elastiska långvariga arbetsflödesexempel .

Läsa filer från den värdbaserade sandbox-miljön

Behandla en hostad sandlådas beständiga $HOME som en resurs som dirigeras per begäran, inte som en allmän gräns för filsystemet. Acceptera endast filer som programmet uttryckligen laddar upp till en dedikerad katalog, verifiera den aktuella sandbox-identiteten och avvisa absoluta sökvägar, blädrering, länkar, icke-regulära filer och överdimensionerat eller ogiltigt innehåll.

För protokollet Responses skickar du en begäran till en värdsession med fältet agent_session_id i brödtexten. Frågesträngsväljaren är för anrop. Sessionsuppladdningar och kodtolkarfiler i Verktygslådan är separata resurser. en uppladdad sandbox-fil monteras inte automatiskt i en Toolbox-container. Se exempel på sessionsfiler för begränsade UTF-8-läsningar och vägledning för lokal och värdbaserad uppladdning.

Alternativ för kontrollbegäran

Värdprogrammet mappar inbyggda fält för Responses-generering till körningsalternativ i Agent Framework. Blir till exempel max_output_tokensmax_tokens, och parallel_tool_calls blir allow_multiple_tool_calls. Utplattade värden från extra_body åsidosätter översatta inbyggda värden.

Använd den synkrona eller asynkrona prepare_options(request, options) hooken för att ta bort eller ersätta anroparens modellalternativ innan en vanlig agent körs. Kroken kan inte ange värdstyrda identitets-, lagrings-, fortsättnings- eller transportfält. För en anpassad SupportsAgentRun implementering som inte kan acceptera körningsmodellalternativ anger du unsupported_options till "warn" (standard), "ignore"eller "error".

Hantera OAuth-medgivandebegäranden

När ett Foundry-värdbaserat MCP-verktyg kräver användarmedgivande returnerar ResponsesHostServer ett ofullständigt svar med ett oauth_consent_request utdataobjekt. Presentera dess consent_link för användaren och fortsätt sedan med det ofullständiga svarets ID som previous_response_id när användaren har slutfört medgivandet. Värden bevarar agentsessionen för detta återförsök och tillhandahåller endast absoluta HTTPS-samtyckeslänkar.

Om värden känner till de förväntade auktoriseringsursprungen begränsar du samtyckeslänkar med allowed_oauth_consent_origins:

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

Om tillåtelselistan utelämnas behålls validering av absolut HTTPS utan att målursprunget begränsas. Om du anger en tom lista avvisas alla medgivandelänkar. Konfigurera endast exakta HTTPS-ursprung; poster som innehåller en sökväg, frågesträng eller fragment avvisas.

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.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 stöder samma instans- eller fabriksformer med begäransomfång som beskrivs för Responses-värden. Den återställer serialiserade sessioner från den konfigurerade lagringsplatsen, så att pågående konversationer kan fortsätta efter att värden har startats om. Information om lagringsbeteende, kvarhållning och anpassning finns i Behåll tillstånd och hantera långvariga konversationer.

När Invocations finns i en värdmiljö använder det det verifierade begäransomfång som beskrivs i Bevara tillstånd och hantera långvariga konversationer. Behandla AgentSession.session_id som ett ogenomskinligt värde; tolka det inte och förlita dig inte på dess interna representation. Lokala körningar behåller sitt befintliga lagringsbeteende för en enskild användare.

Vara värd för ett nativt arbetsflöde med Invocations

Ange workflow= och ett explicit parse_request återanrop för att vara värd för ett nativt arbetsflöde. Återanropet äger programmets JSON-schema och returnerar en WorkflowTurn med antingen typad indata eller den fullständiga väntande svarsbatchen:

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__}",
        ],
    ),
)

Inkludera alla anpassade applikationstyper som arbetsflödet sparar i kontrollpunktsproviderns allowed_checkpoint_types lista.

Värdbaserade arbetsflöden kräver en begäransmedveten fabrik som returnerar en nybyggd graf med stabila arbetsflödes- och exekverar-ID:n. Ett arbetsflöde som byggs direkt är endast tillgängligt för en lokal engångskörning som inte pausar.

Arbetsflödessvar som inte strömmas använder program-JSON med en output händelselista. Streaming genererar inramade output-händelser och request_info-händelser, och done-händelser först efter att den exakta arbetsflödesmarkören har sparats. Behandla strömmade utdata som preliminär tills done är klar. Nativa arbetsflöden stöder legacy_wire_format=Trueinte.

Värd validerar svar mot den exakta väntande kontrollpunkten inom den betrodda användar- och sandboxomfattningen. Om ett arbetsflöde har flera väntande begäranden, svarar du på hela batchen i ett svep. För en körbar parser, typat ärendearbetsflöde, tillåtslista för kontrollpunktstyper och JSON/SSE-exempel, se arbetsflödesexemplet Native Invocations.

Anpassa begäranden och svar om anrop

Som standard POST /invocations accepterar ett JSON-objekt med en sträng message, ett valfritt options objekt och ett valfritt booleskt stream värde. Om du vill acceptera en applikationsspecifik nyttolast anger du ett synkront eller asynkront parse_request återanrop som returnerar InvocationRun(messages, options, stream). Använd prepare_options för att filtrera eller ersätta en kopia av anroparens genereringsalternativ innan agenten körs.

Värden validerar utdata från hooken och avvisar plattformsidentitets-, lagrings-, fortsättnings- och agentkörningskontroller. För agenter som inte accepterar körningsalternativ anger du unsupported_options till "warn" (standard), "ignore", eller "error". Se exemplet på parsern för anrop för en fullständig implementation.

Vid lyckat icke-streaminganrop returneras JSON i formatet {"response": "..."}. Direktuppspelning använder server skickade händelser: en eller flera event: delta bildrutor, följt av event: done lyckade eller event: error misslyckade. En dataström kan skicka deltauppdateringar innan ett fel uppstår, så klienter måste tolka done, inte ett delta, som att strömmen har slutförts utan fel. Värden genererar done först när den har slutfört svarsströmmen och bevarar AgentSession. Det är session_id plattformens sandbox-rutt-ID, inte det serialiserade AgentSession.session_id.

Använd legacy_wire_format=True endast när du migrerar befintliga klienter som kräver det tidigare svaret i oformaterad text och den råa textchunksströmmen. Det här kompatibilitetsläget är inaktuellt och konverterar inte fel till lyckad text. Värdprocessen serialiserar begäranden inom samma session endast inom en och samma process; en compare-and-swap-konflikt mellan processer kan fortfarande uppstå efter effekter från externa verktyg.

Invocations-protokollet återupptar inte arbetsflödeskörningar som väntar eller har avbrutits. Använd mönstret för anpassad hanterare i följande avsnitt när du behöver ett annat arbetsflödesfortsättningsbeteende.

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

En fullständig distribution av anrop finns i exemplet Foundry-hosted Telegram. Den placerar API Management framför den värdbaserade agentwebbhooken och använder hanterade identiteter, Key Vault och Cosmos DB för varaktig konversationshistorik.