Back to Details

apify-integration-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apify Integration Development

Apify集成开发

Design and build an official Apify integration for a company's product, with minimal help from Apify. This skill covers every integration shape Apify supports - workflow-automation apps, AI agent plugins (coding agents and harnesses), AI framework packages, and direct application clients - so a partner team can ship a first-class Apify integration end to end. The cross-cutting rules below apply to all of them, and one category-specific reference file carries the rest.
Building an official integration? Once you publish it, contact integrations@apify.com so the Apify team can review, test, and validate your integration before it reaches users. We'll check the capability surface, cost controls, error handling, and attribution headers, and help you close any gaps.
在仅需Apify少量协助的情况下，为企业产品设计并构建官方Apify集成。本技能涵盖Apify支持的所有集成形态——工作流自动化应用、AI Agent插件（编码Agent与harness）、AI框架包、直接应用客户端——以便合作团队能够端到端交付一流的Apify集成。以下通用规则适用于所有集成类型，特定分类的额外规则请参考对应的分类参考文件。
正在构建官方集成？ 发布后请发送邮件至 integrations@apify.com，Apify团队会在集成面向用户前对其进行审核、测试和验证。我们会检查能力覆盖范围、成本控制、错误处理和归因头，并协助你补齐所有短板。

Step 0 - Learn the Apify model first (required)

步骤0 - 先了解Apify模式（必做）

Before designing anything, fetch and read 
https://apify.com/agents.md
. It is the canonical quickstart for AI agents and the single source of truth for vocabulary, the run flow, and the cost rule. If the fetch fails, the mini-glossary below keeps the skill usable.
Apify vocabulary (always written with a capital A on the platform):
  • Actor - a serverless cloud program that takes JSON input, performs a task, and produces structured output. Not an AI agent.
  • Actor Run - one execution of an Actor. Each run has its own dataset, key-value store, and request queue, and ends in a terminal status (
    SUCCEEDED
    , 
    FAILED
    , 
    TIMED-OUT
    , 
    ABORTED
    ).
  • Dataset - append-only structured storage for a run's results. An Actor call returns the dataset ID, not its contents.
  • Key-Value Store - unstructured/file storage (screenshots, HTML, OUTPUT).
  • Actor Task - a saved, parameterized configuration for running an Actor.
  • Apify Store - the marketplace of Actors at 
    https://apify.com/store.md
    .
  • Apify Console - the web UI at 
    https://console.apify.com
    .
  • Compute Unit (CU) - billing unit: memory (MB) x duration (hours).
Further terms (build, standby, request queue, proxy, pricing models): 
https://docs.apify.com/llms.txt
.
在进行任何设计之前，请获取并阅读 
https://apify.com/agents.md
。这是AI Agent的官方快速入门指南，也是术语、运行流程和计费规则的唯一权威来源。如果无法获取该文档，下方的迷你术语表也能保证本技能的正常使用。
Apify术语（在平台中书写时首字母始终大写）：
  • Actor - 一种接收JSON输入、执行任务并生成结构化输出的无服务器云程序。并非AI Agent。
  • Actor Run - Actor的一次执行。每个运行实例都有独立的Dataset、Key-Value Store和请求队列，并以终止状态结束（
    SUCCEEDED
    、
    FAILED
    、
    TIMED-OUT
    、
    ABORTED
    ）。
  • Dataset - 用于存储运行结果的仅追加式结构化存储。Actor调用返回的是Dataset ID，而非其内容。
  • Key-Value Store - 非结构化/文件存储（可存储截图、HTML、OUTPUT等）。
  • Actor Task - 已保存的、参数化的Actor运行配置。
  • Apify Store - 位于 
    https://apify.com/store.md
    的Actor市场。
  • Apify Console - 位于 
    https://console.apify.com
    的网页管理界面。
  • Compute Unit (CU) - 计费单位：内存（MB）× 时长（小时）。
更多术语（build、standby、请求队列、代理、定价模型）：
https://docs.apify.com/llms.txt
。

Use Apify MCP for live context while planning

规划阶段使用Apify MCP获取实时上下文

The Apify MCP server is the fastest way to research Actors, schemas, pricing, and docs during integration design. See 
https://docs.apify.com/integrations/mcp
(append 
.md
for a markdown version).
If Apify MCP tools are already available in this environment, use them:
  • search-actors
    - find Actors by platform/product keyword (search by product name, not end goal).
  • fetch-actor-details
    - read an Actor's input schema, output format, README, and pricing before you encode its shape into the integration.
  • search-apify-docs
    / 
    fetch-apify-docs
    - pull contextual documentation pages.
The anonymous discovery subset (
search-actors
, 
fetch-actor-details
, 
search-apify-docs
, 
fetch-apify-docs
) works without an account, so you can research even before the developer has connected their token.
在集成设计阶段，Apify MCP服务器是调研Actors、Schema、定价和文档的最快方式。参见 
https://docs.apify.com/integrations/mcp
（追加 
.md
可获取Markdown版本）。
如果当前环境中已提供Apify MCP工具，请使用以下工具：
  • search-actors
    - 按平台/产品关键词查找Actors（请按产品名称搜索，而非最终目标）。
  • fetch-actor-details
    - 在将Actor的形态集成到产品中之前，读取其输入Schema、输出格式、README和定价信息。
  • search-apify-docs
    / 
    fetch-apify-docs
    - 获取相关的文档页面。
匿名发现工具子集（
search-actors
、
fetch-actor-details
、
search-apify-docs
、
fetch-apify-docs
）无需账号即可使用，因此甚至在开发者连接其Token之前就可以开展调研。

Pick your integration shape

选择你的集成形态

Read exactly one reference file based on the product you are integrating into. Each reference carries the category-specific UX design, a canonical capability matrix, and a definition-of-done checklist.
Product shapeExamplesRead
Workflow automation platformZapier, n8n, Make, Pipedream, Activepieces
references/workflow-automation.md
AI agent plugin (coding agent or harness)Cursor, Claude Code, Codex, GitHub Copilot (coding agents); OpenClaw-style runtimes, Hermes-style harnesses (harnesses)
references/ai-harness-plugin.md
AI framework package (PyPI/npm for LLM frameworks)LangChain, LlamaIndex, Haystack, Vercel AI SDK
references/ai-framework-package.md
Application integration (direct client)A backend service, scheduled job, product feature calling Actors via 
apify-client
or REST
references/sdk-integration.md
Paths are relative to this skill folder. If your product spans two shapes (e.g. an AI harness built on top of a framework package), read both - the rules compose. The AI agent plugin reference covers two approaches with different trade-offs: a lightweight skills + MCP bundle for skills/MCP-aware coding agents, and a custom tool-registry plugin for OpenClaw/Hermes-style harnesses.
根据你要集成的产品类型，仅需阅读对应的一份参考文件。每份参考文件都包含该分类特有的UX设计、标准能力矩阵和完成定义检查清单。
产品形态示例参考文件
工作流自动化平台Zapier, n8n, Make, Pipedream, Activepieces
references/workflow-automation.md
AI Agent插件（编码Agent或harness）Cursor, Claude Code, Codex, GitHub Copilot（编码Agents）；OpenClaw式运行时、Hermes式harness（harness类）
references/ai-harness-plugin.md
AI框架包（面向LLM框架的PyPI/npm包）LangChain, LlamaIndex, Haystack, Vercel AI SDK
references/ai-framework-package.md
应用集成（直接客户端）后端服务、定时任务、通过
apify-client
或REST调用Actors的产品功能
references/sdk-integration.md
以上路径均相对于本技能文件夹。如果你的产品跨越两种形态（例如构建在框架包之上的AI harness），请同时阅读两份参考文件——规则是可组合的。AI Agent插件参考文件涵盖两种各有优劣的方案：面向支持skills/MCP的编码Agent的轻量级skills + MCP组合包，以及面向OpenClaw/Hermes式harness的自定义工具注册表插件。

Cross-cutting design rules (true for every integration type)

通用设计规则（适用于所有集成类型）

These invariants were extracted from every existing Apify integration. Apply them regardless of shape.
这些不变规则是从所有现有Apify集成中总结出来的，无论哪种集成形态都适用。

Vocabulary mirroring

术语对齐

Model the integration's resources on Apify's domain (Actor / Run / Dataset / KV Store / Task). Users coming from Apify Console should find the same concepts under the same names.
集成的资源模型应与Apify的领域模型保持一致（Actor / Run / Dataset / KV Store / Task）。从Apify Console过来的用户应该能看到同名的相同概念。

Asynchronous run flow with bounded polling

带轮询上限的异步运行流程

