pipefy-automations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Automations

自动化

Traditional automations (if/then rules), AI automations (prompt-driven), task automations, and simulation. 16 MCP tools.

For AI agents (conversational agents with behaviors), see skills/ai-agents/pipefy-ai-agents/SKILL.md.

传统自动化（if/then规则）、AI自动化（提示驱动）、任务自动化和模拟。16种MCP工具。

如需了解AI代理（具备行为能力的对话式代理），请查看skills/ai-agents/pipefy-ai-agents/SKILL.md。

Traditional automations (rules engine)

传统自动化（规则引擎）

Tool (MCP)	CLI	Purpose
`get_automations`	`pipefy automation list`	List all automations for a pipe.
`get_automation`	`pipefy automation get`	Single automation with full rule config — returns `event_params` and `action_params` (including `aiParams` for AI rules).
`create_automation`	`pipefy automation create`	Create an if/then rule. `active` defaults to true. First-class typed `condition` (see Conditions); other fields via `extra_input` .
`update_automation`	`pipefy automation update`	Patch a rule: first-class typed `condition` (see Conditions) and/or `extra_input` .
`delete_automation`	`pipefy automation delete`	(Two-step destructive)
`simulate_automation`	`pipefy automation simulate`	AI-only dry-run ( `generate_with_ai` action).
`get_automation_events`	`pipefy automation events list`	Available trigger events.
`get_automation_event_attributes`	`pipefy automation event-attributes`	Official `field_map.value` event-attribute tokens.
`get_automation_actions`	`pipefy automation actions list`	Available action types for a pipe.
`create_send_task_automation`	`pipefy automation send-task create`	Shortcut for send-a-task rules.

Logs, usage, and job exports for automations live in skills/observability/pipefy-observability/SKILL.md (

get_automation_logs

get_automation_logs_by_repo

get_automations_usage

export_automation_jobs

, and related tools).

工具（MCP）	CLI 命令	用途
`get_automations`	`pipefy automation list`	列出某个管道的所有自动化规则。
`get_automation`	`pipefy automation get`	获取单个自动化规则的完整配置——返回 `event_params` 和 `action_params` （包含AI规则的 `aiParams` ）。
`create_automation`	`pipefy automation create`	创建if/then规则。 `active` 默认值为true。支持一等类型化 `condition` （参见条件——基于字段测试管控规则）；其他字段通过 `extra_input` 传入。
`update_automation`	`pipefy automation update`	更新规则：支持一等类型化 `condition` （参见条件——基于字段测试管控规则）和/或 `extra_input` 。
`delete_automation`	`pipefy automation delete`	（两步式破坏性操作）
`simulate_automation`	`pipefy automation simulate`	仅适用于AI的试运行（ `generate_with_ai` 动作）。
`get_automation_events`	`pipefy automation events list`	获取可用的触发事件。
`get_automation_event_attributes`	`pipefy automation event-attributes`	获取官方 `field_map.value` 事件属性令牌。
`get_automation_actions`	`pipefy automation actions list`	获取某个管道的可用动作类型。
`create_send_task_automation`	`pipefy automation send-task create`	发送任务规则的快捷工具。

自动化的日志、使用情况和任务导出功能位于skills/observability/pipefy-observability/SKILL.md（包含

get_automation_logs

、

get_automation_logs_by_repo

、

get_automations_usage

、

export_automation_jobs

及相关工具）。

AI automations (prompt-driven)

AI自动化（提示驱动）

Tool (MCP)	CLI	Purpose
`get_ai_automations`	`pipefy ai-automation list`	List AI automations for a pipe.
`get_ai_automation`	`pipefy ai-automation get`	Full config including prompt, fields, condition.
`create_ai_automation`	`pipefy ai-automation create`	Create a prompt-driven automation (requires AI enabled on the pipe).
`update_ai_automation`	`pipefy ai-automation update`	Change name, `active` , prompt, `field_ids` , or `condition` .
`delete_ai_automation`	`pipefy ai-automation delete`	(Two-step destructive)
`validate_ai_automation_prompt`	`pipefy ai-automation validate-prompt`	Pre-flight check. Returns `{valid, problems, warnings, field_map}` — also detects prompt `%{id}` ∩ `field_ids` overlap.

