apify-integration-development

Apify 統合の開発

Apify のサポートを最小限に抑えながら、企業の製品向けに公式の Apify 統合を設計・構築します。このスキルでは、Apify がサポートするすべての統合形態（ワークフロー自動化アプリ、AI エージェントプラグイン（コーディングエージェントとハーネス）、AI フレームワークパッケージ、直接利用するアプリケーションクライアント）を扱い、パートナーチームが Apify の本格的な統合をエンドツーエンドで提供できるようにします。以下の横断的なルールはすべての形態に適用され、各カテゴリ固有の残りの情報は、それぞれのリファレンスファイルに記載されています。

公式統合を構築していますか？ 公開したら、ユーザーに提供される前に Apify チームが統合をレビュー、テスト、検証できるよう、[email protected] までご連絡ください。機能範囲、コスト管理、エラー処理、アトリビューションヘッダーを確認し、不足があれば解消をお手伝いします。

ステップ 0 - まず Apify のモデルを学ぶ（必須）

設計を始める前に、https://apify.com/agents.md を取得して読みます。これは AI エージェント向けの標準クイックスタートであり、用語、実行フロー、コストルールの唯一の信頼できる情報源です。取得に失敗した場合でも、以下の簡易用語集を使えばこのスキルを利用できます。

Apify の用語（プラットフォーム上では常に先頭を大文字の A で表記します）：

• Actor - JSON 入力を受け取り、タスクを実行して、構造化された出力を生成するサーバーレスのクラウドプログラムです。AI エージェントではありません。
• Actor Run - Actor の 1 回の実行です。各実行には専用のデータセット、キーバリューストア、リクエストキューがあり、最終ステータス（SUCCEEDED、FAILED、TIMED-OUT、ABORTED）で終了します。
• Dataset - 実行結果を保存する追記専用の構造化ストレージです。Actor の呼び出しで返されるのはデータセット ID であり、内容ではありません。
• Key-Value Store - スクリーンショット、HTML、OUTPUT などを保存する非構造化／ファイルストレージです。
• Actor Task - Actor を実行するために保存された、パラメーター設定済みの構成です。
• Apify Store - https://apify.com/store.md にある Actor のマーケットプレイスです。
• Apify Console - https://console.apify.com にあるウェブ UI です。
• Compute Unit (CU) - 課金単位です。メモリ（MB）× 実行時間（時間）で計算します。
• Server Actor - 独自の安定した URL で常時稼働する HTTP サーバーとして動く Actor です（API やドキュメントでは、現在も Standby と呼ばれる場合があります）。リクエストを送信すると応答で結果が返されます。開始する実行も、読み取るデータセットもありません。

その他の用語（ビルド、リクエストキュー、プロキシ、料金モデル）：https://docs.apify.com/llms.txt。

計画時に Apify MCP を使って最新情報を確認する

Apify MCP サーバーは、統合の設計時に Actor、スキーマ、料金、ドキュメントを調べる最速の方法です。https://docs.apify.com/integrations/mcp を参照してください（Markdown 版は末尾に .md を追加します）。

この環境ですでに Apify MCP ツールが利用可能な場合は、使用してください。

• search-actors - プラットフォーム／製品のキーワードで Actor を検索します（最終的な目的ではなく、製品名で検索します）。
• fetch-actor-details - Actor の入力スキーマ、出力形式、README、料金を読み取り、その形式を統合に組み込む前に確認します。
• search-apify-docs / fetch-apify-docs - 関連するドキュメントページを取得します。

匿名で利用できる検索ツール（search-actors、fetch-actor-details、search-apify-docs、fetch-apify-docs）はアカウントなしで動作するため、開発者がトークンを連携する前でも調査できます。

統合の形を選ぶ

統合先の製品に基づいて、該当するリファレンスファイルを正確に1つ読んでください。各リファレンスには、カテゴリ固有のUX設計、標準的な機能マトリックス、完了条件のチェックリストが記載されています。

