用途:当用户想构建或修改智能体工作流或某个节点(如“添加节点”“连接这些节点”“路由到电话转接”)时使用。工作流(节点与边)存放在 agent 配置内。
主要能力与用法:通过 REST 读取 GET /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID 获取 workflow 对象,用 PATCH 同一路径整体写回配置。API 没有逐节点/逐边的细粒度端点;画布式逐节点交互编辑仅在 Web 应用提供。所有调用使用 xi-api-key: $API_KEY。
操作要点:每次写入前先读取当前图;节点和边是键控映射而非数组,每个节点有 type、position、edge_order,图始终含 start_node。需先 GET /v1/convai/tools 获取真实 tool id,猜测的 id 会校验失败。一次只改一处,整体 PATCH 回写,遗漏会被视为删除并触发 schema_mismatch;每次成功后重新读取确认。
跨节点约束:同一对节点只能有一条边,双向转换需在同一单边上设置 forward_condition 与 backward_condition;end 和 phone_number 为终端节点,不能有出边或 forward_condition;确定性路由用表达式边,真正判断才用 LLM 条件,且同一节点出边条件须互斥;连接需已存在的 source/target id,新节点需 position。standalone_agent 转接节点的 agent_id 与 node_id 为扁平字段,另需 delay_ms、transfer_message、enable_transferred_agent_first_message。有 override_agent 节点时有效提示词在节点内,改基础提示词可能无效。工具作用域独立于图,节点工具通过 additional_tool_ids 授予。
限制:无逐节点 API;写入易错,需逐步操作;编辑后应重新读取并端到端测试各转换路径(可用模拟测试)。