工具（MCP）	CLI 命令	用途
`get_ai_automations`	`pipefy ai-automation list`	列出某个管道的AI自动化规则。
`get_ai_automation`	`pipefy ai-automation get`	获取完整配置，包括提示词、字段和条件。
`create_ai_automation`	`pipefy ai-automation create`	创建提示驱动的自动化规则（要求管道已启用AI功能）。
`update_ai_automation`	`pipefy ai-automation update`	修改名称、 `active` 状态、提示词、 `field_ids` 或 `condition` 。
`delete_ai_automation`	`pipefy ai-automation delete`	（两步式破坏性操作）
`validate_ai_automation_prompt`	`pipefy ai-automation validate-prompt`	预检查。返回 `{valid, problems, warnings, field_map}` ——还会检测提示词中的 `%{id}` 与 `field_ids` 的重叠情况。

Steps — create an AI automation

步骤——创建AI自动化

Discover field
internal_id
s for any field referenced in the prompt:
```
get_phase_fields phase_id="<phase_id>"
```
Build the prompt with
```
%{<internal_id>}
```
references. Pipefy silently rejects prompts with no field reference (returns
```
"Input parameters are required."
```
).
Important: the
```
%{...}
```
wrapper and a numeric field
```
internal_id
```
from your pipe are required — the exact digits in examples below (e.g.
```
900000101
```
) are fictional placeholders. Discover real IDs via
```
get_phase_fields
```
/
```
get_start_form_fields
```
; do not copy example numbers from docs.

Validate the prompt:

validate_ai_automation_prompt pipe_id=67890 prompt="Summarize %{900000101} and comment." field_ids=["900000101"]

Returns

valid:true|false

problems

warnings

field_map

. Catches mistakes in one read-only call vs 2–3 failed mutation roundtrips.

