🧰

Microsoft Agent Framework - データベース検索エージェントを作って Function Tool の 作り方を学ぶ

に公開
2026/02/02

修正

  • python-1.0.0b260128
    • @ai_function デコレータが @tool に変更
    • AIFunction クラス が FunctionTool に変更

概要

Microsoft Agent Frameworkシリーズ第3弾です。今回はエージェントのツール実装方法を紹介します。Pythonに慣れている人にとってはかなり作りやすいと感じられるのではないかと思っています。

この記事で解説すること

  • エージェントによる 「ユーザー質問理解 → SQL → DB検索 → 結果要約」の実装
  • Function Tool の 実装・詳細設定
  • エージェントによる危険なツール実行をどう抑えるかのポイント

前提

  • テスト時 Microsoft Agent Framework: 1.0.0b260107
  • ローカルでサンプルデータの入っているPostgreSQLが立ち上がっていること
pip install agent-framework psycopg[standard] python-dotenv

ソースコード

  • agent.py
  • db/sql_client.py
  • functions/search_db.py

という形で3つのコードに分割しています。

SQLクライアント

psycopg3を使ってToolで使用するSQLクライアントを管理します。ツールの最後でexecute_sql(sql)を実行してエージェントにクエリの結果を返す想定です。エージェントにDBを変更させないため、デフォルトで読み取り専用になるようにしています。

sql_client.py
import psycopg

class SQLClient:
    def __init__(
        self,
        url: str,
        port: int,
        user: str,
        password: str,
        database: str = "sample_db",
        read_only: bool = True,
    ):
        self.connection = psycopg.connect(
            host=url,
            port=port,
            user=user,
            password=password,
            dbname=database,
        )
        
        # 読み取り専用
        if read_only:
            self.connection.read_only = True
        else:
            self.connection.autocommit = True

    def execute_sql(self, sql: str):
        with self.connection.cursor() as cursor:
            cursor.execute(sql)
            if cursor.description:
                return cursor.fetchall()
            return None

ツール実装

エージェントが生成したSQLを実行するツールです。
普通のpythonの関数に@ai_functionデコレータを付けるだけで、エージェントツールとして使えるようになります。

DBの変更をここでもブロックするために、エージェントが生成したSQLに変更クエリが入っていればここではじくようにしています(本来はもっとちゃんとしたバリデーション関数を作るべき)。ただこの方法は漏れには十分注意しなければなりません
そもそもSQL自体を生成させるのではなく、SQLの土台は事前に作成してツールを作り、エージェントにはその引数だけを生成させるのがよりセキュアであり、トークン使用量の削減にもなります。

search_db.py
import os
import logging
from typing import Any, Dict
from pydantic import Field
# from agent_framework import ai_function
from agent_framework import tool # デコレータ名称変更
from dotenv import load_dotenv

from db.sql_client import SQLClient

logger = logging.getLogger(__name__)

load_dotenv()
sql_client = SQLClient(
    url=os.getenv("DB_URL", "127.0.0.1"),
    port=int(os.getenv("DB_PORT", "5432")),
    user=os.getenv("DB_USER", "postgres"),
    password=os.getenv("DB_PASSWORD", "postgres"),
    database=os.getenv("DB_DATABASE", "sample_db"),
)

FORBIDDEN_STATEMENTS = ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "CREATE"]

# @ai_function(
@tool(
    name="get_sql_result",
    description="SQLを実行して結果を取得します",
)
def get_sql_result(
    sql: str = Field(..., description="実行するSQL文"),
) -> Dict[str, Any]:
    logger.info(f"Executing SQL: \n{sql}")
    # 禁止するSQL文のチェック
    if any(statement in sql.upper() for statement in FORBIDDEN_STATEMENTS):
        return {"result": "許可されていないSQL文が含まれています。\nINSERT, UPDATE, DELETE, DROP, ALTER, CREATE文は使用できません。\nAIエージェントによるDBの変更はセキュリティリスクが高いため禁止されています。"}

    return {"result": sql_client.execute_sql(sql)}

tools = [get_sql_result]

デコレータ引数

  • name: ツール名です。ログ確認時にわかりやすい名前を付けましょう
  • description: str | None: ツールの説明でエージェントがツール選択の手がかりにするため簡潔に役割を書きましょう
  • approval_mode: Literal['always_require', 'never_require'] | None : ツール実行に毎回承認が必要かどうか決めます。別記事で解説予定ですが Human in the Loop のための処理を追加していないとツールが選択された時点で後続に行けずに処理が停止します
  • その他いくつかありますが、一般的な使い方で困らないと思うので一旦省略します。

関数引数

  • 型の指定
    • 基本型だけでなく自作のEnumを使うことで使える値の指定なども可能です
  • pydanticのField
    • descriptionパラメータを付与することで引数に何を入れるべきかエージェントに教えることが出来ます
    • 数値であれば値の範囲指定等も可能

引数の細かい指定については色々記述方法がありますが、ライブラリを理解する学習コストを考えると、個人的にはどうせエージェントへの指示になるのである程度はdescriptionに記述するのが楽だしメンテナンス性も良いと思います。

エージェントの実装

