エラーハンドリング

実運用のエージェントでは、ユーザから不正な入力が来る(メールアドレスの形式が壊れている、必須情報が抜けている等)、外部APIが遅延・エラーを返す、モデル呼び出し自体が失敗する、といったエラーが必ず発生します。

1. 概要

実運用のエージェントでは、ユーザから不正な入力が来る(メールアドレスの形式が壊れている、必須情報が抜けている等)、外部APIが遅延・エラーを返す、モデル呼び出し自体が失敗する、といったエラーが必ず発生します。ツール内で例外を投げっぱなしにすると、Runtime に伝播して500系エラーになり、クライアント側には「何かが失敗した」しか届かず、ユーザは何を直せばよいか分からない状態になります。

これを避けるには、ツール内で try/except して、エラーの説明文を戻り値として返すのが基本パターンです。モデルは戻り値を「ツールの結果」として受け取り、「メールアドレスの形式が正しくないので、name@example.com のような形式で提供してください」といった、ユーザ向けの自然な応答へ組み立て直してくれます。@app.entrypoint 側にも同じ考え方で try/except を入れておくと、想定外の例外に対してもクライアントへ意味のあるレスポンスを返せます。

現状の create_signature は、無効なメールアドレスが渡されても検証せず、そのまま署名に埋め込んでしまいます。ここでは入力検証と例外処理を加えて、不正入力に対しても意味のある応答を返す形に改善します。

2. コードの書き換え

main.py を、以下の内容で全体を置き換えて保存します。前セクションからの変更は、create_signature にメールアドレス形式チェックと try/except を追加、invoke にも try/except を追加した2箇所です。

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')
    """
    try:
        if "@" not in email or "." not in email.split("@")[-1]:
            return f"エラー: メールアドレス '{email}' の形式が正しくありません。'name@example.com' のような形式で指定してください。"
        return (
            "━━━━━━━━━━━━━━━━━━━━━━\n"
            f"【{name}】{COMPANY_NAME} {department} {position}\n"
            f"Email: {email}\n"
            f"Tel:   {COMPANY_TEL}\n"
            "━━━━━━━━━━━━━━━━━━━━━━"
        )
    except Exception as e:
        return f"メール署名の作成中に予期しないエラーが発生しました: {e}"


agent = Agent(
    model=BedrockModel(
        model_id=MODEL_ID,
        region_name="ap-northeast-1",
        temperature=0.0,
        max_tokens=512,
    ),
    tools=[create_signature],
    system_prompt=(
        "あなたはメール署名を作成するアシスタントです。以下の手順で回答してください。\n"
        "1. ユーザの依頼から氏名・部署名・役職・メールアドレスの4項目を抽出する\n"
        "2. 4項目が揃っていれば create_signature ツールを呼び出す\n"
        "3. ツールの結果をそのまま提示する。挨拶文や『以下のとおりです』などの前置き・後書きは付けない\n"
        "4. 4項目のいずれかが揃わなければ、不足している項目だけを箇条書きでユーザに1度確認する"
    ),
)


@app.entrypoint
async def invoke(payload):
    try:
        prompt = payload.get("prompt", "田中太郎(開発部 エンジニア、tanaka@example.com)のメール署名を作って")
        async for event in agent.stream_async(prompt):
            if "data" in event:
                yield event["data"]
    except Exception as e:
        yield f"エージェント実行中にエラーが発生しました: {e}"


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

3. コードの解説

コードを解説します。前セクションからの変更点は create_signature と invoke の2箇所なので、順に抜粋して見ていきます。

    try:
        if "@" not in email or "." not in email.split("@")[-1]:
            return f"エラー: メールアドレス '{email}' の形式が正しくありません。'name@example.com' のような形式で指定してください。"
        return (
            "━━━━━━━━━━━━━━━━━━━━━━\n"
            f"【{name}】{COMPANY_NAME} {department} {position}\n"
            f"Email: {email}\n"
            f"Tel:   {COMPANY_TEL}\n"
            "━━━━━━━━━━━━━━━━━━━━━━"
        )
    except Exception as e:
        return f"メール署名の作成中に予期しないエラーが発生しました: {e}"

create_signature の中で、メールアドレスの簡易的な形式チェック(@ が含まれる、@ 以降にドットが含まれる)を入れています。不正な場合はエラーの説明文を戻り値として返します。ここで例外を投げずに戻り値として返すのが重要で、モデルは戻り値を「ツールの結果」として受け取り、「メールアドレスの形式が正しくないので、name@example.com のような形式で提供してください」のようにユーザ向けの自然な応答へ組み立て直してくれます。全体を try/except Exception で包むことで、想定外の例外に対してもエラー内容を戻り値として返し、CloudWatch Logs に例外だけが残ってクライアントが無反応、といった事態を避けられます。

@app.entrypoint
async def invoke(payload):
    try:
        prompt = payload.get("prompt", "田中太郎(開発部 エンジニア、tanaka@example.com)のメール署名を作って")
        async for event in agent.stream_async(prompt):
            if "data" in event:
                yield event["data"]
    except Exception as e:
        yield f"エージェント実行中にエラーが発生しました: {e}"

invoke 側も同じ考え方で、try/except Exception で全体を包んで、想定外の例外が起きても yield でエラーメッセージをクライアントに返す形にしています。ストリーミング応答なので、yield でエラー文字列を1つ流せば、クライアント側にはそれが応答の一部として届きます。

なお、temperature=0.0 と手順化されたシステムプロンプトを持つ 近年の高度なモデルでは、ツールに不正な引数を渡す前にモデル側で気付いてユーザに確認を返すことが多く、今回追加したツール側の try/except や検証コードが実際に発火する場面は限定的です。ここでの try/except は「モデルの判断がずれたとき」「システムプロンプトを差し替えたとき」「想定外の値や外部連携の失敗が起きたとき」に備えた 保険(多層防御) としての意味合いが強いため、本ハンズオンでは動作確認は省略します。

以上のように、ユーザ入力の不正や外部連携の失敗が想定されるエージェント では、ツール内で例外を投げっぱなしにせず、try/except でエラーの説明文を戻り値として返す実装にしておくのが基本です。モデルが賢く手前で捌いてくれる現代のエージェントでも、想定外の入力・障害への備えとして欠かせない要素で、エラー文字列をモデルが自然文に整えてユーザに返す構造にしておけば、対話が破綻せずユーザに次のアクションを促せる形になります。@app.entrypoint 側にも同じ try/except を入れておけば、想定外の例外にもクライアントへ意味のあるレスポンスを返せます。