Amazon Bedrock AgentCore、コードから図解へ自動ドキュメント生成を支援

ソフトウェア開発において、アーキテクチャドキュメントの維持は最も持続的な課題の一つです。コードベースが急速に進化する中で、開発チームは手動でアーキテクチャ図を作成するために数時間を費やしますが、デプロイから数週間でそれらが古びてしまうことがよくあります。このドキュメントのギャップは知識のサイロ化を招き、開発者のオンボーディングを遅らせ、コンプライアンス監査を複雑にします。

Amazon Bedrock AgentCore は、あらゆるフレームワークやモデルでエージェントを大規模に構築・接続・最適化するためのプラットフォームです。コードベースの分析、アーキテクチャ図の生成、検索可能なドキュメントの自動維持を行う自律型エージェントを通じて解決策を提供します。このアジェンシーアプローチでは、反復的な改善と自己修正を活用し、AWS サービスを介したコード分析、図の生成、自動化された公開を調整しています。

本稿では、世界中のインターディーラー・ブローカーが、既存の継続的インテグレーションおよび継続的デリバリー（CI/CD）ワークフローと統合された自動アーキテクチャ文書化パイプラインをどのように構築したかをご紹介します。このソリューションは、コード分析に AgentCore を、セマンティック検索機能に Amazon Bedrock Knowledge Bases を、継続的デプロイメントに AWS CodePipeline をそれぞれ活用しています。このアプローチは、主要な金融市場でインターディーラー・ブローキングを手掛けるグローバルな金融サービス企業と共同で開発・検証され、2026 年第 1 四半期から電子取引プラットフォームのアーキテクチャ文書化維持のために本番環境で稼働しています。

アーキテクチャ文書化における課題

開発チームは、アーキテクチャ文書化において以下の重要な課題に直面しています。

• 時間がかかる手作業 – Unified Modeling Language（UML）や Mermaid 形式の包括的なアーキテクチャ図を作成するのは多大な労力を要します。大規模なコードベースでは、この手法は持続不可能です。

• 急速な陳腐化 – コードは毎日変更されますが、文書の更新は遅れがちです。数週間で図が現実を反映しなくなり、意思決定の根拠として信頼できなくなります。

知識のサイロ化 – チームメンバーが退職すると属人的なナレッジが消え、レガシーシステムは「ブラックボックス」と化してしまいます。その結果、新規開発者はコードを逆解析せざるを得なくなり、オンボーディングが遅延し、組織全体の知見が損なわれます。

コンプライアンスのギャップ – セキュリティレビューや監査には最新のアーキテクチャ図が必要です。古くなったドキュメントはコンプライアンスリスクを生み、認証取得を遅らせます。

これらの課題はマイクロサービスアーキテクチャにおいて特に深刻化します。サービス間の依存関係やメッセージフローを理解することは、連鎖的な障害を防ぐために不可欠だからです。

ソリューションの概要

本ソリューションでは、AgentCore を活用して .NET コードベースを分析し、包括的なアーキテクチャ図を自動生成する自律型エージェントを構築します。このエージェントは AWS CodePipeline 内で動作し、AWS CodeCommit リポジトリへのコードコミットをトリガーとして起動されます。生成された図とそのメタデータは Amazon Bedrock Knowledge Bases に取り込まれ、アーキテクチャドキュメント全体を対象としたセマンティック検索や自然言語による問い合わせが可能になります。これにより、現在のアーキテクチャ状態を明確に把握でき、その可視性からビジネス価値を引き出すことができます。

主要コンポーネント

本ソリューションでは、効率的なワークフローを実現するために複数の AWS サービスが統合されています：

以下のアーキテクチャ図は、コードを AWS CodeCommit にプッシュしてから図の生成を行い、Amazon Bedrock Knowledge Bases へ取り込むまでの全体システム設計を示しています。

図 1: AWS CodeCommit から図生成を経て Amazon Bedrock Knowledge Bases への取り込みに至る全体のシステム設計

このワークフローは以下の手順で行われます。

