按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
Observability
Read the MCP reference or CLI reference for the surface you are using. Load only the relevant reference.
Monitor AI agent and automation execution, usage stats, credit consumption, and export job history.
Identifiers reference
Full identifier map: observability identifiers.
| Concept | What tools expect | How 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. |
Tools
| Operation | Read-only | Purpose |
|---|---|---|
get_ai_agent_logs | Yes | Execution history for a specific AI agent. |
get_ai_agent_log_details | Yes | Single execution detail for an AI agent log entry. |
get_automation_logs | Yes | Execution history for an automation (by automation ID). |
get_automation_logs_by_repo | Yes | Automation logs filtered by pipe. |
get_agents_usage | Yes | Org-level AI agent execution count and trends. |
get_automations_usage | Yes | Org-level automation execution stats. |
get_automation_execution_metrics | Yes | Per-automation execution metrics over FIFTEEN_MINUTES, SIXTY_MINUTES, TWELVE_HOURS, or TWENTY_FOUR_HOURS; partial success returns partial_errors for denied ids. |
get_ai_credit_usage | Yes | AI credit consumption and remaining balance. |
export_automation_jobs | No | Trigger async export of automation job history. |
get_automation_jobs_export | Yes | Poll export job status (after export_automation_jobs). |
get_automation_jobs_export_csv | Yes | Download finished automation-jobs export as CSV text. |
Steps — diagnose a failing AI agent
- Get the pipe UUID (not the numeric pipe ID):
Operation: get_pipe pipe_id=67890
Capture pipe.uuid from the response.
- Fetch recent agent logs:
Operation: get_ai_agent_logs repo_uuid=<UUID> first=30
- Identify the failed execution — look for
status: failedentries.
- Check credit usage if the agent stopped unexpectedly:
Operation: get_ai_credit_usage organization_uuid=123 period="current_month"
- Fix and re-enable — update the agent config (see
pipefy-ai-agents) and toggle status:
Operation: toggle_ai_agent_status with the agent UUID and active=true (SDK: agent_uuid; MCP: uuid).
Steps — export automation history as CSV
- Trigger the export:
Operation: export_automation_jobs organization_id=123 period="current_month"
- Poll for completion:
Operation: get_automation_jobs_export export_id=<EXPORT_ID>
Repeat until status is finished or failed.
A finished export also carries fileUrl, a signed link to the xlsx. It expires 1 hour after the read that returned it, and anyone holding it can download the file until then. When you hand it to the user, say that it expires in 1 hour; for a fresh link, poll again.
- Fetch CSV text (when finished):
Operation: 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.
Failure modes
- `get_ai_agent_logs` returns empty: use the pipe UUID (e.g.,
abc123-...), not the numeric pipe ID. Get UUID fromget_pipe. - `get_automation_jobs_export` stays in `processing`: large exports take time. Wait at least 60 seconds between polls. If still
processingafter 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.
See also
pipefy-ai-agents— create and configure AI agents.pipefy-automations— create and debug automation rules.
