ツールの定義と説明文

エージェントに「メール署名を作る」「天気を取得する」といった具体的な能力を持たせたいとき、Python 関数として実装したツールをエージェントに渡します。ただし、モデルは Python コードを直接読むわけではなく、人間が書いた説明文を通してしか「このツールは何をするもので、いつ呼び出すべきか」を判断できません。

1. 概要

エージェントに「メール署名を作る」「天気を取得する」といった具体的な能力を持たせたいとき、Python 関数として実装したツールをエージェントに渡します。ただし、モデルは Python コードを直接読むわけではなく、人間が書いた説明文を通してしか「このツールは何をするもので、いつ呼び出すべきか」を判断できません。説明が曖昧だと、必要なときに呼ばれなかったり、間違った引数で呼ばれたりします。

Strands の @tool デコレータと、関数の型ヒント・docstring を組み合わせて使えば、Python の関数定義そのままがツールの入力スキーマとモデル向けの説明文としてモデルに伝わります。docstring の1文目に「いつ使うべきか」を、Args: セクションに各引数の意味と例を書くと、モデルのツール選択と引数抽出の精度が安定します。

現状の create_signature の docstring は最低限の1行だけなので、「いつ使うべきか」の観点と各引数の意味を補うようにアップデートしてみます。

2. コードの書き換え

main.py を、以下の内容で全体を置き換えて保存します。前セクションからの変更は、create_signature の docstring のみです。

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent, tool
from strands.models import BedrockModel

COMPANY_NAME = "DevOps株式会社"
COMPANY_TEL = "03-1234-5678"
MODEL_ID = "<モデルID>"  # ap-northeast-1で利用可能なClaude Sonnetの推論プロファイルID(例: jp.anthropic.claude-sonnet-4-6)に変更してください

app = BedrockAgentCoreApp()


@tool
def create_signature(name: str, department: str, position: str, email: str) -> str:
    """ユーザからメール署名の作成を依頼されたときに使ってください。氏名・部署名・役職・メールアドレスを受け取り、所定のフォーマットのメール署名を返します。会社名と代表電話番号は Runtime 側で自動的に付与されるため、ユーザに問い合わせる必要はありません。

    Args:
        name: 氏名(例: '田中太郎')
        department: 部署名(例: '開発部')
        position: 役職(例: 'エンジニア')
        email: メールアドレス(例: 'tanaka@example.com')
    """
    return (
        "━━━━━━━━━━━━━━━━━━━━━━\n"
        f"【{name}】{COMPANY_NAME} {department} {position}\n"
        f"Email: {email}\n"
        f"Tel:   {COMPANY_TEL}\n"
        "━━━━━━━━━━━━━━━━━━━━━━"
    )


agent = Agent(
    model=BedrockModel(model_id=MODEL_ID, region_name="ap-northeast-1"),
    tools=[create_signature],
    system_prompt="あなたはメール署名を作成するアシスタントです。ユーザから受け取った情報をもとに create_signature ツールを呼び出し、結果をそのまま提示してください。",
)


@app.entrypoint
def invoke(payload):
    prompt = payload.get("prompt", "田中太郎(開発部 エンジニア、tanaka@example.com)のメール署名を作って")
    result = agent(prompt)
    return {"result": str(result)}


if __name__ == "__main__":
    app.run()

3. コードの解説

コードを解説します。前セクションからの変更点は create_signature の docstring の1箇所のみなので、その部分を抜粋して見ていきます。

    """ユーザからメール署名の作成を依頼されたときに使ってください。氏名・部署名・役職・メールアドレスを受け取り、所定のフォーマットのメール署名を返します。会社名と代表電話番号は Runtime 側で自動的に付与されるため、ユーザに問い合わせる必要はありません。
    """

docstring の1文目に「ユーザからメール署名の作成を依頼されたときに使ってください」と、ツールを呼ぶべきシーンを明示しました。これにより、モデルは「メール署名を作って」というユーザ発話に対して、迷わず create_signature を選ぶようになります。「会社名と代表電話番号は Runtime 側で自動的に付与されるため、ユーザに問い合わせる必要はありません」と書き添えることで、モデルが「会社名も聞いた方がいいですか?」といった余計な確認質問を返すのも防げます。

    Args:
        name: 氏名(例: '田中太郎')
        department: 部署名(例: '開発部')
        position: 役職(例: 'エンジニア')
        email: メールアドレス(例: 'tanaka@example.com')

Args: セクションには各引数の意味と実例を並べました。特にメールアドレスのような形式が決まっている値では、'tanaka@example.com' のような例を1つ示すことで、モデルがユーザ入力から引数を抽出する際の判断精度が安定します。

4. 動作確認

agentcore dev は起動したままなので、main.py を保存するとローカルの Python 仮想環境上で自動的に反映されます。Agent Inspectorのチャット欄に、以下の質問を送ってみます。

鈴木花子(営業部 マネージャー、suzuki@example.com)の署名を作成してください

前回と同じ形式の署名が、鈴木花子の情報で組み立てられて返れば、ツール呼び出しが正しく機能しています。Tracesタブで create_signature の引数(name='鈴木花子', department='営業部', position='マネージャー', email='suzuki@example.com')が正しく渡されていることも確認できます。

なお、今回のように 入力の4項目が揃っていて・ツールが1つしかない シンプルなケースでは、前セクションの最小 docstring のままでも同じ結果が返ります。今回強化した docstring が効いてくるのは、ツールが複数あって選択判断が必要・入力が曖昧で引数抽出の精度が要る・モデルに余計な確認質問をさせたくない といった、実運用で普通に発生する状況です。

エージェントがツールを呼ぶかどうか、どんな引数で呼ぶかは、モデルが ツールに添えられた説明文(今回は docstring)を読んで判断 しています。この原則は Strands の @tool でも、MCP プロトコルでツールを公開する場合でも同じで、モデルはツールごとの description を読んでツール選択と引数抽出を行います。ツールがうまく呼ばれない・引数がずれるといったときは、実装コードよりも先に説明文の書き方を工夫するのが最も効きます。MCP サーバとしてツールを公開する側の話は、後の章 AgentCoreで自作アプリケーションのAI操作基盤を作ろう で扱います。