Bedrock AgentCore自动生成代码架构图并维护文档库

架构文档一直是软件开发中最为持久的挑战之一，因为代码库演进迅速。开发团队常常花费数小时手动创建架构图，然而这些文档在部署后几周内就会过时。这种文档缺口造成了知识孤岛，拖慢了开发者 onboarding 的速度，并使合规审计变得复杂。

Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化 AI 智能体的平台，支持任何框架或模型。它通过自主 AI 智能体提供解决方案，能够分析代码库、自动生成架构图并维护可搜索的文档。这种智能体化方法使用迭代式优化和自我修正来协调代码分析、图生成以及通过 AWS 服务的自动化发布。

在这篇文章中，你将了解到一家全球性交易商经纪商如何构建了一个自动化架构文档流水线，该流水线与现有的 CI/CD 工作流集成。该解决方案结合了用于代码分析的 AgentCore、用于语义搜索功能的 Amazon Bedrock Knowledge Bases，以及用于持续部署的 AWS CodePipeline。我们与一家专注于主要金融市场的交易商经纪业务的全球金融服务公司开发和验证了这种方法，该方案自 2026 年第一季度起已在生产环境中运行，用于维护其电子交易平台的架构文档。

架构文档的挑战

开发团队在架构文档方面面临几个关键痛点：

手动流程耗时巨大——使用 UML 或 Mermaid 等格式创建全面的架构图需要大量劳动。对于大型代码库，这变得难以为继。

快速过时——代码每天都在变化，但文档更新滞后。几周之内，图表就不再反映实际情况，使其成为决策的不可靠依据。

知识孤岛——当团队成员离开时，部落知识（tribal knowledge）随之消失。遗留系统变成"黑箱"，迫使新开发者反向工程代码，拖慢了 onboarding 并削弱了组织知识。

合规缺口——安全审查和审计需要最新的架构图。过时的文档造成合规风险并延迟认证。

在微服务架构中，这些挑战会更加严重，因为理解服务依赖关系和消息流对于防止级联故障至关重要。

我们的解决方案使用 AgentCore 创建一个自主 AI 智能体，分析 .NET 代码库并生成全面的架构图。该智能体在 AWS CodePipeline 中运行，在代码提交到 AWS CodeCommit 仓库时触发。然后生成的图表及其元数据被摄入 Amazon Bedrock Knowledge Bases，以支持对完整架构文档的语义搜索和自然语言查询。这使你能更清晰地了解架构的当前状态，并从这种可见性中解锁业务价值。

该解决方案集成了多个 AWS 服务以提供精简的工作流：

以下架构图展示了从将代码推送到 AWS CodeCommit 到图生成再到摄入 Amazon Bedrock Knowledge Bases 的完整系统设计。

图 1：从 AWS CodeCommit 到图生成再到 Amazon Bedrock Knowledge Bases 摄入的完整系统设计

该工作流涉及以下步骤：

1. 开发者将代码变更推送到 AWS CodeCommit。
2. AWS CodeCommit 触发 AWS CodePipeline 执行。
3. AWS CodePipeline 启动构建流程。
4. AWS CodeBuild 从 AWS CodeCommit 仓库获取代码，然后将源代码打包并上传到 Amazon S3 源代码桶。
5. AWS CodeBuild 调用 AgentCore。它准备调用载荷并调用 AgentCore 托管的 Strands 智能体。该智能体使用通过 Amazon Bedrock 提供的大语言模型作为推理引擎来分析代码模式、生成图语法并自我修正验证错误。有关各区域的模型可用性，请参阅 Amazon Bedrock 中的按 AWS 区域划分的支持模型。
6. Strands 智能体从 Amazon S3 获取源代码。
7. Strands 智能体扫描代码库、生成图、验证语法并将图转换为 SVG 文件以进行迭代优化。
8. Strands 智能体将制品上传到 Amazon S3 Architecture Diagrams 桶，包括渲染后的 SVG 文件、Mermaid 源文件以及图描述元数据（JSON）。
9. Amazon Bedrock Knowledge Bases 从 Amazon S3 Architecture Diagrams 桶摄入图制品。摄入流水线使用 Amazon Titan Text Embeddings v2 模型生成向量嵌入，应用分块将图描述和 Mermaid 源分段为语义上有意义的单元，并将生成的向量存储在 Amazon S3 向量存储中。这支持对完整架构文档的语义搜索和检索增强生成（RAG）。
10. 开发者和利益相关者通过自然语言查询知识库，以发现、探索和检索相关架构图及其上下文说明：例如，问"重连活动流是什么样的？"或"列出基础设施组件的所有类图"。

代码分析与优先级排序

智能体首先分析代码库结构。它不是处理每个文件，而是专注于生产代码，同时排除测试文件、构建产物和生成代码。这种优先级排序减少了处理时间并提高了图的相关性。

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：跨理解、生成、验证、转换和发布阶段的迭代式智能体工作流

