kb-agentcore-identity

AgentCore Identity（アウトバウンド認証）

先に AWS Agent Toolkit を当たる。 この領域は aws-agents:agents-connect（アウトバウンド認証を担当） がカバーする。 このスキルは Toolkit の代わりではなく、公式どおりにやったのに動かなかったときの原因を貯めておく場所として使う。 Toolkit 側が同じ内容をカバーしたと分かった項目は、このスキルから削る（両方に置くと、更新されるのは公式側だけなのでこちらが古い情報の発生源になる）。

Bedrock AgentCore Identity を使った外部サービスとの OAuth2 連携パターンを記録する。

@requires_access_token と @tool は必ず分離する

@tool と @requires_access_token を同じ関数にスタックすると、パラメータ解析が干渉してツールが正しく動作しない（エージェントが access_token を入力パラメータとして要求してしまう）。

# ❌ NG: デコレータをスタック → パラメータ干渉
@tool
@requires_access_token(provider_name="my-provider", scopes=[...], auth_flow="USER_FEDERATION")
async def get_pages(*, access_token: str):
    ...

# ✅ OK: トークン取得とツールを分離
@requires_access_token(provider_name="my-provider", scopes=[...], auth_flow="USER_FEDERATION",
    on_auth_url=lambda url: print(f"認可URL: {url}"),
    callback_url="http://localhost:9090/oauth2/callback")
def get_token(access_token: str = ""):
    return access_token

@tool
def get_pages():
    """外部APIのページ一覧を取得する"""
    token = get_token()
    response = httpx.get("https://api.example.com/pages",
        headers={"Authorization": f"Bearer {token}"})
    return response.json()

内部関数パターン（推奨：よりコンパクト）

トークン取得関数をツール内部に定義するとファイルを分けずに済む。公式サンプル（01_outbound.py）もこの方式：

@tool
def add_calendar_event(
    summary: str,
    start_datetime: str,
    end_datetime: str,
    description: str = "",
):
    """Google Calendarに予定を追加する。"""

    @requires_access_token(
        provider_name=PROVIDER_NAME,
        scopes=["https://www.googleapis.com/auth/calendar"],
        auth_flow="USER_FEDERATION",
        on_auth_url=lambda url: print(f"認証URL: {url}"),
        callback_url="http://localhost:9090/oauth2/callback",
    )
    def call_api(access_token: str = ""):
        event = {
            "summary": summary,
            "start": {"dateTime": start_datetime, "timeZone": "Asia/Tokyo"},
            "end": {"dateTime": end_datetime, "timeZone": "Asia/Tokyo"},
        }
        resp = requests.post(
            "https://www.googleapis.com/calendar/v3/calendars/primary/events",
            headers={"Authorization": f"Bearer {access_token}"},
            json=event,
        )
        return resp.json()

    result = call_api()
    if "error" in result:
        return f"失敗: {result['error']['message']}"
    return f"登録完了: {result.get('summary')}"