pipefy-ai-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Agents

Conversational AI agents attached to pipes. Each agent has an agent-level instruction and 1–5 behaviors, each with its own trigger event, prompt, and actions. 7 MCP tools.

For traditional automations and AI automations (prompt-driven), see skills/automations/pipefy-automations/SKILL.md.

关联到管道的对话式AI Agent。每个Agent包含一个Agent级指令和1-5种行为，每种行为都有自己的触发事件、提示词和操作。7种MCP工具。

如需了解传统自动化和AI自动化（提示词驱动），请查看skills/automations/pipefy-automations/SKILL.md。

Tools

工具

Tool (MCP)	CLI	Read-only	Purpose
`get_ai_agents`	`pipefy agent list`	Yes	List AI agents for a pipe ( `repo_uuid` = pipe UUID, not numeric `id` ).
`get_ai_agent`	`pipefy agent get`	Yes	Full agent config including behaviors.
`create_ai_agent`	`pipefy agent create`	No	Create a new conversational agent.
`update_ai_agent`	`pipefy agent update`	No	Full-replace (not patch). Always send complete `behaviors` .
`delete_ai_agent`	`pipefy agent delete`	No	(Two-step destructive)
`toggle_ai_agent_status`	`pipefy agent toggle`	No	Enable/disable the agent (e.g. `--inactive` ).
`validate_ai_agent_behaviors`	`pipefy agent validate-behaviors`	Yes	Pre-flight check before create/update.

The read tools (

get_ai_agents

get_ai_agent

validate_ai_agent_behaviors

) and the write tools (

create

update

delete

toggle

) are all remote-safe: available under the hosted (

profile=remote

) surface.

Execution logs live in skills/observability/ (

get_ai_agent_logs

get_ai_agent_log_details

工具（MCP）	CLI 命令	只读	用途
`get_ai_agents`	`pipefy agent list`	是	列出指定管道的AI Agent（ `repo_uuid` = 管道UUID，而非数字 `id` ）。
`get_ai_agent`	`pipefy agent get`	是	获取包含行为的完整Agent配置。
`create_ai_agent`	`pipefy agent create`	否	创建新的对话式Agent。
`update_ai_agent`	`pipefy agent update`	否	全量替换（非增量更新）。发送请求时必须包含完整的 `behaviors` 。
`delete_ai_agent`	`pipefy agent delete`	否	（两步式破坏性操作）
`toggle_ai_agent_status`	`pipefy agent toggle`	否	启用/禁用Agent（例如使用 `--inactive` 参数）。
`validate_ai_agent_behaviors`	`pipefy agent validate-behaviors`	是	创建/更新前的预飞检查。

只读工具（

get_ai_agents

、

get_ai_agent

、

validate_ai_agent_behaviors

）和写入工具（

create

update

delete

toggle

）均支持远程调用：可在托管环境（

profile=remote

）下使用。

执行日志可在skills/observability/中查看（

get_ai_agent_logs

、

get_ai_agent_log_details

）。

Creation workflow (discover → validate → create → verify)

创建流程（发现 → 验证 → 创建 → 确认）

Never guess event IDs, phase IDs, action types, or field IDs.

切勿猜测事件ID、阶段ID、操作类型或字段ID。

1 — Get pipe metadata

1 — 获取管道元数据

Call

get_pipe(pipe_id)

and extract:

```
uuid
```
→ use as
```
repo_uuid
```
in all AI-agent tools.
```
phases[].id
```
/
```
phases[].name
```
→ needed for
```
move_card
```
actions.

Fields via

get_start_form_fields(pipe_id)

and/or

get_phase_fields(phase_id)

→ needed for

update_card

actions.

调用

get_pipe(pipe_id)

并提取：

```
uuid
```
→ 在所有AI Agent工具中用作
```
repo_uuid
```
。
```
phases[].id
```
/
```
phases[].name
```
→ 执行
```
move_card
```
操作时需要。

通过

get_start_form_fields(pipe_id)

和/或

get_phase_fields(phase_id)

获取字段 → 执行

update_card

操作时需要。

2 — Check existing agents

2 — 检查现有Agent

get_ai_agents(repo_uuid)

to avoid duplicates. To modify an existing agent, use

update_ai_agent

(not create). For full config, use

get_ai_agent(uuid)

调用

get_ai_agents(repo_uuid)

避免重复创建。如需修改现有Agent，请使用

update_ai_agent

（而非创建新Agent）。如需获取完整配置，请使用

get_ai_agent(uuid)

。

3 — Discover valid trigger events

3 — 发现有效的触发事件

get_automation_events(pipe_id)

. Common events:

Event ( `event_id` value)	`event_params` required	Example
card_created	None	`{}`
card_moved	`{"to_phase_id":"<phase_id>"}`	Fires only when card enters that phase.
field_updated	`{"triggerFieldIds":["<field_id>", ...]}`	Fires only when those fields change.
manually_triggered	None	User clicks button on card.

For

card_moved

and

field_updated

, you MUST include

event_params

. Omitting it makes the behavior fire on every occurrence.

调用

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 — Discover valid action types

4 — 发现有效的操作类型

get_automation_actions(pipe_id)

. The 6 known

actionType

values and their required

metadata

Action ( `actionType` value)	`metadata` required
update_card	`pipeId` + `fieldsAttributes` (each entry needs `fieldId` + `inputMode` )
move_card	`destinationPhaseId`
create_card	`pipeId` + `fieldsAttributes`
create_connected_card	`pipeId` + `fieldsAttributes` (requires pipe relation)
create_table_record	`tableId` + `fieldsAttributes` (table field IDs; no `pipeId` )
send_email_template	`emailTemplateId` ; optional `allowTemplateModifications` (bool)

fieldId

values for card actions accept slug or numeric

internal_id

; for

create_table_record

they are table field IDs (validate with

get_table

get_table_record

, not the pipe).

调用

get_automation_actions(pipe_id)

。已知的6种

actionType

值及其所需的

metadata

：

操作（ `actionType` 值）	是否需要 `metadata`
update_card	是
move_card	是
create_card	是
create_connected_card	是
create_table_record	是
send_email_template	是

卡片操作的

fieldId

值接受字段别名（slug）或数字

internal_id

；

create_table_record

的

fieldId

为表格字段ID（需通过

get_table

get_table_record

验证，而非管道）。

5 — Build the behavior dict

5 — 构建行为字典

json

{
  "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": { } }
      ]
    }
  }
}

