AOP の基本構造

Agentino で実行する業務内容は、AOP（Agent Operating Procedure）と呼ばれる手順書で定義します。このページでは、AOP を構成する各セクションの役割や、業務規模に応じた記述形式の使い分けを解説します。

共通の章構成

AOP は Markdown で記述し、次の章で構成します。

# タイトル: 業務の名前
## 概要: 業務が何をしたいのか（1〜2文）
## 進め方: 業務の手順
## 利用可能なツール: この業務で使う道具
## 期待される成果物: 業務が終わったときにできているもの

単段業務の書き方

業務が 1 つの流れで完結する場合は、## 進め方 の中に手順を順に書きます。

# 月次の請求書発行

## 概要
毎月の請求書を取引先ごとに作成し、確認できたら発行し、送付用の下書きを作る。

## 進め方
1. 取引先一覧を会計ソフトから取得する
2. 各取引先の今月の売上を集計する
3. 会計ソフトで請求書を作成する
4. 承認を得て発行し、送付用のメール下書きを作る

## 利用可能なツール
- freee
- google_workspace の gmail

## 期待される成果物
各取引先あての請求書が発行され、送付用の下書きが作成されていること。

多段業務の書き方

業務が複数の段階に分かれる場合は、## フェーズ N: 名前 (使う道具: 道具名) で段を区切ります。各フェーズは独立して実行され、フェーズ間で引き継がれる対象は成果物のみです。

# 月次の請求書発行

## 概要
毎月の請求書を取引先ごとに作成し、確認できたら発行し、送付用の下書きを作る。

## フェーズ 1: 集計 (使う道具: freee (read-only))
取引先一覧と今月の売上を取得する。

## フェーズ 2: 請求書作成 (使う道具: freee)
各取引先の請求書を会計ソフトで作成する。

## フェーズ 3: 発行と送付準備 (使う道具: freee, google_workspace の gmail)
承認を得て請求書を発行し、送付用のメール下書きを作成する。

## 期待される成果物
各取引先あての請求書が発行され、送付用の下書きが作成されていること。

フェーズを分ける理由は 2 つあります。各段に最小権限の道具だけを渡すためと、段の境界で承認を挟むためです。集計フェーズには read 権限の道具だけを持たせ、発行フェーズで write 権限と承認を渡す形で権限を絞り込みます。

実行のときに渡すファイルを使う

請求書や画面のスクリーンショットのように、実行のたびに違うファイルを業務で使う場合は、ファイルを読む段の見出しに 添付ファイル を書きます。単段業務では ## 利用可能なツール に - 添付ファイル を書きます。

## フェーズ 1: 請求書を読む (使う道具: 添付ファイル, hitl)
渡された請求書の PDF から、請求元と金額を読み取る。
ファイルが渡されていなければ、推測で補わず、渡されていないことを成果物に書いて終える。

成果物として次段に渡す: 請求元、金額、請求書のファイルの場所

実行を始めるときに添付したファイルは、最初のフェーズに届きます。後のフェーズで使う場合は、前のフェーズの成果物としてファイルの場所を受け渡し、中身を読む段の見出しにも 添付ファイル を書きます
添付ファイル を書いた段のエージェントに、ファイルを読む道具が渡されます。コンパイルでは、書いていない段に読む道具が渡らない形に変換されているかを検査し、実行を始めるときにも同じ検査を行います
ファイルそのものは AOP に書きません。「実行のときに渡される請求書の PDF」のように、役割で書きます
ファイルは、業務を実行するときに開始画面の入力欄のクリップから添付します
実行の途中でエージェントが質問したとき (hitl) は、その答えと一緒にファイルを添付することもできます。答えと一緒に渡したファイルは、その質問をした段に届きます (中身を読むには、その段にも 添付ファイル を書きます)
添付できる件数と大きさの上限 (1 回の実行の合計を含む) は、探索セッションと同じです (探索セッションとはを参照)

AOP を編集すると業務の挙動が変わる

AOP は実行の Source of truth です。編集した AOP をコンパイルし直すと、業務の挙動が変わります。手順を追加、削除、順序変更したときは、AOP を編集してから再度実行します。

コードがすでにある業務のコンパイル

AOP をコンパイルしたコードがすでにあるとき、Agentino はコンパイルで、コードを AOP の全文から作り直さず、今のコードの上に AOP の直しとコンパイルに添える指示（コンパイルを頼むときに伝える観点や注意。例：「フェーズ 2 の検索件数を厳密に守って」）だけを積みます。前のコンパイルで直った所を保つためです。フェーズの追加、削除、並べ替えや、使う道具の変更も、同じように積みます。前のコンパイルで直った所は今のコードに残るので、それを守るために同じ指示を毎回添え直す必要はありません。添えた指示は、そのコンパイルで作ったコードの記録に残り、次のコンパイルには添えません。

AOP を直さず、指示も添えずにコンパイルしたときは、新しいコードを作りません。 AOP を前の内容に戻したときや、多段業務でフェーズの外の章（## 概要 など）だけを直したとき、指示を添えただけのときに、コードを変える所が無ければ、今のコードを、そのまま今の AOP の版のコードとして保存します。ただし、AOP の版が今のコードを作った版のままのとき（AOP を編集せずに、指示だけを添えたときなど）は、何も保存しません。このように保存し直すのは、フェーズの本文（単段業務では AOP の全体）を直していないときだけです。保存し直すか、直しが届かなかったとして積めなかったにするかを決めるときは、行末の空白や改行の形、空行だけの違いを、直したことに数えません。フェーズの見出しの (使う道具: ...) も、道具の並べ替えや区切りの空白、全角と半角だけの違いは数えません（道具を足したり消したりしたときは、直したことに数えます）。フェーズを直したのに（名前を変えて本文も直したときや、フェーズを足したときを含みます）、直しがコードに届かなかったときは、保存し直さずに、積めなかったとして返します（下の「積めないときの扱いと作り直し」）。