製品の形	例	読むファイル
ワークフロー自動化プラットフォーム	Zapier、n8n、Make、Pipedream、Activepieces	references/workflow-automation.md
AI エージェントプラグイン（コーディングエージェントまたはハーネス）	Cursor、Claude Code、Codex、GitHub Copilot（コーディングエージェント）；OpenClaw のようなランタイム、Hermes のようなハーネス（ハーネス）	references/ai-harness-plugin.md
AI フレームワークパッケージ（LLM フレームワーク向け PyPI/npm）	LangChain、LlamaIndex、Haystack、Vercel AI SDK	references/ai-framework-package.md
アプリケーション統合（直接クライアント）	apify-client または REST を介して Actor を呼び出すバックエンドサービス、スケジュール済みジョブ、製品機能	references/sdk-integration.md

パスはこのスキルフォルダーからの相対パスです。製品が2つの形にまたがる場合（例：フレームワークパッケージ上に構築された AI ハーネス）は、両方を読んでください。ルールは組み合わせて適用されます。AI エージェントプラグインのリファレンスでは、トレードオフの異なる2つのアプローチを扱います。スキル／MCP 対応コーディングエージェント向けの軽量なスキル＋MCP バンドルと、OpenClaw／Hermes のようなハーネス向けのカスタムツールレジストリプラグインです。

横断的な設計ルール（すべての統合タイプに適用）

これらの不変条件は、既存の Apify 統合すべてから抽出されたものです。統合の形にかかわらず適用してください。

用語の対応

統合のリソースは Apify のドメイン（Actor／Run／Dataset／KV Store／Task）に合わせて設計してください。Apify Console を利用しているユーザーが、同じ概念を同じ名前で見つけられるようにします。

非同期実行フローと上限付きポーリング

Actor の実行時間は数秒から数時間に及ぶことがあります。非同期フローを使用し、短時間のジョブ以外には300秒の同期エンドポイントを決して使用しないでください。

POST /v2/actors/{actorId}/runs            -> start, return runId
GET  /v2/actor-runs/{runId}               -> poll until terminal status
GET  /v2/datasets/{datasetId}/items       -> fetch results on SUCCEEDED

ポーリングには上限を設けてください。Run 自身の timeoutSecs に猶予時間を加えて使用し、絶対的な上限をフォールバックとして設けます。while (true) は決して使用しないでください。終端状態でない場合は、ユーザー／エージェントが再度ポーリングしたり、失敗を調査したりできるよう、Run ID を提示してください。

コストを第一級の要素として扱う

実行を開始するすべての経路で、コストを制御できるようにしてください。標準的な制御項目は maxTotalChargeUsd（ほとんどの料金モデルで Run の合計料金に上限を設定）と maxItems（結果ごとの従量課金型 Actor で課金対象アイテム数に上限を設定）です。これらは Actor の入力ではなく、オプション／クエリパラメーターとして送信してください。入力内では Actor が宣言したフィールドとして扱われるか、単に無効になります。0／空／null は上限なしを意味します。LLM 向けの統合では、上限は開発者が制御します。LLM が上限を引き上げることはできません。Web Fetch（下記）のような Server Actor リクエストでは Run を開始しないため、どちらのオプションも必要ありません。

アトリビューションヘッダー

Apify がトラフィックを識別できるよう、すべての送信リクエストに統合ヘッダーを設定してください。x-apify-integration-platform: <your-platform>。リクエストが（UI を操作する人間ではなく）AI ツールによって実行される場合は、x-apify-integration-ai-tool: true も送信してください。このスキルを使って統合を構築した場合は、x-apify-integration-origin: apify-integration-development-skill を追加すると、Apify がスキル生成の統合とカスタム統合を区別できます。1行追加するだけで、テレメトリーへの効果は大きくなります。

認証

