コードとしてのワークフロー
PythonとJavaScriptのSDKでエージェントワークフローを構築、編集、バージョン管理
概要
ワークフローは、ノードとエッジのグラフとして保存されます。このグラフを手動で記述する場合は、エッジID、edge_order リスト、条件オブジェクトの整合性を自分で保つ必要があります。PythonおよびJavaScript SDKの Workflow ビルダーを使用すると、同じグラフをメソッドチェーンで記述できます。その後、agents.create() と agents.update() がすでに受け付けている workflow 値が生成されます。
次の用途に使用できます。
- コードでワークフローを構築し、ほかのコード変更と同じようにレビューする。
- エージェントのワークフローを読み込み、グラフのほかの部分に影響を与えずに1つのノードを変更して、再度プッシュする。
- ワークフローをJSONとしてバージョン管理に保存し、CIで検証する。
ビルダーはSDK内でのみ動作します。新しいAPIエンドポイントを呼び出すことはなく、ビルダーで構築したものはすべて ダッシュボードのビジュアルエディターで開いて編集できます。
要件
- Python:
elevenlabsパッケージ。ビルダーはelevenlabs.agent_workflowsからインポートします。 - JavaScript:
@elevenlabs/elevenlabs-jsパッケージ。ビルダーはパッケージルートからエクスポートされます。
ワークフローを構築する
Workflow オブジェクトは開始ノードを表します。各動詞はノードを追加してそのノードを返すため、そこから次のステップをチェーンできます。
ルーティングメソッドは、次のノードにつながるエッジを決定します。
ワークフロー上で直接呼び出した動詞は、無条件エッジを使って開始ノードから分岐します。次の例では、発信者を注文検索にルーティングし、検索に失敗した場合は本人確認を再試行し、VIPまたは不満を抱えている発信者を転送します。
build() はグラフ全体を検証し、リクエストモデルを返します。また、次の処理も行います。
- APIで必須となる
start_nodeというIDを開始ノードに付与します。 source__target形式でエッジIDを生成します。- エッジを追加した順序で各ノードの
edge_orderを設定します。 - 位置が未指定のノードを配置し、ビジュアルエディターでグラフが左から右に並ぶようにします。
1つのチェーンとしてワークフローを記述する
up() は現在のノードのチェーン元ノードを返すため、各ノードを変数に保持せず、ワークフロー全体を1つの式で記述できます。単一のチェーン内では渡す変数がないため、ノード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では、任意の2つのノード間にどちらか一方向のエッジを1つ設定できます。会話を元の経路に戻せるようにするには、back を使ってエッジに後方条件を指定します。
go_to() / goTo() は、この一般的なケースを自動的に処理します。ターゲットノードから現在のノードへつながるエッジがすでに存在する場合、新しいエッジは既存エッジの後方条件になります。最初の例では、failed.go_to(identify) は identify → lookup_order エッジの後方条件として送信されます。同じ2つのノード間に作成されたそれ以外の2本目のエッジや、ノードからそのノード自体へのエッジは、検証に失敗します。
既存のエージェントを編集する
Workflow.from_agent() / Workflow.fromAgent() は、agents.get() が返したエージェントのワークフローを読み込みます。ノードID、エッジID、エディター上の位置、エッジ順序は維持されるため、再度プッシュしても変更した箇所だけが更新されます。
insert_between() / insertBetween() は、置き換えられるエッジの条件を保持したブランチを関数に渡します。関数は最後に追加したノードを返し、そのノードが元のターゲットに接続されます。このメソッドはそのノードを返します。2つのノード間にエッジがない場合は、None / undefined を返します。
ワークフローをバージョン管理に保存する
to_json_string() / toJSONString() は、ワークフローをAPIの通信形式で書き出します。キーはsnake_caseで、すべての階層でソートされ、2スペースでインデントされます。REST APIとCLIが使用する形式と同じで、同一のワークフローに対して両方のSDKがバイト単位で同一のファイルを書き出すため、差分を小さく保てます。Workflow.from_json() / Workflow.fromJSON() で再度読み込めます。また、CLIの agent_configs/ ディレクトリ内のファイルなど、workflow キーを持つ完全なエージェント設定も読み込めます。
一般的な設定手順は次のとおりです。
ワークフローを可視化する
CLIはワークフローファイルをフローチャートとして描画するため、ダッシュボードを開かずにコードの構築結果を確認できます。to_json_string() / toJSONString() で書き出したワークフロー単体のファイル、または workflow キーを持つエージェント設定を指定できます。
デフォルトでは、ターミナルにボックスと矢印が描画され、各エッジの条件にはエッジ上で番号が付けられ、その内容が下の凡例に表示されます。代わりにMermaidソースを出力するには --format mermaid を使用します。GitHubでレンダリングできるフェンス付きコードブロックとして出力するには、--format mermaid-md を使用します。たとえば、プルリクエストのコメントに利用できます。
このコマンドはローカルファイルのみを読み取るため、APIキーは不要で、CIでも実行できます。
検証
チェーンされた呼び出しが単独で失敗することはありません。build()、to_json() / toJSON()、to_json_string() / toJSONString() はグラフ全体をチェックし、1つの WorkflowValidationError をraiseまたはthrowします。その issues にはすべての問題が含まれ、各問題には code、message、および関連する node_id / nodeId が含まれます。
エラーには次のものがあります。
- 同じノードの組み合わせに2つのエッジがある、またはノードからそのノード自体へのエッジがある。
- 開始ノードに入るエッジ、または終了ノードから出るエッジがある。
- ツールノードから出るエッジが成功エッジまたは失敗エッジではない、あるいは他の種類のノードから成功エッジまたは失敗エッジが出ている。
- 同じIDを持つノードが2つある、または存在しないノードへのエッジがある。
開始ノードから到達できないノードは、on_warning / onWarning を通じて警告として報告され、ビルドは停止しません。
SDKより新しいノードタイプ
APIまたはファイルから読み込んだワークフローには、使用中のSDKバージョンがまだ認識していないノードタイプが含まれていることがあります。これらは from_json() / fromJSON() と to_json_string() / toJSONString() を介して変更されずにラウンドトリップされ、build() は各ノードを警告として報告します。型付きリクエストモデルではこれらを扱えないため、SDKをアップグレードするか、通信形式を直接送信してください。