Amazon Bedrock AgentCore 実践入門 — 全体像を掴むメモ¶

書籍「Amazon Bedrock AgentCore実践入門」（SBクリエイティブ、御田／熊田／森田著）のサンプルコード（リポジトリ内 agentcore-book/ ＝外部公開リポ minorun365/agentcore-book のクローン）を 一次資料に、AgentCore の全体像を「何をする部品の集まりか」というレベルで掴むための調査メモ。 llmops_basics と同じ「写経 .py を持たない概念地図」型の lecture。

実行検証はしていない。AgentCore は AWS へのデプロイ（Runtime/Memory 等はマネージド課金リソース）が前提で、ローカルの uv run 単体で完結しない章が多いため。よって本メモはサンプルコードの構造・API 名・依存から読み解いた解説であり、実出力での green 確認は伴わない（この点で rag_basics 等の「実行して実出力を貼る」メモとは性格が違う）。コードに現れた API・クラス名だけを断定形で書き、コードから読めない挙動は「〜と推測」と明示する。

調査日: 2026-07-17。バージョン・モデル ID は書籍執筆時点で固定されたもの（後述「7. バージョン・落とし穴」）。AgentCore は新しめのサービスで API が動く可能性がある。

0. 一言で（直感）¶

AgentCore ＝エージェントの「脳（推論ループ）」は Strands 等の FW に任せ、その周りの「本番運用に要る足回り」8部品を AWS マネージドで外付けする基盤。

掴ませたいのは3つの対比（＝どのレイヤの話をしているか）:

生 Bedrock API → Strands → AgentCore、の"手作業が消えていく"方向
生 Bedrock（converse ＋ツール呼び出しの while ループを自前で書く）→ Strands（Agent() 1行でその while ループが消える）→ AgentCore（その Agent を認証つきサーバに載せ、記憶・権限・観測を外付けする）。上に行くほど自前実装が減る。
Strands と AgentCore は"競合"ではなく"積む"関係（次元が違う）
Strands＝脳を書く FW（LangGraph/LangChain と同じ土俵）。AgentCore＝その脳を本番で動かす土台（ホスティング・記憶・認証・観測…）。LangGraph でエージェントを組んでいる人にとって AgentCore は "競合 FW" ではなく "その下に敷くインフラ層"。
このリポジトリで手組みした要素の"AWSマネージド版"
context_basics（記憶管理）→ Memory、guardrails_basics（権限ゲート）→ Policy、sandbox_basics（コード実行隔離）→ Built-in Code Interpreter、langfuse_basics（観測）→ Observability、eval_basics（LLM-as-judge）→ Evaluation。手で組んだものが、そのままマネージド部品として並んでいる（対応表は「5. 既存 lecture との対応」）。

一言で言い直すと: 「エージェントを書く」から先の "本番で運用する" を、AWS が8個の部品に切り出してマネージド提供したもの。

1. 3階建ての全体像（Bedrock → Strands → AgentCore）¶

書籍の構成そのものが3階建てになっている。下2階（Bedrock・Strands）でエージェントの中身を作り、3階（AgentCore の8部品）で本番運用の足回りを外付けする。

flowchart TB
    subgraph L1["① 基盤モデル層 Amazon Bedrock（第1章）"]
        BR["Bedrock Runtime<br>converse / converse_stream<br>Claude Sonnet 4.6 など"]
    end
    subgraph L2["② エージェント層 Strands Agents（第3・4章）"]
        AG["Agent 呼び出し<br>ReActループ・@tool・マルチエージェント<br>脳（推論ループ）を書く FW"]
    end
    subgraph L3["③ 本番運用層 AgentCore（第5〜13・15章／8部品）"]
        RT["Runtime<br>ホスティング"]
        MEM["Memory<br>記憶"]
        IDN["Identity<br>外部認証"]
        GW["Gateway<br>ツール集約"]
        POL["Policy<br>権限 Cedar"]
        BT["Built-in Tools<br>Browser / Code Interpreter"]
        OBS["Observability<br>OTel トレース"]
        EV["Evaluation<br>LLM-as-judge"]
    end
    BR --> AG
    AG --> RT
    RT -.-> MEM
    RT -.-> IDN
    RT -.-> GW
    GW -.-> POL
    RT -.-> BT
    RT -.-> OBS
    RT -.-> EV