Phase 1 – 理解：智能体从 Amazon S3 获取源代码并扫描代码库以理解整体结构，识别关键组件、接口及其关系。

Phase 2 – 生成：对于每种架构图类型，智能体利用 Amazon Bedrock 提供的基础模型，根据其分析生成基于 Mermaid 的 UML 图。这些图包括类图、时序图、状态图、组件图和活动图。

Phase 3 – 验证：生成每个图之后，智能体会验证 Mermaid 语法。如果检测到错误，智能体会分析错误信息并重新生成带有修正的图。

Phase 4 – 转换：验证通过后，智能体将图转换为 SVG 格式，以便在 Web 浏览器中高质量渲染。

Phase 5 – 发布：智能体将产物、SVG 文件、Mermaid 源文件和图元数据上传到 Amazon S3 Architecture Diagrams 存储桶。

这种迭代方法达到了 95% 的可靠性，而单次 API 调用的可靠性仅为 65%，原因是智能体能够自主检测并纠正错误。

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 Knowledge Bases 摄取的权限。在发布步骤之后，摄取作业将更新的输出摄取到知识库中，使语义搜索索引与每次代码变更保持同步。

该解决方案生成多种输出格式。SVG 图提供高质量、可伸缩的矢量图形。Mermaid 源文件提供版本控制的、可编辑的图定义。元数据 JSON 文件为 Amazon Bedrock Knowledge Bases 语义搜索层提供支持，实现通过自然语言发现图。

知识库配置和展示层

该解决方案集成了 Amazon Bedrock Knowledge Bases——完全托管的 RAG 能力——作为语义检索层，将静态图转换为可查询的知识系统，并与代码库保持同步。

对于每个生成的图，智能体还会创建一个配套的元数据文件，与 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"
}

知识库配置了三个组件：

数据源：Amazon S3 Architecture Diagrams 存储桶，限定于 metadata/ 和 mermaid/ 前缀，仅索引语义丰富的内容如图描述和源定义，而非原始 SVG 二进制数据。

嵌入模型：Amazon Titan Text Embeddings v2 生成 1024 维向量，每块最多支持 8,192 个词元，为图内容提供高质量的语义表示。

向量存储：Amazon S3 作为向量存储后端，无需单独的向量数据库，与该解决方案的无服务器架构理念一致。

分块策略：采用层级分块，1,500 词元的父块用于完整图上下文，300 词元的子块用于细粒度实体级检索。通过此策略，知识库根据查询返回完整图描述或关于特定实体的聚焦响应。

摄取完成后，开发者可以通过 Amazon Bedrock 控制台、Amazon Bedrock AgentCore 或使用 RetrieveAndGenerate API 的自定义应用程序，使用自然语言查询知识库。例如，查询"系统使用了什么重连策略？"会返回带有指数退避描述的活动图。

知识库在每次流水线运行时刷新，使结果与代码库变更保持同步。

了解成本结构有助于规划文档自动化策略。有关当前定价，请参阅 Amazon Bedrock 定价。要估算特定用量的成本，请使用 AWS Pricing Calculator。以下定价估算基于 2026 年 5 月的费率。

每个代码库的成本细分

对于包含约 1,500 个文件的中型代码库，成本细分如下。Amazon Bedrock 模型推理调用取决于所选模型和词元使用量。请参阅 AWS Pricing Calculator 获取估算。

输入词元：约 29,000 词元。

输出词元：约 10,000 词元。

每次生成总计：约 $0.24。

AWS CodePipeline：每个活跃流水线每月 $1.00（第一个流水线免费） AWS CodeBuild：每构建分钟 $0.005 × 5 分钟 = 每次执行 $0.025 Amazon S3 存储：文档产物的存储成本可忽略不计（通常低于 10 MB）

Amazon Bedrock Knowledge Bases：摄取成本基于 Amazon Titan Text Embeddings v2 的词元使用量进行嵌入生成。对于七个图生成的元数据 和 Mermaid 文件，嵌入成本通常在每次摄取运行 $0.01 以下。Amazon S3 向量存储成本可忽略不计。

每次生成的总成本：约 $0.28。

多代码库投影

对于拥有多个代码库的组织，每周文档更新的成本按线性比例扩展：

5 个代码库：$1.40/周 → $5.60/月。

20 个代码库：$5.60/周 → $22.40/月。

50 个代码库：$14.00/周 → $56/月。

100 个代码库：$28.00/周 → $112.00/月。

投资回报率（ROI）在将自动化文档与手动替代方案进行比较时变得清晰：

图 3：自动化文档与手动文档的投资回报率对比

对于拥有 20 个代码库的组织，每年可节省 $2,000–$8,000 的开发者时间。此外，通过 Amazon Bedrock Knowledge Bases 实现可发现的最新文档可以改善入职流程、合规性和架构决策。

