マイAIエージェントを作るまでの全７本をまとめたら、教訓だらけだった。

はじめに

「無料3,000リクエスト」で自作LLMチャット＆AIエージェントを作ってみた話について全7本を初心者向けに記事のポイントをまとめていました。

夏休みの自由研究として、さくらのAI Engineの無料枠（3,000リクエスト）を使い切るまでLLMチャットとAIエージェントを自作した記録を、Qiitaに7本連続で投稿しました。

自分では「動くところまで書き残しておこう」くらいの気持ちで書いていたのですが、読み返してみると、これから同じように「LLM APIを使って何か自分で作ってみたい」という方には、順番に読むとちょうどいいロードマップになっているなと思ったので、あらためて初心者向けにまとめておきます。

「同じようなものを作ってみたい」「AIにコードを書かせるってどういう感覚なんだろう」という視点で読んでもらえると嬉しいです。

全体像：7本でやったこと

まず、7本はこんな流れです。
ClaudeCodeを使って、自分仕様LLMチャット、マイAIエージェントをバイブコーディングで開発していきます。ClaudeCodeの裏側も、作ったアプリの裏側もさくらのAI Engineです。

導入回：さくらのAI EngineをClaudeCodeから利用するためのセットアップ
   ↓
第１回：最小構成でとにかく動かす（PHP + さくらのAI Engine）
   ↓
第２回：ClaudeCodeRouterの組み合わせでハマる（トラブルシュート）
   ↓
第３回：機能を盛って「使えるやつ」まで育てる
   ↓
第４回：複数ファイルを1ファイルにまとめようとして3日ハマる
   ↓
第５回：AIエージェントを自作して「ループ」の意味がわかる
   ：
番外編：Sonnet 5に投げたら1発で完成した話

順番に見ていきます。

導入回：ClaudeCodeから利用するためのセットアップ

さくらのAIが無料で利用できることを知り、アカウント作成から、APIキーを発行しました。
その後、ブログの手順に従い、ClaudeCodeとClaudeCodeRouterをセットアップし
ClaudeCodeの裏でさくらのAI Engineを動くように準備しました。
バージョンの組み合わせがあるようで、スクリプトで実施できるようにしました。

付録と教訓について

記事の文末にクリックすると展開される領域に付録があります。
ClaudeCode、ClaudeCodeRouter、設定ファイルの作成スクリプトで簡単に環境構築できます。
ClaudeCodeの特定のバージョンからCPUのAVX機能が必須となり、仮想環境で動かなかったため、CPUフラグを確認し、古いバージョンを固定する処理を追加しました。
教訓：環境構築はスクリプト化しておくとメリットしかない

第１回：まずは最小構成で「動くだけ」のものを作る

一番最初にやったのは、フレームワークなしのPHP１ファイルで、OpenAI互換APIを叩くだけの極小チャットです。

ポイントは、APIキーをブラウザ側のJavaScriptに書かないという一点だけ。

Browser → PHP（APIキーはここだけ） → さくらのAI Engine

これだけ守れば、あとはPHPのcURLでAPIにPOSTするだけなので、構成自体はとてもシンプルです。

初心者の方に伝えたいのは、「LLM APIって、実際にはどうやって呼び出しているの？」を知りたいなら、こういう最小構成を一度自分の手で書いてみるのが一番早い、ということです。ストリーミング表示（少しずつ回答が表示されるアレ）も、stream: true を付けて受け取ったデータを順次流すだけなので、仕組みとしては拍子抜けするほど単純でした。
OpenAI互換のAPIの引数に相当するパラメータを理解するだけで解像度が高くなります。この知識はいつか点と点が繋がる瞬間に出会うはずです。

「自分専用のチャット画面がほしい」くらいの動機で、土台としてそのまま使えるボリュームだと思います。

付録と教訓について

記事の文末にクリックすると展開される領域に付録があります。
アプリとして動かすためのindex.phpと起動するための、Dockerfileになります。
dockerが動く場所であれば、シンプルなチャットを体験できます。
BASIC認証とともに手軽にレンタルサーバに置きたいなと思いPHPにしました。
教訓：まずは自分の手に負える範囲の興味のあるサンプルを試すのがいい

第２回：LLM×AIコーディングツールの組み合わせでハマった記録

ここは失敗記録です。ClaudeCodeRouter経由でさくらのAI Engineを使おうとしたら、「Unable to connect to API (ECONNREFUSED)」に何度もぶつかりました。
背景としてどのモデルが使えるのかわかっておらず、また、Thinkingとの組み合わせなど
試行錯誤しました。
条件を変えては再現を確認する地道な作業をそのまま残しています。