• ブラウザー／コンシューマー向け（人間がサインインを完了する）：PKCE を使用した OAuth2。生のトークンを要求しないでください。
• ヘッドレス／サーバー／CI（人間が介在しない）：Authorization: Bearer <APIFY_TOKEN> として API トークンを使用し、環境変数またはシークレットマネージャーに保存してください。ハードコードしたり、ログに記録したりしないでください。

どちらの方法も適切です。どちらが簡単かではなく、認証時に誰がいるかに基づいて選択してください。

HTTP 層の一元化

認証情報と HTTP 層で共有するベース URL 定数を 1 つ用意します。Server Actor は独自のホスト（https://web-fetch.apify.actor）上にあります。これも同じ層を経由させ、認証ヘッダーとアトリビューションヘッダーが引き続き適用されるようにします。429 および 5xx では、指数バックオフで再試行します。ネットワークエラー時に、べき等でない POST /runs は決して再試行しないでください。Actor の実行が重複すると、実際に課金され、副作用も発生します。これは HTTP 層で最も重要な正確性の不変条件です。

エラーの分類

Apify のエラーを、ホストプラットフォームのエラーカテゴリ（再試行可能、認証、恒久的）に対応付けます。汎用的な HTTP メッセージではなく、API の実際のエラーテキストを表示します。権限承認エラー（すべての権限を必要とする Actor には明示的な承認が必要な場合）では、絶対 http(s) URL であることを検証したうえで、承認 URL を含めます。LLM の利用者には、エラーを例外として送出せず、データとして（JSON エラーオブジェクトで）返します。モデルが読み取り、推論するために必要です。

実行完了イベントにはポーリングではなく Webhook を使用

ホストがインバウンド Webhook に対応している場合は、ユーザーが選んだ終了ステータスを指定し、actorId または actorTaskId にスコープした Apify Webhook を登録します。登録は冪等にし（ワークフローを再有効化しても Webhook が重複して作成されないようにします）、Webhook ID を保存して無効化時にクリーンアップできるようにします。また、実際の実行を待たずにトリガーをテストできるよう、必ずサンプルデータまたは代替データを提供します。

ホストが対応している場合は OpenAPI から生成

ホストプラットフォームが OpenAPI 仕様から UI フィールドを生成できる場合は、Apify の仕様（https://apify.com/openapi.json）とタグの許可リストを使用します。仕様で表現できないものに限り、利便性のためのラッパー、課金上限フィールド、簡潔な AI ツール出力の契約を手書きします。

汎用的な実行と併せて高レベルの便利な操作を提供

汎用的な「Actor を実行」は、パワーユーザー向けです。一般的なケース向けの、意見を取り入れた高レベルのアクションをいくつか追加し、パワーユーザーではない人が Actor の設定全体ではなく、2 フィールドのフォームを使えるようにします。代表的なのはWeb Fetchです。URL を 1 つ入力するとページコンテンツが返され、apify/web-fetch Server Actor を基盤としています。POST https://web-fetch.apify.actor/ に {"url": "...", "formats": ["markdown"]} を送信すると、レスポンスにコンテンツが返されます。実行は開始されないため、上記の実行ルール（非同期フロー、ポーリング、maxTotalChargeUsd）は適用されません。コストは、リクエスト成功ごとに fetch イベント 1 件です。正しく処理するためのポイントは 3 つです。必ず formats を送信すること、fetch.httpStatusCode を確認すること（HTTP 200 は Web Fetch 自体が成功したことを示すだけです）、2 種類のエラー形式（Actor からのフラットな {code, error} と、プラットフォームからのネストされた {error: {message}}）を処理し、502/504 を自動で再試行しないことです。完全な仕様は https://apify.com/apify/web-fetch.md を参照してください。maxCrawlDepth: 0 を指定したクローラーの実行で構築しないでください。これは従来の「単一 URL をスクレイピング」するパターンです。

