Samköra flera användare i en och samma värdbaserade agentsession

Som standard får varje anropare sin egen värdbaserade agentsession, enligt beskrivningen i Isolera värdbaserade agentsessioner per användare. Program som betjänar många användare – en Teams-robot, en ISV-gateway eller en kundsupportplattform – behöver inte en session per användare. I stället mappar en mellannivåtjänst många användare till en begränsad pool med delade sessioner och identifierar varje användare vid varje anrop.

Den här artikeln visar hur du poolar sessioner mellan användare från din mellannivå samtidigt som varje användares data hålls isolerade i en delad session.

Plattformen isolerar konversationstillståndet åt dig, även när användare delar en session: en svarskedja som en användare skapar kan inte fortsättas av en annan användare via previous_response_idoch context.get_history() returnerar endast den historik som den aktuella begärans användare har behörighet att se. Du äger två saker: mappningen från användare till session på mellannivån och partitionering av alla data som containern lagrar ( filer, rader eller cacheminne) utöver det plattformshanterade konversationstillståndet.

Ett fullständigt, körbart exempel på sessionsmultiplexering visar båda sidorna – sessionspoolen i mellanskiktet och containerhanteraren – och den här artikeln länkar till dess filer efter hand.

Prerequisites

  • En värdbaserad agent som använder containerprotokoll version 2.0.0. Information om hur du uppgraderar finns i Migrera värdbaserade agenter.
  • Behörigheten Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action som tilldelats till mellannivåtjänstens identitet. Den här behörigheten ingår inte i inbyggda roller. bevilja den via en anpassad roll – se Delegera slutanvändarens identitet. Utan detta avvisas x-ms-user-identity och ett 403 returneras.
  • Klientbiblioteket Azure AI Projects för mellannivån och Azure AI AgentServer SDK för containern (azure-ai-agentserver-core 2.0.0b7+ för Python eller Azure.AI.AgentServer.Core 1.0.0-beta.26+ för .NET).
  • En distribuerad agent att testa mot. Isolering upprätthålls inte för lokala körningar.

Isolera två användare i en delad session

Börja med kärnbeteendet: två användare – kalla dem Alice och Bob, de som agerat för användarna i exemplet – kan dela en agent_session_id, och plattformen håller fortfarande varje användares konversation privat. Ditt mellanskikt identifierar användaren som anropet utförs för vid varje anrop med huvudet x-ms-user-identity (delegering). För att fortsätta en användares konversation vidarebefordrar den användarens föregående svar som previous_response_id.

Den minimala invoke_previous_response_isolation.py anroparen i exemplet skickar exakt det med hjälp av SDK:s agentbundna svarsklient:

# Agent-bound Responses client from the Foundry SDK.
responses_client = project_client.get_openai_client(agent_name=agent_name).responses

# Target the shared session with agent_session_id, and identify the acted-for
# user with x-ms-user-identity (delegation). Pass previous_response_id to
# continue this user's own chain. Don't send x-agent-user-id; Foundry sets the
# container-side request context after it resolves the user.
kwargs = {
    "input": user_message,
    "stream": False,
    "store": True,
    "extra_body": {"agent_session_id": session_id},
    "extra_headers": {"x-ms-user-identity": user_id},
}
if previous_response_id:
    kwargs["previous_response_id"] = previous_response_id

response = responses_client.create(**kwargs)

Plattformen kopplar varje svarskedja till användaren som skapade den. Om Bob skickar Alices previous_response_id när han sitter i samma session misslyckas samtalet – Bob kan inte fortsätta Alices konversation. Den garantin gäller utan extra isoleringskod i containern.

Skala till många användare med en sessionspool

Att isolera två användare i en session är byggblocket. För att betjäna många användare kan du poola dem över en begränsad uppsättning sessioner i stället för att öppna en session per användare.

Varje session räknas mot de regionala gränserna för samtidiga sessioner medan den aktivt bearbetar en tur, så en session per användare skalas inte. Eftersom användarna läser, tänker och skriver mellan svängar är dina högsta samtidiga begäranden vanligtvis en liten del av det totala antalet användare. Ändra storleken på en pool till den högsta, mappa sedan varje användare till en session i den och skicka användarens identitet vid varje anrop, precis som i föregående avsnitt.

Bestäm hur användare ska mappas till sessioner. Vanliga strategier är:

  • Kladdigt, minst laddat. En återkommande användare återanvänder sin session. nya användare går till den minst inlästa sessionen. Den här strategin sprider belastningen jämnt och håller ihop en användares svängar. Utöka poolen när sessioner når ett tak per användare.
  • Hash-baserad. Tilldela en session med hash(user_id) % pool_size. Den här strategin är enkel och tillståndslös, men belastningen kan vara ojämn och när poolens storlek ändras fördelas användarna om.
  • Round-robin. Distribuera begäranden jämnt över poolen. Den här strategin är enkel, men en användares turer kan hamna i olika sessioner.
  • Gruppbaserad. Dirigera efter klientorganisation, team eller region så att relaterade användare delar sessioner. Den här strategin är användbar när användare i en grupp delar samma kontext.

