智能体 ID 与运行 ID

Agent ID 和 Run ID 是将模型请求转化为智能体运行记录所需的最小上下文。

没有这些标识符时，Alephant 仍可针对 Virtual Key 记录网关请求。拥有这些标识符后，Alephant 可以将请求归组为智能体运行，将这些运行连接到 session 和 workflow，并让成本、策略和调试视图更加实用。

标识符模型

智能体运行所需请求头

如果希望请求显示在某次智能体运行下，请在网关请求中发送以下请求头：

较旧的代码片段可能显示 X-Alephant-Agent。新的集成应优先使用 Alephant-Agent-Id。

命名建议

使用稳定、可搜索且可安全存储在日志中的 ID。

良好示例：

Alephant-Agent-Id: agt_support_bot_8f3a
Alephant-Run-Id: run_ticket_8421_20260609_001
alephant-session-id: sess_customer_123_support_20260609
x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001

不要在 ID 或 alephant-property-* 请求头中放入密钥、原始客户电子邮件地址、访问令牌或受监管的个人数据。

Curl 示例

$
curl https://ai.alephant.io/v1/chat/completions \
>
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
>
  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
>
  -H "alephant-session-id: sess_customer_123_support_20260609" \
>
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
>
  -H "alephant-property-workflow: support-triage" \
>
  -H "alephant-property-environment: production" \
>
  -d '{
>
    "model": "openai/gpt-4o-mini",
>
    "messages": [
>
      {
>
        "role": "user",
>
        "content": "Summarize this support ticket and suggest the next action."
>
      }
>
    ]
>
  }'

TypeScript 示例

当来自一个客户端实例的每个请求都属于同一次智能体运行时，请使用默认请求头。

1
import OpenAI from "openai";
2
3
const agentId = "agt_support_bot_8f3a";
4
const runId = "run_ticket_8421_20260609_001";
5
const sessionId = "sess_customer_123_support_20260609";
6
7
const client = new OpenAI({
8
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
9
  baseURL: "https://ai.alephant.io/v1",
10
  defaultHeaders: {
11
    "Alephant-Agent-Id": agentId,
12
    "Alephant-Run-Id": runId,
13
    "alephant-session-id": sessionId,
14
    "alephant-property-workflow": "support-triage",
15
    "alephant-property-environment": "production",
16
  },
17
});
18
19
const response = await client.chat.completions.create({
20
  model: "openai/gpt-4o-mini",
21
  messages: [
22
    {
23
      role: "user",
24
      content: "Summarize this support ticket and suggest the next action.",
25
    },
26
  ],
27
});

如果一个进程处理多次运行，请为每次运行创建一个客户端，或通过运行时支持的 SDK 请求选项传递特定于请求的请求头。

Python 示例

1
import os
2
from openai import OpenAI
3
4
agent_id = "agt_support_bot_8f3a"
5
run_id = "run_ticket_8421_20260609_001"
6
session_id = "sess_customer_123_support_20260609"
7
8
client = OpenAI(
9
    api_key=os.environ["ALEPHANT_VIRTUAL_KEY"],
10
    base_url="https://ai.alephant.io/v1",
11
    default_headers={
12
        "Alephant-Agent-Id": agent_id,
13
        "Alephant-Run-Id": run_id,
14
        "alephant-session-id": session_id,
15
        "alephant-property-workflow": "support-triage",
16
        "alephant-property-environment": "production",
17
    },
18
)
19
20
response = client.chat.completions.create(
21
    model="openai/gpt-4o-mini",
22
    messages=[
23
        {
24
            "role": "user",
25
            "content": "Summarize this support ticket and suggest the next action.",
26
        }
27
    ],
28
)

多步骤运行模式

对一个任务内的每次模型或工具调用使用相同的 Alephant-Run-Id。

run_ticket_8421_20260609_001
  request 1: classify ticket
  request 2: retrieve policy summary
  request 3: draft customer reply
  request 4: score escalation risk

当智能体开始不同任务时，应使用新的 Alephant-Run-Id，即使它属于同一个用户 session。

sess_customer_123_support_20260609
  run_ticket_8421_20260609_001
  run_refund_check_8421_20260609_002
  run_followup_email_8421_20260609_003

n8n 工作流模式

对于 n8n 工作流，请使用 n8n 执行 ID 或工作流生成的 ID 作为 run ID。

建议映射：

如果使用 Alephant n8n 社区节点，请将返回的 requestId 或 requestLogId 传入后续分析步骤。如果通过 n8n HTTP Request 节点调用网关，请直接包含追踪请求头。

付费 Endpoint 与 Trace ID 说明

对于付费 endpoint，trace_id 用于在支付、结算、执行、模型成本、工具成本和收入记录之间进行财务级对账。

请勿用 trace_id 替代 Alephant-Run-Id。请将它们一同使用：

• Alephant-Run-Id 描述智能体任务。
• trace_id 关联付费 endpoint 活动的财务和执行记录。
• x-request-id 标识一次单独的网关请求。

如果付费 endpoint 活动缺少追踪上下文，收入和利润率视图可能会将该调用标记为不完整或未归属。

验证清单

发送请求后：

1. 打开 Logs，按 x-request-id、run ID 或 agent ID 搜索。
2. 打开 Agent 详情页面并检查 Runs 视图。
3. 确认请求成本、token、model、provider 和延迟显示在预期的 Agent 下。
4. 如果运行属于某个工作流，确认所有相关请求共享相同的 Run ID。
5. 如果工作流已商业化，确认支付活动和成本记录共享追踪上下文。

相关页面

• 智能体运行追踪
• 智能体与路由
• 网关集成
• n8n 工作流治理