上記で作成したツールをエージェントに渡しています。
念押しでインストラクションにもデータベース変更の禁止を制約として追加しています。
ツールエラー時の再実行についてはFunctionInvocationConfigurationを使ってエージェントの設定に追加できるので、ツール自体にはエラーハンドリングを入れていません(実際のシステムではログは出した方がいいかも)
テストのためにDevUIにエージェントをホストさせるようにしています。

agent.py
import os

from agent_framework import ChatAgent
from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework._tools import FunctionInvocationConfiguration
from agent_framework.devui import serve
from dotenv import load_dotenv

from functions.search_db import tools

load_dotenv()

INSTRUCTIONS = """
# 役割
あなたはPostgreSQLデータベースに対してSQLクエリを実行し、情報を取得するエージェントです。
データベースには2005年の米国農務省農業研究局(USDA)標準参照用栄養データベースが格納されています。
ユーザーからの質問に基づいて、適切なSQLクエリを生成し、データベースから必要な情報を取得してください。以下の制約条件とツールを守って行動してください。
# 制約条件
- データベースの内容を変更するSQL文(INSERT、UPDATE、DELETE、DROP、ALTER、CREATEなど)は実行しないでください。これらの操作は禁止されています。
# ツール
- get_sql_result: 指定されたSQL文を実行し、その結果を取得します

ユーザーの質問に対して、必要に応じてツールを使用し、最終的な回答を提供してください。
"""

# function invocation configurationを設定(ツール呼び出しの設定変更)
# 以下は全てデフォルト値
MAX_CONSECUTIVE_ERRORS_PER_REQUEST = 3
MAX_ITERATIONS = 40
INCLUDE_DETAILED_ERRORS = False
function_config = FunctionInvocationConfiguration(
    max_consecutive_errors_per_request=MAX_CONSECUTIVE_ERRORS_PER_REQUEST,
    max_iterations=MAX_ITERATIONS,
    include_detailed_errors=INCLUDE_DETAILED_ERRORS,
)

openai_responses_client = AzureOpenAIResponsesClient(
    api_key = os.getenv("API_KEY"),
    endpoint = os.getenv("ENDPOINT"),
    deployment_name = os.getenv("DEPLOYMENT_NAME"),
    function_invocation_configuration=function_config,
)

agent: ChatAgent = openai_responses_client.create_agent(
    name="Agent",
    instructions=INSTRUCTIONS,
    tools=tools,
    allow_multiple_tool_calls=True,
)

if __name__ == "__main__":
    serve([agent], host="localhost", port=8080) 

テスト

python agent.py
> INFO:     Started server process [51636]
> INFO:     Waiting for application startup.
> INFO:     Application startup complete.
> INFO:     Uvicorn running on http://localhost:8080 (Press CTRL+C to quit)

DevUIにエージェントをホストさせているので、Web ブラウザ上でエージェントとのチャットをテストすることが出来ます。
alt text
データベース構造を調べさせてみるとSQLが実行されて結果を基に回答してくれました。本番エージェントで毎回構造を知らないところからだとトークン使用量が増大するので最低限のテーブル構成やリレーション情報はインストラクションに追加した方が良いでしょう

alt text
右のタブでToolsを選択するとツール実行の詳細を確認できます。ツール実行に使った引数、結果の出力を確認できます。確認ボックスが固定サイズなのがちょっと惜しい。

alt text
何か適当にデータを調べてみて、とお願いしたら複数のクエリを生成して並列実行してくれました。思ったより一気に使われてビビりましたが、こういう思わぬツール利用を避けるためにもエージェントによるクエリの一発生成と実行には気を付けたいですね、という良い例になりました。こういう危険性のあるツールはallow_multiple_tool_calls=Falseに設定しておくとか、“必ず1クエリにまとめる” というプロンプト制約を追加するとかするとよいでしょう

ツール実行のブロック

エージェントへの実行権限・セキュリティには十分注意しましょう。今回はデータベースを例にしたので3層で変更へのブロックをしました。それぞれの層の設定にそれぞれメリット・デメリットがあります。

  • エージェントへの制約: 無駄なツール実行を防ぎ、応答性の向上・トークンの節約になります。ただし LLM がユーザーに騙されて jail break 的に突破される可能性があります
  • 関数内でのブロック: DBへのトランザクション増加を防げます。有料API利用のツールであれば無駄な利用料が発生せずに済みます。制約の設定漏れの恐れがあります。また、ブロック時にはエージェントに何故ブロックされたか説明を返してあげるのが望ましいです
  • クライアントでのブロック: 関数内で実際に外部と接続するクライアントの設定でブロックします。一番強力なブロックだと思います。利用するサービスの設定等の十分な理解が必要です

Human in the Loop について

今回は設定しませんでしたが、関数の実行に人の承認を必須にする方法もあります。信頼のおけるユーザーが使っていれば十分機能し、責任の所在がハッキリするという点でメリットがあります。しかし、人の介入を増やし過ぎると、

  • 自動化という目的から離れる恐れ
  • 悪意のある人の指示は防げない
  • 数が増えると承認が雑になる可能性

などがあるため万能ではありません。人の承認はシステム要件として必須にしない方法を出来る限り模索したいです。

おわり

今まで色んなライブラリでツール呼び出しを試してきましたが、個人的には一番作り易くてうれしいです(知らなかっただけで前から同じように作れるライブラリもあったのかもしれない)。まだ試していないこともあるので色々と検証していきたいです。

ヘッドウォータース

Discussion