1
6

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【脱・従量課金】Microsoft Agent Framework を Ollama でローカル運用する Vol.2 〜02-agents/ 厳選ハンズオン〜

1
Posted at

【脱・従量課金 実践編】Microsoft Agent Framework を Ollama でローカル運用する Vol.2 〜02-agents 厳選ハンズオン〜

はじめに

前回の記事では、Microsoft Agent Framework(以下 MAF)公式サンプルの 01-get-started を Azure AI Foundry から OllamaChatClient に書き換え、API課金ゼロで動かすところまでを紹介しました。

今回はその続編です。
公式リポジトリの 02-agents には、ツール呼び出し・ミドルウェア・スキル・会話履歴管理・DevUIなど、実運用で欲しくなる機能が300ファイル超のサンプルとして詰め込まれています。
ただしそのほとんどが Azure AI Foundry / OpenAI / Amazon Bedrock / Anthropic / Cosmos DB / Redis といった外部サービス前提で書かれており、そのままではローカル環境で動きません。

そこで今回は、クラウド課金なしで完結できるものだけを選りすぐり、以下の5テーマに絞って OllamaChatClient 化しました。
300ファイル超から、実際に手元で動かせる約100ファイルまで削ぎ落としています。

テーマ ディレクトリ 内容
Ollama基本 providers/ollama/ ツール呼び出し・推論・マルチモーダルの基本形
Tools & Middleware tools/, middleware/ ツール実行の制御、リクエストの前後処理
Skills skills/ 必要な分だけ小出しに情報を渡して、エージェントの能力を拡張する仕組み
Compaction & Conversations compaction/, conversations/ コンテキストウィンドウと会話履歴の管理
DevUI & Observability devui/, observability/ ブラウザで動くデバッグUIと、エージェント内部の動きを記録・可視化する仕組み

削った側(Azure Foundry / Bedrock / Anthropic / Cosmos DB / Redis / mem0 / embeddings / evaluation など)についても、なぜ除外したかを本記事の最後に触れます。

動作環境

前回同様、uv でパッケージ管理し、Ollama をローカルで起動しておくだけです。

uv sync
ollama serve  # 別ターミナルで起動しておく
ollama pull gemma4:12b-it-qat

今回のサンプルはすべて gemma4:12b-it-qat 一本で動きます。
公式サンプルのコメントには「マルチモーダルは gemma系、推論は qwen3系を試すとよい」という記載もありますが、これは Foundry / OpenAI 版オリジナルサンプルの名残と見られます。
実際に

curl http://localhost:11434/api/show -d '{"name":"gemma4:12b-it-qat"}'

で対応機能(capability)を確認すると ["completion", "vision", "audio", "tools", "thinking"] という結果が返ってきました。
これはツール呼び出し・推論・画像入力のすべてに対応済み、という意味です。
モデルを使い分ける必要はなく、今回は1モデルに統一しています。

💡 モデルが特定の機能に対応しているか迷ったら、まず /api/show で対応機能を確認するのが確実です。
サンプルのコメントは移植元(Foundry/OpenAI版)の前提を引きずっていることがあります。

コード中に頻出する additional_properties=120.0 は、CPU推論で応答が遅くなりがちなローカル環境向けにタイムアウトを120秒へ伸ばしているだけです。
GPU環境では不要かもしれません。

1. Ollama基本 — 素振り

providers/ollama/ には OllamaChatClient の使い方をひととおり体験できるサンプルが5本入っています。
基本形はこれだけです。

from agent_framework import Agent, tool
from agent_framework.ollama import OllamaChatClient

agent = Agent(
    client=OllamaChatClient(
        host="http://localhost:11434", model="gemma4:12b-it-qat", additional_properties=120.0
    ),
    name="TimeAgent",
    instructions="You are a helpful time agent answer in one sentence.",
    tools=get_time,
)

面白いのは ollama_agent_reasoning.py です。
default_options={"think": True} を渡すだけで、モデルの思考過程(reasoning)を取得できます。

