pipefy-ai-agents

AI Agent

仅阅读当前使用界面的参考文档：MCP 或 CLI。以下工作流使用共享的操作名称和参数。

连接到管道的对话式 AI Agent。每个 Agent 都有一条 Agent 级指令和 1–5 个行为，每个行为都有自己的触发事件、提示词和操作。

有关传统自动化和 AI 自动化（由提示词驱动），请参阅 pipefy-automations。

---

工具

操作	只读	用途
get_ai_agents	是	列出管道的 AI Agent（repo_uuid = 管道 UUID，而非数字 id）。
get_ai_agent	是	获取完整的 Agent 配置，包括行为。
create_ai_agent	否	创建新的对话式 Agent（默认启用；设置 active=false 可创建为禁用状态）。
update_ai_agent	否	完整替换（非补丁）。务必发送完整的 behaviors。保留禁用状态。
delete_ai_agent	否	具有破坏性；请先审核并批准。
toggle_ai_agent_status	否	显式启用或停用。
validate_ai_agent_behaviors	是	创建或更新前的预检。

执行日志位于 pipefy-observability（get_ai_agent_logs、get_ai_agent_log_details）。

---

启用状态生命周期

• Agent 默认启用。创建时启用会通过配置更新清除 API 默认的禁用状态占位值（省略 disabledAt）。创建时禁用（active=false）会在创建时及后续的链式更新中显式设置 disabled_at。
• 常规的 update_ai_agent 会保留禁用状态——不会有意重新启用。建议传入先前 get_ai_agent 返回的 disabled_at（disabledAt）以跳过保留状态的重新读取；若省略，SDK 会重新读取并再次发送。
• 显式启用或停用：toggle_ai_agent_status。
• 创建或更新后，检查响应中的 disabled_at 和 active（当 disabled_at 为 null 时，active 为 true）。在 get_ai_agent 的结果中，disabledAt 为 null 表示已启用；behaviors[].active 不代表 Agent 是否启用。无论启用标志如何，只要没有启用的行为，API 就会禁用该 Agent。

---

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

征得同意： 仅当用户明确要求使用 AI 或 Agent 时，才创建或建议创建 AI Agent。如果 AI 看起来可能有用，但用户没有提出要求，请先询问——绝不要在用户未提出要求时主动引入 Agent。

绝不要猜测事件 ID、阶段 ID、操作类型或字段 ID。

1 — 获取管道元数据

调用 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 — 检查现有 Agent

调用 get_ai_agents(repo_uuid) 以避免重复。若要修改现有 Agent，请使用 update_ai_agent（而非 create）。如需完整配置，请使用 get_ai_agent(uuid)。

3 — 查找有效的触发事件

调用 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 — 发现有效的操作类型

get_automation_actions(pipe_id)。已知的 actionType 值及其必需的 metadata：

操作（actionType 值）	必需的 metadata
update_card	pipeId + fieldsAttributes（每个条目都需要 fieldId + inputMode）
move_card	destinationPhaseId
create_card	pipeId + fieldsAttributes
create_connected_card	pipeId + fieldsAttributes（需要管道关联）
create_table_record	tableId + fieldsAttributes（表格字段 ID；不需要 pipeId）
send_email_template	emailTemplateId；可选 allowTemplateModifications（布尔值）
human_validation	emails（收件人列表）和 title。API 接受单独提供其中任意一项，但会拒绝空的 metadata
mcp_tool	mcpServerId + toolName；可选 toolInputs，每项包含 name 和 source：fixed_value 搭配 value，或 card_field 搭配 fieldId

卡片操作的 fieldId 值可以使用 slug 或数字 internal_id；对于 create_table_record，它们是表格字段 ID（请使用 get_table / get_table_record 验证，而不是管道）。

对于不需要 pipeId 或 tableId 的操作，不要提供这些字段。绝不要将其中任何一项设为空字符串：Pipefy 会将其视为你无权访问的 ID，并以“references a pipe or table you do not have access to”拒绝该 Agent。你提供的任何 pipeId 或 tableId 都必须属于同一组织，且调用者必须有权在其中创建卡片。