Actors can run for seconds to hours. Use the asynchronous flow, never the 300-second synchronous endpoint for anything but short jobs:
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
Polling must be bounded: use the run's own 
timeoutSecs
plus a grace buffer, with an absolute ceiling fallback. Never 
while (true)
. On a non-terminal status, surface the run ID so the user/agent can poll again or inspect the failure.
Actors的运行时间从几秒到几小时不等。请使用异步流程，除了短任务外，绝对不要使用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
轮询必须有上限：使用运行自身的
timeoutSecs
加上宽限缓冲区，并设置一个绝对上限作为兜底。绝对不要使用
while (true)
。当处于非终止状态时，应展示运行ID，以便用户/Agent可以再次轮询或检查失败原因。

Cost is first-class

成本控制优先

Every path that starts a run must expose a cost control. The canonical control is 
maxTotalChargeUsd
(caps the run's total charge on most pricing models) and 
maxItems
(caps billed items on pay-per-result Actors). Send them as options / query parameters, never as Actor input - inside input they are either an Actor-declared field or simply invalid. 
0
/ empty / null means no limit. For LLM-facing integrations, the ceilings are developer-controlled; an LLM cannot widen them.
每个启动运行的路径都必须提供成本控制功能。标准的控制参数是
maxTotalChargeUsd
（在大多数定价模式下限制运行的总费用）和
maxItems
（在按结果付费的Actors中限制计费的结果数量）。请将它们作为选项/查询参数发送，绝对不要放在Actor输入中——放在输入里的话，它们要么是Actor自行声明的字段，要么直接无效。
0
/ 空值 / null 表示无限制。对于面向LLM的集成，这些上限是由开发者控制的，LLM无法放宽这些限制。

Attribution headers

归因头

Stamp an integration header on every outbound request so Apify can attribute traffic: 
x-apify-integration-platform: <your-platform>
. When a request is driven by an AI tool (not a human in a UI), also send 
x-apify-integration-ai-tool: true
. If the integration was built using this skill, add 
x-apify-integration-origin: apify-integration-development-skill
so Apify can distinguish skill-generated integrations from custom ones. One line, big telemetry payoff.
在每个出站请求上添加集成标识头，以便Apify统计流量来源：
x-apify-integration-platform: <your-platform>
。如果请求是由AI工具驱动的（而非UI中的人类用户），还需发送
x-apify-integration-ai-tool: true
。如果集成是使用本技能构建的，请添加
x-apify-integration-origin: apify-integration-development-skill
，以便Apify区分由技能生成的集成和自定义集成。只需一行代码，就能带来巨大的遥测价值。

Authentication

身份验证

  • Browser / consumer-facing (a human completes a sign-in): OAuth2 with PKCE. Do not ask for raw tokens.
  • Headless / server / CI (no human present): API token as 
    Authorization: Bearer <APIFY_TOKEN>
    , stored in an env var or secret manager, never hardcoded or logged.
Both paths are real - pick by who is present at auth time, not by which is easier.
  • 浏览器/面向消费者的场景（由人类完成登录）：使用带PKCE的OAuth2。不要索要原始Token。
  • 无界面/服务端/CI场景（无人类参与）：使用API Token，格式为
    Authorization: Bearer <APIFY_TOKEN>
    ，存储在环境变量或密钥管理工具中，绝对不要硬编码或记录到日志中。
两种方式都是正规方案——请根据身份验证时是否有人类参与来选择，而非哪种更简单就选哪种。

Centralized HTTP layer

集中式HTTP层

One base-URL constant, shared between credentials and the HTTP layer. Retries with exponential backoff on 429 and 5xx. Never retry non-idempotent 
POST /runs
on network errors - a duplicate Actor run is a real, billed, side-effecting operation. This is the single most important correctness invariant in the HTTP layer.
设置一个基础URL常量，由凭证模块和HTTP层共享。对429和5xx状态码使用指数退避重试。绝对不要在网络错误时重试非幂等的
POST /runs
请求——重复的Actor运行是真实的、会产生费用的、有副作用的操作。这是HTTP层中最重要的正确性不变规则。

Error taxonomy

错误分类体系

Map Apify errors to the host platform's error categories (retryable vs auth vs permanent). Surface the API's actual error text, not a generic HTTP message. For permission-approval failures (a full-permission Actor needs explicit approval), include the approval URL after validating it is an absolute 
http(s)
URL. For LLM consumers, return errors as data (JSON error objects), never as raised exceptions - the model needs something to read and reason about.
将Apify错误映射到宿主平台的错误分类（可重试、身份验证错误、永久错误）。请展示API返回的实际错误文本，而非通用的HTTP消息。对于权限审批失败（需要全权限的Actor需要显式审批），请在验证审批URL为绝对
http(s)
URL后将其包含在内。对于LLM消费者，请将错误作为数据返回（JSON错误对象），绝对不要抛出异常——模型需要能够读取和推理的内容。

Webhooks over polling for run-finished events

运行完成事件优先使用Webhooks而非轮询

When the host supports inbound webhooks, register an Apify webhook scoped to 
actorId
or 
actorTaskId
with the terminal statuses the user picked. Make registration idempotent (a re-activated workflow should not create duplicate webhooks), persist the webhook ID so deactivation can clean it up, and always provide sample/fallback data so users can test the trigger without waiting for a real run.
当宿主平台支持入站Webhooks时，请注册一个作用域为
actorId
或
actorTaskId
的Apify Webhook，并设置用户选择的终止状态触发条件。请确保注册操作是幂等的（重新激活工作流不应创建重复的Webhook），持久化存储Webhook ID以便停用时清理，并且始终提供示例/兜底数据，让用户无需等待真实运行就能测试触发器。

Generate from OpenAPI where the host allows it

宿主平台允许时优先从OpenAPI生成

If the host platform can generate UI fields from an OpenAPI spec, use Apify's spec (
https://apify.com/openapi.json
) and a tag allowlist. Hand-write only what the spec cannot express: convenience wrappers, bill-cap fields, lean AI-tool output contracts.
如果宿主平台可以从OpenAPI规范生成UI字段，请使用Apify的规范（
https://apify.com/openapi.json
）和标签白名单。仅手动编写规范无法表达的内容：便捷封装、费用上限字段、精简的AI工具输出契约。