結論としては、モデルと設定の組み合わせに相性があるということしか分からず、根本原因は特定できていません。
次の組み合わせにすると安定して動くことまでわかったので、それを最終回まで使っています。

• CCR側のモデルはpreview/Kimi-K2.6がよい
• ClaudeCodeの設定はmodelをOpus、effortをxhigh固定(実際はCCRで設定したKimi-K2.6が利用される)

付録と教訓について

記事の文末にクリックすると展開される領域に付録がありませんでした。

動くまで時間を要したこともあり、本文より付録に時間をかけるスタイルが徹底されていませんでした。
本当はpreview/Kimi-K2.7-Codeの実力を確かめたかったのですが、ClaudeCodeから動かせなかったです。
ClineやChatからは動くのを確認していました。
教訓：試行錯誤する場合は、まずは確実に動く組み合わせを足場にして、１個づつ条件をかえることを試されると良いです。複合条件だと要素を理解していないと発散してしまうので。

第３回：機能を盛って「おもちゃ」から「使えるやつ」へ

第１回のシンプルなチャットに、実際に使うために必要な機能を一気に盛り込んだのがこの回です。

• AIモデルの性能把握の用途
  • 複数モデルの切り替え
  • 用途別のシステムプロンプト（プログラミング支援・要約・翻訳など）
  • キャラクター切り替え（口調を変える）
• 実用的機能拡張
  • チャット履歴の保存・復元
  • Markdown / Mermaid表示
  • 回答の自動保存

ここでの一番の発見は、「どのモデルが一番強いか」ではなく「どのモデルを、どんな用途で使うと面白いか」を見る仕組みを作ったほうが得るものが大きいということでした。実際に触ってみると、コード生成に強いモデルと、雑談として自然なモデルは別だったりします。また、モデルごとのレスポンス時間が体感でわかるくらい違いました。

機能面では試す上で気がついたアイディアを実装しています。

そしてもう一つ、AIにコードを書かせる開発方法そのものについても書いています。「動く」から「使える」に育てる過程では、

AIにコードを書かせる → 人間が動かす → エラーが出る → AIに直させる

というループを200〜300回くらい繰り返しました。AIに全部任せると普通に壊れるので、「AIに実装案を出させて、人間が動作確認して、またAIに直させる」というループが現実的、という感覚は、初心者の方にそのまま持ち帰ってほしいポイントです。
動かなければ、動かないと伝えるのです。

付録と教訓について

記事の文末にクリックすると展開される領域に付録があります。
第1回と同様に、Docker＋index.phpにまとめています。
外部サイトは使わずに、この記事だけで再現できるようにしました。
実際のファイルはPHPもJSもCSSもHTMLもあり、1ファイルにまとめるのは苦労しています。(第4回で解説しています)
教訓：実力未知数モデルに対して動作確認を人間がやると、モデルの能力が把握できる
ただし、ヒューマインザループで動作確認をすると時間がかかるので、本来は計画や設計で確認するのが良さそう

第４回：1ファイル化しようとして3日ハマった話

第3回で作っていたチャットをQiitaで配布のために
複数ファイルのPHPアプリを1ファイルにまとめるビルドスクリプトを並行で作っていた。
ビルド前は動くが、ビルドすると動かない、バグ修正フェーズで3日溶かしました。

一番の学びは、「AIに考えさせる」より「AIの現在認識を整理する」ほうが効く、という点です。複数のバグが絡み合うと、AI側も「今のコードがどういう状態か」の認識がズレていきます。「ここを直して」を繰り返すのではなく、

現在のコード / 再現条件 / 実際の現象 / 期待する結果 / すでに分かっていること

を先に人間側で整理してから渡すと、AIとのやり取りが一気に安定しました。これは自作アプリに限らず、AIにコードを書かせるとき全般に使えるコツだと思います。

付録と教訓について

記事の文末にクリックすると展開される領域に付録があります。
実際に作ったビルド用のPythonコードがあります。
振り返って気が付きましたが、このまま展開したところで、minifyに興味がない方にはなんの利益もないコードでした。
教訓：せっかくネタはあるのに付録の価値を訴求できない構成の記事は見直すべき
いつか見直します。

第５回：AIエージェントを自作して「ループエンジニアリング」の意味がわかった

シリーズの集大成として、LLM API＋ツール実行の最小AIエージェントをPythonで自作しました。

LLM → Tool Call → Tool実行 → Tool Result → Contextへ追加 → LLM → …

