Développement d'intégration Apify

Concevez et construisez une intégration officielle Apify pour le produit d'une entreprise, avec une aide minimale d'Apify. Cette compétence couvre toutes les formes d'intégration qu'Apify supporte - applications d'automatisation de flux, plugins d'agents IA (agents de codage et harnais), paquets de frameworks IA, et clients d'application directs - pour qu'une équipe partenaire puisse livrer une intégration Apify de première classe de bout en bout. Les règles transversales ci-dessous s'appliquent à tous, et un fichier de référence spécifique à chaque catégorie contient le reste.

Construisez une intégration officielle ? Une fois que vous la publiez, contactez integrations@apify.com pour que l'équipe Apify puisse examiner, tester et valider votre intégration avant qu'elle n'atteigne les utilisateurs. Nous vérifierons la surface de capacité, les contrôles de coût, la gestion des erreurs et les en-têtes d'attribution, et vous aiderons à combler les lacunes.

Étape 0 - Apprenez d'abord le modèle Apify (requis)

Avant de concevoir quoi que ce soit, récupérez et lisez https://apify.com/agents.md. C'est le guide de démarrage canonique pour les agents IA et la source unique de vérité pour le vocabulaire, le flux d'exécution et la règle de coût. Si la récupération échoue, le mini-glossaire ci-dessous garde la compétence utilisable.

Vocabulaire Apify (toujours écrit avec un A majuscule sur la plateforme) :

Actor - un programme cloud sans serveur qui prend une entrée JSON, exécute une tâche et produit une sortie structurée. Pas un agent IA.
Actor Run - une exécution d'un Actor. Chaque exécution a son propre dataset, key-value store et request queue, et se termine dans un état terminal (SUCCEEDED, FAILED, TIMED-OUT, ABORTED).
Dataset - stockage structuré en ajout seul pour les résultats d'une exécution. Un appel Actor retourne l'ID du dataset, pas son contenu.
Key-Value Store - stockage non structuré/fichiers (screenshots, HTML, OUTPUT).
Actor Task - une configuration paramétrisée et sauvegardée pour exécuter un Actor.
Apify Store - la marketplace des Actors à https://apify.com/store.md.
Apify Console - l'interface web à https://console.apify.com.
Compute Unit (CU) - unité de facturation : mémoire (MB) x durée (heures).

Autres termes (build, standby, request queue, proxy, pricing models) : https://docs.apify.com/llms.txt.

Utilisez Apify MCP pour le contexte en direct lors de la planification

Le serveur Apify MCP est le moyen le plus rapide de rechercher des Actors, schémas, tarification et docs lors de la conception d'intégration. Voir https://docs.apify.com/integrations/mcp (ajouter .md pour une version markdown).

Si les outils Apify MCP sont déjà disponibles dans cet environnement, utilisez-les :

search-actors - trouvez des Actors par plateforme/mot-clé produit (recherchez par nom de produit, pas par objectif final).
fetch-actor-details - lisez le schéma d'entrée, le format de sortie, le README et la tarification d'un Actor avant de coder sa forme dans l'intégration.
search-apify-docs / fetch-apify-docs - récupérez les pages de documentation contextuelles.

Le sous-ensemble de découverte anonyme (search-actors, fetch-actor-details, search-apify-docs, fetch-apify-docs) fonctionne sans compte, afin que vous puissiez faire des recherches même avant que le développeur ait connecté son token.

Choisissez votre forme d'intégration

Lisez exactement un fichier de référence en fonction du produit que vous intégrez. Chaque référence porte le design UX spécifique à la catégorie, une matrice de capacité canonique et une liste de vérification de définition d'achèvement.

Forme de produit	Exemples	Lire
Plateforme d'automatisation de flux	Zapier, n8n, Make, Pipedream, Activepieces	`references/workflow-automation.md`
Plugin d'agent IA (agent de codage ou harnais)	Cursor, Claude Code, Codex, GitHub Copilot (agents de codage) ; runtimes style OpenClaw, harnais style Hermes (harnais)	`references/ai-harness-plugin.md`
Paquet de framework IA (PyPI/npm pour frameworks LLM)	LangChain, LlamaIndex, Haystack, Vercel AI SDK	`references/ai-framework-package.md`
Intégration d'application (client direct)	Un service backend, job planifié, fonctionnalité produit appelant des Actors via `apify-client` ou REST	`references/sdk-integration.md`

Les chemins sont relatifs au dossier de cette compétence. Si votre produit s'étend sur deux formes (p. ex. un harnais IA construit sur un paquet de framework), lisez les deux - les règles se composent. La référence du plugin d'agent IA couvre deux approches avec des compromis différents : un bundle léger de skills + MCP pour les agents de codage conscients des skills/MCP, et un plugin de registre d'outils personnalisé pour les harnais style OpenClaw/Hermes.