① Bedrock: 生の LLM API 層。boto3 の bedrock-runtime で converse（同期）/converse_stream（逐次）を叩く。ツール利用は「レスポンスの toolUse を検出したら自分で while ループを回して再度 converse を呼ぶ」手動実装（chapter1/03_tool_use.py）。この面倒さが②の価値を際立たせる。
② Strands Agents: Agent() を作って agent("...") と呼ぶだけで①の while ループ（ReAct）が隠蔽される薄い FW。ツールは @tool デコレータ、マルチエージェントは Swarm/GraphBuilder/A2A（詳細は次節）。AgentCore に依存しないので単体でローカル実行できる（第4章のリサーチエージェントは AgentCore を一切使わない純 Strands）。
③ AgentCore: ②で作ったエージェントを本番運用するための8部品。中心は Runtime（エージェントを認証つき HTTP/MCP/A2A サーバとして AWS 上にホスティング）で、そこへ Memory・Identity・Gateway・Policy・Built-in Tools・Observability・Evaluation が接続する構図。

2. Strands Agents 入門（脳の書き味）¶

AgentCore を触る前に、その上で動くエージェント FW = Strands Agentsの書き味を押さえる。要点は「生 Bedrock の手続きが Agent() に畳まれる」こと。

生 Bedrock（第1章）との対比¶

# chapter1/03_tool_use.py:50-64（生 Bedrock：ツール呼び出しを自前 while ループで回す）
response = client.converse(
    modelId="us.anthropic.claude-sonnet-4-6",
    messages=messages,
    toolConfig={"tools": [tool_spec]},   # ツール定義を手で渡す
)
while True:                               # ← このループを自分で書く必要がある
    tool_request = []
    for content in response["output"]["message"]["content"]:
        if "toolUse" in content:
            tool_request.append(content)  # モデルのツール要求を拾う
    if len(tool_request) == 0:
        break                             # テキストだけ返れば終了
    # …ツールを実行し toolResult を messages に足して再度 converse（省略）

# chapter3/06_tools.py:7-18（Strands：同じことが Agent() に畳まれる）
@tool
def get_weather(location: str):
    """locationの天気を取得

    Args:
        location: 都市名
    """
    return f"{location}の天気は晴れで、気温は25℃です。"

agent = Agent(tools=[get_weather])   # ツールを渡すだけ
agent("東京の天気を教えて")            # ← while ループ（ReAct）は内部で自動

観点	生 Bedrock（第1章）	Strands（第3章）
ツール実行ループ	`while True` を自前で書く	`Agent()` が自動で回す
ツール定義	`tool_spec` の dict を手書き	`@tool` ＋ docstring の `Args:` から自動スキーマ生成
ストリーミング	`response["stream"]` を手で回す	`agent.stream_async()` を `async for`
LangGraph との違い	—	LangGraph は `StateGraph`/ノード/エッジを組むが、Strands は `Agent()` 生成のみでReActが隠蔽される（より薄い）

Strands の主要機能（早見）¶

すべて chapter3/ にスニペットがある。「Agent の引数に部品を渡すだけ」で機能が足せるのが設計思想。

機能	API（実コードのまま）	出所
最小エージェント	`from strands import Agent` → `Agent()` → `agent("...")`	`03/01_simple.py`
基本形	`Agent(model=, system_prompt=, tools=[...])`	`03/02_agent.py`
モデル指定	文字列 `Agent(model="us.anthropic.claude-sonnet-4-6")` or `BedrockModel(model_id=, region_name=, temperature=)`	`03/04-1,04-2_model.py`
他社モデル	`strands.models.openai.OpenAIModel`（`[openai]` extra）	`03/04-3_model.py`
ツール	`@tool` デコレータ / 既製 `strands_tools`（`http_request`, `tavily_search`, `calculator` …）	`03/06_tools.py`
Structured Output	Pydantic を `agent("...", structured_output_model=T)` → `result.structured_output`	`03/11_structured_output.py`
セッション永続化	`FileSessionManager` を `Agent(session_manager=)`	`03/08_session.py`
履歴管理	`SlidingWindowConversationManager(window_size=10)`	`03/10_conversation.py`
ツール実行前フック	`agent.hooks.add_callback(BeforeToolCallEvent, cb)` → `event.cancel_tool="理由"` で遮断	`03/09_hook.py`
マルチ: Agents as Tools	子 `Agent` を `tools=[research_agent]` にそのまま渡す	`03/12_agents_as_tools.py`
マルチ: Graph	`strands.multiagent.GraphBuilder` で `add_node`/`add_edge(condition=)`	`03/14_graph.py`
マルチ: Swarm	`strands.multiagent.Swarm([a, b, c])`	`03/15_swarm.py`
マルチ: A2A	`A2AServer(agent).serve()` ↔ `A2AClientToolProvider(known_agent_urls=[...])`	`03/16-_a2a_.py`
トレーシング	`StrandsTelemetry().setup_console_exporter()`（`[otel]` extra）	`03/17_tracing.py`
評価	`strands_evals` の `Case`/`Experiment`/`OutputEvaluator(rubric=)`	`03/18_evals.py`

Swarm/Graph/A2A ≈ このリポジトリの multi_agent lecture（Supervisor/Swarm/Command(goto=)）の Strands 版。LangGraph が「グラフを明示的に組む」のに対し、Strands の Swarm は「name 付き Agent をリストで渡すだけ」で協調が成立する（第4章のリサーチエージェントが実例）。

3. AgentCore の8機能（部品カタログ）¶

AgentCore の本体。Runtime を土台に、残り7部品が接続する。まず一覧、そのあと各部品の最小コード。

#	部品	一言で	中心 API（実コードのまま）	章
1	Runtime	エージェントを認証つき HTTP/MCP/A2A サーバとして AWS にホスティング	`BedrockAgentCoreApp` / `@app.entrypoint` / `app.run()` / CLI `agentcore deploy`	5
2	Memory	会話を「短期記憶（生ログ）」と「長期記憶（要約・検索可能）」に分けて保持	`MemorySessionManager` / `AgentCoreMemorySessionManager`	6
3	Identity	ツールが外部 SaaS を叩く際の OAuth トークン取得・管理を肩代わり	`@requires_access_token(...)` / `IdentityClient`	7
4	Gateway	複数ツール（MCP・HTTP・別ランタイム）を単一エンドポイント＋IAM に集約	`MCPClient` + `aws_iam_streamablehttp_client` / インターセプター Lambda	8
5	Policy	誰がどのツールをどんな条件で呼べるかを Cedar 言語で宣言的に制御	`.cedar`（`permit`/`forbid`/`when`）	9
6	Built-in Tools	マネージドの Browser / Code Interpreter サンドボックスをツール化	`AgentCoreBrowser` / `AgentCoreCodeInterpreter`	10
7	Observability	エージェント実行を OTel トレースで CloudWatch / Langfuse に送る	`StrandsTelemetry().setup_otlp_exporter(...)` / ADOT 自動計装	11
8	Evaluation	実行トレースを組み込み評価器（LLM-as-judge）で自動採点	`strands_evals` + `create_strands_evaluator("Builtin.Helpfulness")`	12

3-1. Runtime（ホスティング）— 第5章¶

エージェントをサーバ化する部品。BedrockAgentCoreApp が ASGI サーバ、@app.entrypoint が公開エンドポイント。ジェネレータを返せばそのまま SSE ストリーミングになる。

# chapter5/01_streaming.py:1-21
from strands import Agent
from bedrock_agentcore import BedrockAgentCoreApp

agent = Agent(model="us.anthropic.claude-sonnet-4-6")  # ② Strands の脳
app = BedrockAgentCoreApp()                            # ③ Runtime サーバ

@app.entrypoint                                         # HTTP エンドポイントとして公開
async def invoke(payload, context):
    stream = agent.stream_async(payload.get("prompt"))  # Strands の非同期ストリーム
    async for event in stream:
        yield event                                     # ジェネレータ = SSE ストリーミング

if __name__ == "__main__":
    app.run()                                            # 0.0.0.0:8080 で待ち受け

3プロトコル対応: HTTP（上記）／MCP サーバ化（FastMCP + mcp.run(transport="streamable-http"), 05/05_mcp_server.py）／A2A サーバ化（serve_a2a(StrandsA2AExecutor(agent)), 05/07_a2a_server.py）。エージェントを他システムから呼べる形に載せ替えられる。
非同期タスク: app.add_async_task(name) → 別スレッドで長時間処理 → app.complete_async_task(task_id) で完了通知（05/04_async.py）。第15章のアンビエントエージェントで実用。
呼び出し側: boto3.client("bedrock-agentcore").invoke_agent_runtime(agentRuntimeArn=, runtimeSessionId=, payload=)。
CLI: agentcore create / agentcore deploy（デプロイ）、agentcore dev（ローカルホットリロード）、agentcore invoke --dev "..."。
注意: app.run() 系はデプロイ前提で、ローカル uv run 単体では完結しない（agentcore dev か deploy 後の呼び出しが前提）。

3-2. Memory（記憶）— 第6章¶

短期記憶（生の会話イベント）と長期記憶（非同期に抽出・要約された検索可能な特徴）を分けて持つマネージドストア。「全履歴を毎回プロンプトに詰めると肥大する」問題への答え。

# chapter6/04_strands.py:14-34（Strands 統合：Agent に記憶を丸ごと接続）
memory_config = AgentCoreMemoryConfig(
    memory_id=MEMORY_ID, session_id=SESSION_ID, actor_id=ACTOR_ID,
    retrieval_config={NAMESPACE: RetrievalConfig()})   # 長期記憶の自動取得先を名前空間で指定
session_manager = AgentCoreMemorySessionManager(
    agentcore_memory_config=memory_config)             # Strands の session_manager I/F を実装
agent = Agent(model="us.anthropic.claude-sonnet-4-6",
              session_manager=session_manager)          # 渡すだけで会話が自動保存