テストとリリース

テストモードは、モック（分離されており、認証情報不要）とライブ E2E（実際の API を使用し、CI で実行を制御）の 2 つを維持します。ホストプラットフォームの CI を通じて、Git タグまたは GitHub Releases でリリースを自動化します。リリースワークフローがバージョンや変更履歴を管理する場合、それらを手動で編集しないでください。

レビューで拒否すべき主なアンチパターン

1. ネットワークエラー時に POST /runs を再試行すること。課金対象の実行が重複します。
2. 上限のない while (true) ポーリング。上限なしにホストを占有します。
3. maxTotalChargeUsd / maxItems をオプションではなく Actor 入力に含めること。上限として機能せず、気付かないまま課金が発生します。
4. サイズ上限や信頼できないコンテンツへの対策なしに、データセット全体を LLM のコンテキストに投入すること。プロンプトインジェクションやコンテキストの肥大化につながります。
5. LLM エージェント向けのツール一覧を 1 つにまとめること。ツールが約 8 個を超えると振り分けの精度が低下するため、サブセットを厳選してください。
6. Apify の実際のエラーテキストではなく、生の HTTP ステータス／メッセージを表示すること。「400」ではユーザーが対処できません。

すべての統合に必要な最小限の API サーフェス

目的	メソッド + パス
Actor の実行を開始	POST /v2/actors/{actorId}/runs
Task の実行を開始	POST /v2/actor-tasks/{taskId}/runs
実行をポーリング	GET /v2/actor-runs/{runId}
実行を一覧表示	GET /v2/actor-runs
データセットの項目	GET /v2/datasets/{datasetId}/items
KV レコード	GET /v2/key-value-stores/{storeId}/records/{key}
KV レコードを設定	PUT /v2/key-value-stores/{storeId}/records/{key}
ストアを検索	GET /v2/store
Webhook の CRUD	POST/GET/DELETE /v2/webhooks
トークンの検証／現在のユーザー	GET /v2/users/me
URL を 1 件取得（Web Fetch、Server Actor）	POST https://web-fetch.apify.actor/

REST リファレンス：https://docs.apify.com/api/v2。OpenAPI 仕様：https://apify.com/openapi.json。

作業ワークフロー

1. https://apify.com/agents.md を取得し、そのモデルを理解します。
2. 上記から統合の形を選び、該当するリファレンスファイルを読みます。
3. 利用可能であれば Apify MCP を使い、統合で公開する具体的な Actor、スキーマ、料金を調査します。
4. 選択したカテゴリの機能マトリックス（各リファレンスに記載）と、UX 仕様（リソース -> 操作 -> フィールド -> エラー）を作成します。
5. リファレンスのカテゴリ固有のルールに従って、統合のひな形を作成します。
6. 該当するリファレンスの末尾にある完了条件チェックリストに照らして確認します。

調査するリファレンス実装

カテゴリごとの実際の公開統合です。不明点があれば、ソースを参照してください。

• ワークフロー自動化：@apify/n8n-nodes-apify（npm）、Apify Zapier アプリ。
• AI エージェントプラグイン（コーディングエージェント）：Cursor、Claude Code、Copilot などのツール向けに提供される Apify プラグインバンドル（MCP サーバー + スキル + ルーター + スラッシュコマンド）。
• AI エージェントプラグイン（ハーネス）：apify-hermes-agent-plugin（PyPI）、@apify/apify-openclaw-plugin。
• AI フレームワークパッケージ：langchain-apify（PyPI）。
• アプリケーション統合：JS/TS、Python、REST での標準的な apify-client の使用方法については、references/sdk-integration.md を参照してください。

統合に関する質問のサポート：[email protected]。構築中の設計ガイダンスと、公開後のレビュー／テストの両方についてお問い合わせください。統合がユーザーに提供される前に、機能範囲、コスト管理、エラー処理、クレジット表記を検証します。