Ollama自作エージェント劇改善：HarnessとScaffoldの正体と定義

📖この記事は約18分で読めます

1. エージェント開発における用語の混乱と解決策

モデルとエージェントの境界線が曖昧になっている

2026年現在のAI開発現場では、「LLMを動かすこと」と「エージェントを作成すること」の区別が曖昧になりつつあります。多くの開発者が、強力なモデルさえあれば自動的に高度な自律性が発現すると誤解しています。

しかし、実際にはモデルの性能だけでは不十分です。同じQwen3-14BやLlama-3.1-70Bを使用しても、 surrounding framework によって出力の質や動作の安定性は大きく異なります。

用語の統一が技術的な壁を下げている

今回の焦点である「Harness」と「Scaffold」の明確な定義は、この混乱を解消する鍵となります。これらは単なる流行語ではなく、エージェントのアーキテクチャを構造的に理解するための重要な概念です。

これらの用語を正しく理解することで、なぜ自分の作ったエージェントが期待通りに動かないのか、その原因を特定しやすくなります。盲目的なプロンプトエンジニアリングから脱却できる可能性が生まれます。

ローカル環境での重要性が増している理由

クラウドAPIではブラックボックス化されがちな処理が、ローカルLLM環境では可視化されます。Ollamaやllama.cpp、vLLMなどを直接制御する場合、内部のデータフローを正確に把握する必要があります。

特にリソース制約のある自宅PC環境では、無駄なコンテキストの投入や不要なツール呼び出しを避けることが、推論速度とコスト効率に直結します。用語の定義は、最適化の起点となります。

2. エージェントの構成要素：Model, Harness, Scaffold

Agent = Model + Harness + Scaffoldの等式

エージェントの本質的な構造は、大きく分けて三つの要素で構成されています。まずは「Model」であり、これはQwenやMistralなどの大規模言語モデルそのものを指します。

次に「Harness」であり、モデルを実行し、ツールを呼び出し、終了条件を判定する実行層です。最後に「Scaffold」があり、システムプロンプトやメモリ管理など、モデルの振る舞いを規定する土台層です。

Model単体ではエージェントにならない

多くの初心者が陥る誤解は、モデルファイル（GGUFなど）をダウンロードするだけでエージェントが完成すると考えることです。モデルはあくまで「脳」であり、手足や感覚器官、そして行動規範が必要です。

例えば、コード生成モデルであっても、ファイルシステムへのアクセス権限や、エラーハンドリングのロジックがなければ、単なるテキスト生成器に過ぎません。これがHarnessとScaffoldの役割です。

実行層と定義層の分離の意義

この二つの層を分離して考えることで、モデルの交換が容易になります。同じHarnessとScaffoldの下で、7Bモデルから70Bモデルへアップグレードする場合、振る舞いの定義部分を書き直す必要がありません。

これはソフトウェアエンジニアリングにおける依存性逆転の法則に近いアプローチです。コアロジックとインフラ層を分離することで、システム全体の保守性と拡張性が劇的に向上します。

3. Harness（ハネス）：エージェントの実行制御層

モデル呼び出しとツールコールの仲介役

Harnessは、エージェントが実際に「動く」ための駆動装置です。ユーザーの入力を受け取り、モデルに送信し、返ってきた出力を解析して次のアクションを決定します。

ここで重要なのは、モデルが生成したJSONや関数呼び出し形式のデータを、実際のOSコマンドやAPIリクエストに変換する処理です。この変換ロジックがHarnessの核心部分となります。

停止タイミングの決定権を持つ

エージェントが無限ループに陥らないようにするための制御も、Harnessの重要な役割です。トークン数の上限、実行時間の制限、または特定の終了フラグの検知など、安全装置として機能します。

ローカル環境では、VRAMの枯渇やCPU負荷の急増といったハードウェア的な制約も考慮する必要があります。Harnessがこれらのリソース状態を監視し、適切に中断判断を下すことが求められます。

LangChainやCrewAIにおけるHarnessの実装

人気のフレームワークであるLangChainでは、ChainやAgentExecutorクラスがHarnessの役割を担っています。一方、CrewAIではCrewクラスがこれに相当します。

これらのフレームワークを使用する場合、Harnessの内部ロジックを完全にカスタマイズするのは難しいですが、設定パラメータを通じて挙動をある程度制御可能です。Ollama APIを直接叩く場合なら、完全に自由なHarness構築が可能です。