agent("私はトルコ料理が好きです。")                        # 呼び出すだけで保存/取得が自動

2つの API レベル: 低レベル boto3（create_event/list_events/retrieve_memory_records）→ SDK（MemorySessionManager の add_turns/get_last_k_turns/search_long_term_memories）→ Strands 統合（AgentCoreMemorySessionManager を Agent(session_manager=) に渡すだけ）。上に行くほど自動化される。
短期 vs 長期: get_last_k_turns(k=5) が短期（直近ログ）、search_long_term_memories(query=, namespace_prefix=) が長期（セマンティック検索）。
名前空間: /strategies/{STRATEGY_ID}/actors/{ACTOR_ID}/ の形。戦略には SEMANTIC / USER_PREFERENCE / SUMMARIZATION / EPISODIC がある（第13章の agentcore.json で4戦略を定義）。
落とし穴（重要）: 長期記憶は非同期抽出なのでタイムラグがある。サンプルは time.sleep(70) で反映を待つ（06/03_sdk.py:48）。「保存直後に検索すると空」。
≈ このリポジトリの context_basics（write/select/compress/isolate の4戦略）のマネージド版。手で trim_messages・要約圧縮していたものが戦略指定で済む。

3-3. Identity（外部認証）— 第7章¶

ツールが外部 SaaS（Atlassian・Google 等）の API を呼ぶときの OAuth トークン取得・リフレッシュ・3LO（three-legged OAuth）フローを、デコレータに委譲する部品。

# chapter7/01_outbound.py:6-24
@tool
def get_confluence_sites():
    @requires_access_token(                       # OAuth トークン取得をラップ
        provider_name="AtlassianProvider",         # 事前登録済みプロバイダー
        scopes=["read:confluence-content.all"],
        auth_flow="USER_FEDERATION",               # 3LO ユーザー連携フロー
        on_auth_url=lambda url: print(url),         # 認可 URL を表示（自動オープンはしない）
        callback_url="http://localhost:9090/oauth2/callback",
    )
    def call_api(access_token: str = ""):          # 取得済みトークンが引数に注入される
        return httpx.get("https://api.atlassian.com/oauth/token/accessible-resources",
                         headers={"Authorization": f"Bearer {access_token}"}).json()
    return call_api()

フロー: on_auth_url で認可 URL を出す → ユーザーがブラウザで認可 → コールバックサーバ（FastAPI, 07/02_callback_server.py）が IdentityClient.complete_resource_token_auth(session_uri=, user_identifier=UserIdIdentifier(...)) でセッションを完了 → 以後トークンが access_token 引数に自動注入。
前提: 外部サービスの OAuth プロバイダーを事前登録しておく必要がある（コードだけでは動かない）。
第13章で実用: フロントの OAuth コールバックは @aws-sdk/client-bedrock-agentcore の CompleteResourceTokenAuthCommand で完了させる（Python/TS 両側に API がある）。

3-4. Gateway（ツール集約）— 第8章¶

複数のツール実装（MCP サーバ・HTTP API・別の AgentCore ランタイム）を、単一のゲートウェイ URL ＋ IAM 認証の裏に束ねる部品。さらにインターセプター（Lambda）でリクエストを検査・改変・遮断できる。

# chapter8/01_mcp_client.py:6-13（ゲートウェイ配下の MCP ツールをまとめて使う）
mcp_client = MCPClient(lambda: aws_iam_streamablehttp_client(
    endpoint="https://<ゲートウェイID>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp",
    aws_service="bedrock-agentcore"))    # IAM 署名でゲートウェイに接続
agent = Agent(tools=[mcp_client])         # ゲートウェイ配下の全ツールが使える
agent("注文情報を検索してください")

インターセプター（08/03_interceptor.py, Lambda）: event["mcp"]["gatewayRequest"]["body"] を検査し、method == "tools/call" のときツール引数を SQLi 正規表現でチェック → 検出時は {"mcp": {"transformedGatewayResponse": {"statusCode": 403, ...}}} を返して遮断。応答契約は interceptorOutputVersion: "1.0"。
HTTP ターゲット経由で別の AgentCore ランタイム（エージェント）を呼ぶ例もある（08/02_http_target.py、素の boto3）。ゲートウェイは MCP 以外もフロントできる。

3-5. Policy（権限）— 第9章¶

「誰が・どのツールを・どんな条件で」呼べるかを、コードに埋めず Cedar 言語のポリシーファイルとしてゲートウェイに外出しし、実行時に強制する部品。実行コードは無く .cedar ファイルだけ（マネコンに貼る）。

// chapter9/01_permit_amount.cedar（金額制限つき許可）
permit(
    principal,
    action == AgentCore::Action::"RefundTarget___process_refund",   // ターゲット名___ツール名
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway"
)
when { context.input.amount < 50000 };     // 実引数 amount が5万未満なら許可

// chapter9/03_forbid_role.cedar（役割による明示拒否。permit より優先される）
forbid(principal, action == AgentCore::Action::"RefundTarget___process_refund",
       resource == AgentCore::Gateway::"...")
when { principal.hasTag("role") && principal.getTag("role") == "intern" };

Cedar の要素: permit/forbid（forbid が優先）、when { ... } 条件、context.input.<param>（ツール実引数）、principal.hasTag/getTag（呼び出し元の属性）、like "sales/*"（ワイルドカード）。
適用: ①ポリシーエンジン作成 → ②.cedar を貼る → ③ゲートウェイに「強制モード」で関連付け。エージェント/ツールのコードは一切変えない（ゲートウェイ層で透過適用）。
≈ このリポジトリの guardrails_basics の権限ゲート（@wrap_tool_call で allow/ask/deny）の宣言的・ゲートウェイ版。「確率の防御 vs 構造の防御」で言えば Cedar は構造の防御（決定論的に許可/拒否）。

3-6. Built-in Tools（組み込みツール）— 第10章¶

マネージドの Browser（ヘッドレスブラウザ）と Code Interpreter（コード実行サンドボックス）を、Strands のツールとしてそのまま渡せる部品。自前でブラウザ VM やサンドボックスを立てなくていい。

# chapter10/01_browser.py:1-8
from strands import Agent
from strands_tools.browser import AgentCoreBrowser
browser = AgentCoreBrowser(region="us-east-1")   # マネージドブラウザを初期化
agent = Agent(tools=[browser.browser])            # .browser をツールとして渡すだけ

Code Interpreter も同型: AgentCoreCodeInterpreter() → agent = Agent(tools=[code_interpreter.code_interpreter])。
≈ このリポジトリの sandbox_basics（Seatbelt/Docker/E2B microVM でコード実行を隔離）のマネージド版。「権限ゲートの先＝コード実行能力そのものの隔離」を AWS が肩代わり。

3-7. Observability（可観測性）— 第11章¶

エージェント実行を OpenTelemetry(OTel) トレースとして CloudWatch か Langfuse に送る部品。「何を考え、どのツールを何回呼び、どこで詰まったか」をブラックボックスにしない。

# chapter11/langfuse/main.py:19-25（Langfuse へ OTLP エクスポート）
StrandsTelemetry().setup_otlp_exporter(
    endpoint=f"{LANGFUSE_HOST}/api/public/otel/v1/traces",
    headers={"Authorization": f"Basic {auth}",       # public:secret を base64
             "x-langfuse-ingestion-version": "4"})    # Langfuse v4 対応

2経路: ① CloudWatch はコード変更ゼロで、コンテナ起動を opentelemetry-instrument python main.py（ADOT ＝ aws-opentelemetry-distro の自動計装）にするだけ。② Langfuse は上記のように OTLP エクスポータを手で向ける。
≈ このリポジトリの langfuse_basics。というよりそのまま Langfuse に繋がる（trace/span/generation の階層で見る）。AgentCore 側は OTel の口を開けるだけで、受け皿は同じ Langfuse。

3-8. Evaluation（評価）— 第12章¶

エージェントの実行トレースを、AgentCore の組み込み評価器（LLM-as-judge）でオンデマンド採点する部品。Strands（実行・トレース収集）と AgentCore（評価ロジック）の分業。

# chapter12/02_on_demand.py:14-32（抜粋）
telemetry = StrandsEvalsTelemetry().setup_in_memory_exporter()   # 実行トレースをメモリに集める
def task_fn(case):
    response = agent(case.input)
    spans = list(telemetry.in_memory_exporter.get_finished_spans())
    return {"output": str(response), "trajectory": spans}
cases = [Case(input="5 + 3 はいくつですか？", expected_output="8")]
evaluator = create_strands_evaluator("Builtin.Helpfulness")       # AgentCore 組み込み評価器
reports = Experiment(cases=cases, evaluators=[evaluator]).run_evaluations(task_fn)
print(f"スコア: {reports[0].overall_score:.2f}")

評価器名はコード上 "Builtin.Helpfulness"（Builtin. 名前空間）が確認できる範囲。他の組み込み評価器名はサンプルに未出。
≈ このリポジトリの eval_basics（golden dataset ＋ LLM-as-a-Judge ＋回帰ゲート）のマネージド版。Case/Experiment の枠組みは eval_basics の設計と同じ発想。

4. 8機能が実アプリでどう組み合わさるか（ハンズオン4章）¶

部品カタログを "1つのアプリ" に束ねるのがハンズオン章。どの章がどの部品を使うかを把握すると、8機能の実戦での役割分担が見える。

