ツール呼び出し
ここでは、モデルが外部のツール(関数)を呼び出しながら回答を組み立てるエージェント的な仕組みを扱います。基本のツール呼び出しループを実装したうえで、ツール実行が失敗したときのハンドリングを追加します。ツール呼び出しループの実装自体は、モデルが1ターンで複数ツールを同時に要求してくる並列呼び出しにも最初から対応しています。
このグループの各セクションでは、Lambda 関数として以下2つのツールを持たせた実装を組み立てます。
| ツール名 | 役割 |
|---|---|
create_signature |
氏名・部署名・役職・メールアドレスを受け取り、Lambda 側で固定の会社名と代表電話番号をくっつけた独自フォーマットのメール署名を返す |
read_fortune |
生年月日(YYYY-MM-DD)を受け取り、その日の運勢・ラッキーカラー・ラッキーナンバーを所定のフォーマットで返す(占い自体は Lambda 側で決めた適当なロジック) |
例えば「田中太郎(開発部 エンジニア、tanaka@example.com)のメール署名を作って」と聞くと、モデルはcreate_signatureを呼び出し、Lambda 側の会社名(DevOps株式会社)と代表電話番号(03-1234-5678)が付いた署名を返してくれます。同じように「1990年5月10日生まれの人の運勢を占って」と聞くと、モデルはread_fortuneを呼び出し、Lambda 側の占いロジックの結果をそのまま渡してくれます。どちらも「Lambda 側が持っている値」がモデル自身には見えないため、応答にその値が含まれていることが「ツールが実際に呼ばれた証拠」になります。zxw
1. ツール呼び出し
1.1 ツール呼び出しの概要
AIエージェントは、モデルが外部のツール(関数)を呼び出しながら回答を組み立てる仕組みです。
モデルは「今の情報だけでは答えられない」と判断すると、使えるツールの中から適切なものを選び、引数と一緒に呼び出しを要求してきます。エージェント側は要求されたツールを実行し、結果をモデルに返します。このツール呼び出し要求→実行→結果を返すというやり取りが完了するまでループを回すのが、エージェントの中核ロジックです。
1.2 Lambdaのコード変更
index.pyを以下の内容に置き換えます。1回のLambda呼び出しの中で完結する形にしていて、ツール定義と run_tool 関数、そして「モデルがツール呼び出しを要求してきたら実行して結果を返す」を繰り返すループを組んだ形です。
import datetime
import os
import boto3
MODEL_ID = os.environ["MODEL_ID"]
REGION = "ap-northeast-1"
bedrock = boto3.client("bedrock-runtime", region_name=REGION)
COMPANY_NAME = "DevOps株式会社"
COMPANY_PHONE = "03-1234-5678"
TOOLS = [
{
"toolSpec": {
"name": "create_signature",
"description": "氏名・部署名・役職・メールアドレスを受け取り、所定のフォーマットのメール署名を返します。会社名と代表電話番号は Lambda 側で自動的に付与されます。",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {"type": "string", "description": "氏名"},
"department": {"type": "string", "description": "部署名"},
"title": {"type": "string", "description": "役職"},
"email": {"type": "string", "description": "メールアドレス"},
},
"required": ["name", "department", "title", "email"],
}
},
}
},
{
"toolSpec": {
"name": "read_fortune",
"description": "生年月日から、その人の今日の運勢・ラッキーカラー・ラッキーナンバーを所定のフォーマットで返します。",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"birthday": {
"type": "string",
"description": "生年月日(YYYY-MM-DD 形式)",
}
},
"required": ["birthday"],
}
},
}
},
]
FORTUNES = ["大吉", "中吉", "吉", "末吉", "小吉"]
LUCKY_COLORS = ["ゴールド", "エメラルドグリーン", "ロイヤルブルー", "ラベンダー", "コーラルピンク"]
LUCKY_NUMBERS = [7, 3, 8, 2, 5]
def run_tool(name: str, params: dict) -> str:
if name == "create_signature":
return (
"━━━━━━━━━━━━━━━━━━━━━━\n"
f"【{params.get('name', '')}】{COMPANY_NAME} {params.get('department', '')} {params.get('title', '')}\n"
f"Email: {params.get('email', '')}\n"
f"Tel: {COMPANY_PHONE}\n"
"━━━━━━━━━━━━━━━━━━━━━━"
)
if name == "read_fortune":
birthday = params.get("birthday", "")
try:
year, month, day = (int(x) for x in birthday.split("-"))
datetime.date(year, month, day)
except ValueError:
return "存在しない日付、または無効な形式です(YYYY-MM-DD 形式で指定してください)"
index = (year + month + day) % 5
return (
"★★★ 誕生日占い ★★★\n"
f"生年月日: {birthday}\n"
f"今日の運勢: {FORTUNES[index]}\n"
f"ラッキーカラー: {LUCKY_COLORS[index]}\n"
f"ラッキーナンバー: {LUCKY_NUMBERS[index]}\n"
"★★★★★★★★★★★★"
)
return f"Unknown tool: {name}"
def lambda_handler(event, context):
question = event["question"]
messages = [{"role": "user", "content": [{"text": question}]}]
for _ in range(5):
response = bedrock.converse(
modelId=MODEL_ID,
messages=messages,
toolConfig={"tools": TOOLS},
)
output_message = response["output"]["message"]
messages.append(output_message)
if response["stopReason"] != "tool_use":
answer = "".join(
block["text"] for block in output_message["content"] if "text" in block
)
return {"answer": answer}
tool_results = []
for block in output_message["content"]:
if "toolUse" not in block:
continue
tool_use = block["toolUse"]
result = run_tool(tool_use["name"], tool_use.get("input", {}))
tool_results.append(
{
"toolResult": {
"toolUseId": tool_use["toolUseId"],
"content": [{"text": result}],
}
}
)
messages.append({"role": "user", "content": tool_results})
return {"answer": "ツール呼び出しが上限に達しました"}
貼り付けたら「Deploy」を押して反映します。
1.3 コードの解説
TOOLS = [
{
"toolSpec": {
"name": "create_signature",
"description": "氏名・部署名・役職・メールアドレスを受け取り、所定のフォーマットのメール署名を返します。会社名と代表電話番号は Lambda 側で自動的に付与されます。",
...
}
},
...
]
TOOLSはモデルに提示するツール定義の配列です。nameはモデルがツールを呼び出すときに指定する識別子、descriptionはモデルがそのツールをいつ使うか判断する材料になります。inputSchemaはJSON Schema形式で、モデルが渡してくる引数の型を宣言します。
モデルは description に書かれた自然言語の説明を読んで「ユーザの質問がこのツールに合うか」を判断するため、description の書き方がツール呼び出しの精度に直結します。例えば create_signature の description に「氏名・部署名・役職・メールアドレスを受け取り、所定のフォーマットのメール署名を返します」と書いてあることで、モデルは「田中太郎のメール署名を作って」のような質問に対してこのツールを選ぶようになります。ツールを増やしていくときは、それぞれの description が「どんなときに呼ばれるべきか」を過不足なく説明できているかを意識するのがポイントです。
COMPANY_NAME = "DevOps株式会社"
COMPANY_PHONE = "03-1234-5678"
会社名と代表電話番号は、Lambda 側の定数として持っています。実運用では「同じ会社の従業員なら共通で使う情報」に該当し、ユーザ側(呼び出し元)から毎回渡してもらう必要のない値をここで固定します。モデルはこの定数を見ることができないので、応答にこの値が含まれていれば create_signature ツールが実際に呼ばれた証拠になります。
def run_tool(name: str, params: dict) -> str:
if name == "create_signature":
return (
"━━━━━━━━━━━━━━━━━━━━━━\n"
f"【{params.get('name', '')}】{COMPANY_NAME} {params.get('department', '')} {params.get('title', '')}\n"
...
f"Tel: {COMPANY_PHONE}\n"
...
)
if name == "read_fortune":
...
run_toolは、モデルが呼び出しを要求してきたツールを実行するローカル関数です。関数名や書き方は自由ですが、以下のように TOOLS 定義とペアになるようにインタフェースを組みます。
- 第1引数
name: モデルが呼び出しを要求したツールの名前。TOOLS[].toolSpec.nameの値(今回なら"create_signature"または"read_fortune")がそのまま渡ってくる - 第2引数
params: モデルが渡してきた引数の辞書。TOOLS[].toolSpec.inputSchemaで宣言した JSON Schema に沿った形(例:create_signatureなら{"name": "田中太郎", "department": "開発部", ...})で渡ってくる - 返り値: ツール実行の結果を文字列で返す。この文字列がそのまま後続の
toolResult.content[].textとしてモデルに戻される
関数本体では name で分岐して、TOOLS で定義した各ツールに対応する処理を実装します。TOOLS に新しいツールを追加したら、run_tool にも同じ name の分岐を1つ足す、というのが基本的なメンテナンスの流れになります。create_signature の COMPANY_NAME/COMPANY_PHONE や、占いの独自ロジックのように「モデルには内容が推測できない値」を持たせておくと、後で動作確認するときに「モデルが自力で答えたのか、ツールを呼んだのか」が判別しやすくなります。
question = event["question"]
messages = [{"role": "user", "content": [{"text": question}]}]
このセクションでは Lambda 呼び出しごとに新しい会話を始める前提にしていて、messages はユーザ発言だけを含んだ状態から開始します。呼び出しをまたぐ会話履歴を扱いたい場合は、「マルチターン会話」セクションのように session_id を受け取って DynamoDB から履歴を復元する形に変えます。
for _ in range(5):
エージェントの中核であるツール呼び出しループの入口です。range(5) で上限回数を設けているのは、モデルが延々とツールを呼び出し続けて課金・実行時間が想定外に膨らむことを防ぐためです。実運用では、要件に応じて上限値を調整します。
response = bedrock.converse(
modelId=MODEL_ID,
messages=messages,
toolConfig={"tools": TOOLS},
)
converse の呼び出しで toolConfig に TOOLS を渡すことで、モデルに使えるツール一覧を提示します。
output_message = response["output"]["message"]
messages.append(output_message)
モデル応答を取り出し、messages に積みます。ループ内でツール呼び出しと結果のやり取りを続けるため、次のループの converse 呼び出しでも同じ messages を参照できるようにしておきます。
if response["stopReason"] != "tool_use":
answer = "".join(
block["text"] for block in output_message["content"] if "text" in block
)
return {"answer": answer}
Converse のレスポンスに含まれる stopReason が tool_use 以外(end_turn など)のときは、モデルが最終回答を返した合図です。テキストを取り出して呼び出し側に返し、ループを抜けます。
tool_results = []
for block in output_message["content"]:
if "toolUse" not in block:
continue
tool_use = block["toolUse"]
result = run_tool(tool_use["name"], tool_use.get("input", {}))
tool_results.append(
{
"toolResult": {
"toolUseId": tool_use["toolUseId"],
"content": [{"text": result}],
}
}
)
stopReason が tool_use のときは、モデルがツール実行を要求している状態です。応答に含まれる toolUse ブロックごとに run_tool を呼び出し、実行結果を toolResult ブロックとして tool_results に詰めていきます。toolUseId はモデルの要求と実行結果を紐づけるためのIDで、モデル側の要求に付いているものをそのまま返します。この for block in output_message["content"]: の書き方は、モデルが1つの応答に複数の toolUse ブロックを詰めて返してきた場合(=並列ツール呼び出し)にもそのまま対応します。
messages.append({"role": "user", "content": tool_results})
まとめた tool_results を user ロールの新しいメッセージとして messages に積みます。次のループでこの実行結果をモデルに渡すことで、モデルはツールの実行結果を踏まえた次のアクション(別のツール呼び出し、または最終回答)を決められます。
| 💡 ポイント |
|---|
モデルは互いに独立して実行できるツール呼び出しを、1ターンで 並列にまとめて 要求してくることがあります。例えば「田中太郎(開発部 エンジニア、tanaka@example.com)のメール署名を作って、あと 1990年5月10日 の運勢も占って」のような複合クエリを投げると、create_signature と read_fortune が1ターンで両方要求され、応答テキストにも両方の結果が含まれる形になります。逆に「まず在庫を検索して、見つかった商品の詳細をもう1つのツールで取ってくる」のように前の結果を踏まえて次を決める必要があるケースでは、モデルが自動的にターンを分けて要求します。並列にするか直列にするかの判断はモデル側が状況に応じて自動で行い、実装側は上の for ループのように「1ターンに複数の toolUse が来ても回せる形」で書いておけば、どちらのパターンも同じコードで扱えます。 |
1.4 動作確認
「テスト」タブを開き、以下の内容で新しいテストイベントを作成します。イベント名は任意(例: signature)です。質問文にはユーザ側で持っている情報(氏名・部署名・役職・メール)だけを渡し、会社名や代表電話番号は Lambda 側に任せます。
{
"question": "田中太郎(開発部 エンジニア、tanaka@example.com)のメール署名を作って"
}
AI の応答は毎回まったく同じにはならないので、以下は一例です。以下のポイントが押さえられていれば成功です(モデルは ━━━ の罫線や 【】 の飾りを絵文字入りの Markdown に置き換えて返すことがあるので、値そのもの で判定します)。
- 質問で渡していない
DevOps株式会社(会社名)が応答に含まれる(Lambda 側の定数から取り出したもの) - 質問で渡していない
03-1234-5678(代表電話番号)が応答に含まれる(Lambda 側の定数から取り出したもの)
{
"answer": "以下のメール署名を作成しました。\n\n━━━━━━━━━━━━━━━━━━━━━━\n【田中太郎】DevOps株式会社 開発部 エンジニア\nEmail: tanaka@example.com\nTel: 03-1234-5678\n━━━━━━━━━━━━━━━━━━━━━━\n\nそのままメール本文の末尾に貼り付けてご利用ください。"
}
会社名と代表電話番号はユーザから渡していないので、モデルには「本来知りようがない値」です。それが応答に正しく DevOps株式会社 と 03-1234-5678 として含まれていれば、モデルが自力で作った署名ではなく、Lambda 上の create_signature ツールを実際に呼び出して結果を受け取っている、と明確に判断できます。
続けて、以下のテストイベントで占いツールも動作するかを確認します。
{
"question": "1990年5月10日生まれの人の運勢を占って"
}
このターンでは、以下のポイントが押さえられていれば成功です(モデルは ★★★ の枠を絵文字入りの見た目に置き換えたり、独自の Markdown 装飾に整形することがあるので、値そのもの で判定します)。
- 応答に「大吉/中吉/吉/末吉/小吉」のいずれかが含まれる
- 応答に「ゴールド/エメラルドグリーン/ロイヤルブルー/ラベンダー/コーラルピンク」のいずれかが含まれる
- 応答に
7 / 3 / 8 / 2 / 5のいずれかがラッキーナンバーとして含まれる - 上の3つが Lambda 側の同一インデックスの値になっている(1990-05-10 なら
(1990+5+10) % 5 = 0なので 大吉 + ゴールド + 7 の組み合わせ)
Lambda 側の並びは任意で決めた組み合わせなので、モデルが自力で「大吉 + ゴールド + 7」といったピンポイントの組み合わせを正解として返すことはまずありません。この組み合わせで返ってきていれば、read_fortune ツールが実際に呼ばれた証拠になります。
{
"answer": "1990年5月10日生まれの方の今日の運勢は以下の通りです。\n\n★★★ 誕生日占い ★★★\n生年月日: 1990-05-10\n今日の運勢: 大吉\nラッキーカラー: ゴールド\nラッキーナンバー: 7\n★★★★★★★★★★★★\n\n素敵な一日をお過ごしください!"
}
2. エラーハンドリング
2.1 エラーハンドリングの概要
前セクションの run_tool は、ツール実行が失敗しても文字列で「エラー」を返すだけで、モデル側にはそれが「エラーなのか正常な結果なのか」区別できません。実運用ではツールが外部APIやDBを叩くことが多く、ネットワーク断や無効なパラメータで失敗するのは日常的です。
Converse APIの toolResult ブロックには status フィールドがあり、"error" を指定するとモデルに「このツール実行は失敗した」と明示的に伝えられます。モデルはそれを踏まえて、別のパラメータで再挑戦したり、ユーザに事情を説明したりできます。
2.2 Lambdaのコード変更
前セクションの index.py に、run_tool を成功/失敗のペア((status, content) タプル)で返す形にし、ループ側で toolResult の status に反映する変更を加えます。index.py を以下の内容に置き換えます。
import datetime
import os
import boto3
MODEL_ID = os.environ["MODEL_ID"]
REGION = "ap-northeast-1"
bedrock = boto3.client("bedrock-runtime", region_name=REGION)
COMPANY_NAME = "DevOps株式会社"
COMPANY_PHONE = "03-1234-5678"
TOOLS = [
{
"toolSpec": {
"name": "create_signature",
"description": "氏名・部署名・役職・メールアドレスを受け取り、所定のフォーマットのメール署名を返します。会社名と代表電話番号は Lambda 側で自動的に付与されます。",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {"type": "string", "description": "氏名"},
"department": {"type": "string", "description": "部署名"},
"title": {"type": "string", "description": "役職"},
"email": {"type": "string", "description": "メールアドレス"},
},
"required": ["name", "department", "title", "email"],
}
},
}
},
{
"toolSpec": {
"name": "read_fortune",
"description": "生年月日から、その人の今日の運勢・ラッキーカラー・ラッキーナンバーを所定のフォーマットで返します。",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"birthday": {
"type": "string",
"description": "生年月日(YYYY-MM-DD 形式)",
}
},
"required": ["birthday"],
}
},
}
},
]
FORTUNES = ["大吉", "中吉", "吉", "末吉", "小吉"]
LUCKY_COLORS = ["ゴールド", "エメラルドグリーン", "ロイヤルブルー", "ラベンダー", "コーラルピンク"]
LUCKY_NUMBERS = [7, 3, 8, 2, 5]
def run_tool(name: str, params: dict) -> tuple[str, str]:
try:
if name == "create_signature":
signature = (
"━━━━━━━━━━━━━━━━━━━━━━\n"
f"【{params.get('name', '')}】{COMPANY_NAME} {params.get('department', '')} {params.get('title', '')}\n"
f"Email: {params.get('email', '')}\n"
f"Tel: {COMPANY_PHONE}\n"
"━━━━━━━━━━━━━━━━━━━━━━"
)
return ("success", signature)
if name == "read_fortune":
birthday = params.get("birthday", "")
try:
year, month, day = (int(x) for x in birthday.split("-"))
datetime.date(year, month, day)
except ValueError:
return ("error", "存在しない日付、または無効な形式です(YYYY-MM-DD 形式で指定してください)")
index = (year + month + day) % 5
result = (
"★★★ 誕生日占い ★★★\n"
f"生年月日: {birthday}\n"
f"今日の運勢: {FORTUNES[index]}\n"
f"ラッキーカラー: {LUCKY_COLORS[index]}\n"
f"ラッキーナンバー: {LUCKY_NUMBERS[index]}\n"
"★★★★★★★★★★★★"
)
return ("success", result)
return ("error", f"Unknown tool: {name}")
except Exception as e:
return ("error", f"ツール実行中にエラーが発生しました: {e}")
def lambda_handler(event, context):
question = event["question"]
messages = [{"role": "user", "content": [{"text": question}]}]
for _ in range(5):
response = bedrock.converse(
modelId=MODEL_ID,
messages=messages,
toolConfig={"tools": TOOLS},
)
output_message = response["output"]["message"]
messages.append(output_message)
if response["stopReason"] != "tool_use":
answer = "".join(
block["text"] for block in output_message["content"] if "text" in block
)
return {"answer": answer}
tool_results = []
for block in output_message["content"]:
if "toolUse" not in block:
continue
tool_use = block["toolUse"]
status, content = run_tool(tool_use["name"], tool_use.get("input", {}))
tool_results.append(
{
"toolResult": {
"toolUseId": tool_use["toolUseId"],
"content": [{"text": content}],
"status": status,
}
}
)
messages.append({"role": "user", "content": tool_results})
return {"answer": "ツール呼び出しが上限に達しました"}
貼り付けたら「Deploy」を押して反映します。
2.3 コードの解説
def run_tool(name: str, params: dict) -> tuple[str, str]:
try:
if name == "create_signature":
signature = (...)
return ("success", signature)
if name == "read_fortune":
birthday = params.get("birthday", "")
try:
year, month, day = (int(x) for x in birthday.split("-"))
datetime.date(year, month, day)
except ValueError:
return ("error", "存在しない日付、または無効な形式です(YYYY-MM-DD 形式で指定してください)")
...
return ("success", result)
return ("error", f"Unknown tool: {name}")
except Exception as e:
return ("error", f"ツール実行中にエラーが発生しました: {e}")
run_tool の返り値を (status, content) のタプルに変えました。成功時は ("success", 結果文字列)、失敗時は ("error", エラーメッセージ) を返す形に統一しています。read_fortune の内側で日付の妥当性チェックを行い、想定外の例外は関数全体を囲む外側の try/except で捕まえて ("error", ...) で返す構造にしています。
status, content = run_tool(tool_use["name"], tool_use.get("input", {}))
tool_results.append(
{
"toolResult": {
"toolUseId": tool_use["toolUseId"],
"content": [{"text": content}],
"status": status,
}
}
)
toolResult ブロックに status フィールドを追加しました。"success" か "error" を指定でき、"error" の場合はモデル側で「このツール呼び出しは失敗した」と認識してくれます。
2.4 動作確認
以下のテストイベントを実行します。read_fortune ツールに、あえて存在しない日付(2月30日)を含む質問を投げます。
{
"question": "1990年2月30日生まれの人の運勢を占って"
}
AI の応答は毎回まったく同じにはならないので、以下のポイントが押さえられていれば成功です。
- モデルが「2月30日は存在しないので占えない」といった内容を返し、正しい生年月日を問い返す(失敗を踏まえてユーザに事情を説明するリカバリ)、あるいは近い日付(例:
1990-02-28)で再度read_fortuneを呼び出してリトライして通常の占い結果を返してくる - もしモデルが
1990-02-30を「そのまま解釈して普通に占ってくれた」ような応答を返した場合は、モデルがtoolResult.status="error"を認識できずにエラー結果を無視している状態です(ツール呼び出しとerror返却自体は行われているものの、モデルがそれを踏まえた振る舞いに切り替えていない)
{
"answer": "申し訳ありません。2月30日は実際には存在しない日付のため、占うことができませんでした。\n\nもしよろしければ、正しい生年月日(例: 1990年2月28日 など)をお教えいただけますか?あらためて占わせていただきます。"
}
toolResult.status に "error" を明示することで、モデルが失敗を認識して自ら別のアプローチ(ユーザへの問い返し/別パラメータでのリトライ)に切り替えていることが確認できます。
| 💡 ポイント |
|---|
今回は toolResult.status に "error" を明示的に載せてモデルに「これは失敗した呼び出しだ」と直接伝える形を取りましたが、モデルの精度向上とともに、status を付けなくてもツールの返却テキスト(例: "存在しない日付、または無効な形式です...")を自然言語のエラー文として読み取り、自らリカバリしてくれる場面が増えてきています。とはいえ、明示的な status を付けるほうがプロトコルとして確実に「失敗」が伝わり、モデルのバージョン差にも影響を受けにくいメリットがあるので、実運用では今の実装のように明示するのが安全です。今後のモデル進化次第では、status を意識せずとも自然にリカバリが成立するケースがさらに広がっていく可能性があります。 |
| 💡 ポイント |
|---|
このグループでは仕組みを体感するために TOOLS 定義・run_tool・ツール呼び出しループを自前で組んでいますが、AgentCore を使うと大きく効率化できます。AgentCore Harness の tools 宣言 では config にツールを列挙するだけで、ツール呼び出し・認証・結果ハンドリング・ループの実行を AgentCore が代行してくれます。AgentCore Gateway は Lambda・REST API・既存 MCP サーバを MCP 準拠のツールに変換して統一エンドポイントで公開でき、run_tool の if 分岐が肥大化する問題を根本から解消できます。加えて AgentCore Code Interpreter を使えば、独自ツールを書かなくてもサンドボックス化された Python 実行環境がそのまま使えるので、動的な計算や小さなスクリプト実行を任せられます。AgentCore Gateway で Lambda 関数などをツールとして公開する具体的な流れは AgentCore Gatewayでツールを統合公開しよう で扱います。 |