4. Scaffold（スケルトン）：振る舞いを定義する土台

システムプロンプトとコンテキスト管理

Scaffoldは、モデルが「誰として」「どのような状況で」動作するかを定義する層です。最も基本的な要素はシステムプロンプトであり、ここで役割や制約、出力フォーマットが指定されます。

さらに、会話履歴の保持方法、外部知識の取得方法、長期記憶の保存場所など、コンテキストウィンドウ内外の信息管理もScaffoldの範疇に入ります。

ツール説明とスキーマの提供

モデルが利用可能なツールの一覧と、それぞれの使用方法に関するドキュメントもScaffoldの一部です。モデルはこれらの説明に基づいて、適切なツールを選択し、引数を生成します。

ツール説明が曖昧だと、モデルは誤った引数を渡したり、存在しない関数を呼び出したりします。Scaffoldの設計品質は、エージェントの実行成功率に直結します。

メモリ機能と状態の保持

短期記憶（会話履歴）と長期記憶（ベクトルデータベースやファイルシステム）の管理もScaffoldが担います。これにより、エージェントは過去の文脈を考慮した一貫した応答が可能になります。

ローカル環境では、SQLiteやChromaDB、Qdrantなどを組み合わせて、軽量かつオフラインで動作するメモリ機構を構築するのが一般的です。Scaffoldの設計次第で、プライバシー保護と利便性の両立が可能です。

5. SkillとToolの違い：パッケージ化された知識

Toolは単一アクション、Skillは複合タスク

ここで注意が必要なのが、Tool（ツール）とSkill（スキル）の区別です。Toolは「ファイルを開く」「検索を実行する」といった単一の原子的操作を指します。

一方、Skillは特定のゴールを達成するために必要な、一連の知識と手順がパッケージ化されたものです。例えば、「Pythonコードのデバッグ」というSkillは、ファイル読み込み、エラー解析、修正提案、テスト実行などの複数のTool呼び出しを含みます。

Skillの再利用性とモジュール性

Skillを独立したモジュールとして設計することで、異なるエージェント間での再利用が可能になります。これは、従来の関数ライブラリと同様の思想です。

例えば、「Webスクレイピング」というSkillを定義しておけば、ニュース集約エージェントも、競合調査エージェントも、同じSkillを呼び出すだけで高度な処理を実現できます。

プロンプトエンジニアリングの高度化

Skillの定義には、高度なプロンプトエンジニアリングが必要です。どのような入力を期待し、どのような出力を返すか、エラー発生時の挙動はどうか、などを詳細に記述します。

これは単なる指示出しではなく、仕様書の作成に近い作業です。Scaffoldの中にSkillの定義を埋め込むか、外部ファイルとして参照するか、アーキテクチャによって異なります。

6. Sub-agent：階層構造による複雑さの管理

サブエージェントの独立した推論能力

Sub-agent（サブエージェント）は、親エージェントから呼び出される、独立したエージェントインスタンスです。独自のモデル、Harness、Scaffoldを持ち、自律的に推論を行います。

これにより、複雑なタスクを階層的に分解できます。親エージェントは「概要設計」を担当し、サブエージェントは「詳細実装」や「テスト実行」のような専門的なタスクを処理します。

リソース分離と並列処理の可能性

サブエージェントは、異なるGPUメモリ領域やCPUコアで並列実行することも可能です。これにより、全体の処理時間を短縮できます。

例えば、コードレビューエージェントと、ドキュメント生成エージェントを同時に動作させる場合、それぞれが独立したコンテキストウィンドウを持つため、干渉がありません。

呼び出しインターフェースの標準化

サブエージェントを有効活用するには、親エージェントとの間で明確なインターフェースを定義する必要があります。入出力のフォーマット、エラーコード、ステータス報告の方法などを統一します。

REST APIやgRPC、あるいは単純なJSONメッセージングなど、通信プロトコルの選択はシステム設計の重要な要素です。ローカル環境では、IPC（プロセス間通信）を用いた高速な連携も検討価値があります。

7. 強化学習（RL）環境におけるエージェント訓練

RL EnvironmentとTrainerの役割

エージェントの能力をさらに高めるために、強化学習（RL）が注目されています。RL環境では、エージェントが試行錯誤を通じて最適な行動ポリシーを学習します。

このプロセスには、環境（RL Environment）、トレーナー（Trainer）、ロールアウト（Rollout）、報酬（Reward）の四つの要素が不可欠です。それぞれが明確な役割分担を持ちます。