章	作るもの	使う AgentCore 機能	スタック
第4章	リサーチエージェント（Plan→Retrieval/WhatsNew→Review の Swarm RAG）	なし（純 Strands・ローカル実行）	Strands `Swarm` + MCP + RSS + rich
第13章	新刊チェッカー BookChecker（フルスタック）	Runtime + Memory + Identity + Built-in Browser + Observability（5機能を1アプリに束ねる本命）	Next.js/Amplify/Cognito + Strands
第14章	社内データ RAG（Bedrock ナレッジベース）	なし（KB は第8章で作ったものを流用）	生 API `retrieve_and_generate` / Strands `retrieve` / MCP の3パターン
第15章	経費精算アンビエントエージェント（S3 アップロード起点）	Runtime + 非同期タスク（イベント駆動・CDK IaC）	AWS CDK(TS) + Strands + Lambda + SNS/DynamoDB

第13章のアーキテクチャ（8機能の束ね方が最も濃い）:

flowchart LR
    U["ユーザー<br>ブラウザ"]
    FE["Next.js + Amplify<br>Cognito 認証"]
    RT["AgentCore Runtime<br>Strands Agent"]
    MEM["Memory<br>好みを検索/保存<br>（4戦略）"]
    IDP["Identity<br>Google OAuth 3LO"]
    BRW["Built-in Browser<br>新刊サイト巡回"]
    GCAL["Google Calendar API"]
    OBS["Observability<br>OTel → CloudWatch/Langfuse"]

    U --> FE
    FE -->|"JWT + prompt をSSEで"| RT
    RT --> MEM
    RT --> BRW
    RT -->|"未認可なら認可URLを返す"| IDP
    IDP --> GCAL
    RT -.-> OBS

第13章の流れ: Cognito ログイン → フロントが JWT を取り Runtime へ SSE POST → Runtime 内の Strands Agent が Built-in Browser で新刊サイトを巡回し、Memory でユーザーの好みを検索・保存、カレンダー登録時は Identity(Google OAuth 3LO) でトークンを取得 → 確認後に Google Calendar へ登録。裏で Observability が OTel 計装。
第15章の型: S3 の receipts/ へのアップロード → S3 イベント → Lambda → invoke_agent_runtime → Runtime 内 Agent が「領収書をマルチモーダル解析 → 経費分類 → 承認者選定 → 承認依頼メール」を非同期タスク（add_async_task/complete_async_task）で実行 → 承認後は Confluence 記録。イベント駆動 × AgentCore の非同期処理を CDK で IaC 化した例。
注意（事実として）: 第14章は README 表では「Streamlit ベースの RAG」とされるが、サンプルコードに Streamlit UI は無い（3つの独立スクリプトのみ）。第4・14章は AgentCore を使わない。Gateway はハンズオン4章のコードにいずれも現れない（第14章が流用する KB は第8章＝Gateway 章で構築する構成）。

5. このリポジトリの既存 lecture との対応（地図）¶

AgentCore の各部品は、この ai-engineering-study で既に手組みした要素のマネージド版。手で作った経験があると、AgentCore が「何を肩代わりしているか」が一発で分かる。

AgentCore 部品	対応する既存 lecture	関係
Runtime（ホスティング）	`local_models`	「モデルは `base_url` で差し替える部品」→ AgentCore はエージェント丸ごとをマネージドサーバ化。手組みには無いレイヤ
Memory（記憶）	`context_basics`	write/select/compress/isolate の4戦略 → 戦略指定で自動化（短期/長期分離もマネージド）
Identity（外部認証）	（対応なし・新規）	外部 SaaS の OAuth 3LO 肩代わりは既存 lecture に無い新要素
Gateway（ツール集約）	`19` / `20`（MCP）	MCP サーバ/クライアントの手組み → ゲートウェイで IAM 認証つきに集約＋インターセプタ
Policy（権限）	`guardrails_basics`	`@wrap_tool_call` の allow/ask/deny（手続き的）→ Cedar（宣言的・構造の防御）
Built-in Tools（Code Interpreter）	`sandbox_basics`	Seatbelt/Docker/E2B の隔離を自作 → マネージドサンドボックスを渡すだけ
Observability	`langfuse_basics`	そのまま Langfuse に繋がる（OTel の口を開けるだけ）
Evaluation	`eval_basics`	golden dataset + LLM-as-a-Judge → 組み込み評価器で採点
Strands マルチエージェント	`multi_agent`	Supervisor/Swarm/ハンドオフ → Strands の `Swarm`/`GraphBuilder`/A2A

まとめの一言: AgentCore は「新しく学ぶこと」というより、手組みで散らばっていた運用要素（記憶・権限・観測・評価・隔離）を、AWS が8個のマネージド部品に整理し直したカタログ。だから既存 lecture の知識がそのまま "AgentCore の各部品が内部で何をしているか" の理解になる。