5 — 构建行为字典

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

• 每个行为的 actionsAttributes 中都 MUST 至少包含一个操作。

• 每个 Agent 最多 5 个行为。

• 每个 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；错误的 slug 则无法解析，会被仅限数字的提取器丢弃（未解析的标记）。无论哪种情况，card.fields 都会为空（同样可能产生幻觉）；请使用 get_start_form_fields / get_phase_fields 确认 ID。点号分隔的关联管道引用（%{field:<parent>.<child>}）不会在运行时传递；要读取关联卡片字段，请使用当前管道上的字段。

• 对于 update_card：如果不移动卡片，请将 destinationPhaseId 设为 ""。

标识符示例（虚构）

请使用 get_pipe / get_start_form_fields 中属于你所在组织的真实值。以下占位符与本仓库中的单元测试样例相对应。语法很重要（pipeId、fieldId、%{field:<internal_id>}、inputMode）——示例中的数字不重要；请替换为各管道的数字 internal_id 和阶段 ID。

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

Metadata 示例

// 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 (no pipeId: leave out what an action does not use)
{ "destinationPhaseId": "900000201", "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 }

// human_validation
{ "emails": ["[email protected]"], "title": "Review this card" }

// mcp_tool (mcpServerId is an MCP server registered on the pipe)
{ "mcpServerId": "<mcp_server_id>", "toolName": "<tool_name>", "toolInputs": [{ "name": "query", "source": "fixed_value", "value": "acme" }, { "name": "email", "source": "card_field", "fieldId": "customer_email" }] }

5b — 可选：能力和 LLM 提供方

在 actionParams.aiBehaviorParams 中，行为还可以包含：

• capabilitiesAttributes — 行为可使用的高级工具。每个条目的格式必须严格为 { "capabilityType": "<type>", "enabled": true|false }（两个键都必需，不得包含其他键；裸字符串或 { "type": ... } 都会被拒绝）。

  产品名称	capabilityType
  IDP / Intelligent Document Processing	advanced_ocr
  Calculations & Analysis	math_operations
  Web Search	web_search
  Web Scraping	web_scraping
  Max effort	max_effort

  capabilityType 不会与固定集合进行比对——任何值都会原样传递，API 会在写入时验证枚举，因此新增能力无需更新工具包即可使用。验证仅检查格式，不检查权限——某项能力仍可能需要在组织级启用才能生效，因此预检通过并不保证该能力已在组织中启用。

• providerId / systemProviderId — 选择行为使用的 LLM 提供方。至多设置其中一个（一个行为只能解析为一个活动提供方）。使用 get_llm_providers 查找有效 ID：每个提供方都包含 type — 自定义（byom）提供方使用 providerId，Pipefy 管理的（system）提供方使用 systemProviderId。get_default_llm_provider 会显示两者均未设置时行为使用的默认提供方。也可以在 Pipefy UI 的组织 AI 设置中查看 ID。

  自带模型（自定义提供方）。 首先检查 validate_llm_provider_access：具有读取权限并不代表拥有写入所需的更高权限 manage_ai_providers 或符合条件的套餐。使用 configuration_file_path（本地 JSON 文件）创建提供方，并将其 id 用作 providerId。对于 update_llm_provider，请发送完整配置：保留 __REDACTED__ 占位符以保留现有密钥，或提供新值以轮换密钥。在 delete_llm_provider 之前检查 get_llm_provider_dependencies；使用 set_llm_provider_active_status 激活提供方。set_default_llm_provider 必须且只能接收 provider_id / system_provider_id 其中一个；reset_default_llm_provider 会清除默认设置。

• dataSourceIds — 行为可使用的知识库来源。每个 ID 都是来自 get_ai_knowledge_bases 的知识库条目 ID。Agent 也包含 Agent 级别的 data_source_ids；两者会合并。创建 → 附加的流程请参阅下文的知识库。

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

6 — 验证（复杂行为建议执行）

validate_ai_agent_behaviors(pipe_id, behaviors) 会检查：

• 输出字段 ID（fieldsAttributes[].fieldId）是否存在于流程中
• 阶段 ID 是否存在
• create_connected_card 对应的流程关系是否存在
• 操作类型是否有效（KNOWN_AI_ACTION_TYPES；create_table_record 的 fieldsAttributes 是表格字段 ID，因此不会与流程字段进行比对，并会提示你通过 get_table 确认；send_email_template 元数据不会执行流程字段 ID 检查）
• 行为结构是否通过 Pydantic 验证（包括规范的 capabilitiesAttributes 结构，以及 providerId 和 systemProviderId 至多存在一个）
• fieldsAttributes[].fieldId 值（输出）会与开始表单字段和阶段字段进行比对，同时接受 slug id 和数字型 internal_id。指令中的 %{field:...} 标记（输入）不会检查是否存在：即使 ID/slug 不存在，也仍会返回 valid: true。slug → 数字型 ID 的重写只会在创建/更新时进行，不会在此处进行。
• 设置 data_source_ids（Agent 级别）还可检查知识库成员关系：它会与每个行为的 dataSourceIds 合并，并针对流程的知识库进行检查。未知 ID 只会产生警告（valid 仍为 true）；如果无法读取知识库列表，则会添加一条警告并跳过检查。

strict_unknown_action_types（默认为 true）：不属于 KNOWN_AI_ACTION_TYPES 的 actionType 会作为问题（阻断项）报告。设置为 false 后，未知操作类型只会降级为警告，因此 valid 仍为 true。

7 — 创建 Agent

使用 create_ai_agent，并提供 name、repo_uuid、instruction 和 behaviors。建议一次调用完成创建，以避免出现不完整的 Agent 框架。Agent 默认处于启用状态；设置 active=false 可使其以禁用状态启动（参见启用状态生命周期）。

创建/更新时，slug fieldId 值会解析为数字型 internal_id，%{field:<slug>} 会重写为 %{field:<internal_id>}，并在适用时自动填充 referencedFieldIds。SDK 会为所有界面注入操作 referenceId 值和 %{action:<uuid>} 占位符；请勿自行生成。

8 — 处理响应

• 成功并返回 agent_uuid → 检查写入响应中的 disabled_at 和 active，以确认 Agent 是否已启用。
• 部分失败（行为被拒绝） → SDK 会抛出 AiAgentConfigureError；使用其 .agent_uuid 找回现有框架。MCP 响应中会包含 agent_uuid。调用 update_ai_agent 并提供完整的必需载荷：uuid、repo_uuid（与创建时使用的同一流程 UUID）、name、instruction 和完整的 behaviors（完整替换，而非补丁）。切勿创建第二个 Agent。创建时生成的框架通常处于禁用状态；更新会保留此状态——如果需要启用 Agent，请在成功恢复更新后调用 toggle_ai_agent_status。
• 失败且没有 UUID → 验证或 API 错误。请参照增强错误信息中的提示文本。

9 — 验证

调用 get_ai_agent(uuid)，确认行为和启用状态（disabledAt 为 null 表示已启用）。不要把 behaviors[].active 视为 Agent 的启用状态；未经确认，切勿假定 Agent 处于停用状态。

---

知识库（数据源）

知识库是按 pipe 作用域划分的数据源，Agent 会从中获取信息。将知识库 ID 填入行为的 dataSourceIds（或 Agent 级别的 data_source_ids）即可附加。所有知识库操作都以 pipe 的 UUID（pipe_uuid）为作用域，而非数字 pipe ID——get_pipe 会返回 uuid。

操作	只读	用途
get_ai_knowledge_bases	是	列出 pipe 上的所有项目（纯文本、文档、数据查询）；每项都有一个用于 dataSourceIds 的 id 和一个 type（knowledge_base_plain_texts、knowledge_base_documents 或 data_lookups）。
get_ai_knowledge_base_plain_text	是	获取一条纯文本及其内容。
create_ai_knowledge_base_plain_text	否	创建纯文本（name、content 1-3500、description 1-900——均为必填）。
update_ai_knowledge_base_plain_text	否	部分更新；至少发送 name/content/description 其中一项。
delete_ai_knowledge_base_plain_text	否	具有破坏性；请先审核并批准。
get_ai_knowledge_base_document	是	获取一份文档的元数据（content 是存储的 URL，而非文本）。
create_ai_knowledge_base_document	否	上传 PDF（name、description 1-900、file_path）。仅支持 .pdf，大小上限为 20 MiB；索引为异步处理。
update_ai_knowledge_base_document	否	仅更新元数据（name/description）；不支持替换文件。
delete_ai_knowledge_base_document	否	具有破坏性；请先审核并批准。
get_ai_knowledge_base_data_lookup	是	获取一项数据查询；返回内容不会包含 conditions——请在客户端保留其定义。
create_ai_knowledge_base_data_lookup	否	创建数据查询（name、description 1-900、source_repo_id 数字 pipe ID、output_fields 1-30、conditions——均为必填）。
update_ai_knowledge_base_data_lookup	否	完全替换：每次调用都重新发送 source_repo_id/output_fields/conditions；省略 search_query 会将其清除；只有 name/description 支持部分更新。
delete_ai_knowledge_base_data_lookup	否	具有破坏性；请先审核并批准。
validate_knowledge_base_access	是	在写入前探测读取权限。

流程：验证访问权限 → 创建纯文本 → 附加

1. 探测访问权限 — validate_knowledge_base_access(pipe_uuid)。绿色结果仅证明具有读取权限（read_ai_agents），不能证明拥有写入所需的 manage_ai_agents 权限。
2. 创建数据源 — create_ai_knowledge_base_plain_text(pipe_uuid, name, content, description)。限制会在客户端快速校验：content 为 1-3500 个字符，description 为 1-900 个字符（均为必填）。保留返回的 id。
3. 附加 — 调用 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。仅接受 .pdf，大小上限为 20 MiB。索引为异步处理，因此文档可能不会立即可搜索。保留返回的 id 并附加它。

数据查找：使用 AI 填充条件创建 → 添加 → 更新（完全替换）

数据查找可让 Agent 按条件搜索源管道中的卡片，并返回所选字段的值。流程与上文第 2 步相同，但有三条自身规则：

1. 创建 — create_ai_knowledge_base_data_lookup(pipe_uuid, name, description, source_repo_id, output_fields, conditions)。source_repo_id 是源管道的数字 ID（API 接受 UUID，但 Agent 运行时查找会出错）。output_fields 接受 1-30 个字段 ID（字段 slug 以及 id、title、created_at 等静态字段）。每个条件都需要 field + operator（不透明的后端字符串，例如 "eq"、"contains"），并且是静态（必须提供字符串 value）或由 AI 填充 — AI 会在运行时询问用户要使用的值：

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

2. 添加 — 保留返回的 id，并像其他类型一样将其添加到 dataSourceIds。还要保留你发送的定义：读取操作不会返回 conditions，因此你保留的副本是查找定义唯一的完整记录。

3. 更新会替换所有内容 — 每次调用 update_ai_knowledge_base_data_lookup 都必须提供 source_repo_id、output_fields 和 conditions（完整的条件集，而不是增量），省略 search_query 会清空该字段。省略时，只有 name/description 会保留已存储的值。

---

Token 规范化与 slug 解析

指令接受五种 token 别名 — 全部会规范化为规范形式 %{field:<internal_id>}：

形式	行为
%{<internal_id>}	规范短形式。
{<internal_id>}	裸形式；自动添加 % 前缀。
{field:<internal_id>}	带前缀的裸形式；自动添加 %。
{field:<slug>}	裸 slug；当行为操作携带 pipeId 时，解析为数字 ID。
%{field:<internal_id>}	规范完整形式。

如果行为中的某个操作提供了 pipeId，%{field:<slug>} 会被重写为 %{field:<internal_id>}。如果 Pipefy UI 在 token 槽位中显示的是纯文本而非标签，payload 中可能仍包含非规范 token。

---

模板参数 / 占位符

每个行为都可以设置 template_params（或 placeholders），其值为 str → str，并可在任意字符串（指令、元数据 ID 等）中使用 {{name}}。也可以设置 instruction_template 来替代 aiBehaviorParams.instruction — 最终指令会在 API 调用前完成插值并写入（由 MCP 工具、CLI 以及 SDK 的 CreateAiAgentInput / UpdateAiAgentInput 执行）。验证期间会移除这些键。

{
  "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 和 placeholders 会合并（冲突时以 placeholders 为准）。

---

命名差异（UI 与 API）

Pipefy UI	API / 工具字段
Description（Agent 创建步骤 1）	instruction（Agent 级别）
Instruction / Prompt（每个行为）	actionParams.aiBehaviorParams.instruction
Pipe UUID	repo_uuid（来自 get_pipe().uuid，不是数字 id）

---

成功标准

• Agent 启用状态符合预期：启用时，get_ai_agent.disabledAt 为 null；behaviors[].active 不能表明 Agent 已启用。
• 创建前，validate_ai_agent_behaviors 不报告任何错误。
• Agent 显示在 Pipefy UI 中该管道的 AI 设置下。

失败模式

• update_ai_agent 是全量替换，而不是补丁。 使用 get_ai_agent 读取 Agent，修改所需内容，然后将完整的行为列表发回。未包含的行为会被删除。可以原样发回读取到的行为；保存时，其中包含的 ID 和 %{action:…} 行会被替换。一个例外是：get_ai_agent 不会返回 eventParams.kindOfSla，因此，若将 SLA 事件上的行为作为读取结果发回，它会丢失 SLA 类型。发送前，请在该行为的 event_params 中设置 kindOfSla。更新不会重新启用已禁用的 Agent；请使用 toggle_ai_agent_status。
• 更新被拒绝时不会回滚。 Pipefy 会先应用名称和指令，并移除现有行为，然后才保存新列表。如果随后新列表被拒绝（RECORD_NOT_SAVED），Agent 就会没有任何行为，或只保留新列表的一部分，并且仍处于启用状态。在调用 update_ai_agent 前，请保留 get_ai_agent 的结果，并运行 validate_ai_agent_behaviors。该工具会根据 get_automation_events 检查每个 event_id，如果无法加载这些事件会发出警告，因此未经验证的 event_id 不会被误判为通过；它还会验证 human_validation/mcp_tool 操作元数据。失败后，调用 get_ai_agent 查看剩余内容，修正负载，然后再次发送完整列表。如果更新因“引用了你无权访问的管道或表”而失败，情况也一样：返回该错误时，行为已经保存。
• RECORD_NOT_SAVED 不会说明原因。 validate_ai_agent_behaviors 现在会指出其中几种原因——未知的 event_id（前提是管道的自动化事件已加载），以及缺少元数据的 human_validation 或 mcp_tool 操作——因此请先运行该工具。此消息仍可能对应预检无法发现的负载错误，所以在断定该管道不支持 AI Agent 行为之前，请先排除这些已知原因。
• 部分失败后的恢复。 如果 create_ai_agent 返回 UUID，但报告失败，请调用 update_ai_agent(uuid, repo_uuid, name, instruction, behaviors)——这五个参数均为必填。复用创建时的 repo_uuid；发送完整的行为列表。不要创建第二个 Agent。更新会保留禁用状态；请使用 toggle_ai_agent_status 更改启用状态。
• 跨管道 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 字段。

另请参阅

• pipefy-automations — 传统自动化和 AI 自动化（不同于 AI Agent）。
• pipefy-observability — Agent 执行日志和额度使用情况。
• docs/mcp/tools/identifiers.md#ai-agents-and-knowledge-bases — 关于各工具／参数应使用 slug、internal_id、uuid 还是数字 ID 的权威说明（AI Agent 的范围由 repo_uuid = pipe UUID 确定）。