代码化工作流
使用 Python 和 JavaScript SDK 构建、编辑和版本管理智能体工作流
概览
工作流存储为由节点和边组成的图。手写该图意味着你必须自行确保边 ID、edge_order 列表和条件对象保持一致。Python 和 JavaScript SDK 中的 Workflow 构建器让你可以通过链式方法调用描述同一张图。随后,它会生成 agents.create() 和 agents.update() 已支持的 workflow 值。
可用于:
- 在代码中构建工作流,并像审核其他代码变更一样审核它。
- 加载智能体的工作流,更改一个节点后推送回去,而不影响图中的其余部分。
- 将工作流以 JSON 形式存储在版本控制系统中,并在 CI 中验证。
构建器完全在 SDK 中运行。它不会调用新的 API 端点,且其构建的任何内容都可以在 控制台的可视化编辑器中打开和编辑。
要求
- Python:
elevenlabs包。构建器从elevenlabs.agent_workflows导入。 - JavaScript:
@elevenlabs/elevenlabs-js包。构建器从包根目录导出。
构建工作流
Workflow 对象代表起始节点。每个动词都会添加一个节点并返回该节点,因此你可以从它继续链式添加下一步:
路由方法决定哪条边通向下一个节点:
直接在工作流上调用的动词会通过无条件边从起始节点分支。以下示例将来电者路由至订单查询,在查询失败时重试身份验证,并转接 VIP 或沮丧的来电者:
build() 会验证整个图并返回请求模型。它还会:
- 将起始节点的 ID 设为 API 要求的
start_node。 - 生成格式为
source__target的边 ID。 - 按添加边的顺序填充每个节点的
edge_order。 - 为所有未设置位置的节点定位,使图在可视化编辑器中从左到右排列。
将工作流写成一条链
up() 返回当前节点链式调用所源自的节点,因此无需将每个节点保存到变量中,即可用一个表达式描述整个工作流。在单条链中,请使用带节点 ID 的 go_to() / goTo(),因为没有可传递的变量:
对于通过 wf.node(id) 获取的节点句柄,up() 返回第一条进入该节点的边所来自的节点。对于起始节点,它返回起始节点本身。
节点选项
Python 中的可选设置使用关键字参数,JavaScript 中则使用末尾的选项对象。其名称与 API 中的节点字段一致:
如果要自行放置节点,每个动词也都接受 position。Python 中的 Workflow(prevent_subagent_loops=True) 或 JavaScript 中的 new Workflow({ preventSubagentLoops: true }) 可防止对话再次进入已访问过的子智能体。
转接目标
条件
when() 接受普通字符串、Condition 或 Expr:
- 字符串是 LLM 条件:由 LLM 决定条件是否成立。
Condition.llm(text, label=...)与此相同,但会在可视化编辑器的边上显示标签。使用Condition.expr(expr, label=...)为表达式添加标签。Expr会根据动态变量求值,无需调用 LLM。
使用 Expr.variable(name) 和 Expr.literal(value) 构建表达式。通过 eq、neq、gt、gte、lt 和 lte 进行比较,使用 add、sub、mul 和 div 进行算术运算。通过 all_of / allOf、any_of / anyOf 以及 if_else / ifElse 组合表达式。普通值会自动包装为 Expr.literal()。Expr.llm(description) 会要求 LLM 从对话中提取一个值;传入 type 和 enum 可获得字符串、数字或固定集合中的一个值,而非布尔值。
循环和反向边
API 允许任意两个节点之间存在一条边,方向不限。若要让对话沿原路返回,请使用 back 为该边设置反向条件:
go_to() / goTo() 会处理这种常见情况。当目标节点已有一条通向此处的边时,新边会成为该边的反向条件。在第一个示例中,failed.go_to(identify) 会作为 identify → lookup_order 边的反向条件发送。相同两个节点之间的其他任何第二条边,以及节点指向自身的任何边,都会导致验证失败。
编辑现有智能体
Workflow.from_agent() / Workflow.fromAgent() 会加载由 agents.get() 返回的智能体工作流。节点 ID、边 ID、编辑器位置和边顺序都会保留,因此推送回去时只会更改你修改过的内容。
insert_between() / insertBetween() 会向你的函数传递一个带有被替换边条件的分支。函数返回其添加的最后一个节点,随后该节点会连接到原目标节点。该方法返回该节点;如果两个节点之间没有边,则返回 None / undefined。
在版本控制中存储工作流
to_json_string() / toJSONString() 会以 API 的传输格式写入工作流:使用 snake_case 键、每层排序,并采用 2 空格缩进。其结构与 REST API 和 CLI 使用的格式相同,且两个 SDK 对同一工作流写出的文件逐字节完全一致,因此差异会保持很小。Workflow.from_json() / Workflow.fromJSON() 可将其读回,也接受包含 workflow 键的完整智能体配置,例如 CLI 的 agent_configs/ 目录中的文件。
典型设置:
可视化工作流
CLI 可将工作流文件绘制为流程图,因此无需打开控制台即可检查代码构建的内容。它接受由 to_json_string() / toJSONString() 写入的纯工作流文件,也接受带有 workflow 键的智能体配置:
默认情况下,它会在终端中绘制方框和箭头,每条边的条件都会在边上编号,并在下方图例中写出。使用 --format mermaid 可改为输出 Mermaid 源码,或使用 --format mermaid-md 将其包装在 GitHub 可渲染的围栏代码块中,例如用于拉取请求评论:
该命令仅读取本地文件,因此无需 API 密钥,也可在 CI 中运行。
验证
链式调用本身不会失败。build()、to_json() / toJSON() 和 to_json_string() / toJSONString() 会检查整个图,并引发或抛出单个 WorkflowValidationError。其 issues 会列出所有问题,每个问题都包含 code、message 以及相关的 node_id / nodeId。
错误包括:
- 相同两个节点之间有两条边,或边指向节点自身。
- 指向起始节点的边,或从结束节点出发的边。
- 工具节点发出的边不是成功或失败边,或者其他类型节点发出成功或失败边。
- 两个节点使用相同 ID,或边指向不存在的节点。
无法从起始节点到达的节点会通过 on_warning / onWarning 报告为警告,不会阻止构建。
比 SDK 更新的节点类型
从 API 或文件加载的工作流可能包含你的 SDK 版本尚未识别的节点类型。它们可通过 from_json() / fromJSON() 和 to_json_string() / toJSONString() 原样往返传递,build() 会将每个此类节点报告为警告。类型化请求模型无法承载它们,因此请升级 SDK,或直接发送传输格式: