🤖AIエージェントを作って学んだ“使う側”から“創る側”になるということ：公式ドキュにない知識と気づき、実践のリアルを全てシェアします

【AIエージェント元年】なぜ今AIエージェントなのか？

ChatGPTをはじめとする対話型AIが急速に普及する中、「調べる」ではなく「一緒に考えてくれる」AIへのニーズが高まっています。しかし初期のAIモデルには学習データのカットオフがあり、リアルタイムな情報提供が苦手という課題がありました。

この課題を解決する鍵として注目されているのが、外部ツールやAPIを活用し、最新情報を取得しながら自律的に思考・行動できるAIエージェントです。
今回は、Pythonとsmolagentsフレームワークを使って、私が実際に構築した「東京交通案内エージェント」の開発プロセスや気づきなどを紹介します。

🤝Smolagentsに出会ったきっかけ

もともと私は、Googleが発表したEmbeddingやAIエージェントに関するホワイトペーパーを読んでおり、「次に来るのは、検索ではなくエージェントだ」と強く感じていました。
ちょうどそのタイミングで、Hugging Faceが新たにリリースしたエージェントフレームワーク「smolagents」の存在を知り、「これだ！」と思ったのが開発のきっかけです。

日頃からHugging Faceの更新情報やライブラリの動向をチェックしていたこともあり、smolagentsの設計思想や軽量さに惹かれ、すぐに自分のプロジェクトで活用することを決めました。
そして最初に取り組んだのが、東京の公共交通に特化したAIエージェントの構築です。

🤖エージェントの設計思想

• どんな目的で「東京の交通案内エージェント」を作ったか

• 想定ユーザーとユースケース（例：旅行者、日本語・英語対応）

• システム構成図

これらの解説は前回のNote記事にまとめてありますので、こちらのリンクから読んでみて下さい。

🚀実装プロセスの全貌

🎌小さな一歩から始まった、東京エージェント開発の道のり

よく東京へ旅行したことのある海外の人たちが口を揃えて言うのが、
東京の公共交通網は複雑で解かりにくいという事です。迷った時は、Google MapsやYahoo!線路情報などで入力すれば大体正確な乗換案内が出てきますが、それでも自然言語でチャット形式で最適ルートだけじゃなくてその他の些細な現地情報など伝えてくれるエージェントがあれば、外国の方も喜ぶのにな、というささやかな思い付きから始まりました。

📚必要なライブラリと初期設定

インストール作業は比較的スムーズでしたが、「smolagentsをどう設計すればいいか」はドキュメントを読みながら手探り状態。とくにエージェントが外部のツールを呼び出して使うためには、そのツール自体を関数として定義しなければならないので、その構築段階で色々迷いました。

私は「東京の経路検索」「観光スポットの提案」という2つの役割を持たせたかったため、それぞれを独立したツールとして定義し、エージェントがその都度呼び出せるようにしました。ここで初めて、「ツールの設計は、エージェントの知能そのものを形づくるものだ」と実感した瞬間です。

👷‍♀️CodeAgentの設定とシステムプロンプト設計

正直、このフェーズが最も頭を悩ませた部分であり、エージェントシステムのコアの部分です。
CodeAgentではシステムプロンプトを自分で定義できますが、このプロンプトがエージェントの「人格」や「思考回路」を決めてしまうほど重要です。最初はテンプレート通りに進めましたが、やはりうまくツールを使えなかったり、経路案内と観光案内を混同したりと、想定外の行動を取る事が多々ありました。
その度に何度もプロンプトを書き直しました。

• 説明が長すぎて簡潔じゃないと混乱する。

• 指示があいまいだと勝手に解釈してしまう。

• 逆に細かすぎると行動できなくなる。

これはシステムプロンプト設計の難しさを体感した瞬間でした。

システムプロンプトについての詳しい解説は、こちらのNote記事からどうぞ。

🛠️UIの設計とStreamlit導入

エージェントの設計が上手く完成しても、それをどうユーザーに届けるかシミュレーションするのはまた別の問題でした。私は以前からStreamlitというUIフレームワークを使った事があったので、迷わずStreamlitを使って対話型のUIを構築しました。

🧪テストラン：成功と失敗の狭間で

最初はしばらくうまく返答が返ってくることが難しく、エージェントの動きに試行錯誤する日が続きました。原因がどこにあるのかを探るためにも、LangFuseというツールをコード内に導入しました。LangFuseは、エージェントの思考プロセス、コード実行、ツール呼び出しの流れを可視化・記録してくれる優れたデバッグツールです。このツールを使ってプロンプトの失敗の流れを確認しながら改善を続けました。

🚨【重要】学びと気づき：smolagentsの良さと、そして“苦労したこと

Smolagentsは、非常に軽量でシンプルに始められるエージェントフレームワークです。ReActベースで設計されており、最低限のコードで強力なエージェントを構築できるという点で、非常に魅力的なツールだと感じました。しかしその一方で、学べば学ぶほど“見えてこないもの”の存在にも気づきました。

💡 一番大事なのに、ドキュメントにほとんど書かれていない「システムプロンプト」の話

私にとって最大の壁となったのが、エージェントのSystem Promptの設計です。上記にもありますが、Smolagentsでは、エージェントの考え方や振る舞いを定義するシステムプロンプトのテンプレートがすでに用意されています。デフォルトテンプレートがあるので、最悪、システムプロントを自分で用意しなくてもエラーは発生しません。しかし、ドメイン特化型エージェント（たとえば「東京交通」に特化したもの）を構築するにはどうしても自分でシステムプロンプトを設計しなければならないと感じました。しかし問題は、最新バージョンのドキュメントにシステムプロンプトに関する記述がほとんどないこと。なぜそのようにテンプレートが分かれているのか、それぞれがどう連携して動いているのかが分からず、答えのない手探り状態で試行錯誤を続ける日々でした。

📖 ドキュメントを読むという“学びの技術”

私には昨年までソフトウェア開発分野で活躍するメンターがいました。彼はPythonのカンファレンスでもスピーチをしたこともある著名なプログラマーです。彼が良く私に言っていたのは、

このプロジェクトを通して再確認したことは、ドキュメントを読むこと自体にも技術がいるということです。オープンソースプロジェクトのドキュメントには共通フォーマットのようなものがあるとはいえ、内容の粒度や構成はプロジェクトごとに大きく異なります。Hugging Faceは丁寧なドキュメントを提供してくれていますが、それでも「ハイレベルの概念」と「低レベルの実装」の間にある大きなギャップは、自分で埋めなければなりません。特にSmolagentsのようなまだ発展途上のフレームワークでは、設計思想そのものがまだドキュメントに書かれていないことも多く、コードベースに隠れた意図を読み解く必要があると感じました。なので、ドキュメントを読むと同時にソースコードも読み込むようにしています。。プロンプトテンプレートの内部構造、CodeAgentの挙動、Memoryの仕組み、、、そういった内部実装を読む事で、ようやく「エージェントの動き」が少しずつ理解できるようになるのです。

🔍「じゃあ何が書かれていないのか？」を常に考える

ドキュメントを読むときに大事なのは、ただ読み手になって何が書かれているかを理解するだけでなく、「何が書かれていないのか」を意識しながら読み進めていく事です。

• なぜそのような設計になっているのか

• 本来書かれるべきなのに省略されているコンセプトは？

• 書かれていない部分に、暗黙の前提やルールは存在しないか？

• これは誰向けに書かれたものなのか？

このような疑問を常に持ち、足りない部分は自分で補充する視点と行動力が、エージェント開発に限らずどの種類のプロジェクト開発にも不可欠だと再確認させられました。

🦾オープンソースへの貢献が、自分を一段階上のレベルに引き上げてくれた

私はAIエージェントを構築する過程で、ただ単に受け身で「使う側」だけに留まりたくはありませんでした。Smolagentsのドキュメンテーションやエージェントのコースに目を通しながら、

「ここはもっと改善できるはず」
「ここの部分はもっとわかりやすく言い換えられるはず」
「この部分のコンセプトは間違っているんじゃないか？」

と、気づいたことが何度もありました。そうした気づきをそのまま流すのではなく、自分の学びを「貢献」に変える挑戦として、実際に公式のHugging Face エージェントコースのGitHubリポジトリにコントリビュートすることを始めました。Issueを出したり、Pull Requestを送ったり、メインテナーとディスカッションを重ねたり。

この経験を通して、３つの大きな気づきがありました。

✅学ぶ」と「貢献する」は両立する：コースマテリアルやドキュメントに目を通しながら、浮かんでくる疑問点をそのまま改善提案に盛り込む事で、学習と貢献が同時に進みます。

✅オープンソースは「読む力」より「直す力」：開存コードを理解して終わり、という受け身の姿勢ではなく、「もっと良くできないか？」と考える視点が、コード力を一気に高めてくれます。

✅英語は壁ではなく「共通言語」：英語が苦手な方は、最初はGitHubレポジトリー内のやりとりに緊張するかもしれません。しかし、大抵のオープンソースのプロジェクトはコミュニティーもとてもオープンで、初めての貢献者を迎え入れる体制や雰囲気が整っています。技術を通じた対話が成り立つという実感が得られるので、とても貢献し甲斐があります。

👩‍🚀これからエージェントを学ぶ人へ

エージェントの学習や開発を始めたばかりの方こそ、「学ぶだけで終わらない」体験をしてほしいと思っています。
教材やドキュメント、ソースコードを参照するだけではなく、

• 自分がつまずいたポイントをIssueとして共有したり、

• 修正できそうな箇所をPull Requestとして送ってみる

そうした一歩を踏み出す事で、あなた自身の理解が深まるだけではなく、未来の学習者の助けにもなります。
これこそがオープンソースの醍醐味です。

読むこと、実践する事、疑うこと、そして貢献すること。

それが、オープンソースから最大限学ぶための４つの視点だと信じています。

🗃️参考資料＆レポジトリー

Smolagents ドキュメンテーション

Hugging Face エージェントコース

Hugging Face MCP コース

東京交通案内エージェントをベースにしたエージェントテンプレート

ここからエージェントを実際に使ってみることができます。