agent = Agent(
    client=OllamaChatClient(...),
    default_options={"think": True},  # エージェントレベルで推論を有効化
)
result = await agent.run("Hey what is 3+4? Can you explain how you got to that answer?")
reasoning = "".join(
    (c.text or "") for c in result.messages[-1].contents if c.type == "text_reasoning"
)
print(f"Reasoning: {reasoning}")

ollama_chat_multimodal.py では base64 画像を Content.from_uri で渡すだけで画像認識が動きます。
クラウドの Vision API を別途契約する必要がないのはやはり気楽です。

ollama_with_openai_chat_client.py も地味に便利です。
Ollama は OpenAI 互換の /v1/ エンドポイントも提供しているため、OpenAIChatClient の base_url をローカルに向けるだけで、OpenAI クライアントの流儀のまま使い回せます。

client = OpenAIChatClient(
    api_key="ollama",  # ダミー値。Ollama は API キーを必要としない
    base_url="http://localhost:11434/v1/",
    model="gemma4:12b-it-qat",
)

2. Tools & Middleware — ループを制御する

tools/(17ファイル)と middleware/(12ファイル)は、エージェントの「暴走」を防ぐための機能が中心です。
ここが個人的に一番実務で刺さるテーマでした。

プログレッシブなツール読み込み

dynamic_tool_exposure.py は、最初から全ツールをモデルに見せるのではなく、必要になったタイミングでツールを追加する実装です。

@tool(approval_mode="never_require")
def load_math_tools(ctx: FunctionInvocationContext) -> str:
    """Load additional math tools (factorial, fibonacci) so they can be used."""
    ctx.add_tools([factorial, fibonacci])
    return "Loaded math tools: factorial, fibonacci. You can now call them."

agent = Agent(
    client=OllamaChatClient(...),
    instructions=(
        "You are a math assistant. If you need math capabilities that are not yet "
        "available, call load_math_tools first, then use the newly available tools."
    ),
    tools=[load_math_tools],  # 最初はこれ1つだけ
)

ツールを何十個も並べるとモデルの選択精度が落ちるのはよく知られた課題で、特に軽量な量子化モデルではその影響が大きくなりがちです。
「まず案内役ツールだけ渡す」戦略はシンプルながら理にかなっています。

呼び出し回数に上限をかける

function_tool_with_max_invocations.py では @tool(max_invocations=1) を付けるだけで、そのツールの生涯呼び出し回数を制限できます。

@tool(max_invocations=1)
def unicorn_function(times: Annotated[int, "The number of unicorns to return."]) -> str:
    """This function returns precious unicorns!"""
    return f"{'🦄' * times}✨"

2回目の呼び出しはモデルに「上限に達した」というエラーが返り、会話を続けながら別の返答を作ってくれます。
他にも max_invocation_exceptions(例外の許容回数)、max_function_calls / max_iterations(クライアント単位のループ上限)など、control_total_tool_executions.py に主要パターンがまとまっています。
軽量モデルほど「もう諦める」といった暗黙の判断は苦手になりがちなので、こうした上限をコード側で明示しておく価値は大きいはずです。

ミドルウェアは3つの書き方がある

middleware/ では、関数ベース・クラスベース・デコレータベースの3種類の書き方が並んでいます。
一番シンプルなデコレータ方式はこうです。

@agent_middleware
async def simple_agent_middleware(context, call_next):
    print("[Agent MiddlewareTypes] Before agent execution")
    await call_next()
    print("[Agent MiddlewareTypes] After agent execution")

chat_middleware.py ではモデルに送る直前のメッセージを書き換えたり、危険なキーワード("password" など)を検知してリクエストを丸ごとブロックしたりできます。
agent_and_run_level_middleware.py では「エージェント全体に効くミドルウェア」と「その1回の run() だけに効くミドルウェア」の実行順序(外側→内側→本体→内側→外側)がコード内のコメントで図解されており、実装とあわせて読むとイメージが掴みやすいです。

3. Skills — 会話を汚さずに能力を増やす

