Kimi K3 でコーディングエージェント:ツール呼び出しと長時間タスク

Kimi K3 の公式ポジショニングで筆頭に来るのが「長時間コーディング」です。1M コンテキストがリポジトリ全体を丸ごと収め、常時オンの推論が多段の計画を支え、ネイティブなツール呼び出しがターミナルや外部関数を駆動します。これはコードエージェントにうってつけです。自らコードを読み、ツールを呼び、長い一連のアクションを繋いでタスクを完遂します。本記事では K3 のツール呼び出しでエージェントを組み上げる方法と、長時間タスクで最もハマりやすい落とし穴を整理します。

ツール呼び出し(function calling)の基本

K3 は OpenAI の tools 仕様に互換です。ツールを一つ定義し、いつ呼ぶかはモデルに委ねます。

import os, json
from openai import OpenAI

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"],
                base_url="https://api.moonshot.cn/v1")

tools = [{
    "type": "function",
    "function": {
        "name": "read_file",
        "description": "リポジトリ内のあるファイルの内容を読み取る",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
}]

messages = [{"role": "user", "content": "auth.py にハードコードされた鍵がないか見て"}]

resp = client.chat.completions.create(
    model="kimi-k3", messages=messages, tools=tools,
)

モデルがツール呼び出しを決めると、返ってくる assistant メッセージに tool_calls が付きます。対応する関数をローカルで実行し、結果を role:"tool" メッセージとして返して、次のターンをリクエストします。

重要な落とし穴:多ターンでは完全な assistant message を原文のまま返す

K2 から移行した人が最もつまずくのがここです。多ターンの対話やツール呼び出しでは、API が返した完全な assistant message を原文のまま次のリクエストに追加してください。content だけを残してはいけません。

K3 は常時推論のため、assistant メッセージには content に加えて推論 / ツールの状態が載っています。content だけを返すとモデルは「記憶喪失」になり、推論チェーンが途切れ、ツール呼び出しが乱れます。正しい書き方はこうです。

# assistant メッセージ全体(tool_calls / 推論状態を含む)を原文のまま append
messages.append(resp.choices[0].message)

# ツールを実行し、結果を tool メッセージとして返す
for call in resp.choices[0].message.tool_calls or []:
    result = run_tool(call.function.name, json.loads(call.function.arguments))
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(result),
    })

# 完全な履歴を持って次のターンをリクエスト
resp = client.chat.completions.create(
    model="kimi-k3", messages=messages, tools=tools,
)

覚えておいてください。message オブジェクトそのものを append し、content だけの新しいものを自分で組み立て直さないこと。

強制呼び出しとツールの動的読み込み

• 強制呼び出し:このターンで必ずツールを使わせたいときは tool_choice="required"(または特定の関数を指定)を設定します。「まず調べてから答える」フローに向いています。
• ツールの動的読み込み:ツールが多いときは、毎ターン tools 配列を満杯にする代わりに、ツール定義を system メッセージに入れて必要に応じて出せます。コンテキストを節約でき、柔軟性も上がります。
• 公式ツール:Moonshot AI は一連の組み込みツール機能も提供しており、公式の /tools、/fibers などのエンドポイント経由で利用できます。詳細は公式ドキュメントに従ってください。

長時間タスクが K3 に向く理由

多くのターンを回すコードエージェントでは、コンテキストが際限なく膨らみます。リポジトリの内容 + ターンごとのツール結果 + 推論履歴です。K3 の二つの特性がこれをちょうど受け止めます。

• 1M コンテキストはリポジトリ全体と長い履歴を収め、途中で上限を超えてコンテキストを失うことがありません(長いコンテキストの整理は 1M コンテキストガイドを参照);
• デフォルトのキャッシュにより、変わらない前置き(リポジトリ、system、ツール定義)が何度もヒットし、長時間エージェントの入力コストを ¥2/M まで押し下げます。さもないと毎ターン前置きを再送するのは高くつきます(試算は K3 価格詳解を参照)。

ですからメッセージを組むときは、リポジトリの内容とツール定義をできるだけ前に置き、安定させてキャッシュを効かせ切り、毎ターン変わる分だけを後ろに追加します。

整リポジトリ改修の実践的な考え方

典型的な「整リポジトリ改修」エージェントのループはこうです。

1. 全体像を与える:リポジトリ(または RAG で検索した関連部分)+ system 指示を一度にコンテキストへ投入;
2. 計画させる:まず K3 に改修計画(どのファイルを変えるか、リスク箇所)を出させます。常時推論の価値がここで最大化します;
3. ツール付きで実行:read_file / write_file / run_tests などのツールを開き、一歩ずつ変更してテストを走らせます;
4. 原文のまま返す:毎ターン、完全な assistant message + tool 結果を返して推論チェーンを保ちます;
5. 仕上げの点検:最初の計画と照らし合わせ、直し漏れがないか、テストが全て緑かを自己チェックさせます。

このフロー全体をアグリゲーションゲートウェイの上に載せることもできます。計画を K3 に任せ、一部のサブタスクを Claude Opus などのモデルに振り分け(K3 vs Claude vs GPTの横断比較を参照)、すべて一つのキーで完結します。

まとめ

K3 でコードエージェントを作る肝はこの三つです。tools でアクションを駆動し、キャッシュ + 前置きでコストを圧縮し、多ターンでは完全な assistant message を原文のまま返す。 この三点を踏めば、長時間タスクも安定して回ります。完全な接続とエラー対処は Kimi K3 API 接続チュートリアルを参照。一つのキーで K3 と他社モデルを自在に振り分けたいなら、GetModel コンソールから始めましょう。