pipefy-ai-agents

AI エージェント

現在のサーフェスに対応するリファレンスのみを参照してください：MCP または CLI。以下のワークフローでは、共通の操作名と引数を使用します。

パイプに接続された会話型 AI エージェントです。各エージェントには、エージェントレベルの指示と、トリガーイベント、プロンプト、アクションをそれぞれ持つ 1～5 個の振る舞いがあります。

従来の自動化と AI 自動化（プロンプト駆動型）については、pipefy-automations を参照してください。

---

ツール

操作	読み取り専用	目的
get_ai_agents	はい	パイプの AI エージェントを一覧表示します（repo_uuid はパイプの UUID であり、数値の id ではありません）。
get_ai_agent	はい	振る舞いを含むエージェントの完全な設定を取得します。
create_ai_agent	いいえ	新しい会話型エージェントを作成します（デフォルトでは有効です。無効状態で開始するには active=false を指定します）。
update_ai_agent	いいえ	全置換（パッチではありません）。必ず完全な behaviors を送信してください。無効状態は維持されます。
delete_ai_agent	いいえ	破壊的操作です。先に確認して承認を得てください。
toggle_ai_agent_status	いいえ	明示的に有効化または無効化します。
validate_ai_agent_behaviors	はい	作成／更新前に必ず事前チェックしてください。

実行ログは pipefy-observability（get_ai_agent_logs、get_ai_agent_log_details）にあります。

---

有効状態のライフサイクル

• エージェントはデフォルトで有効です。有効状態で作成すると、設定更新時に disabledAt を省略することで、API のデフォルトの無効なシェル状態が解除されます。無効状態で作成する場合（active=false）、作成時と連続する更新時に disabled_at が明示的に設定されます。
• 通常の update_ai_agent は無効状態を維持し、意図的に再有効化することはありません。状態維持のための再読み込みを省略するには、以前の get_ai_agent の disabledAt を disabled_at として渡してください。省略した場合、SDK は再読み込みして再送信します。
• 明示的な有効化／無効化には toggle_ai_agent_status を使用します。
• 作成／更新後は、レスポンスの disabled_at と active を確認してください（disabled_at が null の場合、active は true です）。get_ai_agent では、disabledAt が null なら有効です。behaviors[].active はエージェントの有効／無効を示すものではありません。有効な振る舞いがないエージェントは、有効状態のフラグに関係なく API によって無効になります。

---

作成ワークフロー（検出 → 検証 → 作成 → 確認）

同意： AI エージェントの作成または提案は、ユーザーが AI／エージェントを明示的に依頼した場合に限ります。AI が役立ちそうでも依頼されていない場合は、まず確認してください。依頼されていないエージェントを決して導入しないでください。

イベント ID、フェーズ ID、アクションタイプ、フィールド ID を推測してはいけません。

1 — パイプのメタデータを取得する

get_pipe(pipe_id) を呼び出して、以下を抽出します。