本节将引导您在自己的 AWS 环境中部署该解决方案。我们涵盖先决条件、部署步骤和关键配置细节，使流水线能够针对您的代码库运行。

在部署解决方案之前，请确保以下 AWS 服务已启用、权限已配置、技术储备已就位。

AWS 账户设置：确保您的 AWS 账户可以访问 Amazon Bedrock，且目标区域（推荐 us-east-1 以确保模型可用）已启用 Claude Sonnet 和 Amazon Titan Text Embeddings v2。

IAM 权限：为 AWS CodePipeline 创建一个 AWS IAM 角色，授予以下权限：

AWS CodeCommit 仓库访问权限。

AWS CodeBuild 项目执行权限。

AgentCore 调用权限。

Amazon Bedrock Knowledge Bases 的 StartIngestionJob 和 Retrieve 操作权限。

Amazon S3 存储桶的读写权限（源代码、图表和向量存储桶）。

Amazon CloudWatch Logs 创建权限。

AWS Cloud Development Kit（AWS CDK）引导：cdk bootstrap aws://ACCOUNT_ID/us-east-1。

技术技能（300–400 级要求）：

.NET 代码库：您需要熟悉标准 .NET 项目结构和常见编码模式。

CI/CD 流水线：您需要基本了解自动化构建和部署流水线（最好使用 AWS CodePipeline）。

AWS CDK：您需要具备使用 AWS CDK 部署基础设施即代码的经验。

架构可视化：您需要能够熟练解读技术图表和架构模式。

仓库结构：该解决方案最适合遵循标准 .NET 项目约定的代码库，源代码位于 src/ 目录中，生产代码和测试代码有清晰的区分。

前提条件就绪后，请按以下步骤部署端到端流水线。每个步骤都建立在前一个步骤之上，因此请按顺序完成。

部署 AgentCore 智能体：使用 AgentCore CLI 将您的智能体代码打包并部署到 AWS。

# Package the agent
agentcore package \
  --agent-name architecture-diagram-agent \
  --entry-point agent/main.py \
  --requirements requirements.txt \
  --output-dir ./build

# Deploy the agent to AgentCore
agentcore deploy \
  --agent-name architecture-diagram-agent \
  --package ./build/agent.zip \
  --role-arn arn:aws:iam::<ACCOUNT_ID>:role/AgentCoreExecutionRole \
  --region us-east-1

创建 AWS CodePipeline：配置包含 source、build 和 deploy 阶段的流水线，连接到您的 AWS CodeCommit 仓库。

# Create the CodeCommit repository (if not already created)
aws codecommit create-repository \
  --repository-name architecture-diagram-repo \
  --repository-description "Source repo for architecture diagram pipeline"

# Create the CodePipeline (using a JSON input file)
aws codepipeline create-pipeline --cli-input-json file://pipeline-definition.json

# The pipeline-definition.json should define Source (CodeCommit),
# Build (CodeBuild), and Deploy (S3) stages. For the full JSON
# structure, see the AWS CodePipeline documentation.

配置 Amazon S3 存储桶：创建用于源代码暂存和文档托管的存储桶，并设置适当的生命周期策略。

# Create the source code staging bucket
aws s3api create-bucket \
  --bucket amzn-s3-demo-source-bucket1 \
  --region us-east-1

# Create the documentation/diagrams hosting bucket
aws s3api create-bucket \
  --bucket amzn-s3-demo-source-bucket2 \
  --region us-east-1

# Enable versioning
aws s3api put-bucket-versioning \
  --bucket amzn-s3-demo-source-bucket1 \
  --versioning-configuration Status=Enabled

# Add lifecycle policy to expire old versions after 90 days
aws s3api put-bucket-lifecycle-configuration \
  --bucket amzn-s3-demo-source-bucket1 \
  --lifecycle-configuration '{
    "Rules": [{
      "ID": "ExpireOldVersions",
      "Status": "Enabled",
      "NoncurrentVersionExpiration": {"NoncurrentDays": 90},
      "Filter": {"Prefix": ""}
    }]
  }'

创建 Amazon Bedrock Knowledge Bases：配置一个 Knowledge Base，以 Amazon S3 Architecture Diagrams 存储桶作为数据源（限定 metadata/ 和 mermaid/ 前缀），以 Amazon Titan Text Embeddings v2 作为嵌入模型，以 Amazon S3 作为向量存储。设置分层分块，父块 1,500 token，子块 300 token。

# Create the Knowledge Base
aws bedrock-agent create-knowledge-base \
  --name architecture-diagrams-kb \
  --role-arn arn:aws:iam::<ACCOUNT_ID>:role/BedrockKnowledgeBaseRole \
  --knowledge-base-configuration '{
    "type": "VECTOR",
    "vectorKnowledgeBaseConfiguration": {
      "embeddingModelArn": "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0"
    }
  }' \
  --storage-configuration '{
    "type": "S3",
    "s3Configuration": {
      "bucketArn":