High-level convenience operations alongside generic runs

除了通用运行外，提供高层便捷操作

Generic "run Actor" serves power users. Add a few opinionated, high-level actions for the common case (e.g. "Scrape single URL" wrapping a content scraper with 
maxCrawlDepth: 0
, 
maxResults: 1
) so non-power users get a 2-field form instead of a full Actor configuration. Validate the URL before starting a paid run.
通用的「运行Actor」面向高级用户。请针对常见场景添加一些有主见的高层操作（例如「抓取单个URL」，封装了内容抓取器，设置
maxCrawlDepth: 0
、
maxResults: 1
），这样非高级用户只需填写2个字段的表单，而非完整的Actor配置。请在启动付费运行之前验证URL。

Testing and release

测试与发布

Keep two test modes: mocked (hermetic, no credentials) and live E2E (real API, CI-gated). Automate releases through the host platform's CI on Git tags / GitHub Releases. Never hand-edit versions or changelogs if a release workflow manages them.
保留两种测试模式：Mock模式（封闭环境，无需凭证）和实时E2E测试（真实API，由CI管控）。通过宿主平台的CI，在Git标签/GitHub Releases触发自动发布。如果发布工作流已经管理了版本和更新日志，就绝对不要手动编辑。

Top anti-patterns to refuse on review

审核时应拒绝的典型反模式

  1. Retrying 
    POST /runs
    on a network error - duplicates a billed run.
  2. Unbounded 
    while (true)
    polling - ties up the host with no ceiling.
  3. Putting 
    maxTotalChargeUsd
    / 
    maxItems
    inside Actor input instead of options - silently not a cap.
  4. Dumping a full dataset into an LLM context without size caps or untrusted-content fencing - prompt-injection and context blowout.
  5. One monolithic tool list for an LLM agent - routing accuracy degrades past ~8 tools; curate subsets.
  6. Surfacing a raw HTTP status/message instead of Apify's actual error text - users can't act on "400".
  1. 网络错误时重试
    POST /runs
    ——会产生重复的付费运行。
  2. 无上限的
    while (true)
    轮询——会无限制占用宿主平台资源。
  3. 将
    maxTotalChargeUsd
    / 
    maxItems
    放在Actor输入而非选项中——会静默失效，无法起到限制作用。
  4. 未经大小限制或不可信内容隔离，就将完整Dataset倒入LLM上下文——会导致提示注入和上下文溢出。
  5. 为LLM Agent提供单一的庞大工具列表——当工具数量超过约8个时，路由准确率会下降；请策划子集。
  6. 展示原始HTTP状态/消息，而非Apify的实际错误文本——用户无法根据「400」采取行动。

