aws-strands-agents-agentcore

AWS Strands Agents と AgentCore

概要

AWS Strands Agents SDK：モデル主導のオーケストレーションによって AI エージェントを構築するためのオープンソースの Python フレームワークです（最小限のコードで、モデルがツールの使用方法を決定します）。

Amazon Bedrock AgentCore：本番環境でエージェントをデプロイ、運用、スケーリングするためのエンタープライズ向けプラットフォームです。

関係性：Strands SDK は単独で、または AgentCore のプラットフォームサービスと併用して実行できます。AgentCore は任意ですが、エンタープライズ向け機能（8 時間のランタイム、ストリーミング、メモリ、ID、可観測性）を提供します。

---

クイックスタートの判断ツリー

何を構築しますか？

単一目的のエージェント：

• イベント駆動型（S3、SQS、スケジュール実行）→ Lambda にデプロイ
• ストリーミング対応の対話型 → AgentCore Runtime
• API エンドポイント（ステートレス）→ Lambda

マルチエージェントシステム：

• 決定論的なワークフロー → グラフパターン
• 自律的な協調 → Swarm パターン
• シンプルな委任 → エージェント・アズ・ツールパターン

ツール／統合サーバー（MCP）：

• 必ず ECS/Fargate または AgentCore Runtime にデプロイしてください
• 決して Lambda にデプロイしないでください（ステートフルで、永続的な接続が必要です）

デプロイ例については、architecture.md を参照してください。

---

重要な制約

MCP サーバーの要件

1. トランスポート：必ず streamable-http を使用してください（stdio は使用しないでください）
2. エンドポイント：必ず 0.0.0.0:8000/mcp に設定してください
3. デプロイ：必ず ECS/Fargate または AgentCore Runtime を使用してください（Lambda は使用しないでください）
4. ヘッダー：application/json と text/event-stream を受け入れる必要があります

理由：MCP サーバーはステートフルで、永続的な接続が必要です。Lambda は一時的なため、適していません。

詳細については、limitations.md を参照してください。

ツール数の制限

• モデルは 50～100 個を超えるツールの処理が困難です
• 解決策：動的なツール読み込みのために、セマンティック検索を実装してください

実装については、patterns.md を参照してください。

トークン管理

• Claude 4.5：200K コンテキスト（最大で約 180K の使用を推奨）
• 長時間の会話では、会話マネージャーが必須です
• マルチエージェントではコストが 5～10 倍になります

戦略については、limitations.md を参照してください。

---

デプロイの判断マトリックス

コンポーネント	Lambda	ECS/Fargate	AgentCore Runtime
ステートレスエージェント	✅ 最適	❌ 過剰	❌ 過剰
対話型エージェント	❌ ストリーミング非対応	⚠️ 可能	✅ 理想的
MCP サーバー	❌ 絶対に不可	✅ 標準	✅ 機能付き
実行時間	< 15 分	無制限	最大 8 時間
コールドスタート	あり（30～60 秒）	なし	なし

---

マルチエージェントパターンの選択

パターン	複雑さ	予測可能性	コスト	ユースケース
単一エージェント	低	高	1x	ほとんどのタスク
エージェント・アズ・ツール	低	高	2-3x	シンプルな委任
グラフ	高	非常に高い	3-5x	決定論的なワークフロー
Swarm	中	低	5-8x	自律的な協調

推奨：まずは単一エージェントから始め、必要に応じて発展させてください。

例については、architecture.md を参照してください。

---

リファレンスファイルを読むタイミング

patterns.md

• 基本的なエージェントファクトリーパターン（再利用可能なコンポーネント）
• MCP サーバーレジストリパターン（ツールカタログ）
• セマンティックツール検索（50 個を超えるツール）
• ツール設計のベストプラクティス
• セキュリティパターン
• テストパターン

observability.md

• AWS AgentCore Observability Platform のセットアップ
• ランタイムホスト型とセルフホスト型の設定
• 複数ターンの会話におけるセッション追跡
• OpenTelemetry のセットアップ
• コスト追跡フック
• 本番環境の可観測性パターン