Each behavior MUST have at least one action in
```
actionsAttributes
```
.
Maximum 5 behaviors per agent.
The MCP tool auto-injects
```
referenceId
```
and
```
%{action:<uuid>}
```
placeholders — do NOT generate these yourself.
inputMode
is required on every
fieldsAttributes
entry (omitting it fails model validation). Values:
```
fill_with_ai
```
(AI writes the value into an output field),
```
fixed_value
```
(use the literal
```
value
```
),
```
copy_from
```
(
```
value
```
is a
```
%{…}
```
template copying another field).
Input field references (
```
%{field:<internal_id>}
```
in the behavior
```
instruction
```
, auto-populated into
```
referencedFieldIds
```
on create/update) are needed only when the AI must read card field values, not for every
```
fill_with_ai
```
(e.g. instruction-only, OCR/attachment, or knowledge-base context). When card inputs are needed and omitted,
```
card.fields
```
arrives empty at trigger time and the model may hallucinate. A wrong numeric input id is accepted silently (validate and create/update) and becomes a dead
```
referencedFieldId
```
; a wrong slug never resolves and is dropped by the digits-only extractor (unresolved token). Either way
```
card.fields
```
stays empty (same hallucination); confirm the id with
```
get_start_form_fields
```
/
```
get_phase_fields
```
. Dotted connected-pipe refs (
```
%{field:<parent>.<child>}
```
) are not forwarded at runtime; to read a connected card field, use a field on the current pipe.
For
```
update_card
```
: set
```
destinationPhaseId: ""
```
when not moving the card.

json

{
  "name": "<描述性名称>",
  "event_id": "<来自步骤3>",
  "event_params": {},
  "actionParams": {
    "aiBehaviorParams": {
      "instruction": "<事件触发时给AI的提示词>",
      "actionsAttributes": [
        { "name": "<操作标签>", "actionType": "<来自步骤4>", "metadata": { } }
      ]
    }
  }
}

每个行为的
```
actionsAttributes
```
中必须至少包含一个操作。
每个Agent最多包含5种行为。
MCP工具会自动注入
```
referenceId
```
和
```
%{action:<uuid>}
```
占位符 — 请勿自行生成。
每个
fieldsAttributes
条目必须包含
inputMode
（省略会导致模型验证失败）。可选值：
```
fill_with_ai
```
（AI将值写入输出字段）、
```
fixed_value
```
（使用字面
```
value
```
）、
```
copy_from
```
（
```
value
```
为
```
%{…}
```
模板，复制另一个字段的值）。
仅当AI需要读取卡片字段值时，才需要在行为
```
instruction
```
中添加输入字段引用（
```
%{field:<internal_id>}
```
，创建/更新时会自动填充到
```
referencedFieldIds
```
），并非所有
```
fill_with_ai
```
场景都需要（例如仅提示词、OCR/附件或知识库上下文场景）。若需要卡片输入但未添加引用，触发时
```
card.fields
```
会为空，模型可能产生幻觉。错误的数字输入ID会被静默接受（验证和创建/更新时），成为无效的
```
referencedFieldId
```
；错误的字段别名无法解析，会被数字提取器丢弃（未解析令牌）。两种情况都会导致
```
card.fields
```
为空（同样产生幻觉）；请通过
```
get_start_form_fields
```
/
```
get_phase_fields
```
确认ID。带点的关联管道引用（
```
%{field:<parent>.<child>}
```
）在运行时不会被转发；如需读取关联卡片字段，请使用当前管道的字段。
对于
```
update_card
```
：不移动卡片时，请设置
```
destinationPhaseId: ""
```
。

Example identifiers (fictional)

示例标识符（虚构）

Use real values from

get_pipe

get_start_form_fields

for your org. Placeholders below match unit-test fixtures in this repo. The syntax matters (

pipeId

fieldId

%{field:<internal_id>}

inputMode

) — the example digits do not; substitute each pipe's numeric

internal_id

and phase id.

Role	Example value
Pipe (numeric repo id)	`987654321`
Field `internal_id`	`900000101`
Destination phase ( `move_card` )	`900000201`
Target pipe ( `create_card` )	`900000301`

请使用您组织中

get_pipe

get_start_form_fields

返回的真实值。以下占位符与本仓库中的单元测试 fixture 匹配。语法至关重要（

pipeId

、

fieldId

、

%{field:<internal_id>}

、

inputMode

）— 示例数字无关紧要；请替换为每个管道的数字

internal_id

和阶段ID。

角色	示例值
管道（数字仓库ID）	`987654321`
字段 `internal_id`	`900000101`
目标阶段（ `move_card` ）	`900000201`
目标管道（ `create_card` ）	`900000301`

Metadata examples

Metadata示例

json