AOP から別の AOP を呼ぶ業務では、呼ばれる AOP も同じように積みます。呼ばれる AOP のうち、前のコンパイルから版が変わっていないものは、コンパイルし直しません。コンパイルに添えた指示は、呼ばれる AOP には渡りません。

コンパイルの結果には、直しを積んだか、AOP の全文から作ったか、変える所が無かったか、積めなかったかと、直していないフェーズを機械で確かめた範囲が表示されます。ビルダーエージェントでは対話の中のコンパイルの進みの表示に、MCP 連携では get_compile_status の結果に出ます。

直していないフェーズを機械で確かめる範囲

直しを積んだあと、Agentino は、直していないフェーズのコードが、番号の付け替えと、前のフェーズの成果物を読む所のつなぎ直しのほかは、前と 1 文字も違わないことを機械で確かめます。番号の付け替えとつなぎ直しは、フェーズを足す、消す、並べ替える、名前を変えるといった直しで、フェーズの番号や前後のつながりが変わったときに、Agentino が機械で行う書き換えです。ここでの直していないフェーズは、名前と本文と見出しの (使う道具: ...) が、前と 1 文字も違わないフェーズです。行末の空白や改行の形、空行、使う道具の並べ替えだけを直したフェーズも、この確かめでは直したフェーズとして扱い、比べません。名前だけを変えたフェーズは、この確かめでは、前のフェーズを消して新しいフェーズを足したものとして扱い、比べません。どちらも、上の、保存し直すかを決めるときの数え方（空白や改行の形、使う道具の並べ替え、名前だけの変更などを、直したことに数えない）とは違います。確かめるのはコードが前と同じことで、動きが前と同じことではありません。直したフェーズの成果物を受け取る後ろのフェーズは、コードが同じでも、受け取る成果物が変われば動きが変わります。

次のときは、確かめない所があります。

最初か最後のフェーズが別のフェーズに替わる直し（先頭や末尾にフェーズを足す、消す、並べ替えるなど）では、前と今の最初のフェーズ、または前と今の最後のフェーズを確かめません
多段業務でフェーズの外の章（## 概要 など）を直したときは、どのフェーズも変わりうるので、直していないフェーズを比べません
単段業務のようにフェーズに分かれていない業務では、直した所に当たる所だけが変わったことを確かめません
AOP を直さずに指示を添えただけのときは、どのフェーズが変わるかを機械で決められないので、確かめません
フェーズの追加、削除、並べ替え、名前の変更、使う道具の変更を含む直しでは、フェーズどうしをつなぐ部分と、2 つ以上のフェーズが共通で使う部分を比べません（名前の変更は、フェーズの削除と追加に数えます。使う道具の並べ替えだけの直しも、使う道具の変更に数えます）

積めないときの扱いと作り直し

直しを今のコードの上に積めないとき、Agentino はコードを今のままにして、理由をつけてコンパイルを失敗として返します。自動では作り直しません。たとえば、次のときに積めません。

積んだ結果、直していないフェーズのコードや、フェーズどうしをつなぐ部分が変わってしまったとき
直しがコードに届かなかったとき（積む処理が直しを取りこぼしたとみなします）
- 多段業務で、積んだコードのフェーズが今の AOP のフェーズと合っているのに、名前で前と結べる直したフェーズのコードが、番号の付け替えのほかは前のコードから 1 文字も変わらなかったとき
- 多段業務で、名前を変えて本文も直したフェーズや、足したフェーズがあり、積んだコードのフェーズが今の AOP のフェーズと合っているのに、生成コードの全体が、番号の付け替えとつなぎ直しのほかは前のコードから 1 文字も変わらなかったとき
- 単段業務で、AOP を直したのにコードが 1 文字も変わらなかったとき
フェーズの見出しが読めないとき、単段業務を多段業務に変える直し、積む処理の直しが、足したフェーズや名前を変えたフェーズのコードを作らなかったときや、消したフェーズのコードを残したときのように、AOP とコードをフェーズで対応づけられないとき
消したフェーズや名前を変えたフェーズの成果物を、そのすぐ後ろでないフェーズが読んでいるときのように、フェーズどうしのつながりを機械で直せないとき
積む直しを今のコードに当てられないときや、積んだコードが検証に通らないとき
コンパイルの間に、同じ業務のコードが別の保存で変わったとき
呼んでいる別の AOP のどれかを積めないとき（業務全体のコンパイルを止め、どのコードも今のままにします）

積めなかったときにできることは、理由によって違います。直しがコードに届かなかったとき（上の 2 つ目）は、作り直さずにもう一度コンパイルすると、積めることがあります。このときは、もう一度コンパイルして積み直すか、AOP の全文から作り直すかを選べます。コンパイルの間に別の保存が入ったときは、作り直さずにもう一度コンパイルすると、新しいコードの上に積みます。そのほかの理由のときは、AOP の全文から作り直すことを選べます。作り直すと、前のコンパイルで直った所が戻ることがあります。作り直しを選んでも、呼んでいる別の AOP のうち版が変わっていないものは、今のままです。