evaluations.md

• AWS AgentCore Evaluations - LLM-as-a-Judge による品質評価
• 組み込み評価器 13 種（有用性、正確性、GoalSuccessRate など）
• 独自のプロンプトとモデルを使ったカスタム評価器
• オンライン（継続的）評価モードとオンデマンド評価モード
• CloudWatch との統合とアラート

limitations.md

• MCP サーバーのデプロイに関する問題
• ツールの選択に関する問題（50 個超のツール）
• トークンの超過
• Lambda の制限
• マルチエージェントのコストに関する懸念
• スロットリングエラー
• コールドスタートのレイテンシ

---

#-Driven の理念

重要な概念：Strands Agents は、明示的な制御フローのコードを要求するのではなく、オーケストレーションをモデルに委ねます。

# Traditional: Manual orchestration (avoid)
while not done:
    if needs_research:
        result = research_tool()
    elif needs_analysis:
        result = analysis_tool()

# Strands: Model decides (prefer)
agent = Agent(
    system_prompt="You are a research analyst. Use tools to answer questions.",
    tools=[research_tool, analysis_tool]
)
result = agent("What are the top tech trends?")
 automatically orchestrates: research_tool → analysis_tool → respond

---

の選択

主なプロバイダー：AWS Bedrock 経由の Anthropic Claude

モデル ID の形式：anthropic.claude-{model}-{version}

現在のモデル（2025 年 1 月時点）：

• anthropic.claude-sonnet-4-5-20250929-v1:0 - 本番環境向け
• anthropic.claude-haiku-4-5-20251001-v1:0 - 高速／低コスト
• anthropic.claude-opus-4-5-20250514-v1:0 - 複雑な推論

最新モデルの確認：

aws bedrock list-foundation-models --by-provider anthropic \
  --query 'modelSummaries[*].[modelId,modelName]' --output table

---

簡単な例

基本的なエージェント

from strands import Agent
from strands.models import BedrockModel
from strands.session import DynamoDBSessionManager
from strands.agent.conversation_manager import SlidingWindowConversationManager

agent = Agent(
    agent_id="my-agent",
    model=BedrockModel(model_id="anthropic.claude-sonnet-4-5-20250929-v1:0"),
    system_prompt="You are helpful.",
    tools=[tool1, tool2],
    session_manager=DynamoDBSessionManager(table_name="sessions"),
    conversation_manager=SlidingWindowConversationManager(max_messages=20)
)

result = agent("Process this request")

基本的なエージェントファクトリーのパターンについては、patterns.md を参照してください。

MCP サーバー（ECS/Fargate）

from mcp.server import FastMCP
import psycopg2.pool

# Persistent connection pool (why Lambda won't work)
db_pool = psycopg2.pool.SimpleConnectionPool(minconn=1, maxconn=10, host="db.internal")

mcp = FastMCP("Database Tools")

@mcp.tool()
def query_database(sql: str) -> dict:
    conn = db_pool.getconn()
    try:
        cursor = conn.cursor()
        cursor.execute(sql)
        return {"status": "success", "rows": cursor.fetchall()}
    finally:
        db_pool.putconn(conn)

# CRITICAL: streamable-http mode
if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)

デプロイの詳細については、architecture.md を参照してください。

ツールのエラー処理

from strands import tool

@tool
def safe_tool(param: str) -> dict:
    """Always return structured results, never raise exceptions."""
    try:
        result = operation(param)
        return {"status": "success", "content": [{"text": str(result)}]}
    except Exception as e:
        return {"status": "error", "content": [{"text": f"Failed: {str(e)}"}]}

ツール設計のパターンについては、patterns.md を参照してください。

可観測性

AgentCore Runtime（自動）：

# Install with OTEL support
# pip install 'strands-agents[otel]'
# Add 'aws-opentelemetry-distro' to requirements.txt

from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()
agent = Agent(...)  # Automatically instrumented

