pipefy-observability

オブザーバビリティ

使用するインターフェースに応じて、MCP リファレンスまたはCLI リファレンスをお読みください。関連するリファレンスのみを読み込んでください。

AI エージェントや自動化の実行、使用状況の統計、クレジット消費量、エクスポートジョブの履歴を監視します。

---

識別子のリファレンス

識別子の完全な一覧：オブザーバビリティの識別子。

概念	ツールが要求する値	取得方法
AI エージェントのログ用パイプ	repo_uuid — パイプの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 エージェントの実行履歴です。
get_ai_agent_log_details	はい	AI エージェントのログエントリに含まれる、単一の実行の詳細です。
get_automation_logs	はい	自動化の実行履歴です（自動化 ID で指定）。
get_automation_logs_by_repo	はい	パイプで絞り込んだ自動化ログです。
get_agents_usage	はい	組織レベルの AI エージェント実行回数と傾向です。
get_automations_usage	はい	組織レベルの自動化実行統計です。
get_automation_execution_metrics	はい	FIFTEEN_MINUTES、SIXTY_MINUTES、TWELVE_HOURS、またはTWENTY_FOUR_HOURSの期間における自動化ごとの実行メトリクスです。一部の取得に成功した場合、拒否された ID はpartial_errorsに返されます。
get_ai_credit_usage	はい	AI クレジットの消費量と残高です。
export_automation_jobs	いいえ	自動化ジョブ履歴の非同期エクスポートを開始します。
get_automation_jobs_export	はい	エクスポートジョブのステータスを確認します（export_automation_jobsの実行後）。
get_automation_jobs_export_csv	はい	完了した自動化ジョブのエクスポートを CSV テキストとしてダウンロードします。

---

手順 — 失敗する AI エージェントを診断する

1. パイプ UUID を取得します（数値のパイプ ID ではありません）。

   操作：get_pipe pipe_id=67890

   レスポンスからpipe.uuidを取得します。

2. 最近のエージェントログを取得します。

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

3. 失敗した実行を特定します — status: failedのエントリを探します。

4. エージェントが予期せず停止した場合は、クレジット使用量を確認します。

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

5. 修正して再度有効にします — エージェント設定を更新し（pipefy-ai-agentsを参照）、ステータスを切り替えます。

   操作：エージェント 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になるまで繰り返します。

   エクスポートが完了すると、xlsx への署名付きリンクであるfileUrlも返されます。このリンクは、返された読み取りから 1 時間後に有効期限が切れます。それまでの間は、リンクを持っている人なら誰でもファイルをダウンロードできます。ユーザーにリンクを渡す際は、1 時間で有効期限が切れることを伝えてください。新しいリンクが必要な場合は、再度確認します。

3. CSV テキストを取得します（完了後）。

   操作：get_automation_jobs_export_csv export_id=<EXPORT_ID>

---

成功条件

• エージェントログに実行時刻とステータスが表示されます。
• クレジット使用状況に残高が表示され、予期しない減少がありません。
• CSV エクスポートが正常にダウンロードでき、想定される自動化履歴が含まれています。

失敗時の対処

• get_ai_agent_logs が空を返す場合： 数値のパイプ ID ではなく、パイプの UUID（例：abc123-...）を使用してください。get_pipe から UUID を取得します。
• get_automation_jobs_export が processing のままの場合： 大規模なエクスポートには時間がかかります。ポーリングの間隔を少なくとも 60 秒空けてください。数分経っても processing のままの場合は、エクスポートのトリガーを再試行してください。
• クレジット残量が 0 と表示される場合： クレジットが補充されるまで AI 機能が停止することをユーザーに知らせてください。Pipefy の管理者にエスカレーションしてください。

関連項目

• pipefy-ai-agents — AI エージェントを作成、設定します。
• pipefy-automations — オートメーションルールを作成し、デバッグします。