Minimal API surface every integration needs

所有集成都需要的最小API集

PurposeMethod + path
Start an Actor run
POST /v2/actors/{actorId}/runs
Start a Task run
POST /v2/actor-tasks/{taskId}/runs
Poll a run
GET /v2/actor-runs/{runId}
List runs
GET /v2/actor-runs
Dataset items
GET /v2/datasets/{datasetId}/items
KV record
GET /v2/key-value-stores/{storeId}/records/{key}
Set KV record
PUT /v2/key-value-stores/{storeId}/records/{key}
Store search
GET /v2/store
Webhook CRUD
POST/GET/DELETE /v2/webhooks
Validate token / current user
GET /v2/users/me
REST reference: 
https://docs.apify.com/api/v2
. OpenAPI spec: 
https://apify.com/openapi.json
.
用途方法 + 路径
启动Actor运行
POST /v2/actors/{actorId}/runs
启动Task运行
POST /v2/actor-tasks/{taskId}/runs
轮询运行状态
GET /v2/actor-runs/{runId}
列出运行记录
GET /v2/actor-runs
获取Dataset条目
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增删改查
POST/GET/DELETE /v2/webhooks
验证Token/当前用户
GET /v2/users/me
REST参考文档：
https://docs.apify.com/api/v2
。OpenAPI规范：
https://apify.com/openapi.json
。

Working workflow

工作流程

  1. Fetch 
    https://apify.com/agents.md
    and internalize the model.
  2. Pick the integration shape above and read the matching reference file.
  3. Use Apify MCP (if available) to research the concrete Actors, schemas, and pricing the integration will expose.
  4. Draft the capability matrix for the chosen category (each reference has one) and the UX spec (resource -> operation -> fields -> errors).
  5. Scaffold the integration following the category-specific rules in the reference.
  6. Verify against the definition-of-done checklist at the end of that reference.
  1. 获取 
    https://apify.com/agents.md
    并深入理解其模型。
  2. 选择上述集成形态，并阅读对应的参考文件。
  3. 使用Apify MCP（如果可用）调研集成将要对外提供的具体Actors、Schemas和定价信息。
  4. 为所选分类起草能力矩阵（每份参考文件中都有）和UX规范（资源 -> 操作 -> 字段 -> 错误）。
  5. 按照参考文件中特定分类的规则搭建集成的脚手架。
  6. 对照参考文件末尾的完成定义检查清单进行验证。

Reference implementations to study

可供学习的参考实现

Real, public integrations per category - read their source when in doubt:
  • Workflow automation: 
    @apify/n8n-nodes-apify
    (npm), the Apify Zapier app.
  • AI agent plugins (coding agents): the Apify plugin bundle (MCP server + skills + router + slash commands) shipped for Cursor, Claude Code, Copilot, and similar tools.
  • AI agent plugins (harnesses): 
    apify-hermes-agent-plugin
    (PyPI), 
    @apify/apify-openclaw-plugin
    .
  • AI framework packages: 
    langchain-apify
    (PyPI).
  • Application integration: see 
    references/sdk-integration.md
    for the canonical 
    apify-client
    usage in JS/TS, Python, and over REST.
Support for integration questions: 
integrations@apify.com
. Contact us both for design guidance while you build and for review/testing once you publish - we validate the capability surface, cost controls, error handling, and attribution before the integration reaches users.
每个分类都有真实的公开集成——有疑问时请阅读它们的源码：
  • 工作流自动化：
    @apify/n8n-nodes-apify
    （npm）、Apify Zapier应用。
  • AI Agent插件（编码Agent）：为Cursor、Claude Code、Copilot等类似工具发布的Apify插件包（MCP服务器 + skills + 路由器 + 斜杠命令）。
  • AI Agent插件（harness类）：
    apify-hermes-agent-plugin
    （PyPI）、
    @apify/apify-openclaw-plugin
    。
  • AI框架包：
    langchain-apify
    （PyPI）。
  • 应用集成：关于JS/TS、Python以及REST方式下
    apify-client
    的标准用法，请参见
    references/sdk-integration.md
    。
集成问题支持：
integrations@apify.com
。你可以在构建期间联系我们获取设计指导，也可以在发布后联系我们进行审核/测试——我们会在集成面向用户前验证其能力覆盖范围、成本控制、错误处理和归因设置。