> 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. # 智能体 ID 与运行 ID > 为 Alephant Gateway 流量附加智能体、运行、会话、请求和追踪标识符 Agent ID 和 Run ID 是将模型请求转化为智能体运行记录所需的最小上下文。 没有这些标识符时，Alephant 仍可针对 Virtual Key 记录网关请求。拥有这些标识符后，Alephant 可以将请求归组为智能体运行，将这些运行连接到 session 和 workflow，并让成本、策略和调试视图更加实用。 ## 标识符模型 | 标识符 | 范围 | 创建方 | 何时复用 | | ---------- | ---------------- | ----------------------------- | -------------------- | | Agent ID | 稳定的智能体身份 | Alephant dashboard 或 SaaS API | 同一智能体的每个请求均复用 | | Run ID | 一次任务执行 | 您的应用程序、框架或工作流 | 同一任务中的每次模型/工具调用均复用 | | Session ID | 多轮对话或工作流 session | 您的应用程序、框架或工作流 | 在一个 session 的相关运行间复用 | | Request ID | 一次网关请求 | 您的应用程序或 Alephant | 每个 HTTP 请求使用一个唯一值 | | Trace ID | 跨服务或支付级追踪 | Alephant 或您的分布式追踪层 | 可用时在支付、执行和成本记录间复用 | ## 智能体运行所需请求头 如果希望请求显示在某次智能体运行下，请在网关请求中发送以下请求头： | 请求头 | 是否必需 | 用途 | | --------------------- | --------- | -------------------------------------------------------- | | `Authorization` | 是 | `Bearer ` 对范围限定的 Agent 或 Virtual Key 进行身份验证 | | `Alephant-Agent-Id` | 建议用于智能体运行 | 稳定的 Alephant agent ID | | `Alephant-Run-Id` | 建议用于智能体运行 | 一次任务执行的稳定 ID | | `x-request-id` | 建议 | 该单独请求的唯一 ID | | `alephant-session-id` | 可选 | 将多次运行或请求归组到一个 session | | `alephant-property-*` | 可选 | 添加用于搜索和分析的安全运营元数据 | 较旧的代码片段可能显示 `X-Alephant-Agent`。新的集成应优先使用 `Alephant-Agent-Id`。 ## 命名建议 使用稳定、可搜索且可安全存储在日志中的 ID。 良好示例： ```text 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 示例 ```bash 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 示例 当来自一个客户端实例的每个请求都属于同一次智能体运行时，请使用默认请求头。 ```typescript import OpenAI from "openai"; const agentId = "agt_support_bot_8f3a"; const runId = "run_ticket_8421_20260609_001"; const sessionId = "sess_customer_123_support_20260609"; const client = new OpenAI({ apiKey: process.env.ALEPHANT_VIRTUAL_KEY, baseURL: "https://ai.alephant.io/v1", defaultHeaders: { "Alephant-Agent-Id": agentId, "Alephant-Run-Id": runId, "alephant-session-id": sessionId, "alephant-property-workflow": "support-triage", "alephant-property-environment": "production", }, }); const response = await client.chat.completions.create({ model: "openai/gpt-4o-mini", messages: [ { role: "user", content: "Summarize this support ticket and suggest the next action.", }, ], }); ``` 如果一个进程处理多次运行，请为每次运行创建一个客户端，或通过运行时支持的 SDK 请求选项传递特定于请求的请求头。 ## Python 示例 ```python import os from openai import OpenAI agent_id = "agt_support_bot_8f3a" run_id = "run_ticket_8421_20260609_001" session_id = "sess_customer_123_support_20260609" client = OpenAI( api_key=os.environ["ALEPHANT_VIRTUAL_KEY"], base_url="https://ai.alephant.io/v1", default_headers={ "Alephant-Agent-Id": agent_id, "Alephant-Run-Id": run_id, "alephant-session-id": session_id, "alephant-property-workflow": "support-triage", "alephant-property-environment": "production", }, ) response = client.chat.completions.create( model="openai/gpt-4o-mini", messages=[ { "role": "user", "content": "Summarize this support ticket and suggest the next action.", } ], ) ``` ## 多步骤运行模式 对一个任务内的每次模型或工具调用使用相同的 `Alephant-Run-Id`。 ```text 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。 ```text 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。 建议映射： | n8n 概念 | Alephant 字段 | | --------------------- | ---------------------------- | | 工作流或自动化名称 | `alephant-property-workflow` | | 执行 ID | `Alephant-Run-Id` | | 客户、工单或作业分组 | `alephant-session-id` | | 工作流对应的 Alephant Agent | `Alephant-Agent-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. 如果工作流已商业化，确认支付活动和成本记录共享追踪上下文。 ## 相关页面 * [智能体运行追踪](/docs/overview/core-concepts/agent-run-tracing) * [智能体与路由](/docs/overview/core-concepts/agents-routing) * [网关集成](/docs/overview/core-concepts/gateway-integration) * [n8n 工作流治理](/sdk-reference/workflow-integrations/n-8-n-workflow-governance)