最初のファクトリーを書く
宣言的なグラフ形式と JavaScript オーケストレーター形式のどちらでも、自分の you-agent-factory ファクトリーを手順を追って作成します。
これは何か
ファクトリー定義は 3 つのものを名付けます。ワークタイプは、そこを流れる作業の種類で、初期状態・終了状態・失敗状態を持ちます。ワーカーは、実際に実行するランタイムです。エージェント、スクリプト、推論呼び出しなどです。ワークステーションは、ある状態の作業を取り込み、ワーカーへディスパッチし、次の状態へ送り出す工程です。リトライ、レビューループ、ガード、ファンアウト、共有リソースといったものは、すべてこの骨組みに後から足していきます。使いどころ
パッケージ済みファクトリーが望みに近いことをするようになったが、まだ十分ではない、と感じたら自分で書く番です。最後まで動く最小の定義から始めて、そこから育ててください。動かないファクトリーは何も教えてくれませんが、うまく動かないファクトリーは次に直すべき箇所を正確に教えてくれます。形式を選ぶ
orchestrator フィールドがどのエンジンでファクトリーを実行するかを決め、その選択が書き方を決めます。グラフファクトリーはトポロジーを記述し、その中を作業が移動するのをエンジンに任せます。JavaScript ファクトリーは手続きを記述し、ランタイムを直接呼び出します。どちらか一方がもう一方の部分集合というわけではありません。グラフ形式は項目ごとの永続的な状態と並行性を無料で与え、JavaScript 形式は通常の制御構文を与えます。| 問い | グラフファクトリー | JavaScript ファクトリー |
|---|---|---|
| 何を書くか | ワークタイプ、ワーカー、ワークステーションを JSON か YAML で。 | JavaScript の関数 1 つと orchestrator ブロック。 |
| 制御はどう流れるか | 作業が状態間を移動し、入力状態に作業があるワークステーションが動く。 | 上から下へ。通常の await、ループ、条件分岐で。 |
| 状態はどこにあるか | 作業項目そのものの中に、項目ごとに永続的に。 | スクリプトの変数の中に。再開が必要なら明示的なチェックポイントで。 |
| 何を宣言する必要があるか | 作業項目が取りうるすべての状態。 | 引数スキーマと実行ポリシー。 |
動く例から始める
最も速く確実な出発点は、すでに実行したことのあるパッケージ済みファクトリーです。プロジェクト内のルートにインストールすれば、検証を通ることが分かっていて、実行できることが分かっていて、一度に読み切れるほど小さい定義が手に入ります。@you/subagent が最小です。ワークタイプ 1 つ、ワーカー 1 つ、ワークステーション 1 つだけです。グラフファクトリーを書く
エンジンが読む順序で定義を組み立てます。作業を人より先に、人をそれを使う工程より先に宣言します。以下の各ステップで、ファイルにトップレベルの配列を 1 つずつ足していきます。ステップ 1 — ファクトリーに名前を付ける
ファクトリーに名前を付けます。これが唯一の必須トップレベルフィールドであり、後で名前付きファクトリーのコマンドが参照する対象になります。ステップ 2 — ワークタイプとその状態を宣言する
3 つの状態を持つワークタイプを 1 つ宣言します。投入された作業が到着する INITIAL 状態、完了を意味する TERMINAL 状態、そしてグラフが完了させられなかった作業のための FAILED 状態です。handlingBehavior に DEFAULT を付けておくと、ポータブル実行が呼び出し入力の置き場所を判断できます。ステップ 3 — ワーカーを宣言する
ワーカーを 1 つ宣言します。type によって、そのワーカーで使えるフィールドが決まります。AGENT_WORKER はエージェントツールと権限設定を、SCRIPT_WORKER はコマンドと引数を、INFERENCE_WORKER は操作とモデルの実行場所を受け付けます。model と provider を未設定のままにすると、インストール時に設定した運用者の既定値を継承します。ステップ 4 — ワークステーションを宣言する
ワークステーションを 1 つ宣言します。inputs が取り込むワークタイプと状態を、outputs が成功時に送り出す状態を、onFailure がワーカー失敗時に送り出す状態を指定します。body はプロンプトです。呼び出し引数を埋め込んだり、処理中の作業項目を参照したりできます。ステップ 5 — 呼び出しシグネチャを宣言する
呼び出し側が何を渡せばよいか分かるよう、invocation signature を宣言します。各パラメーターは、内部名、コマンドラインで使う外部名、そして受け付けるバインディング(位置引数テキスト、パイプした標準入力、名前付きフラグ)を持ちます。ファイル全体
JavaScript ファクトリーを書く
JavaScript ファクトリーは、ワークステーションのグラフをスクリプトで置き換えます。宣言すべきワークタイプもワーカーもワークステーションもありません。orchestrator ブロックがソース、引数スキーマ、安全ポリシーを持ち、スクリプト自身が書いた順序でエージェントを呼び出します。ステップ 1 — オーケストレーターの種類を宣言する
orchestrator.kind を JAVASCRIPT にします。指定しないと、定義は互換のための既定値でグラフファクトリーとして読み込まれ、エンジンは存在しないワークステーションを探しにいきます。ステップ 2 — ワークフローのソースを指定する
ワークフローのソースを指定します。スクリプトを定義の隣に置く場合はファクトリー相対パスの sourceRef を、定義自体にスクリプト本文を持たせたい場合は inlineSource を使います。パッケージ済みの JavaScript ファクトリーは、単一ファイルとして配布できるようインライン形式を使っています。ステップ 3 — 引数スキーマを宣言する
argsSchema を JSON Schema オブジェクトとして宣言します。これはスクリプト開始前に引数を検証するものであり、スクリプト内の args バインディングに値を入れる元にもなります。ステップ 4 — 既定ポリシーを設定する
defaultPolicy を設定します。ランタイム側の上書きがないときに、そのワークフローに何を許すかを制限します。エージェント呼び出しの総数、同時実行数、子ディスパッチのネストの深さ、ネットワークアクセスの可否、書き込み可能なルートです。READ_ONLY と空の書き込み可能ルートが安全な出発点です。ワークフローのソース
それを読み込む定義
検証して実行する
検証は実行とは別の手順であり、先に行う価値があります。ランタイムを起動せずに、HTTP のファクトリー検証エンドポイントと同じ契約でペイロードを確認します。通ったら、そのファイルをポータブルファクトリーとして直接実行します。実行前に検証する
ポータブルファクトリーとして実行する
あるいは名前を付けてインストールし、どこからでも実行する