ツールの定義と説明文
エージェントに「メール署名を作る」「天気を取得する」といった具体的な能力を持たせたいとき、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操作基盤を作ろう で扱います。