Anroparen i exemplet invoke_session_pool.py implementerar anroparägd tilldelning med två strategier, sticky-fill och round-robin. En återkommande användare behåller alltid sin session. en ny användare placeras av den valda strategin. Sticky-fill-vägen fyller den minst belastade sessionen och öppnar en ny först när varje session har nått sin kapacitetsgräns:

def get_session_for_user(self, user_id: str) -> str:
    if user_id in self.user_to_session:
        return self.user_to_session[user_id]      # returning user is sticky
    session_id = self._next_fill_session()        # new user: place by strategy
    self.user_to_session[user_id] = session_id
    self.session_user_counts[session_id] += 1
    return session_id

def _next_fill_session(self) -> str:
    # Reuse a session with capacity; open a new one only when all are full.
    session_id = next(
        (s for s, count in self.session_user_counts.items()
         if count < self.max_users_per_session),
        None,
    )
    if session_id is None:
        session_id = self._session_name(len(self.session_user_counts))
        self.session_user_counts[session_id] = 0
    return session_id

Mata in det returnerade sessions-ID:t i samma delegerade anrop som visades tidigare: det blir agent_session_id i extra_bodyoch x-ms-user-identity förblir identifieraren per användare.

Hantera begäran i din container

I protokoll 2.0.0 identifierar plattformen den användare som ageras för och gör den tillgänglig för din hanterare via get_request_context(). Verifiera den kontexten (misslyckas när den saknas, till exempel på lokala körningar) och låt sedan plattformen returnera historiken per användare med context.get_history(). main.py-hanteraren i exemplet har inget eget konversationstillstånd:

from azure.ai.agentserver.core import get_request_context

@app.response_handler
async def handler(request, context, _cancellation_signal):
    ctx = get_request_context()
    if not (ctx.user_id and ctx.call_id):
        # Hosted protocol 2.0.0 populates this context; off-platform it's absent.
        raise ValueError("A user context is required on protocol 2.0.0.")

    user_input = await context.get_input_text() or "Hello!"
    history = await context.get_history()       # platform-authorized for this user
    input_items = _build_input(user_input, history)

    response = _responses_client.create(model=_model, input=input_items, store=False)
    return TextResponse(context, request, text=response.output_text)

Eftersom plattformen auktoriserar context.get_history() per begäran får en användare i en delad session aldrig någon annan användares konversationshistorik.

Partitionera data per användare som din container lagrar

Plattformen isolerar konversationshistoriken åt dig. Om containern också lagrar sina egna data – filer, databasrader eller en cache – partitioneras inte dessa data automatiskt. Ange både sessions-ID:t och användar-ID:t så att två användare i samma session inte kan se varandras data:

partition = (agent_session_id, user_id)

Warning

När användare delar en session partitioneras inte de data som containern lagrar. Om din container indexerar dessa data enbart med sessions-ID ser alla användare i poolen samma data. Inkludera alltid användar-ID:t i partitionsnyckeln.

Läs användar-ID:t från plattformskontexten för varje begäran:

from azure.ai.agentserver.core import get_request_context

def partition_key() -> tuple[str, str]:
    ctx = get_request_context()
    if not ctx or not ctx.user_id:
        raise PermissionError("A user context is required on protocol 2.0.0.")
    return (ctx.session_id, ctx.user_id)   # key all user-owned data by this

Plattformen infogar också användaren som förfrågningshuvudet x-agent-user-id. Om din körmiljö inte använder SDK-kontext läser du headerfilen direkt.

Plattformen fyller i get_request_context().user_id i protokoll 2.0.0. Använd aldrig sessions-ID:t ensamt för användarägda data när fler än en användare kan komma in i sessionen.

Ett exempel på lagring per session att bygga vidare på finns i exemplet med anteckningsagenten. Den skapar en fil per session under $HOME. För en delad session utökar du den nyckeln med användar-ID:t från begärandekontexten så att varje användare får en egen partition.

Kontrollera isolering

Bekräfta garantin med exemplets A-A-B-test, invoke_previous_response_isolation.py. Kör den mot din distribuerade agent med två distinkta användare (exemplet är som standard Alice och Bob):

  1. Som Alice skapar du ett svar i en delad session och samlar in dess id.
  2. Som Alice skapar du ett andra svar i samma session med previous_response_id inställt på det första svarets idoch samlar in dess id.
  3. Som Bob, i samma session, skickar du en begäran med previous_response_id inställt på Alice andra svar. Anropet misslyckas – Bob kan inte fortsätta Alices kedja.

Använd två olika Entra-användare eller objekt-ID:er. Två etiketter som matchar samma identitet är inte ett giltigt test mellan användare.

Om en äldre isoleringsheader skickas på en protokoll-2.0.0-sökväg returneras ett fel, eftersom den modellen har ersatts av plattformens användarkontext.

Relaterat innehåll

  • Last updated on