AIエージェント運用から生まれたOSSを公開

みやこでITでAIエージェントの話をすると、モデル名やプロンプトだけでは終わりません。実際の仕事へ入れたとき、誰が実装を持つのか、どこまで変更してよいのか、レビューを誰に任せるのか、といった運用の話がすぐに出てきます。

Netsujoでは、その運用で繰り返し必要になった宣言チェックの一部を Agent Role Contracts として切り出し、MITライセンスで公開しました。2026年10月6日、0.5.0 をnpmの`latest`で安定版として公開しています。

この記事では、読む → 小さく試す → 分かったことを共有する、の順で入れるようにします。コードを書く人だけの入口ではありません。まず正常系と意図した失敗例を見比べるだけでも、「このツールが何を確認し、何を確認しないか」を掴めます。

• GitHub: suirindo/agent-role-contracts
• npm stable: @netsujo/agent-role-contracts@0.5.0
• Stable: `0.5.0`（npm `latest`）
• License: MIT

版の区別（2026年10月6日更新）：このあと紹介する固定手順は、再現可能な基準として v0.1.0 を残しています。現在の安定版は 0.5.0 で、npmの`latest`から取得できます。0.5.0ではG0〜G3が利用でき、G1はtask/action binding、G2はfilesystem-write mapping、G3はlifecycle宣言の整合性を扱います。G2は実ファイルを書かず、G3はControllerやruntimeの状態機械として扱いません。安定版を試す場合は `npm install @netsujo/agent-role-contracts@0.5.0` を使います。

何を確認するツールか

複数のAIへ仕事を渡す前に、チームとTaskの宣言に矛盾がないかを確認します。

対象になるのは、例えば次のような項目です。

• roleとauthority
• 実装者とreviewerの分離
• task typeの明示的なroute
• Taskが要求するwrite scope
• role間のhandoff

具体例を一つ挙げます。

```text

implementer

write: src/**

reviewer

read-only

```

この状態でimplementerへ `secrets/production.txt` の変更を要求するTaskを渡すと、宣言した範囲の外なので、宣言の矛盾としてFAILを返します。

ここで実際のfilesystem permissionを書き換えているわけではありません。仕事を開始する前の段階で、今回頼もうとしていることと、あらかじめ決めた権限の範囲が一致しているかを見ています。

こんな場面で使えます

実装とレビューを別のAIに任せる

例えば、Claude Codeをimplementer、Codexをreviewerとして使う場合でも、契約側では製品名よりroleを先に定義できます。

```text

implementer -> write_scoped

reviewer -> read_only

human -> final approval

```

runtimeを後から入れ替えても、roleとauthorityの考え方をそのまま使えます。

複数のAIへ変更範囲を分ける

```text

frontend-agent -> src/frontend/**

backend-agent -> src/backend/**

```

のように担当範囲を宣言しておけば、Task側のscopeが割当roleの範囲から外れていれば、実行前の宣言検査でFAILとして検出できます。

Handoffの前提を確認する

AI-AからAI-Bへ仕事を渡すときは、Task ID、objective、from/to role、statusなどを含むhandoff documentも検査できます。

長いチャット履歴だけに頼らず、「何を、誰から誰へ渡したことにするのか」をデータとして残せます。

まず5分だけ試す

最初はGitHubのstarter exampleをそのまま動かすのが早いです。Node.js 22.5以上を使います。

GitやNode.jsに慣れていない場合は、いきなり自分の設定を書かなくても構いません。下の正常系と「わざとscopeを外した例」の出力差を読むところから始められます。一人で試して、分からなかった点だけをコミュニティやGitHubへ持ち込む形でも十分です。

```sh

git clone https://github.com/suirindo/agent-role-contracts.git

cd agent-role-contracts

git checkout v0.1.0

node bin/agent-role-contracts.mjs validate \

--bundle examples/starter-bundle.json

node bin/agent-role-contracts.mjs explain \

--bundle examples/starter-bundle.json \

--task examples/starter-task.json \

--format text

```

次に、わざとscopeを外したTaskを渡します。

```sh

node bin/agent-role-contracts.mjs explain \

--bundle examples/starter-bundle.json \

--task examples/starter-task-outside-scope.json \

--format text

```

こちらは `TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY` で失敗します。

自分のプロジェクトへ組み込む段階ではnpmから入れられます。

```sh

npm install @netsujo/agent-role-contracts@0.5.0

```

PASSが意味する範囲

Agent Role ContractsのPASSは、実行許可証ではありません。

確認した宣言の中で、そのcommandが扱う種類の矛盾を検出しなかった、という結果です。runtimeの権限強制、本人確認、実際のreview・human approval、成果物の実バイト、実行成功、コードの正しさ、秘密情報の検査、mergeやdeployの承認、本番採用や外部での採用まで証明しません。

`validate`、`explain`、`handoff` は入力が違うため、確認できる範囲も違います。Handoffを確認したい場合は、handoff documentを渡して `handoff` commandを実行します。

この境界を狭く保っている点は、実務では扱いやすさにつながります。「何を確認したのか」と「まだ確認していないこと」を分けて次のGateへ渡せるからです。

コミュニティで話したことを、動かせる形へ

みやこでITでは、AIエージェント実践LT会などを通じて、成功例だけでなく、どこで止まったか、どう役割を分けたか、何を人間へ残したか、といった運用の話を共有してきました。

今回のOSSも、その延長にあります。

現場で困る。仕組みにする。会社固有の部分を外す。公開できる境界を切り出す。第三者が動かし、IssueやPull Requestで返せるようにする。

技術コミュニティの共有物は、記事や登壇資料だけとは限りません。再利用できるコードまで持っていける知見なら、そこまで外へ返す価値があります。

Agent Role Contractsは、小さなv0.1.0のcheckerから、G0〜G3を含む安定版0.5.0へ進みました。まず境界を読む。次に固定したv0.1.0のexamples、またはnpmの安定版0.5.0を小さく動かす。そこで分かったことを、自分のワークフローやGitHub・みやこでITで共有する。その順で十分です。

• GitHubでコードとexamplesを見る
• npm安定版を見る

試して分かったことや、止めるべきケースが足りないと感じた点は、GitHubのIssue / Pull Requestで返してもらえます。