> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 会话

会话将相关的网关请求和智能体运行归为一次用户旅程、工作流执行或多步骤任务。

当一次业务交互包含多次模型调用、工具调用、重试或智能体运行时，请使用会话。支持对话、n8n 工作流执行、研究任务或付费端点调用都可以表示为会话。

## 会话、运行与请求

| 概念 | 范围            | 示例                           |
| -- | ------------- | ---------------------------- |
| 会话 | 更广泛的交互或工作流上下文 | 一个支持案例、工作流执行或客户对话            |
| 运行 | 会话内的一项智能体任务   | 分类工单、起草回复、核实退款资格             |
| 请求 | 一次网关模型请求      | 一次 `/v1/chat/completions` 调用 |

在相关运行中使用同一个会话 ID；每项任务使用新的运行 ID；每个网关请求使用唯一的请求 ID。

## 建议的请求头

| 请求头                     | 用途                 |
| ----------------------- | ------------------ |
| `alephant-session-id`   | 将相关请求和运行归入一个会话     |
| `alephant-session-name` | 人类可读的会话标签          |
| `alephant-session-path` | 可选的工作流或路由路径        |
| `Alephant-Agent-Id`     | 稳定的 Alephant 智能体身份 |
| `Alephant-Run-Id`       | 会话内的一次任务执行         |
| `x-request-id`          | 一项请求级标识符           |

示例：

```bash
curl https://ai.alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "alephant-session-id: sess_customer_123_support_20260609" \
  -H "alephant-session-name: support ticket 8421" \
  -H "alephant-session-path: /support/triage" \
  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Classify this support ticket." }
    ]
  }'
```

## 会话分析

会话分析有助于回答：

* 哪些会话处于活跃、已完成或被拦截状态？
* 哪些智能体和工作流产生了最高会话成本？
* 哪些会话包含策略事件？
* 哪些会话出现了高延迟、重复重试或异常 token 用量？
* 哪些会话步骤贡献了总成本？

底层 Analytics API 包含用于会话列表、指标和会话详情的会话端点。确切参数和响应形式请参阅 API Reference。

## 实现模式

1. 在对话、工作流或任务启动时生成或加载稳定的会话 ID。
2. 为会话内的每项智能体任务生成新的 Run ID。
3. 每次网关请求均发送 `alephant-session-id`、`Alephant-Agent-Id` 和 `Alephant-Run-Id`。
4. 应用程序可生成时，为每个单独请求发送 `x-request-id`。
5. 查询日志、分析或会话详情视图，检查成本、策略事件和执行步骤。

## 相关页面

* [智能体 ID 与运行 ID](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds)
* [智能体运行追踪](/docs/overview/core-concepts/agent-run-tracing)
* [网关集成](/docs/overview/core-concepts/gateway-integration)