// 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
{ "destinationPhaseId": "900000201", "pipeId": "", "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 }

json

// update_card — 输出字段使用fill_with_ai；提示词中引用输入字段
{ "pipeId": "987654321", "destinationPhaseId": "", "fieldsAttributes": [{ "fieldId": "900000101", "inputMode": "fill_with_ai", "value": "" }] }
// 对应的提示词（aiBehaviorParams.instruction），非metadata:
// "读取%{field:900000102}（标题）和%{field:900000103}（描述），然后填写分类。"

// move_card
{ "destinationPhaseId": "900000201", "pipeId": "", "fieldsAttributes": [] }

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

// create_table_record（fieldsAttributes为表格字段ID；无需pipeId）
{ "tableId": "<table_id>", "fieldsAttributes": [{ "fieldId": "<table_field_id>", "inputMode": "fill_with_ai", "value": "" }] }

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

5b — Optional: capabilities and LLM provider

5b — 可选：功能与LLM提供商

Inside

actionParams.aiBehaviorParams

a behavior may also carry:

capabilitiesAttributes
— advanced tools the behavior can use. Each entry is exactly
```
{ "capabilityType": "<type>", "enabled": true|false }
```
(both keys required, no extra keys — bare strings or
```
{ "type": ... }
```
are rejected).
Product name
capabilityType
IDP / Intelligent Document Processing
advanced_ocr
Calculations & Analysis
math_operations
Web Search
web_search
Web Scraping
web_scraping
Max effort
max_effort
```
capabilityType
```
is not checked against a fixed set — any value passes through and the API validates the enum on write, so new capabilities work without a toolkit update. Validation checks shape only, not entitlement — a capability may still require organization-level enablement to have any effect, so a green pre-flight does not guarantee the capability is active for the org.
providerId
/ systemProviderId
— pick the behavior's LLM provider. Set at most one (a behavior resolves to a single active provider). Discover valid IDs with
```
get_llm_providers
```
(CLI:
```
pipefy ai-provider list
```
): each provider carries
```
type
```
— use
```
providerId
```
for a custom (
```
byom
```
) provider and
```
systemProviderId
```
for a Pipefy-managed (
```
system
```
) one.
```
get_default_llm_provider
```
shows what a behavior falls back to when neither is set. IDs are also visible in the organization's AI settings in the Pipefy UI.
Bring your own model (custom provider). To back a behavior with your own vendor credentials, create a custom provider first, then use its
```
id
```
as
```
providerId
```
:
```
validate_llm_provider_access
```
(confirm read access — writes need the stronger
```
manage_ai_providers
```
org permission and an eligible plan, so a write may still be denied) →
```
create_llm_provider
```
with the configuration in a local JSON file (
```
configuration_file_path
```
; never inline — secrets are never logged or returned; the file's
```
provider
```
key selects the vendor). Manage it with
```
update_llm_provider
```
(send the full configuration; leave the
```
__REDACTED__
```
placeholders from
```
get_llm_providers
```
in place to keep existing secrets, or put a new value to rotate one),
```
set_llm_provider_active_status
```
, and
```
delete_llm_provider
```
(check
```
get_llm_provider_dependencies
```
first). Set the organization default with
```
set_default_llm_provider
```
(exactly one of
```
provider_id
```
/
```
system_provider_id
```
) or clear it with
```
reset_default_llm_provider
```
. CLI:
```
pipefy ai-provider create
```
/
```
update
```
/
```
delete
```
/
```
set-active-status
```
/
```
default set
```
/
```
default reset
```
.
dataSourceIds
— knowledge base sources the behavior can draw on. Each ID is a knowledge base item ID from
```
get_ai_knowledge_bases
```
(CLI:
```
pipefy kb list
```
). Agents also carry an agent-level
```
data_source_ids
```
; the two are unioned. See Knowledge bases below for the create → attach flow.

Product name	`capabilityType`
IDP / Intelligent Document Processing	`advanced_ocr`
Calculations & Analysis	`math_operations`
Web Search	`web_search`
Web Scraping	`web_scraping`
Max effort	`max_effort`

json

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

在

actionParams.aiBehaviorParams

中，行为还可包含：

capabilitiesAttributes
— 行为可使用的高级工具。每个条目必须严格为
```
{ "capabilityType": "<type>", "enabled": true|false }
```
（必须包含两个键，无额外键 — 纯字符串或
```
{ "type": ... }
```
会被拒绝）。
产品名称
capabilityType
IDP / 智能文档处理
advanced_ocr
计算与分析
math_operations
网页搜索
web_search
网页抓取
web_scraping
最大算力
max_effort
```
capabilityType
```
不会与固定集合校验 — 任何值都会被传递，API会在写入时验证枚举值，因此新功能无需更新工具包即可使用。验证仅检查格式，而非权限 — 功能可能仍需组织级启用才能生效，因此预飞检查通过不代表该功能在组织中已激活。
providerId
/ systemProviderId
— 选择行为的LLM提供商。最多设置其中一个（一个行为只能对应一个活跃提供商）。通过
```
get_llm_providers
```
（CLI：
```
pipefy ai-provider list
```
）获取有效ID：每个提供商包含
```
type
```
— 自定义（
```
byom
```
）提供商使用
```
providerId
```
，Pipefy托管（
```
system
```
）提供商使用
```
systemProviderId
```
。
```
get_default_llm_provider
```
可查看未设置时行为默认使用的提供商。ID也可在Pipefy UI的组织AI设置中查看。
自带模型（自定义提供商）。如需使用自有供应商凭证支持行为，请先创建自定义提供商，然后将其
```
id
```
用作
```
providerId
```
：调用
```
validate_llm_provider_access
```
（确认读取权限 — 写入需要更强的
```
manage_ai_providers
```
组织权限和符合要求的套餐，因此写入仍可能被拒绝）→ 使用本地JSON文件（
```
configuration_file_path
```
；请勿内联配置 — 密钥不会被记录或返回；文件中的
```
provider
```
键选择供应商）调用
```
create_llm_provider
```
。通过
```
update_llm_provider
```
（发送完整配置；保留
```
get_llm_providers
```
返回的
```
__REDACTED__
```
占位符以保留现有密钥，或输入新值进行轮换）、
```
set_llm_provider_active_status
```
和
```
delete_llm_provider
```
（先调用
```
get_llm_provider_dependencies
```
）进行管理。通过
```
set_default_llm_provider
```
（
```
provider_id
```
/
```
system_provider_id
```
二选一）设置组织默认提供商，或通过
```
reset_default_llm_provider
```
清除默认设置。CLI命令：
```
pipefy ai-provider create
```
/
```
update
```
/
```
delete
```
/
```
set-active-status
```
/
```
default set
```
/
```
default reset
```
。
dataSourceIds
— 行为可调用的知识库来源。每个ID来自
```
get_ai_knowledge_bases
```
（CLI：
```
pipefy kb list
```
）返回的知识库条目ID。Agent也包含Agent级的
```
data_source_ids
```
；两者会合并。请查看下方的知识库了解创建 → 关联流程。

产品名称	`capabilityType`
IDP / 智能文档处理	`advanced_ocr`
计算与分析	`math_operations`
网页搜索	`web_search`
网页抓取	`web_scraping`
最大算力	`max_effort`

json

{
  "instruction": "从附件发票中提取总金额。",
  "capabilitiesAttributes": [{ "capabilityType": "advanced_ocr", "enabled": true }],
  "actionsAttributes": [ /* ... */ ]
}

6 — Validate (recommended for complex behaviors)

6 — 验证（复杂行为推荐执行）

validate_ai_agent_behaviors(pipe_id, behaviors)

checks:

Output field IDs (
```
fieldsAttributes[].fieldId
```
) exist in the pipe
Phase IDs exist
Pipe relations exist for
```
create_connected_card
```
Action types are valid (the 6 in
```
KNOWN_AI_ACTION_TYPES
```
;
```
create_table_record
```
```
fieldsAttributes
```
are table field IDs, so they are not checked against the pipe and surface a warning to verify with
```
get_table
```
;
```
send_email_template
```
metadata runs no pipe field-ID checks)
Behavior structure passes Pydantic validation (including canonical
```
capabilitiesAttributes
```
shape and at most one of
```
providerId
```
/
```
systemProviderId
```
)
```
fieldsAttributes[].fieldId
```
values (outputs) are checked against start-form and phase fields, accepting both slug
```
id
```
and numeric
```
internal_id
```
. Instruction
```
%{field:...}
```
tokens (inputs) are not existence-checked: a missing id/slug still yields
```
valid: true
```
. Slug → numeric rewrite happens only on create/update, not here.
Pass
```
data_source_ids
```
(agent-level) to also check knowledge base membership: it is unioned with each behavior's
```
dataSourceIds
```
and checked against the pipe's knowledge bases. Unknown IDs are warnings only (
```
valid
```
stays true); if the knowledge base list cannot be read, a single warning is added and the check is skipped.

