Claude API の『messages.X.role must alternate』を1分で直す — 400 invalid_request_error の典型パターン

# ✅ 正しい構造
messages = [
    {"role": "user", "content": "こんにちは"},
    {"role": "assistant", "content": "こんにちは、お手伝いします"},
    {"role": "user", "content": "天気を教えて"},
]

# ❌ 失敗例: user が2連続
messages = [
    {"role": "user", "content": "こんにちは"},
    {"role": "user", "content": "天気を教えて"},  # ここで違反
]
 
# ✅ 修正例: 連続した user 発言は1つにまとめる
messages = [
    {"role": "user", "content": "こんにちは\n\n天気を教えて"},
]

def append_message(messages, role, content):
    """role が連続しないように吸収するヘルパー"""
    if messages and messages[-1]["role"] == role:
        # 同じ role なら content を結合する
        last = messages[-1]
        if isinstance(last["content"], str):
            last["content"] = f"{last['content']}\n\n{content}"
        else:
            # content が list（tool_use 等）の場合は別の戦略を取る
            last["content"].append({"type": "text", "text": content})
    else:
        messages.append({"role": role, "content": content})
    return messages

# ❌ 失敗例: tool_result を返さずに次の user 発言を挟んでいる
messages = [
    {"role": "user", "content": "東京の天気を教えて"},
    {"role": "assistant", "content": [
        {"type": "tool_use", "id": "toolu_01ABC", "name": "get_weather", "input": {"city": "Tokyo"}}
    ]},
    {"role": "user", "content": "ありがとう"},  # ← tool_result を飛ばしている
]

# ✅ 修正例: tool_use と対応する tool_result を返す
messages = [
    {"role": "user", "content": "東京の天気を教えて"},
    {"role": "assistant", "content": [
        {"type": "tool_use", "id": "toolu_01ABC", "name": "get_weather", "input": {"city": "Tokyo"}}
    ]},
    {"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": "toolu_01ABC", "content": "晴れ、24度"}
    ]},
    {"role": "assistant", "content": "東京は今、晴れで24度ですね。"},
]

# ❌ 失敗例: ナイーブな先頭削除
def trim_history(messages, max_len=20):
    return messages[-max_len:]

# ✅ 修正例: tool ペアを尊重した切り詰め
def trim_history_safely(messages, max_len=20):
    if len(messages) <= max_len:
        return messages
 
    # 末尾から max_len 件を取る候補を作成
    start_idx = len(messages) - max_len
 
    # 切断面が tool_use を含む assistant ターンの直後なら、もう1つ前から取る
    while start_idx > 0:
        msg = messages[start_idx]
        if msg["role"] == "user" and isinstance(msg.get("content"), list):
            has_tool_result = any(
                isinstance(b, dict) and b.get("type") == "tool_result"
                for b in msg["content"]
            )
            if has_tool_result:
                # この user ターンは前の tool_use の結果なので、ペアごと取り直す
                start_idx -= 1
                continue
        break
 
    # 必ず user で開始するように調整
    while start_idx < len(messages) and messages[start_idx]["role"] != "user":
        start_idx += 1
 
    return messages[start_idx:]

def validate_messages(messages):
    """Claude Messages API に送る前の最終チェック。
    違反を見つけたら詳細なエラーを raise する。"""
    if not messages:
        raise ValueError("messages が空です")
 
    if messages[0]["role"] != "user":
        raise ValueError(f"最初のメッセージは user である必要があります（実際: {messages[0]['role']}）")
 
    # 1. 交互ルールのチェック
    for i in range(1, len(messages)):
        if messages[i]["role"] == messages[i - 1]["role"]:
            raise ValueError(
                f"messages[{i}] と messages[{i-1}] の role が同じです: '{messages[i]['role']}'"
            )
 
    # 2. tool_use と tool_result の対応チェック
    for i, msg in enumerate(messages):
        if msg["role"] == "assistant" and isinstance(msg.get("content"), list):
            tool_use_ids = {
                b["id"] for b in msg["content"]
                if isinstance(b, dict) and b.get("type") == "tool_use"
            }
            if not tool_use_ids:
                continue
            # 直後の user ターンを確認
            if i + 1 >= len(messages) or messages[i + 1]["role"] != "user":
                raise ValueError(f"messages[{i}] の tool_use に対応する user ターンがありません")
            next_content = messages[i + 1].get("content")
            if not isinstance(next_content, list):
                raise ValueError(f"messages[{i+1}] は tool_result を含む list である必要があります")
            result_ids = {
                b["tool_use_id"] for b in next_content
                if isinstance(b, dict) and b.get("type") == "tool_result"
            }
            missing = tool_use_ids - result_ids
            if missing:
                raise ValueError(f"messages[{i}] の tool_use_id {missing} に対応する tool_result が不足しています")
 
    return True
 
# 使い方
try:
    validate_messages(messages)
    response = client.messages.create(model="claude-sonnet-4-6", messages=messages, max_tokens=1024)
except ValueError as e:
    print(f"[配列の不整合] {e}")