pipefy-observability

Observability

Monitor AI agent and automation execution, usage stats, credit consumption, and export job history. 10 MCP tools.

CLI status (v0.1): use MCP tools below. Observability Typer commands are planned for v0.3+.

---

Identifiers reference

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_id — numeric	Known from account setup or get_organization.

---

Tools

Tool (MCP)	CLI	Read-only	Purpose
get_ai_agent_logs	— (CLI v0.3+)	Yes	Execution history for a specific AI agent.
get_ai_agent_log_details	— (CLI v0.3+)	Yes	Single execution detail for an AI agent log entry.
get_automation_logs	— (CLI v0.3+)	Yes	Execution history for an automation (by automation ID or pipe).
get_automation_logs_by_repo	— (CLI v0.3+)	Yes	Automation logs filtered by pipe UUID.
get_agents_usage	— (CLI v0.3+)	Yes	Org-level AI agent execution count and trends.
get_automations_usage	— (CLI v0.3+)	Yes	Org-level automation execution stats.
get_ai_credit_usage	— (CLI v0.3+)	Yes	AI credit consumption and remaining balance.
export_automation_jobs	— (CLI v0.3+)	Yes	Trigger async export of automation job history.
get_automation_jobs_export	— (CLI v0.3+)	Yes	Poll export job status (after export_automation_jobs).
get_automation_jobs_export_csv	— (CLI v0.3+)	Yes	Download finished automation-jobs export as CSV text.

---

Steps — diagnose a failing 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

---

Steps — export automation history as 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>

---

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

See also

• skills/ai-agents/ — create and configure AI agents.
• skills/automations/ — create and debug automation rules.