• 開発者がコード変更を AWS CodeCommit にプッシュします。
• AWS CodeCommit が AWS CodePipeline の実行をトリガーします。
• AWS CodePipeline がビルドプロセスを開始します。
• AWS CodeBuild は AWS CodeCommit リポジトリからコードを取得し、ソースコードをパッケージ化して Amazon S3 のソースコードバケットへアップロードします。
• AWS CodeBuild は AgentCore を呼び出します。呼び出しペイロードの準備を行い、AgentCore 上でホストされている Strands エージェントを起動します。このエージェントは、Amazon Bedrock を介して利用可能な大規模言語モデルを推論エンジンとして使用し、コードパターンの分析、図記法の生成、自己修正による検証エラーの解消を行います。リージョン別のモデル利用状況については、Amazon Bedrock の AWS リージョン別サポートモデル を参照してください。
• Strands エージェントは Amazon S3 からソースコードを取得します。
• Strands エージェントがコードベースをスキャンし、図を生成・構文検証を行い、反復的な改良のために SVG ファイルへ変換します。

Strands エージェントは、レンダリングされた SVG ファイルや Mermaid ソースファイル、図の記述メタデータ（JSON）などを含むアーキテクチャダイアグラムを Amazon S3 の「Architecture Diagrams」バケットにアップロードします。

Amazon Bedrock Knowledge Bases は、この S3 バケットからダイアグラムのアーティファクトを取り込みます。取り込みパイプラインでは、Amazon Titan Text Embeddings v2 モデルを使用してベクトル埋め込みを生成し、図の記述や Mermaid ソースを意味のある単位に分割するチャンキング処理を適用した上で、生成されたベクトルを Amazon S3 ベクターストアに保存します。これにより、アーキテクチャドキュメント全体に対するセマンティック検索と、検索拡張生成（RAG）が可能になります。

開発者や関係者は、自然言語を通じて知識ベースに問い合わせを行い、関連するアーキテクチャ図とその文脈説明を発見・探索・取得できます。例えば、「再接続アクティビティのフローはどのようなものか？」や「インフラストラクチャコンポーネントのクラス図をすべてリストアップしてください」といった質問が可能です。

コード分析と優先順位付け

エージェントはまず、コードベースの構造を分析します。すべてのファイルを処理するのではなく、テストファイル、ビルド成果物、生成されたコードを除外し、本番環境のコードに焦点を当てます。この優先順位付けにより、処理時間の短縮とダイアグラムの関連性向上が図られます。

def scan_codebase(source_path: str) -> str:
    """Scan .NET codebase and return structured analysis."""
    cs_files = []
    for root, dirs, files in os.walk(source_path):
        dirs[:] = [d for d in dirs if d not in ['bin', 'obj', 'packages', '.git']]
        for file in files:
            if file.endswith('.cs'):
                analysis = analyze_csharp_file(os.path.join(root, file))
                cs_files.append(analysis)
    return json.dumps({
        "files_found": len(cs_files),
        "summary": generate_summary(cs_files),
        "files": cs_files
    })

スキャンにより、インターフェース、抽象クラス、具体的な実装、およびそれらの依存関係といった主要なアーキテクチャ要素が特定されます。この構造化された分析は、正確な図を生成するためにエージェントに必要な文脈を提供します。

Amazon Bedrock AgentCore を活用したドキュメントエージェントのデプロイ

AgentCore を使用すれば、Strands エージェントによる反復的な改善と自己修正機能を活用する自律型ドキュメントエージェントをホストできます。

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent
from strands.models.bedrock import BedrockModel

app = BedrockAgentCoreApp()

def create_uml_agent():
    model = BedrockModel(
        model_id="your-selected-model-id",
        region_name="us-east-1",
        temperature=0.3,
        max_tokens=4096
    )
    agent = Agent(
        model=model,
        system_prompt=UML_GENERATION_PROMPT,
        tools=[fetch_source_from_s3, scan_codebase, save_mermaid_diagram,
               validate_mermaid_syntax, convert_to_svg, upload_to_s3]
    )
    return agent

