pipefy-observability

可观测性

请阅读你所用接口的 MCP 参考文档 或 CLI 参考文档。只加载相关参考文档。

监控 AI Agent 和自动化的执行情况、使用统计、额度消耗和导出作业历史。

---

标识符参考

完整的标识符映射：可观测性标识符。

概念	工具所需参数	获取方式
AI Agent 日志对应的 Pipe	repo_uuid — Pipe 的 UUID	使用数字类型的 pipe_id 调用 get_pipe；使用 pipe.uuid。
自动化日志对应的自动化	automation_id — 数字类型	get_automations pipe_id=...
使用统计对应的组织	organization_uuid — UUID 或 数字类型的组织 ID	get_organization 会返回 uuid；也可以使用数字 ID（由服务端解析）。执行指标 / 导出需要数字类型的 organization_id。

---

工具

操作	只读	用途
get_ai_agent_logs	是	特定 AI Agent 的执行历史。
get_ai_agent_log_details	是	AI Agent 日志条目的单次执行详情。
get_automation_logs	是	自动化的执行历史（按自动化 ID 查询）。
get_automation_logs_by_repo	是	按 Pipe 筛选自动化日志。
get_agents_usage	是	组织级 AI Agent 执行次数和趋势。
get_automations_usage	是	组织级自动化执行统计。
get_automation_execution_metrics	是	单个自动化在 FIFTEEN_MINUTES、SIXTY_MINUTES、TWELVE_HOURS 或 TWENTY_FOUR_HOURS 时间段内的执行指标；部分成功时，会通过 partial_errors 返回被拒绝的 ID。
get_ai_credit_usage	是	AI 额度消耗和剩余额度。
export_automation_jobs	否	触发自动化作业历史的异步导出。
get_automation_jobs_export	是	轮询导出作业状态（在调用 export_automation_jobs 之后）。
get_automation_jobs_export_csv	是	将已完成的自动化作业导出下载为 CSV 文本。

---

步骤 — 诊断故障 AI Agent

1. 获取 Pipe UUID（不是数字类型的 Pipe ID）：

   操作：get_pipe pipe_id=67890

   从响应中获取 pipe.uuid。

2. 获取最近的 Agent 日志：

   操作：get_ai_agent_logs repo_uuid=<UUID> first=30

3. 找出失败的执行记录 — 查找 status: failed 条目。

4. 如果 Agent 意外停止，检查额度使用情况：

   操作：get_ai_credit_usage organization_uuid=123 period="current_month"

5. 修复并重新启用 — 更新 Agent 配置（参见 pipefy-ai-agents），然后切换状态：

   操作：使用 Agent UUID 和 active=true 调用 toggle_ai_agent_status（SDK：agent_uuid；MCP：uuid）。

---

步骤 — 将自动化历史导出为 CSV

1. 触发导出：

   操作：export_automation_jobs organization_id=123 period="current_month"

2. 轮询直至完成：

   操作：get_automation_jobs_export export_id=<EXPORT_ID>

   重复轮询，直到 status 为 finished 或 failed。

   已完成的导出还会包含 fileUrl，这是指向 xlsx 文件的签名链接。该链接会在返回它的读取操作完成 1 小时后过期，在此之前，任何持有该链接的人都可以下载文件。将链接提供给用户时，请说明它会在 1 小时后过期；如需获取新链接，请再次轮询。

3. 获取 CSV 文本（导出完成后）：

   操作：get_automation_jobs_export_csv export_id=<EXPORT_ID>

---

成功标准

• Agent 日志显示执行时间戳和状态。
• 额度使用情况显示剩余额度；没有意外减少。
• CSV 导出下载成功，并包含预期的自动化历史。

故障模式

• **get_ai_agent_logs 返回空结果：**使用管道 UUID（例如，abc123-...），而不是数字管道 ID。通过 get_pipe 获取 UUID。
• **get_automation_jobs_export 一直处于 processing 状态：**大型导出需要时间。每次轮询之间至少等待 60 秒。如果几分钟后仍处于 processing 状态，请重新触发导出。
• **剩余额度显示为 0：**提醒用户，额度补充前，AI 功能将停止工作。请升级反馈给 Pipefy 管理员。

另请参阅

• pipefy-ai-agents — 创建和配置 AI Agent。
• pipefy-automations — 创建和调试自动化规则。