skills/ は個人的に今回一番の目玉だと思っています。
Claude Skills を触ったことがある方ならピンと来るはずですが、MAF にも同種の仕組みが実装されています。ポイントは プログレッシブディスクロージャー(段階的開示)です。

  1. 広告(Advertise) — スキル名と短い説明(数十〜100トークン程度)だけを、最初からシステムプロンプトに載せておく
  2. 読み込み(Load) — 実際にそのスキルを使うことになったら、load_skill ツールで詳しい説明文を読み込む
  3. 資料参照(Read resources) — 変換表のような参考資料は、必要になったタイミングで read_skill_resource を使って個別に読む
  4. スクリプト実行(Run scripts) — 実際の処理は run_skill_script でスクリプトとして実行する

要するに、最初は「名前と一言説明」だけを渡しておき、実際に使う段階になってから詳しい情報を小出しに渡す、という仕組みです。
いきなり全部をプロンプトに詰め込まないので、一度に読み込める文章量(コンテキストウィンドウ)が小さいローカルモデルとの相性がとても良いです。
ファイルベースのスキルはこんな見た目です。

skills_dir = Path(__file__).parent / "skills"
skills_provider = SkillsProvider.from_paths(
    skill_paths=str(skills_dir),
    script_runner=subprocess_script_runner,
)

async with Agent(
    client=client,
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
) as agent:
    response = await agent.run(
        "How many kilometers is a marathon (26.2 miles)? And how many pounds is 75 kilograms?"
    )

スキルの実体は、SKILL.md(スキルの説明文)+ 参考資料(Markdown)+ 実行スクリプト(Python)という3点セットです。
専用のディレクトリを1つ置くだけでスキルを増やせます。
skills/ にはこの他に、Pythonクラスとして定義する class_based_skill、コードで完結させる code_defined_skill、複数の定義方法を1エージェントに混在させる mixed_skills、スクリプト実行前に人間の承認を挟む script_approval、特定のスキルだけを絞り込む skill_filtering、MCP経由でスキルを配信する mcp_based_skill を合わせて、7パターンが揃っています。

4. Compaction & Conversations — 記憶とコンテキストの管理

ローカルLLMは商用APIに比べてコンテキストウィンドウが小さいモデルも多く、「会話が長くなるとどう畳むか」は死活問題です。
compaction/ には6種類の圧縮方法が並んでいますが、面白いのは ChatClientを一切使わない純粋なロジックのサンプルが大半 ということ。
ローカルのメッセージリストを直接いじって動作を確認できるので、Ollamaを起動していなくても試せます。

# TruncationStrategy / SlidingWindowStrategy / SelectiveToolCallCompactionStrategy /
# ToolResultCompactionStrategy / SummarizationStrategy / TokenBudgetComposedStrategy
selected_strategy = SelectiveToolCallCompactionStrategy(keep_last_tool_call_groups=0)
projected = await apply_compaction(messages, strategy=selected_strategy)

実際にエージェントと組み合わせた例が compaction_provider.py です。
「直近3グループだけモデルに見せる」方法と「古いツール呼び出し結果を要約に畳む」方法を、履歴保存の前後で別々に適用しています。

compaction = CompactionProvider(
    before_strategy=SlidingWindowStrategy(keep_last_groups=3, preserve_system=True),
    after_strategy=ToolResultCompactionStrategy(keep_last_tool_call_groups=1),
    history_source_id=history.source_id,
)

conversations/ では FileHistoryProvider で会話を .jsonl としてローカルディスクに永続化するサンプルが目玉です。
DBもRedisも要らず、.jsonl ファイル1つでセッションを再開できます。

context_providers=[
    FileHistoryProvider(
        storage_directory,
        dumps=orjson.dumps if orjson else None,
        loads=orjson.loads if orjson else None,
    )
],

5. DevUI & Observability — 見えないものを見る

devui/ は MAF に付属するブラウザデバッグUIです。
エージェントやワークフローを1行書くだけでチャット画面付きのWebサーバーが立ち上がります。

uv run python 02-agents/devui/main.py
# → http://localhost:8080 でエージェント/ワークフロー一覧とチャットUIが開く