Create the automation (only if

valid:true

create_ai_automation pipe_id=67890 trigger_event="card_created" prompt="Summarize %{900000101} and comment." field_ids=["900000101"]

查找提示词中引用字段的
internal_id
：

get_phase_fields phase_id="<phase_id>"

构建提示词，使用
```
%{<internal_id>}
```
引用字段。Pipefy会静默拒绝未包含字段引用的提示词（返回
```
"Input parameters are required."
```
）。
重要提示：必须使用
```
%{...}
```
包裹，且字段
```
internal_id
```
为您管道中的数字ID——以下示例中的具体数字（如
```
900000101
```
）为虚构占位符。请通过
```
get_phase_fields
```
/
```
get_start_form_fields
```
查找真实ID，请勿直接复制文档中的示例编号。

验证提示词：

validate_ai_automation_prompt pipe_id=67890 prompt="Summarize %{900000101} and comment." field_ids=["900000101"]

valid:true|false

、

problems

、

warnings

和

field_map

。通过一次只读调用即可捕获错误，避免2-3次失败的变更往返操作。

创建自动化规则（仅当

valid:true

时执行）：

create_ai_automation pipe_id=67890 trigger_event="card_created" prompt="Summarize %{900000101} and comment." field_ids=["900000101"]

Steps — create a traditional automation

步骤——创建传统自动化

Discover events for the pipe:
```
get_automation_events pipe_id=67890
```
.
Discover actions for the pipe:
```
get_automation_actions pipe_id=67890
```
. (Always discover first; never guess
```
trigger_id
```
/
```
action_id
```
.)
Build the rule with the discovered IDs and call
```
create_automation
```
.
Verify by reading back with
```
get_automation
```
.

查找管道的可用事件：
```
get_automation_events pipe_id=67890
```
。
查找管道的可用动作：
```
get_automation_actions pipe_id=67890
```
。（务必先查找，切勿猜测
```
trigger_id
```
/
```
action_id
```
。）
使用查找到的ID构建规则，并调用
```
create_automation
```
。
验证：通过
```
get_automation
```
读取已创建的规则。

Conditions — gate a rule on field tests

条件——基于字段测试管控规则

create_automation

and

update_automation

take a first-class

condition

(CLI:

--condition

). Do not guess the shape from GraphQL introspection — it is:

json

{
  "expressions": [
    {"field_address": "900000101", "operation": "equals", "value": "Done", "structure_id": 0}
  ],
  "expressions_structure": [[0]]
}

field_address

is the field internal_id
(numeric, from

get_start_form_fields

get_phase_fields

), not the slug. For a connected card's field use

<connectorFieldId>.<targetFieldId>

operation

(soft enum — any value is passed through, the API validates):

equals

not_equals

present

blank

string_contains

string_not_contains

number_greater_than

number_less_than

date_is_today

date_is_yesterday

date_in_current_week

date_in_last_week

date_in_current_month

date_in_last_month

date_in_current_year

date_in_last_year

date_is

date_is_after

date_is_before

. Omit

value

for

present

blank

```
expressions_structure
```
groups expressions (by
```
structure_id
```
) as AND-of-ORs: inner arrays are OR'd, the inner arrays are AND'd —
```
[[0, 1], [2]]
```
is
```
(expr0 OR expr1) AND expr2
```
.

Omit

condition

to leave a traditional rule unconditional (no default is injected). A

condition

argument wins over any

condition

extra_input

create_automation

和

update_automation

支持一等类型化的

condition

（CLI：

--condition

）。请勿通过GraphQL自省猜测其结构，正确结构如下：

json

{
  "expressions": [
    {"field_address": "900000101", "operation": "equals", "value": "Done", "structure_id": 0}
  ],
  "expressions_structure": [[0]]
}

```
field_address
```
为字段的**
```
internal_id
```
**（数字格式，来自
```
get_start_form_fields
```
/
```
get_phase_fields
```
），而非slug。对于关联卡片的字段，请使用
```
<connectorFieldId>.<targetFieldId>
```
格式。

operation

（软枚举——任何值都会被传递，由API进行验证）：

equals

、

not_equals

、

present

、

blank

、

string_contains

、

string_not_contains

、

number_greater_than

、

number_less_than

、

date_is_today

、

date_is_yesterday

、

date_in_current_week

、

date_in_last_week

、

date_in_current_month

、

date_in_last_month

、

date_in_current_year

、

date_in_last_year

、

date_is

、

date_is_after

、

date_is_before

。使用

present

blank

时可省略

value

。

```
expressions_structure
```
按
```
structure_id
```
对表达式进行分组，采用“或的与”逻辑：内部数组为或关系，内部数组之间为与关系——
```
[[0, 1], [2]]
```
表示
```
(expr0 或 expr1) 且 expr2
```
。

若省略

condition

，则传统规则将无任何条件（不会注入默认条件）。

condition

参数的优先级高于

extra_input

中的

condition

。

Steps — update a card field with a dynamic value

步骤——使用动态值更新卡片字段

Use when the user wants an if/then rule to stamp or copy values onto the triggering card (for example, set a datetime when

card_created

fires). This is create_automation
with

action_id: update_card_field

and

extra_input.action_params.field_map

— not the MCP tool

update_card_field

(that tool uses field slug for one-off card edits).

Discover field
internal_id
s (digits only — never slug in

fieldId

get_start_form_fields pipe_id=67890
get_phase_fields phase_id="<phase_id>"

Discover trigger, action, and event-attribute tokens:

get_automation_events pipe_id=67890
get_automation_actions pipe_id=67890
get_automation_event_attributes

For

update_card_field

acceptedParameters

omits

field_map

; use the payload shape below (see

docs/mcp/tools/automations-and-ai.md

). Prefer

value_token

from

get_automation_event_attributes

when stamping execution time.

Create disabled (

active=false

) so the rule does not fire while you verify:

create_automation pipe_id=67890 name="Stamp execution time on new cards" trigger_id=card_created action_id=update_card_field active=false extra_input={"action_params":{"card_id":"%{id}","field_map":[{"fieldId":"<destination_internal_id>","inputMode":"copy_from","value":"%{automation_event_execution_datetime}"}],"fields_map_order":["<destination_internal_id>"]}}

Common

value

tokens when

inputMode

copy_from

%{id}

(also use in

card_id

%{created_at}

%{automation_event_execution_datetime}

%{<other_internal_id>}

to copy another field.

Verify persisted config:

get_automation automation_id=<id>

Confirm

action_params.field_map

round-tripped.

Enable when correct:

update_automation automation_id=<id> extra_input={"active":true}

当用户希望通过if/then规则标记或复制值到触发卡片时使用此方法（例如，当

card_created

触发时设置日期时间）。需使用

create_automation

，并指定

action_id: update_card_field

和

extra_input.action_params.field_map

——请勿使用MCP工具

update_card_field

（该工具通过字段slug进行单次卡片编辑）。

查找字段的
internal_id
（仅数字——

fieldId

中切勿使用slug）：

get_start_form_fields pipe_id=67890
get_phase_fields phase_id="<phase_id>"

查找触发事件、动作和事件属性令牌：

get_automation_events pipe_id=67890
get_automation_actions pipe_id=67890
get_automation_event_attributes

对于

update_card_field

，

acceptedParameters

中不包含

field_map

；请使用以下负载格式（参见

docs/mcp/tools/automations-and-ai.md

）。标记执行时间时，优先使用

get_automation_event_attributes

返回的

value_token

。

创建禁用状态的规则（

active=false

），以便在验证期间规则不会触发：

create_automation pipe_id=67890 name="Stamp execution time on new cards" trigger_id=card_created action_id=update_card_field active=false extra_input={"action_params":{"card_id":"%{id}","field_map":[{"fieldId":"<destination_internal_id>","inputMode":"copy_from","value":"%{automation_event_execution_datetime}"}],"fields_map_order":["<destination_internal_id>"]}}

当

inputMode

为

copy_from

时，常见的

value

令牌包括：

%{id}

（也可用于

card_id

）、

%{created_at}

、

%{automation_event_execution_datetime}

、

%{<other_internal_id>}

（用于复制其他字段）。

验证持久化配置：

get_automation automation_id=<id>

确认

action_params.field_map

已正确保存。

启用规则（验证正确后）：

update_automation automation_id=<id> extra_input={"active":true}

Steps — simulate a traditional automation

步骤——模拟传统自动化

simulate_automation

is AI-only today (only

generate_with_ai

action_id

is accepted). For non-AI rules, watch

get_automation_logs

after the trigger fires.

Read a working rule first:

get_automation automation_id=<id>

— copy

event_params

and

action_params

verbatim.

Simulate with a real sample card:

simulate_automation pipe_id=67890 action_id=generate_with_ai sample_card_id=456

Result is async: returns
```
simulation_id
```
+
```
status:"processing"
```
with null
```
simulationResult
```
. No polling tool exists in v0.1 — wait, then re-invoke
```
get_automation_logs
```
or
```
simulate_automation
```
.

目前

simulate_automation

仅适用于AI（仅接受

generate_with_ai

作为

action_id

）。对于非AI规则，请在触发事件后查看

get_automation_logs

。

先读取一个可用规则：

get_automation automation_id=<id>

——直接复制

event_params

和

action_params

。

使用真实示例卡片进行模拟：

simulate_automation pipe_id=67890 action_id=generate_with_ai sample_card_id=456

结果为异步：返回
```
simulation_id
```
+
```
status:"processing"
```
，且
```
simulationResult
```
为null。v0.1版本中无轮询工具——请等待一段时间后，重新调用
```
get_automation_logs
```
或
```
simulate_automation
```
。

Traditional automation preflight

传统自动化预检查

field_map

destination

fieldId

field_map

目标

fieldId

create_automation

, when

extra_input.action_params.field_map

is present, the SDK checks each

fieldId

against numeric

internal_id

values on the action pipe (

action_repo_id

, default

pipe_id

). Slug-shaped

fieldId

values and unknown numeric ids fail before GraphQL with

success: false

and the offending id. Recovery:

get_start_form_fields

get_phase_fields

→ use

internal_id

, not slug.

在

create_automation

中，当存在

extra_input.action_params.field_map

时，SDK会检查每个

fieldId

是否与动作管道（

action_repo_id

，默认为

pipe_id

）中的数字

internal_id

匹配。slug格式的

fieldId

或未知数字ID会在GraphQL请求前失败，返回

success: false

及错误ID。解决方法：使用

get_start_form_fields

get_phase_fields

获取

internal_id

，而非slug。

Phase transition (

move_single_card

)

阶段转移（

move_single_card

）

For

move_single_card

actions with trigger

card_moved

, create_automation
only validates that the destination phase is reachable from the source via

cards_can_be_moved_to_phases

(same read-only data as

move_card_to_phase

update_automation

does not run this check.

If invalid, the tool returns

success: false

with a text error message listing allowed destination phases by name and id, plus a hint that transition rules are configured in the Pipefy UI only (not editable via API). There is no structured

valid_destinations

field on this envelope.

Recovery: read the allowed phases in

error.message

, or call

get_phase_allowed_move_targets(phase_id=<source_phase_id>)

on the source phase from

event_params.to_phase_id

, then re-issue

create_automation

with a permitted destination phase id.

对于触发事件为

card_moved

的

move_single_card

动作，**仅

create_automation

**会验证目标阶段是否可从源阶段通过

cards_can_be_moved_to_phases

到达（与

move_card_to_phase

使用相同的只读数据）。

update_automation

不会执行此检查。

若验证失败，工具会返回

success: false

及文本错误消息，列出允许的目标阶段名称和ID，并提示阶段转移规则仅可在Pipefy UI中配置（无法通过API编辑）。该响应中无结构化的

valid_destinations

字段。

解决方法：在

error.message

中读取允许的阶段，或调用

get_phase_allowed_move_targets(phase_id=<source_phase_id>)

（源阶段ID来自

event_params.to_phase_id

），然后使用允许的目标阶段ID重新调用

create_automation

。

Notification disambiguation

通知工具区分

Pick the right tool for "notification" intent:

User signal words	Tool	Why
"notificação", "tarefa", "lembrete para alguém validar"	`create_send_task_automation`	Built-in: handles `event_id` , `task_title` , `recipients` , optional `event_params` and `condition` .
"enviar e-mail", "responder ao cliente"	`send_email_with_template` / `send_inbox_email` (members-email-webhooks)	Email surface, not automations.
"webhook", "chamar serviço externo"	`create_webhook` (members-email-webhooks)	HTTP callback on card events.
"automação", "regra if/then"	`create_automation`	Generic rules engine.

Do NOT hand-build

action_params.taskParams

via

create_automation

when

create_send_task_automation

is the right tool.

根据“通知”意图选择合适的工具：

用户关键词	工具	原因
"notificação"、"tarefa"、"lembrete para alguém validar"	`create_send_task_automation`	内置功能：处理 `event_id` 、 `task_title` 、 `recipients` ，可选 `event_params` 和 `condition` 。
"enviar e-mail"、"responder ao cliente"	`send_email_with_template` / `send_inbox_email` （members-email-webhooks）	邮件相关功能，不属于自动化范畴。
"webhook"、"chamar serviço externo"	`create_webhook` （members-email-webhooks）	卡片事件触发的HTTP回调。
"automação"、"regra if/then"	`create_automation`	通用规则引擎。

当

create_send_task_automation

为合适工具时，请勿通过

create_automation

手动构建

action_params.taskParams

。

Agentic + human-in-the-loop pattern

智能代理+人工审核模式

Combine AI automations with task automations so AI handles routine work and humans validate high-impact decisions. The highest-leverage pattern in the catalog.

Example flow:

```
create_ai_automation
```
: when card enters "Análise", AI fills classification and risk fields automatically.
```
create_send_task_automation
```
: when the AI-filled field is updated, send a task to the manager — "Validate the classification on card [title]".
```
create_automation
```
or
```
create_field_condition
```
: when the manager marks "Approved", move the card to the next phase.

Use this pattern for approvals, financial decisions, content publication, and any step where errors have real-world consequences. See also: skills/process-design/ Orchestration patterns.

将AI自动化与任务自动化结合，让AI处理常规工作，人工审核高影响决策。这是目录中价值最高的模式。

示例流程：

```
create_ai_automation
```
：当卡片进入“分析”阶段时，AI自动填充分类和风险字段。
```
create_send_task_automation
```
：当AI填充的字段更新时，向经理发送任务——“验证卡片[标题]的分类”。
```
create_automation
```
或
```
create_field_condition
```
：当经理标记“已批准”时，将卡片移至下一阶段。

此模式适用于审批、财务决策、内容发布及任何错误会产生实际影响的步骤。另请参阅：skills/process-design/ 编排模式。

Success criteria

成功标准

```
get_automation
```
returns the new rule with correct trigger and actions.
```
validate_ai_automation_prompt
```
returns
```
valid:true
```
before AI automation creation.
```
simulate_automation
```
(AI rules) eventually returns a non-null
```
simulationResult
```
.

```
get_automation
```
返回包含正确触发事件和动作的新规则。
创建AI自动化前，
```
validate_ai_automation_prompt
```
返回
```
valid:true
```
。
```
simulate_automation
```
（AI规则）最终返回非空的
```
simulationResult
```
。

Failure modes

失败模式

simulate_automation
is AI-only. Only
```
generate_with_ai
```
```
action_id
```
accepted. For traditional rules, use
```
get_automation_logs
```
after the rule fires.

Async simulation result.

simulate_automation

returns

simulation_id

status:"processing"

+ null

simulationResult

; no polling tool in v0.1. Wait, then call

get_automation_logs

or re-invoke

simulate_automation

validate_ai_automation_prompt
returns
valid:false
. Read
```
problems
```
(per-field) and
```
warnings
```
. Most common: prompt missing
```
%{internal_id}
```
reference, or
```
field_ids
```
overlap with prompt
```
%{id}
```
tokens.

create_automation
cycle detection. Same-pipe

card_created

create_card

rejected with

"This automation can't be created! It would result in an endless card creation cycle."

Use a different trigger, target a different pipe, or use

update_card

instead.

create_automation
fails with unknown event/action. Always run
```
get_automation_events
```
+
```
get_automation_actions
```
first; do not guess IDs.
Phase transition error on
move_single_card
. Only
```
create_automation
```
preflights transitions. Read allowed phase ids in the error text or call
```
get_phase_allowed_move_targets
```
, then re-issue with a permitted destination. UI is the only edit surface for transition rules.
Cross-pipe
PERMISSION_DENIED
. SA must be member of both source and destination pipes for
```
create_connected_card
```
/ cross-pipe
```
create_card
```
. Recovery:
```
get_pipe_members
```
+
```
invite_members
```
.
get_automation_logs_by_repo
returns empty. Pipe has no traditional automation executions; not an error. AI agent executions are separate (see
```
get_ai_agent_logs
```
).
create_send_task_automation
fires immediately when
active=true
. Pass
```
active=false
```
first if you want to wire it up before the rule starts firing. The 2026-04-16 orphaned-task incident is the cautionary tale.

update_automation
API asymmetry.

create_automation

takes a top-level

active

param;

update_automation

requires

extra_input={"active": false}

. Pass

active

through

extra_input

when toggling on an existing rule.

action_repo_id
semantics. For cross-pipe actions (
```
create_connected_card
```
,
```
create_card
```
into another pipe), this is the destination pipe, not the source.
Simulation reuses real rule params. Before simulating, call
```
get_automation
```
to read
```
event_params
```
and
```
action_params
```
of a working rule and pass them verbatim. Don't hand-craft params.
field_map
uses slug in
fieldId
. Preflight rejects non-numeric
```
fieldId
```
before GraphQL; slugs (e.g.
```
due_date
```
) used to surface as
```
INTERNAL_SERVER_ERROR
```
. Recovery:
```
get_start_form_fields
```
/
```
get_phase_fields
```
→ use
```
internal_id
```
.
Unknown
field_map

fieldId
.
```
create_automation
```
preflight fails with the offending id when the destination field is not on the action pipe. Re-discover ids on
```
action_repo_id
```
(not only the trigger pipe for cross-pipe actions).
Used
update_card_field
MCP tool for a rule. That tool updates one card by slug; automations need
```
create_automation
```
+
```
field_map
```
with numeric
```
fieldId
```
.
Missing or wrong
card_id
. Set
```
action_params.card_id
```
to
```
"%{id}"
```
for the triggering card; empty/wrong values prevent the intended update.
Token typo in
field_map.value
. Typos in
```
%{…}
```
templates leave fields unchanged at runtime. Compare with Automation Event Attributes and a working rule from
```
get_automation
```
.
Rule runs but field unchanged. Check
```
get_automation_logs
```
/
```
get_automation_logs_by_repo
```
for execution errors; invalid
```
fieldId
```
may fail silently (no card update).

simulate_automation
仅适用于AI。仅接受
```
generate_with_ai
```
作为
```
action_id
```
。对于传统规则，请在规则触发后使用
```
get_automation_logs
```
。
模拟结果异步。
```
simulate_automation
```
返回
```
simulation_id
```
+
```
status:"processing"
```
+ null
```
simulationResult
```
；v0.1版本中无轮询工具。请等待一段时间后，调用
```
get_automation_logs
```
或重新调用
```
simulate_automation
```
。
validate_ai_automation_prompt
返回
valid:false
。查看
```
problems
```
（按字段）和
```
warnings
```
。最常见原因：提示词缺少
```
%{internal_id}
```
引用，或
```
field_ids
```
与提示词中的
```
%{id}
```
令牌重叠。

create_automation
循环检测。同一管道中

card_created

create_card

的组合会被拒绝，返回

"This automation can't be created! It would result in an endless card creation cycle."

。请使用其他触发事件、目标其他管道，或改用

update_card

。

create_automation
因未知事件/动作失败。务必先运行
```
get_automation_events
```
+
```
get_automation_actions
```
；切勿猜测ID。
move_single_card
阶段转移错误。仅
```
create_automation
```
会预检查阶段转移。在错误文本中读取允许的阶段ID，或调用
```
get_phase_allowed_move_targets
```
，然后使用允许的目标阶段重新调用。阶段转移规则仅可在UI中编辑。
跨管道
PERMISSION_DENIED
。服务账号必须同时是源管道和目标管道的成员，才能执行
```
create_connected_card
```
/ 跨管道
```
create_card
```
。解决方法：
```
get_pipe_members
```
+
```
invite_members
```
。
get_automation_logs_by_repo
返回空。管道无传统自动化执行记录；这并非错误。AI代理执行记录单独存储（参见
```
get_ai_agent_logs
```
）。
create_send_task_automation
在
active=true
时立即触发。如果希望先配置规则再启用，请先传递
```
active=false
```
。2026-04-16的孤立事件就是前车之鉴。

update_automation
API不对称。

create_automation

接受顶级

active

参数；

update_automation

要求传入

extra_input={"active": false}

。启用现有规则时，请通过

extra_input

传递

active

参数。

action_repo_id
语义。对于跨管道动作（
```
create_connected_card
```
、向其他管道
```
create_card
```
），此参数为目标管道ID，而非源管道。
模拟复用真实规则参数。模拟前，调用
```
get_automation
```
读取可用规则的
```
event_params
```
和
```
action_params
```
，并直接传递这些参数。请勿手动构建参数。
field_map
在
fieldId
中使用slug。预检查会在GraphQL请求前拒绝非数字
```
fieldId
```
；此前slug（如
```
due_date
```
）会导致
```
INTERNAL_SERVER_ERROR
```
。解决方法：使用
```
get_start_form_fields
```
/
```
get_phase_fields
```
获取
```
internal_id
```
。
field_map
中存在未知
fieldId
。当目标字段不在动作管道中时，
```
create_automation
```
预检查会失败并返回错误ID。请在
```
action_repo_id
```
中重新查找ID（跨管道动作时，切勿仅在触发管道中查找）。
使用
update_card_field
MCP工具配置规则。该工具通过slug更新单张卡片；自动化规则需使用
```
create_automation
```
+ 包含数字
```
fieldId
```
的
```
field_map
```
。
card_id
缺失或错误。将
```
action_params.card_id
```
设置为
```
"%{id}"
```
以指向触发卡片；空值/错误值会导致预期的更新无法执行。
field_map.value
中令牌拼写错误。
```
%{…}
```
模板中的拼写错误会导致运行时字段无变化。请与Automation Event Attributes及
```
get_automation
```
返回的可用规则进行对比。
规则运行但字段未更新。查看
```
get_automation_logs
```
/
```
get_automation_logs_by_repo
```
中的执行错误；无效
```
fieldId
```
可能会静默失败（无卡片更新）。

另请参阅

skills/ai-agents/pipefy-ai-agents/SKILL.md — conversational agents with behaviors (different from AI automations).
skills/observability/pipefy-observability/SKILL.md — execution logs and usage stats.
skills/introspection/pipefy-introspection/SKILL.md — discover trigger and action types via raw schema.
skills/process-design/pipefy-process-design/SKILL.md — Orchestration patterns (agentic + human validation).

docs/mcp/tools/identifiers.md#field-references-slug-vs-internal_id

— canonical map of which tool/argument expects slug vs

internal_id

vs uuid vs numeric id (

field_address

and

field_map[].fieldId

want internal_id).

skills/ai-agents/pipefy-ai-agents/SKILL.md —— 具备行为能力的对话式代理（与AI自动化不同）。
skills/observability/pipefy-observability/SKILL.md —— 执行日志和使用统计。
skills/introspection/pipefy-introspection/SKILL.md —— 通过原始架构发现触发事件和动作类型。
skills/process-design/pipefy-process-design/SKILL.md —— 编排模式（智能代理+人工审核）。

docs/mcp/tools/identifiers.md#field-references-slug-vs-internal_id

—— 规范说明不同工具/参数应使用slug、

internal_id

、uuid还是数字ID（

field_address

和

field_map[].fieldId

需使用internal_id）。

pipefy-automations

Original

Translation

Automations

自动化

Traditional automations (rules engine)

传统自动化（规则引擎）

AI automations (prompt-driven)

AI自动化（提示驱动）

Steps — create an AI automation

步骤——创建AI自动化

Steps — create a traditional automation

步骤——创建传统自动化

Conditions — gate a rule on field tests

条件——基于字段测试管控规则

Steps — update a card field with a dynamic value

步骤——使用动态值更新卡片字段

Steps — simulate a traditional automation

步骤——模拟传统自动化

Traditional automation preflight

传统自动化预检查

`field_map`
destination
`fieldId`

`field_map`
目标
`fieldId`

Phase transition (
`move_single_card`
)

阶段转移（
`move_single_card`
）

Notification disambiguation

通知工具区分

Agentic + human-in-the-loop pattern

智能代理+人工审核模式

Success criteria

成功标准

Failure modes

失败模式

See also

另请参阅

pipefy-automations

Original

Translation

Automations

自动化

Traditional automations (rules engine)

传统自动化（规则引擎）

AI automations (prompt-driven)

AI自动化（提示驱动）

Steps — create an AI automation

步骤——创建AI自动化

Steps — create a traditional automation

步骤——创建传统自动化

Conditions — gate a rule on field tests

条件——基于字段测试管控规则

Steps — update a card field with a dynamic value

步骤——使用动态值更新卡片字段

Steps — simulate a traditional automation

步骤——模拟传统自动化

Traditional automation preflight

传统自动化预检查

field_map destination fieldId

field_map目标fieldId

Phase transition (move_single_card)

阶段转移（move_single_card）

Notification disambiguation

通知工具区分

Agentic + human-in-the-loop pattern

智能代理+人工审核模式

Success criteria

成功标准

Failure modes

失败模式

See also

另请参阅

`field_map`
destination
`fieldId`

`field_map`
目标
`fieldId`

Phase transition (
`move_single_card`
)

阶段转移（
`move_single_card`
）