Codemodeとは何か
What Is Codemode (lucumr.pocoo.org)
要約
Codemodeは、LLM(大規模言語モデル)がHarness(LLMを実行するフレームワーク)側で複雑な操作を表現・実行するための仕組みです。従来のツール呼び出しとは異なり、CodemodeはHarness内のサンドボックス環境(例: QuickJS、WASM)で実行され、ネットワークやファイルシステムへのアクセスは制限されますが、より高度な並列処理や状態管理を可能にします。これにより、画像生成や分類などの内部APIをLLMから直接呼び出すことが容易になり、エージェントの能力が拡張されます。
全文翻訳
Codemodeとは
1年前、私はカスタムツールをコンテキスト(またはMCPサーバー)にロードするのではなく、より多くのスクリプトを使用することを推奨する記事をいくつか書きました。最も重要なのは、「Code Is All You Need」と書き、MCPはコードを必要とすることについても書きました。Pi 1.0では、Codemode経由でMCPサポートを追加しました。これはある意味で長年の懸案事項でしたが、一部の人には驚きかもしれません。そこで、このブログでこのすべてが何を意味するのかについて、最新の考えを共有したいと思います。
ツールとは
PiのようなハーネスがLLMに呼び出し可能なツールを提供する場合、それはツールの定義を提供することによって行われ、それがサーバーサイドのトークン構造に変換されます。モデルがツールを呼び出すように促されるかどうかは、強化学習プロセスの結果です。詳細を知りたい場合は、以前書いたこちらの記事を参照してください。
私たちがCLIとbashを強く支持する理由の一つは、それらが呼び出しの簡単な構成を可能にし、モデルがトレーニング中にファイルシステムの仕組みも学習するためです。たとえば、モデルがecho foo > /tmp/test.txtのようなツールを呼び出すと、そのツール呼び出しの後で/tmpにtest.txtという名前のファイルが作成されたことをモデルは学習します。
しかし、bashには基本的な制限があります。それは、実行可能なプログラムしか構成できないことです。そして、プログラムではないがLLMのネイティブツールであるべきものがいくつか存在します。
最も明白な例はreadやview_imageです。マルチモーダルモデルが画像を読み取る必要がある場合、catを使用することはできません。なぜなら、ハーネスは実際の画像ペイロードをLLMのプロトコルに注入する必要があるからです。
もう一つの非常に鮮明な例はサブエージェントです。サブエージェントを起動およびオーケストレーションするためには、ハーネスによって提供されるツールを避けることは困難です。理論的には、エージェントは環境変数とUnixソケットを介して外部ハーネスと通信するCLIツールを提供できますが、それはかなり粗雑なプロセスです。しかし、それは別の問題、つまりコードがどこで実行されるかという問題も抱えています。
脳 vs 手
これをよりよく理解するためには、すべての部品がどこで実行されるのかをもう少し考えることが重要です。通常、実際には2つの異なるシステムが関与しています。1つ目は脳、つまりハーネスです。これは1台のマシンで実行され、信頼されています。2つ目はしばしば同じマシンですが、実際にはツールが実行される場所、つまり手です。Piでは、これを実行環境と呼びますが、すべての操作のターゲットと考えることができます。
私たちにとって重要なのは、ハーネスの脳とbashを実行しツールを実行するターゲット環境の間に境界線があることです。
この境界線を半分に分割することには、いくつかの非常に重要な結果があります。まず、それらが異なるファイルシステムで実行され、信頼レベルが異なることを意味します。たとえば、Gondolinのようなサンドボックスソリューションを使用する場合、bash関連のものはうまくサンドボックス化されますが、ハーネス自体はサンドボックス化されません。
ハーネスのオーケストレーション
ここでCodemodeが実際に行うことに移ります。Codemodeは、LLMがハーネス側で複雑な操作を表現およびオーケストレーションするための方法ですが、実行環境側ではありません。Codemodeはハーネス内で、独自のサンドボックスで実行されます。Piの場合、これはQuickJS内でWASMランタイムで実行され、意図的に制限があります。ネットワーク、ファイルシステム、タイマー、限られたRAMはありません。唯一の方法は、より多くのツールを呼び出すことです。CodemodeがSchemeや他の言語を実行することも想像できます。
Codemodeに慣れていない場合、それは基本的に、ある言語(この場合はJavaScript)からツール呼び出しを発行する方法です。これにより、LLMのコンテキストを経由せずに呼び出しを構成できます。命名の功績は、Cloudflareの友人たちにあります。彼らがこの言葉を考案しました。
たとえば、通常のツール呼び出しとしてbash呼び出しをLLMに発行する場合、末尾の2000行のみをコンテキストに投入し、エージェントがさらに多くの情報が必要な場合は、オーバーフローファイル自体を確認する必要があります。しかし、エージェントがCodemode経由でその呼び出しを発行した場合、Codemode側はより大きな出力を構造的に受け取ります。
最も重要なのは、CodemodeがJavaScriptであるため、エージェントは並行操作と基本的なワークフローを表現できることです。エージェントが現在これを使用している一般的な方法は、まずツールの応答から5〜10項目をプローブして、それがどのように見えるかを確認し、次に次のn項目を処理するCodemodeスクリプトを記述することです。
Codemodeを使用すると、状態をトランスクリプトに渡すこともできます!これは、1回のCodemode呼び出しでデータを保存し、セッションの次の呼び出しで再度ロードできることを意味します。そして覚えておいてください。これはサンドボックスではなく、ハーネスホスト上で行われます。
Piの場合、Codemodeを使用すると、Piの従来のインターフェイスでは自然に意味をなさない呼び出しを発行することもできます。たとえば、画像モデルを使用して画像を生成したい場合や、ワンショット分類モデルでテキストを分類したい場合、それらのPi APIはCodemode経由で公開されますが、コンテキストを無駄にする通常のツール経由ではありません。
見た目
これについてたくさん話したので、もう少し具体的に説明する価値があるでしょう。最近の私のPiセッションでのCodemodeの呼び出しをいくつか見ていきましょう。これらのコードは人間が書いたものではないことに注意してください。これらはPiの実際のセッションからのもので、表示のために再インデントされています。エージェントは、モデルがそのツールを自然に選択するタスクであるか、ユーザーがそれを要求したため、自動的にCodemodeの使用を開始します。
CodemodeはデフォルトではPiでMCPが有効な場合にのみ有効ですが、設定で"defaultTools": ["+codemode"]を使用してオンにできます。Piに有効にするように依頼してください。
画像生成
画像生成から始めましょう。画像生成はPiがAI SDKコアでサポートする機能ですが、エージェントが使用できるツールではありません。過去には、画像モデルを使用する唯一の方法は、カスタム拡張機能を記述するか、エージェント自体にノードを実行させて内部画像APIを使用することでした。しかし、内部モデルAPIの多くをCodemode内で公開しているため、エージェントはそれを使用できます。
const [painter] = await models.getAvailableOfType("image");
const result = await models.generateImages(painter, {
input: [{ type: "text", text: "A cute little puppy sitting on a grassy " +
"lawn, soft natural light, photorealistic" }],
});
if (result.stopReason !== "stop") return result.errorMessage;
for (const block of result.output) {
if (block.type === "image") image(block);
else text(block.text);
}
image()呼び出しが画像をLLMに画像コンテンツとして送信することに注意してください。ハーネス側では、エージェントに直接フィードされ、エージェントがその画像をbashに渡せるようにするために一時的な成果物としてディスクにも保存されます。
分類
同様のことが、Jevのような分類モデルにも当てはまります。これらも、エージェントのワークフローに通常のツールを介してうまく適合しません。しかし、カスタムツールを提供する代わりに、CodemodeはエージェントがAI SDKにアクセスしてそれらを直接呼び出すことを可能にします。ここでは、Jevを使用してGitHubの課題を大量に処理し、迅速な感情分析を行う方法を示します。
const jev = await models.getModelOfType("classifier", "typesafe", "jev-latest");
const r = await tools.bash({
command: "gh issue list --state open --limit 100 " +
"--json number,title,body,comments",
});
const issues = JSON.parse(r.output);
const results = await Promise.all(issues.map(async (issue) => {
const res = await models.classify(jev, {
state: {
title: issue.title,
body: (issue.body || "").slice(0, 4000),
comments: issue.comments.slice(-5).map(c => c.body.slice(0, 800)),
},
questions: {
sentiment: {
type: "choice",
instructions: "What is the overall sentiment of the author towards pi?",
criteria: {
positive: "Appreciative, happy, constructive praise",
neutral: "Matter-of-fact report or request without emotion",
negative: "Frustrated, annoyed, upset, or angry",
},
},
frustration: {
type: "score",
instructions: "How frustrated is the reporter?",
criteria: ["not at all", "mildly", "clearly frustrated", "very angry"],
},
kind: {
type: "choice",
instructions: "What kind of issue is this?",
criteria: {
bug: "Bug report or regression",
feature: "Feature request or enhancement",
question: "Question or support request",
other: "Docs, discussion, meta, spam",
},
},
},
});
if (res.stopReason !== "stop") {
return { n: issue.number, title: issue.title, error: res.errorMessage };
}
return { n: issue.number, title: issue.title, ...res.answers };
}));
store("sentiment_results", results);
return results
.filter(r => !r.error)
.sort((a, b) => b.frustration.score - a.frustration.score)
.slice(0, 12)
.map(r => `#${r.n} ${r.frustration.score.toFixed(2)} [${r.kind.choice}] ${r.title}`);
上記の例では、store()も呼び出していることに注意してください。これは、その実行の結果をセッショントランスクリプトにダンプします。将来のCodemodeの呼び出しは、必要に応じてその結果を読み戻すことができます。
Promise.allは問題ありません。Piはツール実行の総数を4つに制限し、残りはキューで管理するためです。
より冒険的な例として、デバッグ目的でJevを使用してゲームエンジンを駆動することが挙げられます。
Codemode with Jev for Game Debugging
ここでは、私のtankctlコマンドについて知っており、ゲームループを駆動してユーザーが問題をデバッグするのを支援するために、最小限のハーネスを迅速に構築しました。各ステップでゲームエンジンに戻って現在の状況のテキストダンプを取得し、次にJevに次に何をすべきかを判断させる30ステップのループを構築したことに注意してください。
const jev = await models.getModelOfType("classifier", "typesafe", "jev-latest");
const tank = async (cmd) =>
(await tools.bash({ command: `tools/tankctl "${cmd}"` })).output;
await tank("start --map assets/maps/night_arena.map");
const questions = {
action: {
type: "choice",
instructions: "You control the tank '@' in a top-down tank game. " +
"Choose the best next action.",
criteria: {
attack: "an enemy has line of sight to you and you can fire at it",
approach: "no enemy has line of sight; drive toward the nearest enemy",
dodge: "an enemy shot is heading at you and will hit soon",
powerup: "a powerup is close and no enemy threatens you",
},
},
};
function commandFor(choice, st) {
const p = st.player;
const enemy = st.enemies.filter(e => !e.dead)
.sort((a, b) => (b.los - a.los) || (a.dist - b.dist))[0];
if (choice === "attack" && enemy) {
return `fire_at tank ${enemy.id}; frames 30 until clear,damage,kill`;
}
if (choice === "dodge") {
// move perpendicular to the closest incoming shot
const s = st.projectiles.filter(s => !s.yours)
.sort((a, b) => a.eta - b.eta)[0];
const dir = s && Math.abs(s.vel[0]) > Math.abs(s.vel[1])
? (p.pos[1] > s.pos[1] ? "+down" : "+up")
: (p.pos[0] > (s ? s.pos[0] : 0) ? "+right" : "+left");
return `input ${dir}; frames 20 until damage; input stop`;
}
const powerup = st.powerups.filter(u => u.available)
.sort((a, b) => a.dist - b.dist)[0];
if (choice === "powerup" && powerup) {
return `goto ${powerup.pos[0]} ${powerup.pos[1]} 180`;
}
return enemy ? `goto ${enemy.pos[0]} ${enemy.pos[1]} 90` : null;
}
const log = [];
for (let step = 0; step < 30; step++) {
const st = JSON.parse(await tank("state"));
if (st.state !== "playing") break;
const threats = st.projectiles
.filter(s => !s.yours && s.miss_dist < 1.5 && s.eta < 1.5)
.map(s => `incoming shot dist ${s.dist} eta ${s.eta}s`)
.join("\n") || "no incoming shots";
const r = await models.classify(jev, {
state: { map: await tank("view 8"), threats, hp: st.player.hp },
questions,
});
if (r.stopReason !== "stop") {
log.push(`#${step} classifier error: ${r.errorMessage}`);
break;
}
const choice = r.answers.action.choice;
const cmd = commandFor(choice, st);
if (!cmd) break;
log.push(`#${step} hp=${st.player.hp} ${choice} -> ${await tank(cmd)}`);
}
return log.join("\n");
MCPサーバーの呼び出し
最後に、CodemodeはMCPサーバーの呼び出しに非常に役立ちます。そして、MCPツールをLLMに公開していないため、エージェントはまず提供されたAPIを使用してCodemode内でツール検索を発行し、接続されているサーバーで何ができるかを発見します。この形式の段階的な発見により、今日の多くのユースケースでMCPビジネスが十分に機能します。
たとえば、ここではエージェントがツールを検出せずにSentry MCPに直接アクセスしているのがわかります。これは、RLプロセス中にSentry MCPがどのように見えるかについてすでに学習しているためと思われます。しかし、システムプロンプトに注入された情報から、Sentryサーバーがそもそも利用可能であることを学習します。ここでは完全に推測しているわけではありません。
const orgs = await tools.mcp__sentry__find_organizations({});
const { organizations } = orgs.structuredContent;
const results = await Promise.allSettled(organizations.map(org =>
tools.mcp__sentry__find_projects({
organizationSlug: org.slug,
regionUrl: org.regionUrl,
})
));
return organizations.map((org, i) => {
const r = results[i];
if (r.status !== "fulfilled") return { org: org.slug, error: String(r.reason) };
if (r.value.isError) return { org: org.slug, error: r.value.content };
return {
org: org.slug,
projects: r.value.structuredContent.projects.map(p => p.slug),
};
});
最新のMCPは戦い
MCPについてはあまり話したくありませんが、MCPは実際にはCodemodeから大いに恩恵を受けるプロトコルです。問題の一部は、MCPが実際には(まだ?)Codemodeを使用していないハーネスをターゲットにしていることが多いことです。しかし、潮は変わりつつあります。それまでの間、一時的なつなぎとして、Cloudflareが行ったように、MCPサーバー内でCodemodeを実行するという方法がありました。しかし、今ではCodemode内でCodemodeを実行することになり、これはかなり悪いです。これは二重のJSONエスケープを意味し、小さなモデルが混乱しやすく、内部コードは外部ツールを呼び出せません。たとえば、PiでCloudflare MCPサーバーを使用する場合、エージェントはJavaScriptを記述し、それをさらにJavaScript経由で渡す必要があります。これは実際には最適ではありませんが、これも理解できます。
const accRes = await tools.mcp__cloudflare__execute({
code: `async () => {
const r = await cloudflare.request({ method: "GET", path: "/accounts" });
return r.result.map(a => ({ id: a.id, name: a.name }));
}`,
});
const accounts = JSON.parse(accRes.content.map(c => c.text).join(""));
const out = [];
for (const account of accounts) {
const r = await tools.mcp__cloudflare__execute({
account_id: account.id,
code: `async () => {
const r = await cloudflare.request({
method: "GET",
path: \
`/accounts/${accountId}/workers/scripts`,
});
return r.result.map(s => ({ id: s.id, modified: s.modified_on }));
}`,
});
out.push({ account: account.name, workers: r.content.map(c => c.text).join("") });
}
return out;
MCPの要望
最後に、Codemodeは今日のMCPとどの程度うまく機能するか?まあ…驚くほどうまくはありません。これは、MCPサーバーがまだCodemodeを使用するハーネスをターゲットにしていないためです(ただし、現時点ではほとんどのハーネスがそれをサポートしていると思います)。
これがうまく機能するためには、いくつかの推奨事項があります。
- 構造化コンテンツ: Codemodeは、呼び出しが適切にフォーマットされたJSONを返すことを望みます。そのため、サーバーから返される必要があり、多くのサーバーはまだそうしていません。MCPの
outputSchemaシステムは、そのために優れています。 - 一貫した結果: 興味深い失敗例は、MCPサーバーが一貫性のないデータを返さない場合です。たとえば、結果セット内の項目の数に応じてトークンを最適化しようとするためです。これにより、最初のプローブは5項目で成功する可能性がありますが、サーバーが最大バッチサイズを返すと失敗します。
- 大きなバイナリデータ: 現在、MCPはまだ大きなバイナリデータをサポートしていないため、非常に興味深いユースケースの多くはまだうまく機能しません。ファイルアップロードをMCP以外のチャネルで行えるようにするための、事前署名付きURLのようなさまざまな奇妙な回避策が発生します。
- 構成可能なツール検索: MCPサーバーは、タスクに適したツールについて、MCPクライアントよりもよく知っている可能性があります。しかし、ハーネスが複数のMCPサーバーにツール検索を分散できるような優れたメカニズムは現在ありません。すべてが創発的な動作であり、複数のアクティブサーバーにはうまくスケールしません。
Codemodeの未来
では、これは私たちをどこに置くのでしょうか?1年前にCLIを推奨したことの逆転でしょうか?私はそうは思いません。実際、私の見解では、MCPエコシステムは、1年前に私たちが機能すると指摘したまさにそのもの、つまりコードを拾い上げました。しかし、CodemodeはMCPを超えて、ハーネス内でエージェントにより多くの自由を表現するための有能なメカニズムとして機能できます。
しかし、まだ解決する必要のあることもいくつかあります。まず、Codemodeでの耐久性はより困難です。ここでは、呼び出しをスナップショットするために、耐久性のあるワークフローエンジンからのアイデアを採用する必要があるかもしれません。あるいは、JavaScriptよりもStarlarkのようなものがより良い構成言語かもしれません。その決定的な性質を考えると。
画像、バイナリデータ、そしてこのパターンが小さなモデルでは機能しないという事実は、まだ fleshed out する必要があるものです。したがって、それは確かにまだ完璧な解決策ではありませんが、私たちがより多く活用すると予想する非常に有用なパターンです。