会话机制与会话隔离

一次请求的组成

会话 Header 位于 HTTP 请求头，AG-UI 和 Chat Completions 则规定请求体及响应的格式。它们处在请求的不同位置，不是三个互斥的选项。

一次 HTTP 请求
├─ URL：选择此次调用的协议接口
├─ Headers
│  ├─ 鉴权 Header：证明调用方有权访问 Endpoint
│  └─ 会话 Header：标识请求属于哪个会话
└─ Body：使用本次所选协议的格式
   ├─ AG-UI：threadId、runId、messages 等
   └─ Chat Completions：model、messages、stream 等

一次请求选择一种协议。协议能力由代码实际实现并在控制台声明，可以实现一种或多种；Agent 实现了两种协议并完成声明时，可以分别通过两个接口调用，但不要把两种协议的请求体混装在一次请求中。接入前以目标 Endpoint 的调用示例为准。两种协议的会话承载位置不同：

AgentCore 控制台的 Chat Completions 调试请求所携带的 sessionId 查询参数属于平台接入用法，不是标准 Chat Completions 的 Body 字段。业务接入时存在多个承载位置，则使用同一个会话值。

调试面板构造方式与业务调用参考

下表的“调试面板实际构造方式”描述调试面板的请求组装行为，“业务调用参考”提供相应的填写建议。业务接口的必填字段、可省略字段及服务端处理规则，以目标 Endpoint 和所用应用的接口约定为准。

AG-UI 和 Chat Completions 的调试请求都包含 messages；服务端是否保存或恢复历史，见“历史与状态的归属”。

场景一：控制台调试 AG-UI 会话

在调试面板中创建会话并输入问题后，面板生成会话标识，并构造类似下面的请求。示例中的地址和标识仅用于说明位置。

POST /ag-ui/agent HTTP/1.1
Host: <agent-endpoint>
Content-Type: application/json
Accept: text/event-stream
X-AgentCore-Session-ID: demo-session-01
<鉴权 Header 名>: <实际鉴权值>

{
  "threadId": "demo-session-01",
  "runId": "demo-run-01",
  "messages": [
    {"id": "demo-message-01", "role": "user", "content": "请介绍这份报告的主题。"}
  ],
  "state": {},
  "tools": [ ],
  "context": [ ],
  "forwardedProps": {}
}

会话标识同时出现在 Header 与 Body 中：选择 AG-UI 并不意味着不再需要会话 Header。

场景二：业务应用继续同一个 AG-UI 会话

调用方自行保存会话标识。第二次调用复用 demo-session-01，并为本次运行使用新的 demo-run-02。服务未自动保存历史时，调用方还需携带上一轮消息，下面的 assistant 内容必须替换成上一轮实际返回结果。

POST /ag-ui/agent HTTP/1.1
Host: <agent-endpoint>
Content-Type: application/json
Accept: text/event-stream
X-AgentCore-Session-ID: demo-session-01
<鉴权 Header 名>: <实际鉴权值>

{
  "threadId": "demo-session-01",
  "runId": "demo-run-02",
  "messages": [
    {"id": "demo-message-01", "role": "user", "content": "请介绍这份报告的主题。"},
    {"id": "demo-message-02", "role": "assistant", "content": "替换为上一轮实际返回的内容。"},
    {"id": "demo-message-03", "role": "user", "content": "请把结论整理为三点。"}
  ],
  "state": {},
  "tools": [ ],
  "context": [ ],
  "forwardedProps": {}
}

新开一段对话时，同时更换会话 Header 的值和 threadId，并只传入新对话需要的消息。更换 runId 只表示开始新一次运行，不表示新开一个会话。

场景三：业务应用调用 Chat Completions 接口

下面的示例与控制台调试使用一致的会话承载位置：查询参数 sessionId 和会话 Header 使用相同的值；Body 使用 Chat Completions 格式，不添加 AG-UI 的 threadId、runId。该查询参数属于平台接入用法，业务调用是否需要携带以目标 Endpoint 的调用示例为准；调用示例包含此参数时，使用与会话 Header 相同的会话值。

POST /openai/v1/chat/completions?sessionId=demo-session-02 HTTP/1.1
Host: <agent-endpoint>
Content-Type: application/json
X-AgentCore-Session-ID: demo-session-02
<鉴权 Header 名>: <实际鉴权值>

{
  "model": "agentcore",
  "messages": [
    {"role": "user", "content": "请用一句话介绍你能做什么。"}
  ],
  "stream": false
}

路径和 model 按应用实际实现填写：上面的路径适用于 AgentCoreServer 默认接口，已有 HTTP 服务可能使用其他路径；model 是请求协议字段，是否影响下游模型选择由应用决定。需要跨协议继续对话时，由应用保证一致的历史与状态管理，见“历史与状态的归属”。

场景四：业务应用使用自定义会话 Header 名称

创建 Agent 时将会话 Header 名设为 X-Business-Session，则上述请求中的会话 Header 改为：

X-Business-Session: demo-session-01

AG-UI 的 threadId 仍填 demo-session-01，每次运行仍使用新 runId。自定义 Header 名称不改变协议 Body 的字段名，也不改变会话与实例的容量关系。