Back to Details

pipefy-observability

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Observability

可观测性

Monitor AI agent and automation execution, usage stats, credit consumption, and export job history. 11 MCP tools.
监控AI agent与自动化执行情况、使用统计数据、积分消耗情况，并导出任务历史记录。涵盖11款MCP工具。

Identifiers reference

标识符参考

Full cross-tool map: 
docs/mcp/tools/identifiers.md#observability
.
ConceptWhat tools expectHow to obtain
Pipe for AI agent logs
repo_uuid
— the pipe UUID
get_pipe
with numeric 
pipe_id
; use 
pipe.uuid
.
Automation for logs
automation_id
— numeric
get_automations pipe_id=...
Org for usage stats
organization_uuid
— UUID or numeric org id
get_organization
returns the 
uuid
; a numeric id also works (resolved server-side). Execution-metrics / export take numeric 
organization_id
.
完整的跨工具映射：
docs/mcp/tools/identifiers.md#observability
。
概念工具所需参数获取方式
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
。

Tools

工具

Tool (MCP)CLIRead-onlyPurpose
get_ai_agent_logs
pipefy agent logs list
YesExecution history for a specific AI agent.
get_ai_agent_log_details
pipefy agent logs get
YesSingle execution detail for an AI agent log entry.
get_automation_logs
pipefy automation logs --automation
YesExecution history for an automation (by automation ID).
get_automation_logs_by_repo
pipefy automation logs --repo
YesAutomation logs filtered by pipe.
get_agents_usage
pipefy usage agents
YesOrg-level AI agent execution count and trends.
get_automations_usage
pipefy usage automations
YesOrg-level automation execution stats.
get_automation_execution_metrics
pipefy usage execution-metrics
YesPer-automation execution metrics (totalRuns, success/failure rate, avg duration, lastRun) over a rolling window; partial success returns 
partial_errors
for denied ids.
get_ai_credit_usage
pipefy usage credits
YesAI credit consumption and remaining balance.
export_automation_jobs
pipefy export automation-jobs
YesTrigger async export of automation job history.
get_automation_jobs_export
pipefy automation export status
YesPoll export job status (after 
export_automation_jobs
).
get_automation_jobs_export_csv
pipefy export automation-jobs-csv
YesDownload finished automation-jobs export as CSV text.
工具（MCP）CLI命令是否只读用途
get_ai_agent_logs
pipefy agent logs list
是查看特定AI agent的执行历史。
get_ai_agent_log_details
pipefy agent logs get
是查看AI agent日志条目中单次执行的详细信息。
get_automation_logs
pipefy automation logs --automation
是查看某一自动化（按自动化ID）的执行历史。
get_automation_logs_by_repo
pipefy automation logs --repo
是按Pipe筛选自动化日志。
get_agents_usage
pipefy usage agents
是查看组织级AI agent的执行次数及趋势。
get_automations_usage
pipefy usage automations
是查看组织级自动化的执行统计数据。
get_automation_execution_metrics
pipefy usage execution-metrics
是查看滚动时间窗口内各自动化的执行指标（总运行次数、成功/失败率、平均时长、最后一次运行时间）；部分成功时会返回
partial_errors
字段，包含未通过的ID。
get_ai_credit_usage
pipefy usage credits
是查看AI积分消耗情况及剩余余额。
export_automation_jobs
pipefy export automation-jobs
是触发自动化任务历史记录的异步导出。
get_automation_jobs_export
pipefy automation export status
是查询导出任务状态（调用
export_automation_jobs
之后）。
get_automation_jobs_export_csv
pipefy export automation-jobs-csv
是将完成的自动化任务导出结果以CSV文本形式下载。

Steps — diagnose a failing AI agent

步骤 — 排查故障AI agent

  1. Get the pipe UUID (not the numeric pipe ID):
    MCP: 
    get_pipe pipe_id=67890
    Capture 
    pipe.uuid
    from the response.
  2. Fetch recent agent logs:
    MCP: 
    get_ai_agent_logs repo_uuid=<UUID> page=1
  3. Identify the failed execution — look for 
    status: failed
    entries.
  4. Check credit usage if the agent stopped unexpectedly:
    MCP: 
    get_ai_credit_usage organization_id=123
  5. Fix and re-enable — update the agent config (see 
    skills/ai-agents/
    ) and toggle status:
    MCP: 
    toggle_ai_agent_status agent_id=456
  1. 获取Pipe UUID（不是数字类型的Pipe ID）：
    MCP命令：
    get_pipe pipe_id=67890
    从响应中提取
    pipe.uuid
    。
  2. 获取近期agent日志：
    MCP命令：
    get_ai_agent_logs repo_uuid=<UUID> page=1
  3. 定位失败的执行记录 — 查找
    status: failed
    的条目。
  4. 若agent意外停止，检查积分使用情况：
    MCP命令：
    get_ai_credit_usage organization_id=123
  5. 修复并重新启用 — 更新agent配置（详见
    skills/ai-agents/
    ）并切换状态：
    MCP命令：
    toggle_ai_agent_status agent_id=456

Steps — export automation history as CSV

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

  1. Trigger the export:
    MCP: 
    export_automation_jobs organization_id=123 period="current_month"
  2. Poll for completion:
    MCP: 
    get_automation_jobs_export export_id=<EXPORT_ID>
    Repeat until 
    status
    is 
    finished
    or 
    failed
    .
  3. Fetch CSV text (when finished):
    MCP: 
    get_automation_jobs_export_csv export_id=<EXPORT_ID>
  1. 触发导出：
    MCP命令：
    export_automation_jobs organization_id=123 period="current_month"
  2. 轮询导出完成状态：
    MCP命令：
    get_automation_jobs_export export_id=<EXPORT_ID>
    重复执行直到
    status
    变为
    finished
    或
    failed
    。
  3. 获取CSV文本（导出完成后）：
    MCP命令：
    get_automation_jobs_export_csv export_id=<EXPORT_ID>

Success criteria

成功标准

  • Agent logs show execution timestamps and statuses.
  • Credit usage shows remaining balance; no unexpected drops.
  • CSV export downloads successfully and contains expected automation history.
  • Agent日志显示执行时间戳和状态。
  • 积分使用情况显示剩余余额，无异常消耗。
  • CSV导出成功下载，且包含预期的自动化历史记录。

Failure modes

故障模式

  • get_ai_agent_logs
    returns empty:     use the pipe UUID (e.g., 
    abc123-...
    ), not the numeric pipe ID. Get UUID from 
    get_pipe
    .
  • get_automation_jobs_export
    stays in 
    processing
    :     large exports take time. Wait at least 60 seconds between polls. If still 
    processing
    after several minutes, retry the export trigger.
  • Credit usage shows 0 remaining: alert the user — AI features will stop working until credits are replenished. Escalate to the Pipefy admin.
  • get_ai_agent_logs
    返回空结果：     使用Pipe的UUID（例如
    abc123-...
    ），而非数字类型的Pipe ID。可通过
    get_pipe
    获取UUID。
  • get_automation_jobs_export
    一直处于
    processing
    状态：     大型导出需要时间。轮询间隔至少为60秒。若数分钟后仍处于
    processing
    状态，重新触发导出。
  • 积分使用情况显示剩余余额为0： 向用户发出警报 — AI功能将停止工作，直至积分补充完成。需上报给Pipefy管理员。

See also

另请参阅

  • skills/ai-agents/
    — create and configure AI agents.
  • skills/automations/
    — create and debug automation rules.
  • skills/ai-agents/
    — 创建并配置AI agent。
  • skills/automations/
    — 创建并调试自动化规则。