報酬関数の設計：VerifiableとSparse/Dense

報酬（Reward）の設計はRLの成功を左右します。検証可能（Verifiable）な報酬は、テストケースのパス/フェールや、人間による評価に基づきます。

また、報酬の与え方には、エピソード終了時のみ与える「疎（Sparse）」報酬と、各ステップで与える「密（Dense）」報酬があります。タスクの種類に応じて、適切な報酬戦略を選択する必要があります。

ローカル環境でのRLの課題

しかし、RLは計算リソースを大量に消費します。自宅PCでフルスケールのRLを行うのは現実的ではありません。代わりに、既存のモデルをファインチューニングし、小さなRLステップを追加するのが現実的です。

LLaMA-FactoryやAxolotlなどのツールを活用し、少量のデータで効率的な学習を行うアプローチが、ローカルLLMユーザーには推奨されます。

8. コンテキストエンジニアリング：ウィンドウ内の最適化

コンテキストウィンドウの効率的な活用

コンテキストエンジニアリングとは、エージェントのコンテキストウィンドウに何を、どのように投入するかを設計するプロセスです。システムプロンプト、会話履歴、取得した知識などを適切に配置します。

LLMのコンテキストウィンドウには限りがあります。特に7B〜14Bクラスのモデルでは、32K〜128Kトークンが一般的です。この限られた空間をいかに有効活用するかが鍵です。

学習時と推論時のコスト構造の違い

コンテキストの設計は、学習時と推論時で異なるコスト構造を持っています。学習時は、関連性の低い情報をフィルタリングしてデータ品質を高め、推論時は、不要な情報を除外して処理速度を向上させます。

例えば、長文ドキュメントをそのまま投入するのではなく、要約済みテキストや関連箇所のみを抽出して投入することで、推論の精度と速度を両立できます。

RAGとの連携による拡張

Retrieval-Augmented Generation（RAG）技術と組み合わせることで、コンテキストウィンドウの制限を突破できます。必要な情報だけをリアルタイムで取得し、ウィンドウに投入します。

これにより、モデルの事前学習データに含まれていない最新の情報や、ドメイン特化知識を活用した応答が可能になります。ローカル環境では、QdrantやMilvusなどのベクトルデータベースとの連携が一般的です。

9. 実践ガイド：Ollamaでの最小構成エージェント構築

必要なツールと環境準備

実際に手を動かしてエージェントを構築してみましょう。まずは、Ollamaがインストールされた環境を準備します。次に、PythonとLangChain、またはCrewAIなどのフレームワークをインストールします。

モデルとしては、ツール呼び出しに強いQwen2.5-Coder-7Bや、汎用性の高いLlama-3.1-8Bがおすすめです。VRAMが16GB以上あれば、14Bクラスも動作可能です。

基本的なコード構造の実装

以下に、LangChainを用いた最小構成のエージェント例を示します。Harnessの役割を担うAgentExecutorと、Scaffoldの役割を担うToolsとPromptsを定義しています。

from langchain.agents import AgentExecutor, create_react_agent
from langchain_community.llms import Ollama
from langchain_core.tools import Tool

# Model (LLM)
llm = Ollama(model="qwen2.5-coder:7b")

# Scaffold: Tools definition
def search_tool(query: str) -> str:
    # 実際の検索ロジックを実装
    return f"Search results for {query}"

tools = [
    Tool(name="Search", func=search_tool, description="Useful for searching information")
]

# Scaffold: Prompt template
prompt = create_react_agent_prompt(tools)

# Harness: Agent creation
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# Execution
response = agent_executor.invoke({"input": "What is the latest news about Ollama?"})
print(response)

カスタマイズと拡張のポイント

この基本構造を基に、独自のToolを追加したり、Scaffoldのプロンプトを調整したりできます。例えば、ファイルシステムへのアクセス権限を与えるToolを追加すれば、ローカルファイルの処理が可能になります。

また、メモリ機能を追加することで、会話履歴を保持する長期記憶型のエージェントに発展させることも可能です。段階的に機能を追加していくのが、失敗を防ぐコツです。

10. メリットとデメリット：正直な評価

メリット：プライバシーとカスタマイズ性

ローカルでエージェントを構築する最大のメリットは、データのプライバシー保護です。機密情報を外部サーバーに送信する必要がありません。

また、HarnessやScaffoldを自由にカスタマイズできるため、特定の業務フローに最適化されたエージェントを構築できます。クラウドAPIでは実現できない、高度な制御が可能です。