strict_unknown_action_types
(default

true

): an

actionType

outside the known 6 is reported in

problems

(blocking). Set

false

to demote unknown action types to

warnings

only, so

valid

stays true. CLI:

--strict

(default) /

--no-strict

agent validate-behaviors

agent create

, and

agent update

validate_ai_agent_behaviors(pipe_id, behaviors)

会检查：

输出字段ID（
```
fieldsAttributes[].fieldId
```
）是否存在于管道中
阶段ID是否存在
```
create_connected_card
```
所需的管道关联关系是否存在
操作类型是否有效（
```
KNOWN_AI_ACTION_TYPES
```
中的6种；
```
create_table_record
```
的
```
fieldsAttributes
```
为表格字段ID，因此不会与管道校验，会显示警告提示通过
```
get_table
```
验证；
```
send_email_template
```
的metadata不会进行管道字段ID校验）
行为结构是否通过Pydantic验证（包括规范的
```
capabilitiesAttributes
```
格式，以及最多设置一个
```
providerId
```
/
```
systemProviderId
```
）
```
fieldsAttributes[].fieldId
```
值（输出字段）会与启动表单和阶段字段校验，接受字段别名
```
id
```
和数字
```
internal_id
```
。提示词中的
```
%{field:...}
```
令牌（输入字段）不会进行存在性校验：缺失的ID/别名仍会返回
```
valid: true
```
。字段别名→数字ID的转换仅在创建/更新时进行，不在此步骤。
传入
```
data_source_ids
```
（Agent级）还会检查知识库成员资格：会与每个行为的
```
dataSourceIds
```
合并，并与管道的知识库进行校验。未知ID仅会触发警告（
```
valid
```
仍为true）；若无法读取知识库列表，会添加一个警告并跳过此检查。

strict_unknown_action_types
（默认

true

）：若

actionType

不在已知的6种范围内，会在

problems

中报告（阻塞操作）。设置为

false

可将未知操作类型降级为仅警告，使

valid

保持true。CLI命令：

agent validate-behaviors

、

agent create

和

agent update

中使用

--strict

（默认）/

--no-strict

参数。

7 — Create the agent

7 — 创建Agent

create_ai_agent

with

name

repo_uuid

instruction

, and

behaviors

. One-call creation is preferred — avoids partial agent shells. Agents are active by default.

The CLI

agent create

agent update

require

--pipe

(numeric pipe id) and run

validate_ai_agent_behaviors

automatically as a pre-flight, blocking the write when

problems

are found and surfacing

warnings

under a

preflight

key. The MCP tools do not auto-preflight, so call

validate_ai_agent_behaviors

yourself (step 6) before

create_ai_agent

update_ai_agent

. CLI flags:

--repo-uuid

--name

--instruction

--behaviors

(JSON array),

--data-sources

(JSON array);

agent validate-behaviors

instead takes

--data-source-id

(repeatable).

On create/update, slug

fieldId

values are resolved to numeric

internal_id

%{field:<slug>}

is rewritten to

%{field:<internal_id>}

, and

referencedFieldIds

is auto-populated when applicable.

调用

create_ai_agent

并传入

name

、

repo_uuid

、

instruction

