pipefy-ai-agents

用途

Pipefy AI Agents 用于管理依附于 pipe（管道）的对话式 AI 智能体。每个智能体包含一条智能体级指令（instruction）和 1 至 5 个行为（behavior），每个行为拥有自己的触发事件、提示词和动作。若需要传统自动化或提示词驱动的 AI 自动化，应参考 pipefy-automations。

主要能力

该技能提供以下操作：

• get_ai_agents（只读）：列出某个 pipe 的 AI 智能体，参数 repo_uuid 为 pipe 的 UUID，而非数字 id。
• get_ai_agent（只读）：获取智能体的完整配置，包括行为。
• create_ai_agent：创建新的对话式智能体，默认处于启用状态；传 active=false 可创建为禁用状态。
• update_ai_agent：整体替换（非增量补丁），必须发送完整的行为列表，会保留禁用状态。
• delete_ai_agent：破坏性操作，需先审查并批准。
• toggle_ai_agent_status：显式启用或停用。
• validate_ai_agent_behaviors（只读）：创建或更新前的预检。

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

使用方式

创建流程（发现 → 校验 → 创建 → 验证）

1. 获取 pipe 元数据：调用 get_pipe(pipe_id)，提取 uuid（作为所有 AI 智能体工具的 repo_uuid）、phases[].id / phases[].name（用于 move_card 动作），以及通过 get_start_form_fields(pipe_id) 和/或 get_phase_fields(phase_id) 获取字段（用于 update_card 动作）。
2. 检查已有智能体：get_ai_agents(repo_uuid) 以避免重复；修改已有智能体应使用 update_ai_agent。
3. 发现有效触发事件：get_automation_events(pipe_id)。常见事件包括 card_created（无需 event_params）、card_moved（需 {"to_phase_id":"<phase_id>"}）、field_updated（需 {"triggerFieldIds":["<field_id>", ...]}）、manually_triggered（无需 event_params）。对 card_moved 和 field_updated 必须包含 event_params，否则行为会在每次发生时触发。
4. 发现有效动作类型：get_automation_actions(pipe_id)。已知 actionType 及其必需元数据包括 update_card（pipeId + fieldsAttributes）、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）、mcp_tool（mcpServerId + toolName，可选 toolInputs）。
5. 构建行为字典，每个行为必须至少有一个动作，每个智能体最多 5 个行为。fieldsAttributes 中每一项都必须带 inputMode，取值为 fill_with_ai、fixed_value 或 copy_from。
6. 校验：validate_ai_agent_behaviors(pipe_id, behaviors) 检查输出字段 ID、阶段 ID、管道关系、动作类型有效性及行为结构。
7. 创建智能体：create_ai_agent，传入 name、repo_uuid、instruction 和 behaviors。
8. 处理响应：成功时检查 disabled_at 与 active；部分失败时使用 AiAgentConfigureError 的 .agent_uuid 恢复已有外壳，调用 update_ai_agent 发送完整载荷，不要创建第二个智能体。
9. 验证：get_ai_agent(uuid) 确认行为与启用状态（disabledAt 为 null 表示启用）。

可选能力与 LLM 提供商

行为内可携带 capabilitiesAttributes，每项为 { "capabilityType": "<type>", "enabled": true|false }。已知能力类型包括 advanced_ocr（IDP 智能文档处理）、math_operations（计算与分析）、web_search（网络搜索）、web_scraping（网页抓取）、max_effort（最大努力）。capabilityType 不针对固定集合校验，由 API 在写入时验证枚举。

providerId / systemProviderId 用于选择行为的 LLM 提供商，最多设置一个。自定义（自带模型）提供商使用 providerId，Pipefy 托管（系统）提供商使用 systemProviderId。可通过 get_llm_providers 发现有效 ID，get_default_llm_provider 查看默认回退。

dataSourceIds 指定行为可使用的知识库来源，与智能体级 data_source_ids 取并集。

知识库（数据源）

知识库是 pipe 范围内的数据源，所有操作以 pipe UUID（pipe_uuid）为范围。操作包括：get_ai_knowledge_bases、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、delete_ai_knowledge_base_plain_text、get_ai_knowledge_base_document、create_ai_knowledge_base_document（仅接受 .pdf，上限 20 MiB，索引异步）、update_ai_knowledge_base_document（仅元数据）、delete_ai_knowledge_base_document、get_ai_knowledge_base_data_lookup、create_ai_knowledge_base_data_lookup、update_ai_knowledge_base_data_lookup（整体替换）、delete_ai_knowledge_base_data_lookup、validate_knowledge_base_access。

典型流程：validate-access → 创建纯文本 → 挂载。先调用 validate_knowledge_base_access(pipe_uuid) 探测访问权限（仅证明读权限），再创建来源并保留返回的 id，最后将该 id 加入行为的 dataSourceIds 或智能体级 data_source_ids。

适用场景

适用于需要为 Pipefy 管道引入对话式 AI 智能体的业务流程自动化场景，例如根据卡片创建或移动触发 AI 处理、自动填写字段、发送邮件模板、人工验证、调用 MCP 工具，以及结合知识库与文档处理能力。

限制

• 每个智能体最多 5 个行为，每个行为必须至少有一个动作。
• update_ai_agent 为整体替换，必须发送完整行为列表。
• 对 card_moved 和 field_updated 必须提供 event_params，否则会在每次发生时触发。
• 输入字段引用（%{field:<internal_id>}）仅在 AI 需要读取卡片字段值时使用；错误的数字 id 会被静默接受并成为无效引用，错误的 slug 会被丢弃，两种情况都会导致 card.fields 为空。
• 点号连接的跨管道引用（%{field:<parent>.<child>}）在运行时不会被转发。
• 知识库纯文本 content 限 1-3500 字符，description 限 1-900 字符；文档仅接受 .pdf 且上限 20 MiB，索引异步。
• 能力校验仅检查结构，不检查授权，预检通过不保证能力对组织已启用。
• 删除类操作均为破坏性，需先审查并批准。
• 创建或建议 AI 智能体仅在用户明确要求 AI / 智能体时进行。