このループを回すだけで、Claude CodeやCodexのようなコーディングエージェントの中で起きていることに、かなり近い動きが再現できます。ここで初めて、

• プロンプトエンジニアリング（AIに何をさせるか）
• コンテキストエンジニアリング（AIに何を見せるか）
• ハーネスエンジニアリング（AIをどう安全に制御するか）
• ループエンジニアリング（AIをどう繰り返し動かすか）

という4つの言葉が自分の中でつながりました。「AIエージェントを作る」＝「LLMを賢くする」ではなく、「LLMをどういう環境に置いて、どう回すかを設計する」ことだという実感は、実際に自分でループを実装してみないとなかなか腹落ちしないと思います。

危険なコマンドをブロックするパーミッション管理や、ツールごとの実行権限（自動実行／確認あり）の仕組みも入れているので、「エージェントって内部で何をやっているんだろう」を知りたい方は、ソース全文を読んでみると輪郭がつかめるはずです。

付録と教訓について

記事の文末にクリックすると展開される領域に付録があります。
PythonのコードでさくらのAIエンジンを使ったコーディングエージェントです。
ClaudeCodeの1%のちからのないものですが、仕組みの設計やLLMにおいて重要なことを気づかせてくれました。
また、エージェントの裏側についてAIがアイデアを出してくれたため、方向性など個人のエッセンスを与えて形になりました。
Planモードをしっかり活用することがコツでした。
教訓：AIエージェントを作って見るからこそ、AIエージェントへの指示の重要事項に気がつく

番外編：Kimiでは完成しなかったものをSonnet 5に投げたら1発で完成した

最後は、PHPすら不要な「index.htmlをブラウザで開くだけ」のLLMチャットです。さくらのAI EngineのエンドポイントはブラウザのJavaScriptから直接fetchしてもCORSエラーにならなかったので、サーバーなしでも成立しました。

面白かったのは、同じ要求をKimi-K2.6やQwen3.6に投げても完成しなかったアニメーション部分が、Sonnet 5に投げたら1発で完成したという点です。モデルによって得意不得意がはっきり出る場面があると実感しました。

APIキーの保存先はブラウザのLocalStorage一択で、「消えたらまた貼ればいい」くらいに割り切ったほうがコードがシンプルになる、というのも実用上の小さな学びでした。

付録と教訓について

記事の文末にクリックすると展開される領域に付録があります。
数日ともにしたKimi-K26の実力やクセと限界が何となくわかったので、どのようにコンテキストを整えるかではなく、どうやったら短時間でクリアできるかに発想を転換する。
このシリーズの記事としてはルール違反かもしれませんが、難しいことの見極め（諦め）からより良い結果に繋がりそう
教訓：LLMで思い通りにイカないことはモデルを変えると解消することがある。

初心者の方が今日からできること

• まずは第１回のような最小構成（1ファイル・フレームワークなし）で、LLM APIを直接呼び出す体験をしてみる
• APIキーはフロントエンドに書かず、必ずサーバー側（またはブラウザ完結ならせめてLocalStorage）に置く
• AIにコードを直させるときは、「直して」を繰り返す前に、現在のコード・再現条件・期待する結果を自分で整理してから渡す
• 複数のLLMモデルを同じ構成で切り替えられるようにして、実際に同じ質問を投げ比べてみる
• 余裕が出てきたら、LLM＋ツール実行の最小エージェントを自作して「ループ」の感覚をつかんでみる

まとめ

6本を通して一番伝えたいのは、「LLM APIを使ったアプリは、思ったより小さく作り始められる」ということです。第１回のPHP１ファイル構成も、番外編のHTML１ファイル構成も、フレームワークなしで十分動きます。

一方で、機能を足したり複数ファイルを1つにまとめたりし始めると、AIに任せているつもりが人間側のデバッグ力を試される場面が出てきます。うまくいかないときほど、「もっとAIに考えさせる」より「人間が現状を整理してAIに渡す」ほうが効く、というのが今回一番の収穫でした。

無料枠を使い切るつもりが結局3,000リクエストは使いきれず数百を残しました。業務利用でなければ十分な量だったので、興味があればぜひ同じように手を動かしてみてください。同じ道で詰まったときに、この記事が地図の代わりになれば嬉しいです。

教訓：qiitaにシリーズとして記事を書くのであれば、共通する書き方など雛形を準備してから書くべき

記事を書く段階から、このような教訓や知見など向き合ってないことが、失敗でした…

最後まで読んでいただきありがとうございました。