和

behaviors

。推荐一次性创建 — 避免生成不完整的Agent外壳。Agent默认处于活跃状态。

CLI的

agent create

agent update

命令需要

--pipe

（数字管道ID），并会自动运行

validate_ai_agent_behaviors

作为预飞检查，当发现

problems

时会阻止写入，并在

preflight

键下显示

warnings

。MCP工具不会自动执行预飞检查，因此请在调用

create_ai_agent

update_ai_agent

前自行执行步骤6的验证。CLI参数：

--repo-uuid

、

--name

、

--instruction

、

--behaviors

（JSON数组）、

--data-sources

（JSON数组）；

agent validate-behaviors

则使用

--data-source-id

（可重复使用）。

创建/更新时，字段别名

fieldId

会被解析为数字

internal_id

，

%{field:<slug>}

会被重写为

%{field:<internal_id>}

，

referencedFieldIds

会在适用时自动填充。

8 — Handle responses

8 — 处理响应

Success with
agent_uuid
→ done.
Partial failure (UUID returned, behaviors rejected) → call
```
update_ai_agent
```
with the full required payload:
```
uuid
```
,
```
repo_uuid
```
(same pipe UUID used on create),
```
name
```
,
```
instruction
```
, and complete
```
behaviors
```
(full-replace, not patch). Do NOT create a second agent.
Failure without UUID → validation or API error. Trust the hint text in the enriched error.

成功返回
agent_uuid
→ 操作完成。
部分失败（返回UUID，但行为被拒绝） → 调用
```
update_ai_agent
```
并传入完整必填参数：
```
uuid
```
、
```
repo_uuid
```
（与创建时使用的管道UUID相同）、
```
name
```
、
```
instruction
```
和完整的
```
behaviors
```
（全量替换，非增量更新）。请勿创建第二个Agent。
失败未返回UUID → 验证或API错误。请参考错误信息中的提示文本。

9 — Verify

9 — 确认

get_ai_agent(uuid)

to confirm behaviors match expectations.

调用

get_ai_agent(uuid)

确认行为符合预期。

Knowledge bases (data sources)

知识库（数据源）

Knowledge bases are pipe-scoped data sources an agent draws on. Attach one by putting its ID in a behavior's

dataSourceIds

(or the agent-level

data_source_ids

). All knowledge base operations are scoped by the pipe UUID (

pipe_uuid

), not the numeric pipe ID —

get_pipe

returns the

uuid

Tool (MCP)	CLI	Read-only	Purpose
`get_ai_knowledge_bases`	`pipefy kb list`	Yes	List every item on a pipe (plain texts, documents, data lookups); each has an `id` for `dataSourceIds` and a `type` ( `knowledge_base_plain_texts` , `knowledge_base_documents` , or `data_lookups` ).
`get_ai_knowledge_base_plain_text`	`pipefy kb plain-text get`	Yes	Fetch one plain text with its content.
`create_ai_knowledge_base_plain_text`	`pipefy kb plain-text create`	No	Create a plain text ( `name` , `content` 1-3500, `description` 1-900 — all required).
`update_ai_knowledge_base_plain_text`	`pipefy kb plain-text update`	No	Partial update; pass at least one of name/content/description.
`delete_ai_knowledge_base_plain_text`	`pipefy kb plain-text delete`	No	(Two-step destructive) MCP needs `confirm=true` ; CLI needs `--yes` .
`get_ai_knowledge_base_document`	`pipefy kb document get`	Yes	Fetch one document's metadata ( `content` is the stored URL, not text).
`create_ai_knowledge_base_document`	`pipefy kb document create`	No	Upload a local PDF in one shot ( `file_path` / `--file` , `name` , `description` 1-900). `.pdf` + 20 MiB cap client-side; indexing is async.
`update_ai_knowledge_base_document`	`pipefy kb document update`	No	Metadata-only update (name/description); no file replacement.
`delete_ai_knowledge_base_document`	`pipefy kb document delete`	No	(Two-step destructive) MCP needs `confirm=true` ; CLI needs `--yes` .
`get_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup get`	Yes	Fetch one data lookup; the payload never includes `conditions` — keep the definition client-side.
`create_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup create`	No	Create a data lookup ( `name` , `description` 1-900, `source_repo_id` numeric pipe ID, `output_fields` 1-30, `conditions` — all required).
`update_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup update`	No	Full replacement: resend `source_repo_id` / `output_fields` / `conditions` every call; omitted `search_query` clears it; only name/description are partial.
`delete_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup delete`	No	(Two-step destructive) MCP needs `confirm=true` ; CLI needs `--yes` .
`validate_knowledge_base_access`	`pipefy kb validate-access`	Yes	Probe read access before writes.

知识库是Agent可调用的管道级数据源。将知识库ID添加到行为的

dataSourceIds

（或Agent级的

data_source_ids

）即可关联。所有知识库操作均以管道UUID（

pipe_uuid

）为范围，而非数字管道ID —

get_pipe

会返回

uuid

。

