Agent 应用部署上线后可能运行多个实例。有一类请求需要尽力路由到持有状态的同一可用实例，才能继续访问实例内存里正在运行的任务，例如订阅任务事件、取消执行中的任务。本文说明这类请求如何借助会话亲和性访问实例内运行态，以及为什么亲和性不能替代持久化。

背景信息 #

平台在运行时可能同时拉起多个 Agent 实例。默认由平台调度决定一次请求交给哪个可用实例处理，无需应用干预。

区别只出现在带实例内运行态的请求上。当一个请求启动了长任务，任务的运行态（事件流、可取消句柄等）只存在于启动它的那个实例的内存里。平台会尽力将后续请求路由到持有该运行态的同一可用实例；如果原实例不可用，后续请求可能无法访问原运行态。会话亲和性正是为解决这一路由问题而设。

使用会话亲和性路由请求 #

要让平台尽力将相关请求路由到持有状态的同一可用实例，应用必须为同一部署中启动任务的请求以及后续访问同一任务的请求携带相同的 x-iga-pages-conversation-id 请求头（名称大小写不敏感）。平台据此执行会话亲和路由。

await fetch("/api/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-iga-pages-conversation-id": conversationId,
  },
  body: JSON.stringify({ message: "你好" }),
});

使用时需注意几点约束：

• 该头是路由输入，不是身份凭证。 它不代表用户身份、会话授权或不可猜测的 token；Handler 必须按应用定义的 conversationId 格式校验该值，并在多租户场景校验当前用户对该 Conversation 的归属权。
• 同一逻辑会话的全部相关请求必须携带完全相同的值，普通 RPC、流式、取消、停止请求一致，平台才能据此执行会话亲和路由。
• SDK 不会自动读取该请求头。 应用仍需把同一个 conversationId 显式传给 Store 方法、Blob key 与 getConversationSandbox(conversationId)。
• 浏览器原生 EventSource 无法设置自定义请求头，需要携带该头时应改用基于 fetch 的 SSE reader。
• 静态文件及不进入 Agent Function 的请求不适用该机制。

与持久化的边界 #

会话亲和性只在同一部署内提供“尽力而为”的实例粘滞，并不保证实例长期不变。实例失效或被回收后，平台可以选择新的实例；届时携带同一 x-iga-pages-conversation-id 的请求可能无法访问原实例内存里的运行态。因此：

• 会话亲和性面向短生命周期的实例内运行态，用于提高运行中任务在同一可用实例内的可达性。
• 持久化才是长期状态的归宿。需要跨请求、跨实例、跨重启保留的数据，必须由应用通过 Store、Blob 等存储显式保存并在需要时恢复。

换言之，会话亲和性是运行态的路由优化，而非状态的存储方案。凡是不能容忍实例切换而丢失的状态，都应落到持久化存储中。会话状态的持久化参见会话存储 Store，文件类数据参见对象存储 Blob。

本地开发边界 #

iga pages dev 会把 x-iga-pages-conversation-id 原样传给 Handler，但不模拟生产环境的跨实例调度与会话亲和。您可以在单进程中验证事件流、取消和恢复逻辑；真实的跨实例亲和需要在部署环境中验证。