> 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.

# 智能体运行追踪

> 跨智能体运行追踪模型调用、工具调用、工作流步骤、策略决策、成本和收入

智能体运行追踪将单个 AI 请求关联到其所属的更大任务。

请求日志很有用，但生产环境中的智能体通常会执行多步骤工作：模型调用、工具调用、重试、工作流分支、策略决策，有时还包括支付事件。Alephant 将这些活动视为一次运行，以便团队端到端地了解发生了什么。

## 追踪模型

| 对象          | 用途                                          |
| ----------- | ------------------------------------------- |
| Workspace   | 顶层租户和计费边界                                   |
| Department  | 预算、成员和策略覆盖的组织范围                             |
| Agent       | 应用程序、服务、工作流或自主智能体受治理的身份                     |
| Virtual Key | 用于路由流量和归属用量的范围限定凭据                          |
| Session     | 一系列相关交互或工作流步骤                               |
| Run         | 一次智能体任务或工作流的执行                              |
| Step        | 模型调用、工具调用、API 调用、支付事件、策略检查或工作流操作            |
| Request     | 通过 Alephant Gateway 路由的兼容 provider 的 LLM 请求 |

## 一次运行可包含的内容

一次运行追踪可包含：

* 模型调用及所选 provider
* 工具调用和外部 API 调用
* 工作流步骤和分支结果
* Prompt template ID 和版本
* Token 用量、延迟、错误和重试行为
* 允许、阻止、限流或升级处理等策略决策
* 预算消耗和剩余预算上下文
* 付费 endpoint 的支付事件、收入和利润率数据
* 用于安全与合规审查的审计事件

## 追踪请求头

网关请求可包含可选请求头，帮助 Alephant 将请求归组到 session 和 run：

| 请求头                     | 用途                              |
| ----------------------- | ------------------------------- |
| `x-request-id`          | 用于幂等性和日志查找的稳定请求标识符              |
| `Alephant-Agent-Id`     | 用于智能体运行归属的稳定 Alephant agent ID  |
| `Alephant-Run-Id`       | 一次任务执行 ID，在同一 run 的所有模型/工具调用中复用 |
| `alephant-session-id`   | 将多个请求归组到同一 session              |
| `alephant-session-path` | 记录 workflow 或 route 路径          |
| `alephant-session-name` | 人类可读的 session 标签                |
| `alephant-property-*`   | 用于筛选和归属的自定义元数据                  |
| `alephant-prompt-id`    | 将用量关联到 prompt template          |

当应用程序、框架或工作流引擎已知任务上下文时，请使用这些请求头。如果没有 session 请求头，Alephant 仍会记录 Virtual Key 的请求级元数据。

有关包含 curl、TypeScript、Python 和 n8n 示例的详细设置指南，请参阅 [智能体 ID 与运行 ID](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds)。

## 常见问题

### 为什么不只使用请求日志？

请求日志展示单个模型调用。运行追踪说明更大的执行上下文：哪个智能体执行了操作、哪个工作流步骤产生调用、应用了哪个策略决策，以及总运行成本如何构成。

### session 和 run 有什么区别？

session 是更广泛的交互或工作流上下文。run 是该上下文中的一次执行。例如，一个支持自动化 session 可以包含多次智能体运行、工具调用和后续模型请求。

### 这与成本如何关联？

每一步都可能产生模型成本、工具成本、支付成本或收入。Alephant 将这些信号汇总到智能体、工作流、session、department 和 workspace。

## 相关页面

* [Agent Gateway](/docs/overview/core-concepts/agent-gateway)
* [Audit & Logs](/docs/overview/security-compliance/audit-logs)
* [Cost Analytics](/docs/overview/fin-ops-budget/cost-analytics)
* [Agent Finance](/docs/overview/fin-ops-budget/agent-finance)