Gunakan satu sesi agen terhosting untuk beberapa pengguna

Secara bawaan, setiap pemanggil mendapatkan sesi agen yang dihosting secara terpisah, seperti yang dijelaskan dalam Mengisolasi sesi agen yang dihosting per pengguna. Aplikasi yang melayani banyak pengguna - bot Teams, gateway ISV, atau platform dukungan pelanggan - tidak memerlukan satu sesi per pengguna. Sebagai gantinya, layanan lapis menengah memetakan banyak pengguna ke sekumpulan sesi bersama yang terbatas dan mengidentifikasi setiap pengguna di setiap panggilan.

Artikel ini menunjukkan cara membuat pool sesi antar pengguna dari lapisan middle tier, sembari memastikan data tiap pengguna tetap terisolasi dalam sesi bersama.

Platform ini mengisolasi status percakapan untuk Anda, bahkan ketika pengguna berbagi sesi: rantai respons yang dibuat oleh satu pengguna tidak dapat dilanjutkan oleh pengguna lain melalui previous_response_id, dan context.get_history() hanya mengembalikan riwayat yang diizinkan untuk dilihat pengguna permintaan saat ini. Anda memiliki dua hal: pemetaan pengguna-ke-sesi di tingkat tengah Anda, dan pemartisian data apa pun yang disimpan kontainer Anda sendiri (file, baris, atau cache) di luar status percakapan yang dikelola platform tersebut.

Contoh multipleks sesi yang lengkap dan dapat dijalankan mendemonstrasikan kedua sisi - pool sesi lapisan menengah dan handler kontainer - dan artikel ini menautkan file-file tersebut di sepanjang pembahasan.

Prasyarat

  • Agen yang dihosting yang menggunakan protokol kontainer versi 2.0.0. Untuk meningkatkan, lihat Memigrasikan agen yang dihosting.
  • Izin Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action yang diberikan kepada identitas layanan lapis menengah Anda. Izin ini tidak disertakan dalam peran bawaan; berikan melalui peran kustom — lihat Mendelegasikan identitas pengguna akhir. Tanpa itu, header x-ms-user-identity ditolak dengan 403.
  • Pustaka klien proyek AI Azure untuk tingkat tengah, dan Azure AI AgentServer SDK untuk kontainer (azure-ai-agentserver-core 2.0.0b7+ untuk Python, atau Azure.AI.AgentServer.Core 1.0.0-beta.26+ untuk .NET).
  • Agen yang disebarkan untuk diuji. Isolasi tidak diterapkan untuk eksekusi lokal.

Mengisolasi dua pengguna dalam sesi bersama

Mulai dari perilaku inti: dua pengguna—sebut saja Alice dan Bob, yaitu pengguna yang diwakili dalam contoh—dapat berbagi satu agent_session_id, dan platform tetap menjaga kerahasiaan percakapan masing-masing pengguna. Lapisan menengah Anda mengidentifikasi pengguna yang diwakili di setiap panggilan dengan header x-ms-user-identity (delegasi). Untuk melanjutkan percakapan pengguna sendiri, ia meneruskan respons pengguna sebelumnya sebagai previous_response_id.

Untuk mengirim header identitas yang sama dari Azure Developer CLI, gunakan azd ai agent invoke --user-identity. Lihat Meneruskan identitas pengguna akhir untuk contoh dan cara memilih sesi pengguna dan status percakapan.

Pemanggil minimal invoke_previous_response_isolation.py dalam sampel mengirimkan persis itu, menggunakan klien Responses SDK yang terikat ke agen:

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

Platform ini mengikat setiap rantai respons dengan pengguna yang membuatnya. Jika Bob mengirim previous_response_id milik Alice saat berada dalam sesi yang sama, panggilan gagal - Bob tidak bisa melanjutkan percakapan Alice. Jaminan itu berlaku tanpa kode isolasi tambahan dalam kontainer Anda.

Skalakan untuk banyak pengguna dengan kumpulan sesi

Pengisolasian dua pengguna dalam satu sesi adalah dasar utamanya. Untuk melayani banyak pengguna, kumpulkan mereka di sekumpulan sesi yang terikat alih-alih membuka satu sesi per pengguna.

Setiap sesi dihitung ke dalam batas sesi serentak regional saat sesi tersebut secara aktif memproses satu giliran interaksi, sehingga satu sesi per pengguna tidak dapat diskalakan. Karena pengguna membaca, berpikir, dan mengetik di sela-sela interaksi, jumlah puncak permintaan serentak Anda biasanya hanya sebagian kecil dari total jumlah pengguna Anda. Tentukan ukuran pool sesuai puncak beban tersebut, lalu petakan setiap pengguna ke sesi di dalamnya dan teruskan identitas pengguna itu pada setiap pemanggilan, tepat seperti pada bagian sebelumnya.