• uuid → すべての AI エージェントツールで repo_uuid として使用します。
• phases[].id / phases[].name → move_card アクションに必要です。
• get_start_form_fields(pipe_id)`` および／または get_phase_fields(phase_id)で取得するフィールド →update_card` アクションに必要です。

2 — 既存のエージェントを確認する

重複を避けるために get_ai_agents(repo_uuid) を呼び出します。既存のエージェントを変更するには、作成ではなく update_ai_agent を使用します。完全な設定を取得するには、get_ai_agent(uuid) を使用します。

3 — 有効なトリガーイベントを検出する

get_automation_events(pipe_id) を呼び出します。一般的なイベントは次のとおりです。

イベント（event_id の値）	必須の event_params	例
card_created	なし	{}
card_moved	{"to_phase_id":"<phase_id>"}	カードがそのフェーズに入った場合のみ発火します。
field_updated	{"triggerFieldIds":["<field_id>", ...]}	それらのフィールドが変更された場合のみ発火します。
manually_triggered	なし	ユーザーがカード上のボタンをクリックします。

card_moved と field_updated では、必ず event_params を含めてください。省略すると、振る舞いは発生のたびに発火します。

4 — 有効なアクションタイプを確認する

get_automation_actions(pipe_id)。既知の actionType 値と、必須の metadata は次のとおりです。

アクション（actionType の値）	必須の metadata
update_card	pipeId + fieldsAttributes（各エントリーに fieldId + inputMode が必要）
move_card	destinationPhaseId
create_card	pipeId + fieldsAttributes
create_connected_card	pipeId + fieldsAttributes（パイプのリレーションが必要）
create_table_record	tableId + fieldsAttributes（テーブルのフィールド ID。pipeId は不要）
send_email_template	emailTemplateId。allowTemplateModifications（ブール値）は任意
human_validation	emails（受信者リスト）と title。API はどちらか一方だけでも受け付けますが、空の metadata は拒否します
mcp_tool	mcpServerId + toolName。toolInputs は任意で、各項目に name と source が必要です。source は、value を指定する fixed_value、または fieldId を指定する card_field のいずれかです

カードアクションの fieldId 値には、スラッグまたは数値の internal_id を指定できます。create_table_record の場合は、テーブルのフィールド ID を指定します（パイプではなく、get_table / get_table_record で検証してください）。

不要なアクションには pipeId や tableId を含めないでください。空文字列として指定することも避けてください。Pipefy はこれをアクセスできない ID として読み取り、「references a pipe or table you do not have access to」というエラーでエージェントを拒否します。指定する pipeId または tableId は、いずれも同じ組織に属し、呼び出し元がカードを作成できるものでなければなりません。

5 — behavior dict を作成する

{
  "name": "<descriptive name>",
  "event_id": "<from step 3>",
  "event_params": {},
  "actionParams": {
    "aiBehaviorParams": {
      "instruction": "<prompt for the AI when this event fires>",
      "actionsAttributes": [
        { "name": "<action label>", "actionType": "<from step 4>", "metadata": { } }
      ]
    }
  }
}

• 各 behavior の actionsAttributes には、少なくとも 1 つのアクションが必要です。

• エージェントごとの behavior は最大 5 つです。

• すべての fieldsAttributes エントリーで inputMode が必須です（省略するとモデルの検証に失敗します）。値は fill_with_ai（AI が値を出力フィールドに書き込む）、fixed_value（リテラル値 value を使用する）、copy_from（value が別のフィールドをコピーする %{…} テンプレート）です。

• 入力フィールドの参照（behavior の instruction 内の %{field:<internal_id>}。作成／更新時に referencedFieldIds に自動入力されます）が必要なのは、AI がカードのフィールド値を読み取る必要がある場合に限られます。すべての fill_with_ai で必要なわけではありません（例：指示のみ、OCR／添付ファイル、ナレッジベースのコンテキスト）。カードの入力値が必要なのに参照を省略すると、トリガー時に card.fields が空で届き、モデルが内容を捏造する可能性があります。誤った数値の入力 ID は（検証と作成／更新時に）黙って受け入れられ、機能しない referencedFieldId になります。誤ったスラッグは解決されず、数字のみを対象とする抽出処理によって破棄されます（未解決トークン）。どちらの場合も card.fields は空のままで（同様に内容が捏造されます）、ID は get_start_form_fields / get_phase_fields で確認してください。ドット付きの接続先パイプ参照（%{field:<parent>.<child>}）は実行時に引き継がれません。接続されたカードのフィールドを読み取るには、現在のパイプ上のフィールドを使用してください。

• update_card の場合、カードを移動しないときは destinationPhaseId: "" を設定してください。

識別子の例（架空）

組織の get_pipe / get_start_form_fields から実際の値を使用してください。以下のプレースホルダーは、このリポジトリのユニットテスト用フィクスチャに対応しています。重要なのは構文（pipeId、fieldId、%{field:<internal_id>}、inputMode）であり、数字ではありません。各パイプの数値の internal_id とフェーズ ID に置き換えてください。

役割	値の例
パイプ（数値のリポジトリ ID）	987654321
フィールドの internal_id	900000101
移動先フェーズ（move_card）	900000201
対象パイプ（create_card）	900000301

メタデータの例

// update_card — output field fill_with_ai; input fields referenced in instruction
{ "pipeId": "987654321", "destinationPhaseId": "", "fieldsAttributes": [{ "fieldId": "900000101", "inputMode": "fill_with_ai", "value": "" }] }
// companion instruction (aiBehaviorParams.instruction), not metadata:
// "Read %{field:900000102} (title) and %{field:900000103} (description), then fill the category."

// move_card (no pipeId: leave out what an action does not use)
{ "destinationPhaseId": "900000201", "fieldsAttributes": [] }

// create_card
{ "pipeId": "900000301", "fieldsAttributes": [{ "fieldId": "title", "inputMode": "fill_with_ai", "value": "" }] }

// create_table_record (fieldsAttributes are TABLE field IDs; no pipeId)
{ "tableId": "<table_id>", "fieldsAttributes": [{ "fieldId": "<table_field_id>", "inputMode": "fill_with_ai", "value": "" }] }

// send_email_template
{ "emailTemplateId": "<template_id>", "allowTemplateModifications": false }

// human_validation
{ "emails": ["[email protected]"], "title": "Review this card" }

// mcp_tool (mcpServerId is an MCP server registered on the pipe)
{ "mcpServerId": "<mcp_server_id>", "toolName": "<tool_name>", "toolInputs": [{ "name": "query", "source": "fixed_value", "value": "acme" }, { "name": "email", "source": "card_field", "fieldId": "customer_email" }] }

5b — オプション：機能と LLM プロバイダー

actionParams.aiBehaviorParams 内のビヘイビアには、次の項目を含めることもできます。

• capabilitiesAttributes — ビヘイビアが使用できる高度なツールです。各エントリーは厳密に { "capabilityType": "<type>", "enabled": true|false } の形式です（両方のキーが必須で、追加のキーは指定できません。文字列のみ、または { "type": ... } は拒否されます）。

  製品名	capabilityType
  IDP / Intelligent Document Processing	advanced_ocr
  Calculations & Analysis	math_operations
  Web Search	web_search
  Web Scraping	web_scraping
  Max effort	max_effort

  capabilityType は固定セットと照合されません。どの値もそのまま渡され、書き込み時に API が列挙型を検証するため、新しい機能もツールキットの更新なしで使用できます。検証で確認するのは形式のみで、利用権限は確認しません。機能を有効にするには組織レベルでの有効化が必要な場合があるため、事前チェックに合格しても組織で機能が有効とは限りません。

• providerId ／ systemProviderId — ビヘイビアの LLM プロバイダーを指定します。設定できるのはどちらか一方だけです（ビヘイビアで有効になるプロバイダーは 1 つです）。get_llm_providers で有効な ID を確認してください。各プロバイダーには type があり、カスタム（byom）プロバイダーには providerId、Pipefy 管理の（system）プロバイダーには systemProviderId を使用します。get_default_llm_provider では、どちらも設定されていない場合にビヘイビアが使用するプロバイダーを確認できます。ID は Pipefy UI の組織の AI 設定にも表示されます。

  独自モデルの持ち込み（カスタムプロバイダー）。 まず validate_llm_provider_access を実行してください。読み取りアクセスがあっても、書き込みに必要な、より強い manage_ai_providers 権限や対象プランの利用資格があるとは限りません。ローカル JSON ファイルである configuration_file_path を指定してプロバイダーを作成し、その id を providerId として使用します。update_llm_provider には設定全体を送信してください。既存のシークレットを保持するには __REDACTED__ プレースホルダーを残し、値をローテーションするには新しい値を指定します。delete_llm_provider の前に get_llm_provider_dependencies を確認してください。有効化には set_llm_provider_active_status を使用します。set_default_llm_provider には provider_id ／ system_provider_id のどちらか一方だけを指定します。reset_default_llm_provider はデフォルトをクリアします。

• dataSourceIds — ビヘイビアが参照できるナレッジベースのソースです。各 ID は get_ai_knowledge_bases から取得するナレッジベースアイテム ID です。エージェントにもエージェントレベルの data_source_ids があり、両者は統合されます。作成から紐付けまでの流れについては、以下のナレッジベースをご覧ください。

{
  "instruction": "Extract totals from the attached invoice.",
  "capabilitiesAttributes": [{ "capabilityType": "advanced_ocr", "enabled": true }],
  "actionsAttributes": [ /* ... */ ]
}

6 — 検証（複雑な動作の場合に推奨）

validate_ai_agent_behaviors(pipe_id, behaviors) では、次の項目を確認します。

• 出力フィールド ID（fieldsAttributes[].fieldId）がパイプ内に存在すること
• フェーズ ID が存在すること
• create_connected_card のパイプ間リレーションが存在すること
• アクションタイプが有効であること（KNOWN_AI_ACTION_TYPES。create_table_record の fieldsAttributes はテーブルのフィールド ID であるため、パイプとの照合は行われず、get_table で確認するよう警告が表示されます。send_email_template のメタデータでは、パイプのフィールド ID 照合は行われません）
• 動作の構造が Pydantic の検証に合格すること（正規の capabilitiesAttributes 形式、および providerId と systemProviderId のいずれか一方のみであることを含みます）
• fieldsAttributes[].fieldId の値（出力）は、開始フォームとフェーズのフィールドと照合されます。slug の id と数値の internal_id の両方を使用できます。指示内の %{field:...} トークン（入力）は存在確認されません。ID／slug が見つからなくても、valid: true になります。slug から数値への置き換えは、ここでは行われず、作成／更新時にのみ行われます。
• ナレッジベースへの所属も確認するには、data_source_ids（エージェントレベル）を設定します。この値は各動作の dataSourceIds と統合され、パイプのナレッジベースと照合されます。不明な ID は警告のみで、valid は true のままです。ナレッジベース一覧を読み取れない場合は、警告が 1 件追加され、確認はスキップされます。

strict_unknown_action_types（デフォルトは true）：KNOWN_AI_ACTION_TYPES に含まれない actionType は problems に報告され、処理をブロックします。false に設定すると、不明なアクションタイプは warnings のみに分類され、valid は true のままになります。

7 — エージェントを作成する

name、repo_uuid、instruction、behaviors を指定して create_ai_agent を呼び出します。部分的なエージェントのシェルが作成されるのを避けるため、1 回の呼び出しで作成する方法を推奨します。エージェントはデフォルトで有効です。無効状態で開始するには、active=false を設定します（有効状態のライフサイクルを参照）。

作成／更新時には、slug 形式の fieldId 値が数値の internal_id に解決され、%{field:<slug>} が %{field:<internal_id>} に書き換えられます。また、該当する場合は referencedFieldIds が自動的に設定されます。SDK は、すべての表示先に対してアクションの referenceId 値と %{action:<uuid>} プレースホルダーを挿入します。これらを自分で生成しないでください。

8 — 応答を処理する

• agent_uuid を伴う成功 → 書き込み応答の disabled_at と active を確認し、エージェントが有効になっていることを検証します。
• 部分的な失敗（behaviors が拒否された場合） → SDK は AiAgentConfigureError を発生させます。.agent_uuid を使って既存のシェルを復旧します。MCP の応答にも agent_uuid が含まれます。update_ai_agent を呼び出し、必須項目をすべて含むペイロードを渡します。必要な項目は uuid、repo_uuid（作成時と同じパイプ UUID）、name、instruction、完全な behaviors です（パッチではなく全置換です）。2 つ目のエージェントを作成してはいけません。作成されたシェルは無効になっていることが多く、更新してもその状態が維持されます。復旧更新の成功後にエージェントを有効にする必要がある場合は、toggle_ai_agent_status を呼び出してください。
• UUID を伴わない失敗 → 検証エラーまたは API エラーです。拡張エラーに含まれるヒントテキストに従ってください。

9 — 確認する

get_ai_agent(uuid) を呼び出し、動作と有効状態を確認します（disabledAt が null なら有効です）。behaviors[].active をエージェントの有効状態とみなさないでください。確認せずに無効だと判断しないでください。

---

ナレッジベース（データソース）

ナレッジベースは、エージェントが利用するパイプ単位のデータソースです。動作の dataSourceIds（またはエージェントレベルの data_source_ids）にIDを設定してアタッチします。ナレッジベースに関するすべての操作は、数値のパイプIDではなく、パイプのUUID（pipe_uuid）を対象とします。get_pipe は uuid を返します。

操作	読み取り専用	目的
get_ai_knowledge_bases	はい	パイプ上のすべての項目（プレーンテキスト、ドキュメント、データルックアップ）を一覧表示します。それぞれに dataSourceIds に指定する id と、type（knowledge_base_plain_texts、knowledge_base_documents、または data_lookups）があります。
get_ai_knowledge_base_plain_text	はい	1件のプレーンテキストとその内容を取得します。
create_ai_knowledge_base_plain_text	いいえ	プレーンテキストを作成します（name、content 1～3500、description 1～900 — すべて必須）。
update_ai_knowledge_base_plain_text	いいえ	部分更新です。name/content/description のうち少なくとも1つを指定してください。
delete_ai_knowledge_base_plain_text	いいえ	破壊的な操作です。事前に確認して承認してください。
get_ai_knowledge_base_document	はい	1件のドキュメントのメタデータを取得します（content はテキストではなく、保存されたURLです）。
create_ai_knowledge_base_document	いいえ	PDFをアップロードします（name、description 1～900、file_path）。.pdf のみ対応し、上限は20 MiBです。インデックス作成は非同期で行われます。
update_ai_knowledge_base_document	いいえ	メタデータのみを更新します（name/description）。ファイルの置き換えはできません。
delete_ai_knowledge_base_document	いいえ	破壊的な操作です。事前に確認して承認してください。
get_ai_knowledge_base_data_lookup	はい	1件のデータルックアップを取得します。ペイロードに conditions は含まれないため、定義はクライアント側で保持してください。
create_ai_knowledge_base_data_lookup	いいえ	データルックアップを作成します（name、description 1～900、数値のパイプIDである source_repo_id、output_fields 1～30、conditions — すべて必須）。
update_ai_knowledge_base_data_lookup	いいえ	全置換です。呼び出しごとに source_repo_id／output_fields／conditions を再送信してください。search_query を省略するとクリアされます。部分更新が可能なのは name/description のみです。
delete_ai_knowledge_base_data_lookup	いいえ	破壊的な操作です。事前に確認して承認してください。
validate_knowledge_base_access	はい	書き込み前に読み取りアクセスを確認します。

フロー：アクセス確認 → プレーンテキスト作成 → アタッチ

1. アクセスを確認する — validate_knowledge_base_access(pipe_uuid)。成功結果で確認できるのは読み取りアクセス（read_ai_agents）のみです。書き込みに必要な manage_ai_agents の権限があることは確認できません。
2. データソースを作成する — create_ai_knowledge_base_plain_text(pipe_uuid, name, content, description)。制限はクライアント側ですぐに検証されます。content は1～3500文字、description は1～900文字です（どちらも必須）。返された id を保持してください。
3. アタッチする — create_ai_agent／update_ai_agent を呼び出す際、動作の dataSourceIds（またはエージェントレベルの data_source_ids）にその id を追加します。まず validate_ai_agent_behaviors(pipe_id, behaviors, data_source_ids=[...]) で検証してください。不明なIDは警告として表示されます。

PDFドキュメントの場合は、手順2で pipe_uuid、name、description、file_path を指定して create_ai_knowledge_base_document を使用します。受け付けるのは .pdf のみで、上限は20 MiBです。インデックス作成は非同期で行われるため、ドキュメントがすぐに検索可能になるとは限りません。返された id を保持し、アタッチしてください。

データルックアップ：AI が入力する条件を指定して作成 → 追加 → 更新（全置換）

データルックアップを使うと、エージェントは条件に基づいてソースパイプ内のカードを検索し、指定したフィールド値を返せます。手順 2 では上記と同じフローを使用しますが、次の 3 つの独自ルールがあります。

1. 作成 — create_ai_knowledge_base_data_lookup(pipe_uuid, name, description, source_repo_id, output_fields, conditions)。source_repo_id はソースパイプの数値 ID です（API では UUID も受け付けますが、エージェントの実行時にルックアップが機能しなくなります）。output_fields には 1～30 個のフィールド ID を指定します（フィールドのスラッグに加え、id、title、created_at などの静的フィールドも指定できます）。各条件には field と operator（バックエンド固有の文字列。例："eq"、"contains"）が必要です。また、条件は静的（文字列の value が必須）または AI 入力（AI が実行時にユーザーに値を尋ねる）のいずれかです。

   [{"field": "customer_email", "operator": "eq", "usingFillWithAi": true,
     "inputName": "Customer email", "inputType": "text",
     "inputDescription": "The customer's email address"}]
   

2. 追加 — 返された id を保持し、他の種類と同様に dataSourceIds に追加します。送信した定義も保持してください。読み取りでは conditions が返されないため、ルックアップの完全な記録は手元のコピーだけになります。

3. 更新は全置換 — update_ai_knowledge_base_data_lookup を呼び出すたびに、source_repo_id、output_fields、conditions（差分ではなく、すべての条件セット）が必要です。また、search_query を省略するとクリアされます。省略時に保存済みの値が維持されるのは name／description のみです。

---

トークンの正規化とスラッグの解決

インストラクションでは 5 種類のトークン別名を使用でき、すべて正規形 %{field:<internal_id>} に正規化されます。

形式	動作
%{<internal_id>}	正規の短縮形です。
{<internal_id>}	% が自動的に付加されます。
{field:<internal_id>}	プレフィックス付きの形式で、% が自動的に付加されます。
{field:<slug>}	スラッグ形式です。動作に pipeId が指定されている場合、数値 ID に解決されます。
%{field:<internal_id>}	正規の完全形式です。

動作に pipeId が指定されている場合、%{field:<slug>} は %{field:<internal_id>} に書き換えられます。Pipefy UI のトークンスロットにチップではなくプレーンテキストが表示される場合、ペイロードに正規化されていないトークンが残っている可能性があります。

---

テンプレートパラメーター／プレースホルダー

動作ごとに str → str の値を持つ template_params（または placeholders）を指定し、任意の文字列（インストラクション、メタデータ ID など）で {{name}} を使用できます。任意で aiBehaviorParams.instruction の代わりに instruction_template を設定することもできます。最終的なインストラクションは補間され、API 呼び出し前に書き込まれます（MCP ツール、CLI、SDK の CreateAiAgentInput／UpdateAiAgentInput によって処理されます）。これらのキーは検証時に除去されます。

{
  "name": "Classify card",
  "event_id": "card_created",
  "instruction_template": "Read {{field_ref}} and classify the card.",
  "template_params": { "field_ref": "%{field:900000101}" },
  "actionParams": {
    "aiBehaviorParams": {
      "actionsAttributes": [
        {
          "name": "Fill classification",
          "actionType": "update_card",
          "metadata": { "pipeId": "{{pipe}}", "fieldsAttributes": [{ "fieldId": "{{class_field}}", "inputMode": "fill_with_ai", "value": "" }] }
        }
      ]
    }
  },
  "placeholders": { "pipe": "987654321", "class_field": "900000101" }
}

template_params と placeholders はマージされます（競合する場合は placeholders が優先されます）。

---

UI と API の名称の違い

Pipefy UI	API／ツールのフィールド
説明（エージェント作成の手順 1）	instruction（エージェントレベル）
インストラクション／プロンプト（動作ごと）	actionParams.aiBehaviorParams.instruction
パイプ UUID	repo_uuid（get_pipe().uuid から取得。数値の id ではありません）

---

成功条件

• エージェントの有効化状態が意図した状態と一致していること。有効な場合、get_ai_agent.disabledAt は null です。behaviors[].active ではエージェントの有効化状態は確認できません。
• 作成前に validate_ai_agent_behaviors がエラーなしと報告すること。
• エージェントが Pipefy UI のパイプの AI 設定に表示されること。

失敗モード

• update_ai_agent はパッチではなく、全置換です。 get_ai_agent でエージェントを読み取り、必要な箇所を変更して、behaviors リスト全体を送信してください。含めなかった behavior は削除されます。読み取った behavior はそのまま返してもかまいません。保存時に、それらに含まれる ID と %{action:…} の行は置き換えられます。ただし例外として、get_ai_agent は eventParams.kindOfSla を返さないため、読み取ったまま SLA イベントの behavior を返すと、その SLA の種類が失われます。送信する前に、その behavior の event_params に kindOfSla を設定してください。更新によって無効化済みのエージェントが再有効化されることはありません。その場合は toggle_ai_agent_status を使用してください。
• 更新が拒否されてもロールバックされません。 Pipefy は名前と指示を適用し、新しいリストを保存する前に現在の behaviors を削除します。その後、リストが拒否されると（RECORD_NOT_SAVED）、エージェントには behavior がなくなるか、新しいリストの一部だけが残り、有効状態は維持されます。update_ai_agent の前に、get_ai_agent の結果を保持し、validate_ai_agent_behaviors を実行してください。このツールは各 event_id を get_automation_events と照合します。イベントを読み込めない場合は警告するため、未検証の event_id が問題なしと判断されることはありません。また、human_validation／mcp_tool アクションのメタデータも検証します。失敗したら get_ai_agent を呼び出して残っている内容を確認し、ペイロードを修正してリスト全体を再送信してください。更新時に「参照先のパイプまたはテーブルにアクセスできません」というエラーが発生した場合も同様です。このエラーが返る時点で behaviors はすでに保存されています。
• RECORD_NOT_SAVED から原因は特定できません。 validate_ai_agent_behaviors は、原因のいくつかを示すようになりました。パイプの自動化イベントを読み込める場合の不明な event_id と、メタデータが不足している human_validation または mcp_tool アクションです。まずこのツールを実行してください。事前検証では検出できないペイロードエラーも同じメッセージで示されるため、パイプが AI エージェントの behaviors に対応していないと結論づける前に、ここで挙げた原因を除外してください。
• 部分的な失敗からの復旧。 create_ai_agent が UUID を返しながら失敗を報告した場合は、update_ai_agent(uuid, repo_uuid, name, instruction, behaviors) を呼び出してください。5 つすべてが必須です。作成時と同じ repo_uuid を使い、behaviors リスト全体を送信してください。エージェントを 2 つ作成してはいけません。更新後も無効状態は維持されます。有効状態を変更する場合は toggle_ai_agent_status を使用してください。
• パイプ間の PERMISSION_DENIED。 create_connected_card またはパイプ間の create_card を含む behaviors では、サービスアカウントがソースと宛先の両方のパイプのメンバーである必要があります。メンバーでない場合、API は詳細のない PERMISSION_DENIED を返します。復旧するには、宛先のパイプで get_pipe_members と invite_members を実行してください。
• move_card のフェーズ遷移ルール。 宛先フェーズには、ソースフェーズから遷移できる必要があります（cards_can_be_moved_to_phases）。validate_ai_agent_behaviors と create_ai_agent／update_ai_agent は、このエラーに valid_destinations と、遷移ルールは Pipefy の UI でのみ編集できるというヒントを追加します。
• エージェントあたりの behaviors は最大 5 件です。 6 件目を追加すると、保存全体が拒否されます。
• ゴーストエージェント。 get_ai_agents に表示されるエージェントでも、get_ai_agent で「Agent not found」が返ることがあります。これは Pipefy バックエンドの問題で、セッションをまたいで継続します。再試行しないでください。
• GraphQL エラーのヒント。 専用の読み取りツールが permission-denied または not-found を返す場合、error.message に具体的なツール名が記載されることがあります（例："Use 'get_ai_agents' to list agents..."）。そのヒントに従い、別の手順を推測しないでください。
• 検証による拒否。 よくある問題は、無効な trigger_event、長すぎるプロンプト、必須のアクション設定の不足です。behavior ごとに errors フィールドを確認してください。

関連項目

• pipefy-automations — 従来の自動化とAIによる自動化（AIエージェントとは異なります）。
• pipefy-observability — エージェントの実行ログとクレジット使用量。
• docs/mcp/tools/identifiers.md#ai-agents-and-knowledge-bases — 各ツールや引数でスラッグ、internal_id、uuid、数値 ID のどれを指定するかを示す正式な対応表です（AIエージェントは repo_uuid = pipe UUID でスコープを指定します）。