使う道具の書き方
AOP では、利用する道具を道具名で指定し、必要な権限を割り当てます。 このページでは、道具の指定構文や権限の絞り込み方、コンパイルが宣言をどう扱うか、コードの囲みに書いた文をそのまま使わせる書き方を説明します。
書き方
AOP のフェーズ見出しや本文では、使う道具を次の形式で書きます。
(使う道具: 道具名)
(使う道具: 道具名 (read-only))
(使う道具: 道具名 の カテゴリ)具体例は次のとおりです。
(使う道具: google_workspace の drive (read-only))(使う道具: browser (profile: github-login))(使う道具: hitl)(使う道具: sandbox)(使う道具: 添付ファイル, hitl)
先頭に書くのは道具名です。
google_workspace や freee のような接続先の名前と、browser や sandbox や 添付ファイル のような標準の道具の名前がここに入ります。
コードの囲み（``` や ~~~ のように、バッククォートかチルダを 3 つ以上並べた行で挟んだ部分）の中に書いた宣言は、宣言として読まれません。
どこが囲みになるかは、Markdown の決まり（CommonMark）に沿って読みます。
箇条書きや引用（> で始まる行）の中の囲みも囲みとして読み、HTML のコメント（<!-- から --> まで）の中の行は囲みとして読みません。
囲みが閉じていないときは、コンパイルはコードを生成する前に失敗します。
箇条書きや引用の中の囲みは、文書の途中で箇条書きや引用が終わると、そこで終わるので、閉じる行がなくても失敗しません。
失敗の理由には、囲みを開いた行の行番号が書かれます。
複数の道具と、道具を使わない段
1 つの段に複数の道具を書くときは、, + 、 のどれか、または前後に空白を置いた と で区切ります。
(使う道具: google_workspace の drive (read-only), slack の notify)
(使う道具: freee と google_workspace の gmail)道具を使わない段には、なし と書きます。
(使う道具: なし)カテゴリ
カテゴリは、1 つの道具が持つ機能のまとまりです。
たとえば Google Workspace は calendar docs drive gmail sheets のカテゴリを持ちます。
の に続けてカテゴリを書くと、その道具のうち指定した機能だけをフェーズに渡せます。
(使う道具: google_workspace の drive)カテゴリを持つ道具と、持たない道具があります。
- カテゴリを持つ道具は、カテゴリを書いて絞り込めます。カテゴリを書かなければ、コンパイルは、その道具の機能のうち、その段に要るものに絞って渡すことがあります
- カテゴリを持たない道具は、道具名だけで指定します。この道具にカテゴリを書くとエラーになります
自分で追加した MCP サーバーは、カテゴリを持ちません。 接続先が提供するツールをまとめて渡す形になるため、道具名だけで指定してください。
どの道具がどのカテゴリを持つかは、使えるツールの一覧を参照してください。
read 系と write 系
道具には read 系と write 系があります。 read 系はデータの取得のみを行い、write 系はデータの作成や更新、投稿を含みます。
権限を絞るときは、(read-only) を付けます。
情報収集のフェーズには read 系のみを持たせ、発行や投稿のフェーズで write 系を渡すことで、権限を最小限に保ちます。
宣言と実装ツールの対応
コンパイルは、宣言に書いた道具を、書いた段に付けます。
道具は、書いた名前、カテゴリ、(read-only) の指定のとおりに付きます。
ただし、接続先の道具（MCP と HTTP API）のカテゴリを全部書いたときは、カテゴリを書かないときと同じく、コンパイルは、その道具の機能のうち、その段に要るものに絞って渡すことがあります。
宣言と違う付け方や、宣言に書いていない接続先の道具（MCP と HTTP API）とブラウザを段に付けたコードを見つけると、コンパイルは書き直させ、直らなければ失敗します。
段の本文に接続先の道具の名前が出てきても、その段の宣言に書いていなければ付きません。
そのまま渡す宣言を書いた段には、囲みの中の文を持つ専用の道具も付きます（下の「囲みの中の文を道具にそのまま渡す」を参照してください）。
標準の道具の語は、コンパイル時に、その道具を使う設定へ翻訳されます。
たとえば (使う道具: browser の read のみ) と書くと、ブラウザ操作ツールの read と navigation のみを許可する設定へ翻訳されます。
読めない宣言のときのコンパイル
宣言が道具として読めないときと、使えるツールの一覧にも追加した MCP サーバーにもない道具を宣言したときは、コンパイルはコードを生成する前に失敗します。 失敗の理由には、どの段のどの宣言かが書かれます。 道具として読めない宣言には、候補が見つかれば、書き直しの候補が添えられます。
たとえば 会計ソフト や メール のような業務上の言い方は、道具として読めません。
使えるツールの一覧の道具名とカテゴリで、宣言を書き直してください。
宣言のない段で道具の名前が出てきたとき
段の見出しや本文に接続先の道具の名前（slack など）が出てきても、その段に宣言がなければ、道具は付きません。
コンパイルは成功し、名前がコードの囲みの外に出てきたときは、結果に警告が付きます。
警告には、どの段の本文がどの道具の名前を含んでいるかが書かれます。
その道具を使うときは、段の見出しに (使う道具: 道具名 の カテゴリ) を書き足します。
単段業務では、## 利用可能なツール に - 道具名 の カテゴリ を書き足します。
(使う道具: なし) と書いた段は、宣言のある段として扱われ、警告は付きません。
囲みのすぐ上にそのまま渡す宣言を書いた段も、宣言のある段として扱われ、この警告は付きません。
MCP からコンパイルしたときは、警告が get_compile_status の warnings に入ります。
詳しくはMCP 連携を参照してください。
コードの囲みに書いた文の扱い
SQL や長いプロンプトのように、一字一句そのまま使ってほしい文は、コードの囲みに書きます。 コンパイルは、囲みの中身を要約も書き換えもせず、そのままの形で、段のエージェントへの指示に入れます。 囲みの外の文は、コンパイルが指示に組み立てるときに、言い回しが変わることがあります。
どのエージェントへの指示に入るかは、囲みを書いた場所で決まります。
- 多段業務では、段の本文に書いた囲みは、その段のエージェントへの指示に入ります
- 多段業務で、どの段にも入らない章（
## 概要や## 期待される成果物など）に書いた囲みは、エージェントを作る全部の段の指示に入ります - 単段業務では、どこに書いた囲みも、その業務のエージェントへの指示に入ります
- 箇条書きや引用の中の囲みは、行の頭の字下げと
>を除いた中身が入ります - 中身が空か、空白だけの囲みは、指示に入れません
別の AOP を呼ぶ段には、エージェントへの指示がないため、その段に書いた囲みは、どのエージェントにも届きません。 エージェントを作る段が 1 つもない AOP では、どの段にも入らない章の囲みも届きません。 どちらのときも、コンパイルは成功し、結果に、届かない囲みを開いた行の行番号を書いた警告が付きます。
コンパイルは、生成したコードの指示に、囲みの中身がそのままの形で入っているかを確かめます。 入っていなければ書き直させ、直らなければ失敗します。
AOP を直さずに、または一部の段だけを直してコンパイルし直すと、直していない所には、前に生成したコードが引き継がれることがあります。 引き継いだコードが、囲みの中身をまだ一字一句そのまま届ける形になっていないときは、コンパイルは成功し、結果に警告が付きます。 警告には、囲みを開いた行の行番号（多段業務では段の番号も）と、届く形にする方法が書かれます。
囲みの中の文を道具にそのまま渡す
囲みの中の文を、エージェントに書き写させずに道具へそのまま渡すときは、囲みのすぐ上の行に、次の形の宣言を書きます。 宣言と囲みの間には、空行を挟んでもかまいません。
(この <文の呼び名> を <道具> の <機能> に、そのまま渡す。差し替え: <印>、<印>)<文の呼び名> には、TypeScript や SQL のように、囲みの中の文を指す語を書きます。
<道具> の <機能> は (使う道具: …) と同じ書き方で、(read-only) も付けられます。
1 つの宣言に書ける道具は 1 つで、書けるのは MCP で接続する道具だけです。
差し替える所がないときは、。差し替え: … を書きません。
箇条書きや引用の中の囲みにも、同じように書けます。
(この で始まり、そのまま と 渡す をこの順に含む括弧は、そのまま渡す宣言として読みます。
全角の括弧で書いた （この と、括弧と この の間に空白を挟んだ形も、同じように読みます。
宣言のつもりのない注記でも、この形の括弧が囲みのすぐ上にあれば宣言として読むので、宣言として誤りがあると、コンパイルは失敗します。
そのまま渡す宣言のつもりでなければ、括弧の中を「この」で始まらない語で書き始めると、宣言として読まれなくなります。
失敗の理由にも、この書き換え方が書かれます。
囲みの言語の指定（```ts の ts のように、囲みを開く行のバッククォートかチルダの直後に書く語）によって、渡し方が変わります。
- 言語の指定が
ts、js、typescriptの囲み（大文字と小文字は区別しません）は、TypeScript としてそのまま走ります。TypeScript から呼べるのは、宣言に書いた道具の、書いた機能の範囲です。機能を書かなければその道具の全部の機能を呼べ、(read-only)を付ければ読む操作だけを呼べます - それ以外の言語の指定の囲み（
sqlなど。指定のない囲みも含む）は、宣言に書いた機能（書かなければ全部の機能）の操作のうち、囲みの中の文を受け取る引数が登録されている操作に、文をそのまま渡します。(read-only)を付ければ読む操作から、付けなければ書く操作から選びます
ts、js、typescript 以外の言語の指定の囲みを受け取れる道具は限られます。
受け取れない道具を書くと、コンパイルは止まり、この組織に受け取れる道具があれば、その道具を候補として返します（下の「そのまま渡す宣言でコンパイルが止まるとき」を参照してください）。
ts、js、typescript 以外の言語の指定の囲みを渡す先の操作が、文のほかにも値を必要とするときは、その値の全体を AOP に書いておきます。
コンパイルは、AOP に書かれた字面を値に使い、英字や数字、_、- の並びから一部を切り出した字面は使いません。
AOP に値を書いていないと、コンパイルが失敗するか、AOP に書かれたほかの字面が値に使われることがあります。
そのまま渡す宣言を書いた段には、囲みの中の文を持つ専用の道具が付きます。
段のエージェントは、文を書き写さず、差し替える値だけを渡して、この道具を呼びます。
(使う道具: …) に接続先の道具を書いていない段では、接続先の道具として付くのは、この専用の道具だけです。
囲みの中身は、ほかの囲みと同じく、その段のエージェントへの指示にも入ります。
## フェーズ 2: 検索する
前のフェーズで決めた検索語で、下の TypeScript を 1 回だけ走らせ、結果を 1 文で返す。
(この TypeScript を exa の web (read-only) に、そのまま渡す。差し替え: <検索語>)
```ts
import { callMCPTool } from "./client.js";
async function main(): Promise<void> {
const result = await callMCPTool("exa", "web_search_exa", {
query: "<検索語>",
objective: "検索語について書かれた記事を探す",
numResults: 3,
});
console.log(JSON.stringify(result));
}
main().catch((e) => {
console.error(String(e));
process.exit(1);
});
```この例では、段のエージェントが検索語を決めて専用の道具に渡すと、<検索語> がその値に置き換わった TypeScript が走ります。
TypeScript の中では、./client.js の callMCPTool に、道具名と操作の名前と引数を渡して、接続先を呼びます。
いちばん外側では await を使えないため、例のように async function main() で包み、最後に main().catch(...) で呼びます。
エージェントが受け取るのは、TypeScript が出力した内容（例では console.log で書いた結果）です。
差し替える所の書き方
宣言の 差し替え: の後には、囲みの中で、実行のたびに値を入れ替える所の字面を書きます。
この字面を印と呼びます。
印が複数あるときは、、 か , で区切ります。
印そのものに 、 や , を含めるときは、その印をバッククォートで囲みます。
印に入れる値は、その段のエージェントが実行のときに決めます。
値は、引用符を補うなどの手を加えずに、文字のまま印と置き換わります。
囲みの中に同じ印が何か所あっても、全部が同じ値に置き換わります。
差し替え: に書いていない字面は、囲みの中にあっても置き換わりません。
TypeScript の文字列の中に置いた印に、引用符を含む値が入ると、TypeScript が壊れて失敗することがあります。 その失敗はエージェントに返り、エージェントは値を直して呼び直せます。
そのまま渡す宣言でコンパイルが止まるとき
次のような宣言を書くと、コンパイルはコードを生成する前に失敗します。
- そのまま渡す宣言の形として読めない宣言
- 道具の語が道具として読めない宣言（候補が見つかれば、書き直しの候補が添えられます）
- HTTP API で接続する道具や、
browserなどの標準の道具、なしを書いた宣言 - 2 つ以上の道具を書いた宣言と、機能ごとに
(read-only)の有無が違う宣言 ts、js、typescript以外の言語の指定の囲みに付けた宣言で、渡す先の操作が 1 つに決まらないものと、囲みの中の文を受け取る引数が登録された操作がないもの- 差し替えの印に、空のもの、2 回書かれたもの、すぐ下の囲みの中にないもの、囲みの中でほかの印と重なって値が入らないものがある宣言
- すぐ下の囲みが、空か空白だけの宣言
- 1 つの囲みの上に 2 つ以上並べた宣言（2 つの道具に渡すときは、囲みを 2 つ書きます）
- 多段業務で、どの段にも入らない章に書いた宣言と、別の AOP を呼ぶ段に書いた宣言
失敗の理由には、どの宣言かと、直し方が書かれます。
どの宣言かは、宣言の文や行番号、段の番号で示します。
囲みの中の文を受け取る引数が登録された操作がないときは、言語の指定を ts にして TypeScript で書く案内と、この組織に文を受け取れる道具があれば、その道具が書かれます。
囲みのすぐ上にないそのまま渡す宣言からは、道具を作りません。
書いた道具が道具として読めるときは、コンパイルは成功し、結果に警告が付きます。
MCP からコンパイルしたときは、このページで説明した警告は、どれも get_compile_status の warnings に入ります。
使える道具の一覧
標準で使える道具と、接続して使うツールの一覧は、使えるツールの一覧を参照してください。