6. 用語集（混同しやすい同系語）¶

このメモで最重要のセクション。「〜Core」「〜Agent」「ランタイム」「記憶」「トレース」が何を指すかを1枚で。

用語	何を指すか	隣の語との違い
Amazon Bedrock	AWS の基盤モデル API サービス（Claude 等をホスト）	①の層。生の LLM 呼び出し（`converse`）。エージェント機能は無い
Bedrock AgentCore	エージェントを本番運用する8部品のマネージド基盤	③の層。Bedrock の"上"に乗る運用インフラ。FW ではない
Strands Agents	AgentCore 上で動くエージェント実装 FW（`Agent()`）	②の層。脳を書く FW（LangGraph 相当）。AgentCore 無しでも単体で動く
AgentCore Runtime	エージェントを認証つきサーバとしてホスティングする部品	8部品の1つ。「AgentCore 全体」ではなく「ホスティング担当」
harness（ハーネス）	マネコンで作る呼び出しラッパ。`invoke_harness` で叩く	Runtime（デプロイ済みエージェント）とは別の呼び出し口（5.2 vs 5.3節）
短期記憶	生の会話イベント（直近 k ターン）	`get_last_k_turns`。即時・生ログ
長期記憶	要約・抽出されセマンティック検索できる特徴	`search_long_term_memories`。非同期抽出でラグあり（≈70秒）
戦略 (strategy)	長期記憶の抽出方式（SEMANTIC/USER_PREFERENCE/SUMMARIZATION/EPISODIC）	名前空間 `/strategies/{id}/actors/{id}/` で指定
Identity の 3LO	three-legged OAuth（ユーザー・アプリ・SaaS の3者認可）	`auth_flow="USER_FEDERATION"`。ユーザーのブラウザ認可を挟む
Gateway	複数ツールを束ねる単一エンドポイント	ツール集約。Policy はこの Gateway に強制適用される
Policy / Cedar	ツール呼び出しの許可/拒否を宣言する言語・エンジン	`permit`/`forbid`（forbid 優先）。コードを変えずゲートウェイ層で強制
インターセプター	ゲートウェイのリクエスト/レスポンスを加工する Lambda	Policy（許可判定）とは別。内容の検査・改変・遮断（例: SQLi ブロック）
Built-in Tools	マネージドの Browser / Code Interpreter	「AWS が用意したツール」。`@tool` の自作ツールと対比
Swarm / Graph / A2A	Strands のマルチエージェント方式	Swarm=リスト渡しで協調 / Graph=ノード・エッジ明示 / A2A=別サーバのエージェントを呼ぶ
StrandsTelemetry	Strands 側の OTel 計装 API	`setup_console_exporter`（手元確認）/ `setup_otlp_exporter`（Langfuse/CloudWatch 送信）
create_strands_evaluator	AgentCore の組み込み評価器を作る関数	`"Builtin.Helpfulness"` 等。`strands_evals`（実行・収集）と分業

困りごと → 見るものクイック早見: エージェントを本番に置きたい → Runtime（5章）／会話を覚えさせたい → Memory（6章）／外部 SaaS を叩かせたい → Identity（7章）／ツールが増えて散らかった → Gateway（8章）／危険な呼び出しを止めたい → Policy（9章）／ Web 操作・コード実行させたい → Built-in Tools（10章）／中で何が起きたか見たい → Observability（11章）／品質を測りたい → Evaluation（12章）。

7. バージョン・落とし穴（実行するなら）¶

書籍執筆時点で固定されたバージョン（本を再現するならこれに合わせる。AgentCore は新しめのサービスで API が動く可能性があるので、実機で詰まったら最新版も確認）。

項目	値	補足
Strands 本体	`strands-agents==1.38.0`	全章で固定
Strands ツール	`strands-agents-tools==0.5.1`	機能ごとに extra（`[agent_core_browser]` `[otel]` `[a2a]` 等）
AgentCore SDK	`bedrock-agentcore==1.6.4`	一部章で `[strands-agents-evals]` `[strands-agents]` extra
boto3	`boto3==1.42.96` / `boto3[crt]`	—
MCP	`mcp==1.27.0`	—
Python	3.14（大半） / 3.13（第10章 Browser）	第10章 Browser だけ 3.13 必須
リージョン	`us-east-1`（バージニア北部）に統一	—
モデル	`us.anthropic.claude-sonnet-4-6`（4.5世代は不使用）	haiku-4-5 / opus-4-6 も一部で
AgentCore CLI	`@aws/agentcore`（当初 `v1.0.0-preview.8` → 現在は `@latest` 案内）	CDK アップデート起因のエラー回避で 2026/6/30 に `@latest` へ