工具（MCP）	CLI 命令	只读	用途
`get_ai_knowledge_bases`	`pipefy kb list`	是	列出管道中的所有条目（纯文本、文档、数据查询）；每个条目包含用于 `dataSourceIds` 的 `id` 和 `type` （ `knowledge_base_plain_texts` 、 `knowledge_base_documents` 或 `data_lookups` ）。
`get_ai_knowledge_base_plain_text`	`pipefy kb plain-text get`	是	获取单个纯文本条目及其内容。
`create_ai_knowledge_base_plain_text`	`pipefy kb plain-text create`	否	创建纯文本条目（ `name` 、 `content` 长度1-3500字符、 `description` 长度1-900字符 — 均为必填项）。
`update_ai_knowledge_base_plain_text`	`pipefy kb plain-text update`	否	增量更新；至少传入name/content/description中的一项。
`delete_ai_knowledge_base_plain_text`	`pipefy kb plain-text delete`	否	（两步式破坏性操作） MCP需要 `confirm=true` ；CLI需要 `--yes` 参数。
`get_ai_knowledge_base_document`	`pipefy kb document get`	是	获取单个文档的元数据（ `content` 为存储的URL，而非文本）。
`create_ai_knowledge_base_document`	`pipefy kb document create`	否	一次性上传本地PDF文件（ `file_path` / `--file` 、 `name` 、 `description` 长度1-900字符）。客户端限制为 `.pdf` 格式且大小不超过20 MiB；索引为异步操作。
`update_ai_knowledge_base_document`	`pipefy kb document update`	否	仅更新元数据（名称/描述）；不支持替换文件。
`delete_ai_knowledge_base_document`	`pipefy kb document delete`	否	（两步式破坏性操作） MCP需要 `confirm=true` ；CLI需要 `--yes` 参数。
`get_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup get`	是	获取单个数据查询条目；返回的 payload 从不包含 `conditions` — 请在客户端保存定义。
`create_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup create`	否	创建数据查询条目（ `name` 、 `description` 长度1-900字符、 `source_repo_id` 为数字管道ID、 `output_fields` 数量1-30、 `conditions` — 均为必填项）。
`update_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup update`	否	全量替换：每次调用必须重新传入 `source_repo_id` / `output_fields` / `conditions` ；省略 `search_query` 会清除该值；仅name/description支持增量更新。
`delete_ai_knowledge_base_data_lookup`	`pipefy kb data-lookup delete`	否	（两步式破坏性操作） MCP需要 `confirm=true` ；CLI需要 `--yes` 参数。
`validate_knowledge_base_access`	`pipefy kb validate-access`	是	在写入前探测访问权限。

Flow: validate-access → create plain text → attach

流程：验证权限 → 创建纯文本 → 关联

Probe access —
```
validate_knowledge_base_access(pipe_uuid)
```
(CLI:
```
pipefy kb validate-access
```
). A green result proves read access only (
```
read_ai_agents
```
), never the
```
manage_ai_agents
```
entitlement writes need. The CLI create/update commands gate on this automatically; MCP callers should probe first (create/update do not auto-probe).
Create the source —
```
create_ai_knowledge_base_plain_text(pipe_uuid, name, content, description)
```
. Limits fail fast client-side:
```
content
```
1-3500 chars,
```
description
```
1-900 chars (both required). Keep the returned
```
id
```
.

Attach — add that

id

to a behavior's

dataSourceIds

(or the agent-level

data_source_ids

) when calling

create_ai_agent

update_ai_agent

. Validate first with

validate_ai_agent_behaviors(pipe_id, behaviors, data_source_ids=[...])

— unknown IDs surface as warnings.

For a PDF document instead of plain text, use

create_ai_knowledge_base_document(pipe_uuid, name, description, file_path)

(CLI:

pipefy kb document create --file …

) at step 2. It uploads the local PDF in one shot;

.pdf

and the 20 MiB cap are enforced client-side, and indexing is asynchronous (the document may not be searchable immediately). The rest of the flow is identical — keep the returned

id

and attach it.

探测权限 — 调用
```
validate_knowledge_base_access(pipe_uuid)
```
（CLI：
```
pipefy kb validate-access
```
）。验证通过仅证明具备读取权限（
```
read_ai_agents
```
），不代表具备写入所需的
```
manage_ai_agents
```
权限。CLI的创建/更新命令会自动进行此检查；MCP调用者应提前探测（创建/更新不会自动探测）。
创建数据源 — 调用
```
create_ai_knowledge_base_plain_text(pipe_uuid, name, content, description)
```
。客户端会快速校验限制：
```
content
```
长度1-3500字符，
```
description
```
长度1-900字符（均为必填项）。保存返回的
```
id
```
。

关联 — 在调用

create_ai_agent

update_ai_agent

时，将该

id

添加到行为的

dataSourceIds

（或Agent级的

data_source_ids

）。建议先通过

validate_ai_agent_behaviors(pipe_id, behaviors, data_source_ids=[...])

验证 — 未知ID会显示警告。

若要使用PDF文档而非纯文本，请在步骤2调用

create_ai_knowledge_base_document(pipe_uuid, name, description, file_path)

（CLI：

pipefy kb document create --file …

）。该命令会一次性上传本地PDF文件；客户端会强制校验

.pdf

格式和20 MiB大小限制，索引为异步操作（文档可能无法立即被搜索）。其余流程完全相同 — 保存返回的

id

并关联即可。

Data lookups: create with an AI-filled condition → attach → update (full replacement)

数据查询：创建带AI填充条件的查询 → 关联 → 更新（全量替换）

A data lookup lets the agent search cards in a source pipe by conditions and return selected field values. Same flow as above at step 2, with three rules of its own:

Create —

create_ai_knowledge_base_data_lookup(pipe_uuid, name, description, source_repo_id, output_fields, conditions)