デメリット：リソース消費と設定の複雑さ

一方で、デメリットも無視できません。GPUメモリやCPUリソースを大量に消費するため、高性能なハードウェアが必要です。また、設定の複雑さから、初心者には敷居が高いと言えます。

モデルの選択、量子化レベルの調整、フレームワークの設定など、試行錯誤を繰り返す必要があります。特に、大規模モデルを動かす場合、VRAM不足によるエラーに直面する頻度が高いです。

コストパフォーマンスの比較

長期的に見れば、ローカル環境の方がコスト効率が良くなることが多いです。クラウドAPIは使用量に応じて課金されるため、頻繁な利用では高額になります。

一方、ローカル環境は初期投資のみで、その後無料で利用可能です。ただし、電気代やハードウェアの劣化コストも考慮する必要があります。

11. 活用方法：読者が試せる具体的なシナリオ

コードアシスタントとしての活用

最も実用的な活用方法は、コードアシスタントとしての利用です。CursorやContinueのようなツールと連携させ、オフラインでコード補完やレビューを行います。

特に、社内システムや機密プロジェクトでは、外部接続を遮断した環境での利用が求められます。ローカルエージェントは、このようなシナリオに最適です。

ドキュメント処理と要約

大量のドキュメントを処理し、要約や情報抽出を行うエージェントも構築可能です。RAG技術と組み合わせることで、正確な回答を提供できます。

例えば、契約書や技術仕様書をアップロードし、特定の条項やリスク要因を自動で検出するエージェントを作成できます。これは、法務やエンジニアリング分野で大きな価値を生みます。

パーソナルアシスタントの構築

個人のスケジュール管理、メールの分類、タスクの優先順位付けなど、パーソナルアシスタントとしての活用も可能です。プライバシーを重視するユーザーには、魅力的な選択肢です。

音声認識や音声合成技術と連携させ、音声インターフェースを持つエージェントにすることもできます。これにより、より自然な対話体験を実現できます。

12. 今後の展望：エージェント技術の進化

マルチエージェントシステムの普及

今後、単一エージェントから、複数のエージェントが協調して動作するマルチエージェントシステムへの移行が進むでしょう。各エージェントが専門領域を持ち、連携して複雑なタスクを処理します。

これにより、より高度な自律性と柔軟性が実現します。例えば、研究調査エージェント、データ分析エージェント、レポート生成エージェントが連携し、包括的な分析レポートを自動作成します。

モデルサイズのスケーラビリティ

モデル技術の進歩により、より小さなモデルでも高い性能を発揮するようになります。これにより、ローカル環境でのエージェント運用がさらに容易になります。

量子化技術の向上や、モデルアーキテクチャの最適化が進むことで、VRAM 8GB程度のGPUでも、実用的なエージェントを動作させられる日が近づいています。

開発者体験の向上

フレームワークやツールの成熟により、エージェント開発のハードルは低下します。低コード/ノーコードツールが登場し、専門知識のないユーザーでも簡単にエージェントを構築できる時代が来るでしょう。

これにより、AIエージェントは、より多くの産業や個人に普及し、日常業務の効率化に貢献します。

13. まとめ：用語の定義がもたらす可能性

明確な理解が技術革新の基盤となる

HarnessとScaffoldの明確な定義は、単なる用語の整理ではありません。エージェントの設計思想を理解し、より高度なシステムを構築するための基盤となります。

モデル、実行層、定義層を分離して考えることで、システムの柔軟性と保守性が向上します。これは、ソフトウェアエンジニアリングの基本原理に立ち返ったアプローチです。

ローカルLLMユーザーへのメッセージ

ローカルLLMを愛する読者の皆様には、これらの概念を実際に手を動かして体験していただきたいと思います。OllamaやLangChainなどを活用し、自分専用のエージェントを構築してみてください。

失敗を恐れず、試行錯誤を繰り返すことで、真の理解が深まります。そして、その経験が、より高度なAIシステムの開発へとつながるでしょう。

未来への一歩を踏み出そう

AIエージェントの時代は、すでに始まっています。用語の定義を理解し、技術の仕組みを把握することで、私たちは単なるユーザーから、創造的な開発者へと変身できます。

自宅のPCを起動し、ターミナルを開き、新しいエージェントの構築を始めましょう。その一歩が、あなたの仕事や生活を変える可能性を秘めています。

---

📦 この記事で紹介した商品