落とし穴（サンプルを動かす前提）:

app.run() 系はデプロイ前提。ローカル uv run 単体では動かない（agentcore dev か deploy が要る）。
プレースホルダー置換が必須の章が多い（<ゲートウェイID> <メモリーID> <戦略ID> ARN 等）。README の動作前提を読んでから。
Memory 長期記憶は非同期ラグ（保存直後は検索が空。サンプルは time.sleep(70)）。
Cedar / Lambda / Dockerfile は uv run しない（デプロイ・貼付するもの）。第9章 .cedar はマネコン貼付、第8章 03_interceptor.py は Lambda デプロイ用。
CLI 生成の雛形は未使用（第5・13章の model/load.py・mcp_client/ 等は agentcore create が吐いた雛形で main からは呼ばれない）。読者が「使われてなさそう」で迷わないよう注意。
サンプルの eval(expression)（第12章の calculator ツール）は入門書の簡潔さ優先のベタ書き。任意コード実行なので実運用では使わない。
バージョン記述の齟齬が本の中に散見（第11章 cloudwatch 側は非固定で bedrock-agentcore==1.17.0 に解決される等）。厳密再現なら uv.lock を確認。

8. 拡張アイデア・学習の進め方¶

課金ゼロで手を動かせる範囲から始めて、AWS 実機は必要になってから、が現実的。

まず Strands だけをローカルで触る（課金は Bedrock トークンのみ・AgentCore 不要） — 第3章スニペット（@tool・Swarm・GraphBuilder）と第4章リサーチエージェントは AgentCore を使わず uv run で動く。ここで「脳の書き味」を掴む。LangGraph 経験があれば「薄さ」を体感できる。
既存 lecture と対で読む（実装済みの手組み版と見比べる） — Policy を読むなら guardrails_basics（@wrap_tool_call allow/ask/deny）、Built-in Code Interpreter なら sandbox_basics、Observability なら langfuse_basics、Evaluation なら eval_basics を並べる。「手で組むと何行か」を知ってからマネージドを見ると、AgentCore の価値が定量的に分かる。
AgentCore 実機に進むなら第5章（Runtime）→ 第13章（フルスタック束ね）の順 — Runtime のデプロイ（agentcore deploy）を1回通してから、Memory/Identity/Browser を足していく第13章に進むと段階的。AWS アカウント・課金・IAM 設定が要る（付録の環境構築を先に）。
multi_agent lecture と Strands Swarm/Graph を対比 — LangGraph の Command(goto=) ハンドオフと Strands の Swarm/GraphBuilder で「同じ協調をどう書くか」を並べると、FW 選定の目が育つ。
Policy(Cedar) を単体で深掘り — Cedar は AgentCore 専用ではなく AWS Verified Permissions の言語。permit/forbid/when/principal.getTag の評価モデルを別途学ぶと、権限設計の汎用スキルになる。

9. 参照¶

書籍: 「Amazon Bedrock AgentCore実践入門 ― Strands Agentsで構築するAIエージェント［AWS深掘りガイド］」SBクリエイティブ、御田（みのるん）／熊田／森田著。https://www.amazon.co.jp/dp/4815641234
サンプルコード: agentcore-book/（本リポ内クローン）／公開リポ minorun365/agentcore-book
本メモが読んだ主なファイル（章 ↔ 部品）:
第1章生 Bedrock: agentcore-book/chapter1/01_converse.py 03_tool_use.py
第3章 Strands: agentcore-book/chapter3/06_tools.py 14_graph.py 15_swarm.py 16-*_a2a_*.py
第5章 Runtime: agentcore-book/chapter5/01_streaming.py 04_async.py 05_mcp_server.py 07_a2a_server.py
第6章 Memory: agentcore-book/chapter6/03_sdk.py 04_strands.py
第7章 Identity: agentcore-book/chapter7/01_outbound.py 02_callback_server.py
第8章 Gateway: agentcore-book/chapter8/01_mcp_client.py 03_interceptor.py
第9章 Policy: agentcore-book/chapter9/01_permit_amount.cedar 03_forbid_role.cedar
第10章 Built-in Tools: agentcore-book/chapter10/01_browser.py 02_code_interpreter.py
第11章 Observability: agentcore-book/chapter11/langfuse/main.py cloudwatch/Dockerfile
第12章 Evaluation: agentcore-book/chapter12/02_on_demand.py
第13章フルスタック: agentcore-book/chapter13/main.py app/page.tsx
第15章アンビエント: agentcore-book/chapter15/src/agent.py cdk/lib/expense-agent-stack.ts
関連 lecture: multi_agent / context_basics / guardrails_basics / sandbox_basics / langfuse_basics / eval_basics / llmops_basics（全体地図）

作成: 2026-07-17 ／最終更新: 2026-07-17