Tentukan cara memetakan pengguna ke sesi. Strategi umum meliputi:

  • Lengket, paling sedikit dimuat. Pengguna yang kembali tetap menggunakan sesi mereka; pengguna baru dialihkan ke sesi dengan beban paling ringan. Strategi ini menyebarkan beban secara merata dan membuat giliran pengguna bersama-sama. Perbesar pool saat sesi mencapai batas per pengguna.
  • Berbasis hash. Tetapkan sesi dengan hash(user_id) % pool_size. Strategi ini sederhana dan tidak menyimpan status, tetapi beban bisa tidak merata dan perubahan ukuran kumpulan dapat mendistribusikan ulang pengguna.
  • Round-robin. Distribusikan permintaan secara merata di seluruh kumpulan. Strategi ini sederhana, tetapi giliran pengguna dapat mendarat pada sesi yang berbeda.
  • Berbasis kelompok. Rutekan menurut penyewa, tim, atau wilayah sehingga pengguna terkait berbagi sesi. Strategi ini berguna ketika pengguna dalam sebuah grup memiliki konteks yang sama.

Pemanggil invoke_session_pool.py dalam sampel mengimplementasikan penetapan milik penelepon dengan dua strategi, sticky-fill dan round-robin. Pengguna yang kembali selalu mempertahankan sesinya; sedangkan pengguna baru akan ditempatkan sesuai strategi yang dipilih. Metode sticky-fill mengisi sesi dengan beban paling ringan dan membuka sesi baru hanya ketika setiap sesi telah mencapai kapasitas:

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

Masukkan ID sesi yang dikembalikan ke dalam panggilan yang didelegasikan yang sama seperti yang ditunjukkan sebelumnya: ID sesi tersebut menjadi agent_session_id dalam extra_body, dan x-ms-user-identity tetap menjadi pengidentifikasi per pengguna.

Menangani permintaan di kontainer Anda

Pada protokol 2.0.0, platform tersebut menentukan pengguna yang diwakili dan menyediakannya kepada handler Anda melalui get_request_context(). Validasi konteks tersebut (anggap gagal jika konteksnya tidak ada, misalnya saat berjalan secara lokal), lalu biarkan platform mengembalikan riwayat tiap pengguna dengan context.get_history(). Handler main.py dalam sampel tidak menyimpan status percakapan sendiri:

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)

Karena platform mengotorisasi context.get_history() per permintaan, pengguna dalam sesi bersama tidak pernah menerima riwayat percakapan pengguna lain.

Pisahkan data per pengguna yang disimpan oleh kontainer Anda

Platform ini mengisolasi riwayat percakapan untuk Anda. Jika kontainer Anda juga menyimpan datanya sendiri - file, baris database, atau cache - data tersebut tidak dipartisi secara otomatis. Kunci dengan ID sesi dan ID pengguna sehingga dua pengguna dalam sesi yang sama tidak dapat melihat data satu sama lain:

partition = (agent_session_id, user_id)

Peringatan

Saat pengguna berbagi sesi, platform tidak mempartisi data yang disimpan kontainer Anda sendiri. Jika kontainer Anda mengindeks data tersebut hanya berdasarkan ID sesi, setiap pengguna dalam pool akan melihat data yang sama. Selalu sertakan ID pengguna dalam kunci partisi.

Baca ID pengguna dari konteks platform per permintaan:

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

Platform ini juga menyisipkan pengguna sebagai header permintaan x-agent-user-id. Jika runtime Anda tidak menggunakan konteks SDK, baca header ini secara langsung.

Platform ini mengisi get_request_context().user_id pada protokol 2.0.0. Jangan pernah menggunakan ID sesi saja untuk data milik pengguna ketika lebih dari satu pengguna dapat memasuki sesi.

Untuk contoh penyimpanan per sesi yang dapat dijadikan dasar, lihat contoh agen pencatat. Sistem ini menggunakan satu file per sesi di bawah $HOME. Untuk sesi bersama, perluas kunci tersebut dengan ID pengguna dari konteks permintaan sehingga setiap pengguna mendapatkan partisi mereka sendiri.

Memverifikasi isolasi

Konfirmasi jaminan dengan uji A-A-B pada sampel, invoke_previous_response_isolation.py. Jalankan pada agen yang telah Anda terapkan dengan dua pengguna yang berbeda (sampel ini secara default menggunakan Alice dan Bob):

  1. Sebagai Alice, buat respons di sesi bersama dan catat id-nya.
  2. Sebagai Alice, buat respons kedua dalam sesi yang sama dengan previous_response_id diatur ke id dari respons pertama, dan ambil id-nya.
  3. Sebagai Bob, dalam sesi yang sama, kirimkan permintaan dengan previous_response_id disetel ke respons kedua Alice. Panggilan gagal - Bob tidak dapat melanjutkan rangkaian Alice.

Gunakan dua pengguna Entra atau ID objek yang berbeda. Dua label yang merujuk ke identitas yang sama bukanlah pengujian antar pengguna yang valid.

Jika mengirim header isolasi lama pada jalur protokol 2.0.0, akan menghasilkan error karena model tersebut telah digantikan oleh konteks pengguna platform.

Konten terkait

  • Terakhir diperbarui pada