@app.entrypoint
def handler(payload):
    return agent(payload["prompt"])

セルフホスト：

export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_RESOURCE_ATTRIBUTES="service.name=my-agent"

opentelemetry-instrument python agent.py

一般的な OpenTelemetry：

from strands.observability import StrandsTelemetry

# Development
telemetry = StrandsTelemetry().setup_console_exporter()

# Production
telemetry = StrandsTelemetry().setup_otlp_exporter()

詳細なパターンについては、observability.md を参照してください。

---

セッションストレージの選択

Local dev         → FileSystem
Lambda agents     → S3 or DynamoDB
ECS agents        → DynamoDB
Interactive chat  → AgentCore Memory
Knowledge bases   → AgentCore Memory

ストレージバックエンドの比較については、architecture.md を参照してください。

---

AgentCore Platform と SDK のみを使う場合の選択

Strands SDK のみを使用

• シンプルでステートレスなエージェント
• 厳密なコスト管理が必要
• エンタープライズ機能が不要
• デプロイの柔軟性が必要

Strands SDK + AgentCore Platform を使用

• 8 時間のランタイムサポートが必要
• ストリーミング応答が必要
• エンタープライズ向けのセキュリティ／コンプライアンスが必要
• セッションをまたいだインテリジェンスが必要
• マネージドインフラストラクチャを利用したい

プラットフォームサービスの詳細については、architecture.md を参照してください。

---

よくあるアンチパターン

1. ❌ エージェントに 50 個超のツールを詰め込む → セマンティック検索を使用する
2. ❌ 会話管理を行わない → SlidingWindow または Summarising を実装する
3. ❌ MCP サーバーを Lambda にデプロイする → ECS/Fargate を使用する
4. ❌ タイムアウトを設定しない → あらゆる箇所で実行制限を設定する
5. ❌ トークン制限を無視する → 会話マネージャーを実装する
6. ❌ コストを監視しない → 初日からコスト追跡を実装する

詳細については、patterns.md と limitations.md を参照してください。

---

本番環境へのチェックリスト

デプロイ前に、以下を確認してください。

• 会話管理を設定済み
• AgentCore Observability を有効化、または OpenTelemetry を設定済み
• AgentCore Evaluations を設定して品質を監視
• 可観測性フックを実装済み
• コスト追跡を有効化済み
• すべてのツールでエラー処理を実装済み
• セキュリティ権限を検証済み
• MCP サーバーを ECS/Fargate にデプロイ済み
• タイムアウト制限を設定済み
• セッションバックエンドを設定済み（本番環境では DynamoDB）
• CloudWatch アラームを設定済み

---

リファレンスファイルのナビゲーション

• architecture.md - デプロイパターン、マルチエージェントのオーケストレーション、セッションストレージ、AgentCore サービス
• patterns.md - 基盤コンポーネント、ツール設計、セキュリティ、テスト、パフォーマンス最適化
• limitations.md - 既知の制約、回避策、緩和戦略、課題
• observability.md - AgentCore Observability プラットフォーム、ADOT、GenAI ダッシュボード、OpenTelemetry、フック、コスト追跡
• evaluations.md - AgentCore Evaluations、組み込み評価器、カスタム評価器、品質モニタリング

---

主なポイント

1. MCP サーバーでは streamable-http を必ず使用し、Lambda は絶対に使用しないでください
2. ツールが 15 個を超える場合は、セマンティック検索を使用してください
3. 会話管理を必ず実装してください
4. マルチエージェントではコストが 5～10 倍になります（初日から追跡してください）
5. あらゆる場所でタイムアウト制限を設定してください
6. ツールのエラー処理は必須です
7. ステートレスな処理には Lambda、対話型の処理には AgentCore を使用してください
8. 本番環境では AgentCore Observability と Evaluations を使用してください
9. シンプルに始め、段階的に複雑さを増やしてください
10. デフォルトでセキュリティを確保してください
11. 設定とコードを分離してください