(CLI:

pipefy kb data-lookup create --source-repo-id … --output-fields '[…]' --conditions '[…]'

source_repo_id

is the numeric ID of the source pipe (a UUID is accepted by the API but the lookup then breaks when the agent runs it).

output_fields

takes 1-30 field IDs (field slugs plus static fields like

id

title

created_at

). Each condition needs

field

operator

(opaque backend string, e.g.

"eq"

"contains"

) and is either static (string

value

required) or AI-filled — the AI asks the user for the value at runtime:

json

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

Attach — keep the returned
```
id
```
and add it to
```
dataSourceIds
```
, exactly as for the other kinds. Also keep the definition you sent: reads never return
```
conditions
```
, so your copy is the only complete record of the lookup.
Update replaces everything —
```
update_ai_knowledge_base_data_lookup
```
requires
```
source_repo_id
```
,
```
output_fields
```
, and
```
conditions
```
on every call (the complete condition set, not a delta), and omitting
```
search_query
```
clears it. Only
```
name
```
/
```
description
```
keep their stored values when omitted.

数据查询允许Agent按条件搜索源管道中的卡片并返回指定字段的值。步骤2的流程与上述相同，但需遵循以下三条规则：

创建 — 调用

create_ai_knowledge_base_data_lookup(pipe_uuid, name, description, source_repo_id, output_fields, conditions)

（CLI：

pipefy kb data-lookup create --source-repo-id … --output-fields '[…]' --conditions '[…]'

）。

source_repo_id

为源管道的数字ID（API接受UUID，但Agent运行时查询会失败）。

output_fields

接受1-30个字段ID（字段别名以及

id

、

title

、

created_at

等静态字段）。每个条件需要

field

operator

（后端内部字符串，例如

"eq"

、

"contains"

），且为静态（需要字符串

value

）或AI填充 — AI会在运行时向用户请求值：

json

[{"field": "customer_email", "operator": "eq", "usingFillWithAi": true,
  "inputName": "客户邮箱", "inputType": "text",
  "inputDescription": "客户的邮箱地址"}]

关联 — 保存返回的
```
id
```
并添加到
```
dataSourceIds
```
，与其他类型的数据源完全相同。同时保存您发送的定义：读取操作从不返回
```
conditions
```
，因此您的副本是查询的唯一完整记录。
更新会替换所有内容 —
```
update_ai_knowledge_base_data_lookup
```
每次调用都需要传入
```
source_repo_id
```
、
```
output_fields
```
和
```
conditions
```
（完整的条件集合，而非增量）；省略
```
search_query
```
会清除该值；仅
```
name
```
/
```
description
```
在省略时会保留存储的值。

Token normalization & slug resolution

令牌规范化与字段别名解析

Instructions accept five token aliases — all normalize to canonical

%{field:<internal_id>}

Form	Behavior
`%{<internal_id>}`	Canonical short form.
`{<internal_id>}`	Bare; auto-prefixed with `%` .
`{field:<internal_id>}`	Bare-with-prefix; auto- `%` .
`{field:<slug>}`	Bare slug; resolved to numeric when behavior action carries `pipeId` .
`%{field:<internal_id>}`	Canonical full form.

%{field:<slug>}

is rewritten to

%{field:<internal_id>}

when an action in the behavior supplies

pipeId

. If the Pipefy UI shows plain text instead of chips in token slots, the payload probably still has non-canonical tokens.

提示词支持五种令牌别名 — 均会规范化为标准格式

%{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在令牌插槽中显示纯文本而非芯片，可能是payload中仍包含非标准令牌。

Template params / placeholders

模板参数 / 占位符

Per behavior you can pass

template_params

(or

placeholders

) with

str → str

values and use

{{name}}

in any string (instruction, metadata IDs, etc.). Optionally set

instruction_template

instead of

aiBehaviorParams.instruction

— the tool interpolates and writes the final instruction before the API call. These keys are stripped before validation.

json

{
  "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

and

placeholders

merge (placeholders wins on conflict).

您可为每个行为传递

template_params

（或

placeholders

），包含

str → str

的键值对，并在任意字符串（提示词、metadata ID等）中使用

{{name}}

。也可选择设置

instruction_template

替代

aiBehaviorParams.instruction

— 工具会在API调用前插值并写入最终提示词。这些键在验证前会被移除。

json

{
  "name": "卡片分类",
  "event_id": "card_created",
  "instruction_template": "读取{{field_ref}}并对卡片进行分类。",
  "template_params": { "field_ref": "%{field:900000101}" },
  "actionParams": {
    "aiBehaviorParams": {
      "actionsAttributes": [
        {
          "name": "填充分类",
          "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

优先级更高）。

Naming differences (UI vs API)

命名差异（UI vs API）

Pipefy UI	API / Tool field
Description (agent creation step 1)	`instruction` (agent-level)
Instruction / Prompt (per behavior)	`actionParams.aiBehaviorParams.instruction`
Pipe UUID	`repo_uuid` (from `get_pipe().uuid` , NOT the numeric `id` )

Pipefy UI	API / 工具字段
描述（Agent创建步骤1）	`instruction` （Agent级）
指令 / 提示词（每个行为）	`actionParams.aiBehaviorParams.instruction`
管道UUID	`repo_uuid` （来自 `get_pipe().uuid` ，而非数字 `id` ）

Success criteria

成功标准

```
get_ai_agent
```
returns the agent with
```
status: active
```
.
```
validate_ai_agent_behaviors
```
reports no errors before creation.
Agent appears in the Pipefy UI under the pipe's AI settings.

```
get_ai_agent
```
返回的Agent状态为
```
status: active
```
。
创建前
```
validate_ai_agent_behaviors
```
未报告错误。
Agent出现在Pipefy UI的管道AI设置中。

Failure modes

失败场景

update_ai_agent
is full-replace, not patch. Fetch existing behaviors with
```
get_ai_agent
```
first, merge, then update — otherwise existing behaviors are silently dropped.
Behavior save is all-or-nothing (
RECORD_NOT_SAVED
). One invalid behavior rejects the entire list. The MCP tool auto-validates the payload on failure; if structurally correct, the error indicates a pipe-level restriction (not your payload). Inform the user this pipe does not support AI agent behaviors and suggest alternatives.
Partial-failure recovery. If
```
create_ai_agent
```
returns a UUID but reports failure, call
```
update_ai_agent(uuid, repo_uuid, name, instruction, behaviors)
```
— all five are required. Reuse the create
```
repo_uuid
```
; send the full behaviors list. Do NOT create a second agent.
Cross-pipe
PERMISSION_DENIED
. Behaviors with
```
create_connected_card
```
or cross-pipe
```
create_card
```
require the service account to be a member of both source and destination pipes. When it is not, the API returns a bare
```
PERMISSION_DENIED
```
. Recovery:
```
get_pipe_members
```
+
```
invite_members
```
on the destination pipe.
Phase transition rule on
move_card
. Destination must be reachable from the source phase (
```
cards_can_be_moved_to_phases
```
). Both
```
validate_ai_agent_behaviors
```
and
```
create_ai_agent
```
/
```
update_ai_agent
```
enrich this error with
```
valid_destinations
```
and a hint that transition rules are editable in the Pipefy UI only.
Maximum 5 behaviors per agent. Adding a 6th rejects the whole save.
Ghost agents. An agent listed by
```
get_ai_agents
```
may return "Agent not found" on
```
get_ai_agent
```
— a Pipefy backend artifact, persists across sessions, do not retry.
GraphQL error hints. When a dedicated read tool returns permission-denied or not-found, the
```
error.message
```
may cite concrete tools (e.g.
```
"Use 'get_ai_agents' to list agents..."
```
). Trust the hint; don't improvise alternative flows.
Validation rejections. Common issues: invalid
```
trigger_event
```
, prompt too long, missing required action config. Read the
```
errors
```
field per behavior.
delete_ai_agent
first call returns preview. Expected — show preview to user, then call with
```
confirm=true
```
.

update_ai_agent
是全量替换，非增量更新。请先通过
```
get_ai_agent
```
获取现有行为，合并后再更新 — 否则现有行为会被静默删除。
行为保存是全有或全无（
RECORD_NOT_SAVED
）。一个无效行为会导致整个列表被拒绝。MCP工具会在失败时自动验证payload；若结构正确，错误表明存在管道级限制（与您的payload无关）。请告知用户该管道不支持AI Agent行为并建议替代方案。
部分失败恢复。 若
```
create_ai_agent
```
返回UUID但报告失败，请调用
```
update_ai_agent(uuid, repo_uuid, name, instruction, behaviors)
```
— 必须包含全部五个参数。复用创建时的
```
repo_uuid
```
；发送完整的行为列表。请勿创建第二个Agent。
跨管道
PERMISSION_DENIED
。包含
```
create_connected_card
```
或跨管道
```
create_card
```
的行为要求服务账号同时是源管道和目标管道的成员。若不符合，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中编辑。
每个Agent最多5种行为。 添加第6种行为会导致整个保存操作被拒绝。
幽灵Agent。
```
get_ai_agents
```
列出的Agent在调用
```
get_ai_agent
```
时可能返回"Agent not found" — 这是Pipefy后端的异常现象，会跨会话存在，请不要重试。
GraphQL错误提示。 当专用读取工具返回权限拒绝或未找到时，
```
error.message
```
可能会引用具体工具（例如
```
"Use 'get_ai_agents' to list agents..."
```
）。请信任提示；不要尝试替代流程。
验证拒绝。 常见问题：无效的
```
trigger_event
```
、提示词过长、缺少必填的操作配置。请查看每个行为的
```
errors
```
字段。
delete_ai_agent
首次调用返回预览。这是预期行为 — 向用户展示预览，然后调用时传入
```
confirm=true
```
。

另请参阅

skills/automations/pipefy-automations/SKILL.md — traditional automations and AI automations (different from AI agents).
skills/observability/pipefy-observability/SKILL.md — agent execution logs and credit usage.
skills/introspection/pipefy-introspection/SKILL.md — Recipe 2 inspects full behavior config via
```
execute_graphql
```
.
```
docs/mcp/tools/identifiers.md#ai-agents-and-knowledge-bases
```
— canonical map of which tool/argument expects slug vs
```
internal_id
```
vs uuid vs numeric id (AI agents scope by
```
repo_uuid
```
= pipe UUID).

skills/automations/pipefy-automations/SKILL.md — 传统自动化和AI自动化（与AI Agent不同）。
skills/observability/pipefy-observability/SKILL.md — Agent执行日志和额度使用情况。
skills/introspection/pipefy-introspection/SKILL.md — 方案2通过
```
execute_graphql
```
检查完整行为配置。
```
docs/mcp/tools/identifiers.md#ai-agents-and-knowledge-bases
```
— 规范映射，说明哪些工具/参数需要字段别名、
```
internal_id
```
、uuid或数字ID（AI Agent以
```
repo_uuid
```
= 管道UUID为范围）。

pipefy-ai-agents

Original

Translation

AI Agents

AI Agents

Tools

工具

Creation workflow (discover → validate → create → verify)

创建流程（发现 → 验证 → 创建 → 确认）

1 — Get pipe metadata

1 — 获取管道元数据

2 — Check existing agents

2 — 检查现有Agent

3 — Discover valid trigger events

3 — 发现有效的触发事件

4 — Discover valid action types

4 — 发现有效的操作类型

5 — Build the behavior dict

5 — 构建行为字典

Example identifiers (fictional)

示例标识符（虚构）

Metadata examples

Metadata示例

5b — Optional: capabilities and LLM provider

5b — 可选：功能与LLM提供商

6 — Validate (recommended for complex behaviors)

6 — 验证（复杂行为推荐执行）

7 — Create the agent

7 — 创建Agent

8 — Handle responses

8 — 处理响应

9 — Verify

9 — 确认

Knowledge bases (data sources)

知识库（数据源）

Flow: validate-access → create plain text → attach

流程：验证权限 → 创建纯文本 → 关联

Data lookups: create with an AI-filled condition → attach → update (full replacement)

数据查询：创建带AI填充条件的查询 → 关联 → 更新（全量替换）

Token normalization & slug resolution

令牌规范化与字段别名解析

Template params / placeholders

模板参数 / 占位符

Naming differences (UI vs API)

命名差异（UI vs API）

Success criteria

成功标准

Failure modes

失败场景

See also

另请参阅