Règles de conception transversales (vraies pour chaque type d'intégration)

Ces invariants ont été extraits de chaque intégration Apify existante. Appliquez-les indépendamment de la forme.

Mirroring du vocabulaire

Modelez les ressources de l'intégration sur le domaine d'Apify (Actor / Run / Dataset / KV Store / Task). Les utilisateurs venant de la Apify Console devraient trouver les mêmes concepts sous les mêmes noms.

Flux d'exécution asynchrone avec polling limité

Les Actors peuvent s'exécuter pendant des secondes à des heures. Utilisez le flux asynchrone, jamais l'endpoint synchrone de 300 secondes que pour les tâches courtes :

POST /v2/actors/{actorId}/runs            -> démarrer, retourner runId
GET  /v2/actor-runs/{runId}               -> faire un poll jusqu'au statut terminal
GET  /v2/datasets/{datasetId}/items       -> récupérer les résultats sur SUCCEEDED

Le polling doit être limité : utilisez le timeoutSecs de l'exécution lui-même plus un buffer de grâce, avec un plafond absolu de secours. Jamais while (true). Sur un statut non-terminal, surfacez l'ID d'exécution afin que l'utilisateur/agent puisse faire un poll à nouveau ou inspecter l'échec.

Le coût est de première classe

Chaque chemin qui démarre une exécution doit exposer un contrôle de coût. Le contrôle canonique est maxTotalChargeUsd (limite la charge totale de l'exécution sur la plupart des modèles de tarification) et maxItems (limite les articles facturés sur les Actors au paiement par résultat). Envoyez-les comme options / paramètres de requête, jamais comme entrée Actor - à l'intérieur de l'entrée, ils sont soit un champ déclaré par un Actor, soit simplement invalides. 0 / vide / null signifie pas de limite. Pour les intégrations orientées LLM, les plafonds sont contrôlés par le développeur ; un LLM ne peut pas les élargir.

En-têtes d'attribution

Horodatez un en-tête d'intégration sur chaque requête sortante afin qu'Apify puisse attribuer le trafic : x-apify-integration-platform: <votre-plateforme>. Quand une requête est conduite par un outil IA (pas un humain dans une UI), envoyez aussi x-apify-integration-ai-tool: true. Si l'intégration a été construite avec cette compétence, ajoutez x-apify-integration-origin: apify-integration-development-skill afin qu'Apify puisse distinguer les intégrations générées par compétence des intégrations personnalisées. Une seule ligne, un grand bénéfice pour la télémétrie.

Authentification

Orienté navigateur / consommateur (un humain complète une connexion) : OAuth2 avec PKCE. Ne demandez pas de tokens bruts.
Sans serveur / serveur / CI (pas d'humain présent) : token API comme Authorization: Bearer <APIFY_TOKEN>, stocké dans une variable d'env ou secret manager, jamais codé en dur ou enregistré.

Les deux chemins sont réels - choisissez en fonction de qui est présent au moment de l'authentification, pas en fonction de ce qui est plus facile.

Couche HTTP centralisée

Une constante base-URL, partagée entre les credentials et la couche HTTP. Réessais avec backoff exponentiel sur 429 et 5xx. Ne réessayez jamais les POST /runs non-idempotents sur les erreurs réseau - une exécution Actor en doublon est une opération réelle, facturée et avec effets secondaires. C'est le seul invariant de correction le plus important dans la couche HTTP.

Taxonomie des erreurs

Mappez les erreurs Apify aux catégories d'erreurs de la plateforme hôte (réessayable vs authentification vs permanent). Surfacez le texte d'erreur réel de l'API, pas un message HTTP générique. Pour les échecs d'approbation de permission (un Actor en pleine permission a besoin d'une approbation explicite), incluez l'URL d'approbation après l'avoir validée comme une URL http(s) absolue. Pour les consommateurs LLM, retournez les erreurs en tant que données (objets d'erreur JSON), jamais en tant qu'exceptions levées - le modèle a besoin de quelque chose à lire et à raisonner.

Webhooks plutôt que polling pour les événements run-finished

Quand l'hôte supporte les webhooks entrants, enregistrez un webhook Apify limité à actorId ou actorTaskId avec les statuts terminaux que l'utilisateur a choisis. Rendez l'enregistrement idempotent (un flux réactivé ne devrait pas créer de webhooks en doublon), persistez l'ID du webhook afin que la désactivation puisse le nettoyer, et fournissez toujours des données d'exemple/secours pour que les utilisateurs puissent tester le trigger sans attendre une véritable exécution.

Générez à partir d'OpenAPI où l'hôte le permet

Si la plateforme hôte peut générer des champs UI à partir d'une spec OpenAPI, utilisez la spec d'Apify (https://apify.com/openapi.json) et une allowlist de tags. N'écrivez à la main que ce que la spec ne peut pas exprimer : wrappers de commodité, champs de plafond de facturation, contrats de sortie d'outil IA légers.

Opérations de commodité de haut niveau aux côtés des exécutions génériques

La "exécution Actor" générique sert les utilisateurs avancés. Ajoutez quelques actions opiniâtres et de haut niveau pour le cas courant (p. ex. "Scraper une URL unique" enveloppant un content scraper avec maxCrawlDepth: 0, maxResults: 1) afin que les utilisateurs non-avancés obtiennent un formulaire à 2 champs au lieu d'une configuration Actor complète. Validez l'URL avant de démarrer une exécution payante.

Test et livraison

Gardez deux modes de test : simulé (hermétique, pas de credentials) et E2E en direct (API réelle, limitée par CI). Automatisez les livraisons via le CI de la plateforme hôte sur Git tags / GitHub Releases. Ne modifiez jamais à la main les versions ou changelogs si un flux de livraison les gère.

Anti-patterns principaux à refuser lors de la révision

Réessayer POST /runs sur une erreur réseau - duplique une exécution facturée.
Polling while (true) sans limite - bloque l'hôte sans plafond.
Mettre maxTotalChargeUsd / maxItems à l'intérieur de l'entrée Actor au lieu d'options - n'est silencieusement pas un plafond.
Déverser un dataset complet dans un contexte LLM sans plafonds de taille ou clôture de contenu non approuvé - prompt injection et débordement de contexte.
Une liste d'outils monolithique pour un agent LLM - la précision du routage se dégrade au-delà de ~8 outils ; curez les sous-ensembles.
Surfacer un statut/message HTTP brut au lieu du texte d'erreur réel d'Apify - les utilisateurs ne peuvent pas agir sur "400".

Surface API minimale que chaque intégration doit avoir

Objectif	Méthode + chemin
Démarrer une exécution Actor	`POST /v2/actors/{actorId}/runs`
Démarrer une exécution Task	`POST /v2/actor-tasks/{taskId}/runs`
Faire un poll d'une exécution	`GET /v2/actor-runs/{runId}`
Lister les exécutions	`GET /v2/actor-runs`
Items du dataset	`GET /v2/datasets/{datasetId}/items`
Enregistrement KV	`GET /v2/key-value-stores/{storeId}/records/{key}`
Définir l'enregistrement KV	`PUT /v2/key-value-stores/{storeId}/records/{key}`
Recherche de store	`GET /v2/store`
Webhook CRUD	`POST/GET/DELETE /v2/webhooks`
Valider le token / utilisateur actuel	`GET /v2/users/me`

Référence REST : https://docs.apify.com/api/v2. Spec OpenAPI : https://apify.com/openapi.json.

Flux de travail fonctionnel

Récupérez https://apify.com/agents.md et intériorisez le modèle.
Choisissez la forme d'intégration ci-dessus et lisez le fichier de référence correspondant.
Utilisez Apify MCP (si disponible) pour rechercher les Actors concrets, les schémas et la tarification que l'intégration exposera.
Rédigez la matrice de capacité pour la catégorie choisie (chaque référence en a une) et la spec UX (ressource -> opération -> champs -> erreurs).
Structurez l'intégration en suivant les règles spécifiques à la catégorie dans la référence.
Vérifiez par rapport à la liste de vérification de définition d'achèvement à la fin de cette référence.

Implémentations de référence à étudier

De vraies intégrations publiques par catégorie - lisez leur source en cas de doute :

Automatisation de flux : @apify/n8n-nodes-apify (npm), l'app Apify Zapier.
Plugins d'agents IA (agents de codage) : le bundle de plugin Apify (serveur MCP + skills + router + slash commands) livré pour Cursor, Claude Code, Copilot et outils similaires.
Plugins d'agents IA (harnais) : apify-hermes-agent-plugin (PyPI), @apify/apify-openclaw-plugin.
Paquets de frameworks IA : langchain-apify (PyPI).
Intégration d'application : voir references/sdk-integration.md pour l'utilisation canonique de apify-client en JS/TS, Python et sur REST.

Support pour les questions d'intégration : integrations@apify.com. Contactez-nous à la fois pour l'orientation de conception pendant que vous construisez et pour la révision/test une fois que vous publiez - nous validons la surface de capacité, les contrôles de coût, la gestion des erreurs et l'attribution avant que l'intégration n'atteigne les utilisateurs.