@app.entrypoint
async def invoke(payload: Dict[str, Any], context: Any) -> AsyncGenerator[Dict[str, Any], None]:
    """AgentCore entrypoint for UML generation."""
    # Extract parameters from payload
    source_s3_bucket = payload.get("source_s3_bucket")
    source_s3_key = payload.get("source_s3_key")
    project_name = payload.get("project_name", "Project")
    diagrams_bucket = payload.get("diagrams_bucket", "")

    # Create UML agent instance
    agent = create_uml_agent()

    # Construct generation prompt
    generation_prompt = f"""Generate complete UML documentation for {project_name}.

Steps:
1. Fetch source code from Amazon S3 bucket: {source_s3_bucket}, key: {source_s3_key}
2. Scan and analyze the codebase
3. Generate all required diagrams
4. Validate and convert each diagram to SVG
5. Upload all artifacts to Amazon S3

Begin now by fetching the source code."""

    # Stream async response
    stream = agent.stream_async(generation_prompt)

    # Process stream events
    async for event in stream:
        if "data" in event and isinstance(event["data"], str):
            yield {"content": event["data"]}

このエージェントは、コードベースの分析結果と図生成の現在の状態に基づいてツールの使用を判断します。このようなアジェンティックなアプローチにより、検証エラーが発生した際に自己修正が可能となり、単発の API 呼び出しと比較して信頼性が大幅に向上します。

アジェンティックなワークフロー

このエージェントは、人間のアーキテクトがドキュメント作成に取り組む際のアプローチを模倣する反復的なワークフローに従います。

図 2：理解、生成、検証、変換、公開の各フェーズにわたる反復型アジェンティック・ワークフロー

フェーズ 1（理解）: エージェントは Amazon S3 からソースコードを取得し、コードベースをスキャンして全体構造を理解します。これにより、主要なコンポーネント、インターフェース、および関係性が特定されます。

フェーズ 2（生成）: アーキテクチャ図の各タイプについて、エージェントは Amazon Bedrock を通じて利用可能なファウンデーションモデルを使用して、分析結果に基づいて Mermaid ベースの UML を生成します。生成される図には、クラス図、シーケンス図、状態図、コンポーネント図、アクティビティ図が含まれます。

フェーズ 3：検証

各図を生成した後、エージェントは Mermaid の構文を検証します。エラーを検出した場合、エラーメッセージを分析して修正を加えた上で図を再生成します。

フェーズ 4：変換

検証が完了すると、エージェントは図を SVG フォーマットに変換し、Web ブラウザでの高品質な描画を実現します。

フェーズ 5：公開

エージェントは、アーティファクト、SVG ファイル、Mermaid ソースファイル、および図のメタデータを Amazon S3 の「Architecture Diagrams」バケットにアップロードします。

この反復的なアプローチにより、単発の API 呼び出しで得られる 65% の信頼性に対し、95% の信頼性を達成しています。これは、エージェントがエラーを自律的に検出・修正できるためです。

AWS CodePipeline の統合

このパイプラインは、コードコミットから公開されたドキュメントの生成、そしてナレッジベースへの取り込みまで、一連のワークフローを統括します：

version: 0.2

env:
  variables:
    SOURCE_BUCKET: "amzn-s3-demo-source-bucket1"
    DOCS_BUCKET: "amzn-s3-demo-source-bucket2"
    VECTOR_STORE_BUCKET: "amzn-s3-demo-destination-bucket"
    AGENT_ID: "agentcore-uml-agent"
    PROJECT_NAME: "MyDotNetService"
    KB_ID: "architecture-diagrams-kb"
    DATA_SOURCE_ID: "architecture-diagrams-source"
    AWS_REGION: "us-east-1"

phases:
  install:
    runtime-versions:
      python: 3.11
    commands:
      - pip install boto3 awscli
  pre_build:
    commands:
      # Package source code
      - zip -r source_code.zip src/
      # Upload to S3 for agent access
      - aws s3 cp source_code.zip s3://${SOURCE_BUCKET}/source_code.zip
  build:
    commands:
      # Invoke AgentCore agent - generates SVG, Mermaid, and metadata JSON
      - |
        python invoke_agentcore.py \
          --agent-id ${AGENT_ID} \
          --project-name ${PROJECT_NAME} \
          --s3-bucket ${SOURCE_BUCKET} \
          --s3-key source_code.zip \
          --output-dir uml_output \
          --region ${AWS_REGION}
      # Verify expected output structure before publishing
      - |
        echo "Verifying output structure..."
        ls -R uml_output/
        test -d uml_output/svg && echo "SVG directory found"
        test -d uml_output/mermaid && echo "Mermaid directory found"
        test -d uml_output/metadata && echo "Metadata directory found"
  post_build:
    commands:
      # Sync each artifact type independently to preserve structure
      # Using --size-only to avoid unnecessary overwrites on unchanged files
      - aws s3 sync uml_output/svg/ s3://${DOCS_BUCKET}/svg/ --size-only
      - aws s3 sync uml_output/mermaid/ s3://${DOCS_BUCKET}/mermaid/ --size-only
      - aws s3 sync uml_output/metadata/ s3://${DOCS_BUCKET}/metadata/ --size-only
      # Wait for S3 eventual consistency before triggering ingestion
      - sleep 5
      # Trigger Amazon Bedrock Knowledge Bases ingestion after all files are uploaded
      - |
        python trigger_kb_sync.py \
          --knowledge-base-id ${KB_ID} \
          --data-source-id ${DATA_SOURCE_ID} \
          --region ${AWS_REGION}

artifacts:
  files:
    - uml_output/**/*

実行には AWS CodeBuild が使用され、必要な依存関係を備えた一貫した環境が提供されます。AWS Identity and Access Management (IAM) ロールにより、パイプラインは AWS CodeCommit へのアクセス、AgentCore の呼び出し、Amazon S3 への公開、および Amazon Bedrock ナレッジベースの取り込みトリガーを実行する権限を取得します。公開ステップの後、インジェクションジョブが更新された出力をナレッジベースに取り込むため、コードの変更ごとにセマンティック検索インデックスが最新の状態に保たれます。

出力フォーマット

本ソリューションは複数の出力形式を生成します。SVG 図形は高品質でスケーラブルなベクターグラフィックを提供し、Mermaid ソースファイルはバージョン管理可能な編集可能な図定義を記述します。また、メタデータ JSON ファイルは Amazon Bedrock Knowledge Bases のセマンティック検索層を駆動し、自然言語による図形の発見を可能にします。

知識ベースの設定とプレゼンテーションレイヤー

本ソリューションでは、完全マネージド型の RAG（Retrieval-Augmented Generation）機能である Amazon Bedrock Knowledge Bases を統合し、セマンティック検索層として機能させます。これにより、静的な図形をコードベースと同期するクエリ可能な知識システムへと変換します。

生成された各図形に対して、エージェントは SVG ファイルや Mermaid ファイルと同じく「Architecture Diagrams」バケット内に保存される、対応するメタデータファイルも作成します。

{
  "diagram_type": "sequence",
  "title": "Message Publishing Flow",
  "description": "End-to-end message publishing sequence including connection establishment, channel creation, and broker confirmation.",
  "entities": ["Publisher", "ConnectionManager", "Channel", "RabbitMQ Broker"],
  "mermaid_source": "sequenceDiagram\n Publisher->>ConnectionManager: GetConnection()...",
  "svg_s3_uri": "s3://amzn-s3-demo-source-bucket2/svg/3-sequence-diagram-publish.svg",
  "source_repository": "my-dotnet-service",
  "generated_at": "2025-01-15T10:30:00Z"
}

知識ベースの設定

知識ベースは以下の 3 つのコンポーネントで構成されます。

データソース: Amazon S3 の「Architecture Diagrams」バケットを使用し、インデックス対象をメタデータの metadata/ プレフィックスと Mermaid ソースの mermaid/ プレフィックスに限定します。これにより、生の SVG バイナリデータではなく、図形の説明やソース定義など意味的に豊かなコンテンツのみを対象とします。

埋め込みモデル: Amazon Titan Text Embeddings v2 を採用し、1,024 次元のベクトルを生成します。チャンクあたり最大 8,192 トークンをサポートしており、図形の内容を高品質なセマンティック表現として捉えることができます。

ベクターストア: ベクターストアのバックエンドには Amazon S3 を利用し、専用のベクター