フォルダ探索モード(main.py)とインメモリ登録モード(in_memory_mode.py)の2通りがあり、後者は1ファイルの中でエージェントとワークフローをまとめて serve() に渡すだけです。
承認必須ツール(send_email)とミドルウェア(危険ワードのブロック、特定地名の拒否)を組み合わせた agent_weather/ は、DevUI上で人間承認フローの挙動を確認するのにちょうどいいサンプルです。

observability/ は、エージェントの内部動作を記録して後から追跡できるようにする機能(Observability、可観測性)のサンプルです。
「裏側で何回モデルを呼んだか」「各ツールの実行にどれくらい時間がかかったか」といった処理の流れを、ログのように記録できます。
この記録の仕組みには、業界標準の技術である OpenTelemetry が使われています。

一番手軽な実装は、例えば以下です。

from agent_framework.observability import configure_otel_providers, get_tracer

configure_otel_providers(enable_sensitive_data=True)
with get_tracer().start_as_current_span("Scenario: Agent Chat"):
    ...

処理のひとかたまり(例: モデルへの1回の問い合わせ、ツールの1回の実行)を「スパン」という単位で記録し、それを時系列でつなげたものが「トレース」です。
本来はこのトレースを Application Insights(Azureの監視サービス)や Aspire Dashboard(Microsoft製のローカル向け可視化ツール)のような専用ツールに送って画面上で確認します。
ただ、環境変数 ENABLE_CONSOLE_EXPORTERS=true を立てるだけで、そうした外部ツールを別途用意しなくても、ターミナルにそのままログとして出力できます。

変換作業で気づいたパターン

300ファイル超をふるいにかけながら気づいたのは、クラウド依存コードの書き換えパターンは驚くほど画一的だったということです。

# Before(クラウド版によくあるパターン)
async with (
    AzureCliCredential() as credential,
    Agent(client=FoundryChatClient(credential=credential), ...) as agent,
):
    ...

# After
async with Agent(
    client=OllamaChatClient(host="http://localhost:11434", model="gemma4:12b-it-qat", additional_properties=120.0),
    ...
) as agent:
    ...

AzureCliCredential によるログイン処理がまるごと不要になるので、async with の入れ子が1段減ってコードも素直になります。
あとは load_dotenv() と環境変数の読み込みを消して、直接値を書くだけです。
この「決め打ちで書く」方針は前回記事から一貫させています。

今回あえて除外したもの

以下は「クラウド課金なしで完結できるものだけ」という基準で今回の記事からは外しました。

  • クラウド専用プロバイダ一式(providers/azure, providers/foundry, providers/openai, providers/anthropic, providers/amazon, providers/copilotstudio, providers/github_copilot)
  • 外部ストレージ前提の履歴管理(Cosmos DB, Redis)— Dockerでローカル起動すれば動きそうなものもあり、次回以降の検討候補
  • 埋め込み・評価系(embeddings/, evaluation/)— OpenAI/Foundryの埋め込みAPI前提で、Ollama版のサンプルが現状ない
  • A2A(Agent2Agent)プロトコル(a2a/)— 両側をOllamaで賄えば動きそうだが、サーバー2台構成のデモがやや重く見送り(今後挑戦したい)
  • サンドボックス実行系(code_act/, Hyperlight/Monty系)— ハイパーバイザ依存で環境差が大きい

まとめ

  • 02-agents は300ファイル超あるが、クラウド課金なしで動くのは Ollama基本・Tools/Middleware・Skills・Compaction/Conversations・DevUI/Observability の5テーマ、約100ファイル
  • gemma4:12b-it-qat は tools・thinking・vision すべてに対応しており、モデルを使い分ける必要はなかった(/api/show で確認するのが確実)
  • クラウド版→Ollama版の書き換えは「クライアント初期化+認証処理を削って直書きする」というほぼ定型作業
  • 特に Skills(プログレッシブディスクロージャー)と Compaction(コンテキスト圧縮)は、コンテキストが限られがちなローカルLLM運用との相性が良い

次回 Vol.3 では 03-workflows/ を扱う予定です。
ぜひ本記事のコードも リポジトリ から手元で動かしてみてください。

1
6
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
6

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?