用 AgentCore 把代码自动做成架构图
本文说明如何用 AgentCore 分析 .NET 代码、经 CodePipeline 生成 UML 与 SVG,并写入知识库,同时给出令牌成本与多仓库投资回报。

目录
#用 AgentCore 把代码自动做成架构图
架构文档仍然是软件开发中最顽固的难题之一,因为代码库演进很快。开发团队常常花数小时手工绘制架构图,却在部署后几周内眼看它们过时。这种文档缺口会造成知识孤岛,拖慢开发者上手,并让合规审计更复杂。
Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化智能体的平台,不限定框架或模型。它通过自主智能体提供一套办法:分析代码库、生成架构图,并自动维护可搜索的文档。这种智能体方法使用迭代细化与自我纠正,通过 AWS 服务协调代码分析、图表生成和自动发布。
在本文中,你将了解一家全球银行间经纪商如何构建一条自动化架构文档流水线,并接入现有的持续集成与持续交付(CI/CD)工作流。该方案把用于代码分析的 AgentCore、用于语义搜索的 Amazon Bedrock Knowledge Bases,以及用于持续部署的 AWS CodePipeline 组合在一起。我们与一家专注于主要金融市场银行间经纪业务的全球金融服务公司一起开发并验证了这种方法。自 2026 年第一季度起,它已在生产环境中运行,为其电子交易平台维护架构文档。
架构文档的难题
开发团队在架构文档上面临几项关键痛点:
- 耗时的手工过程:用统一建模语言(UML)或 Mermaid 等格式制作完整架构图,劳动强度很高。对大型代码库,这变得不可持续。
- 迅速过时:代码每天都在变,文档更新却滞后。几周之内,图就不再反映现实,无法可靠地用于决策。
- 知识孤岛:团队成员离开后,只存在于少数人头脑中的知识就消失了。遗留系统变成“黑盒”,迫使新开发者逆向工程代码,拖慢上手并降低组织知识。
- 合规缺口:安全评审和审计需要当前的架构图。过时文档会造成合规风险并延误认证。
在微服务架构中,这些问题会叠加,因为理解服务依赖和消息流对于防止级联故障至关重要。
方案概览
我们的方案使用 AgentCore 创建一个自主智能体,分析 .NET 代码库并生成完整的架构图。智能体运行在 AWS CodePipeline 内,在代码提交到 AWS CodeCommit 仓库时触发。生成的图及其元数据随后被接入 Amazon Bedrock Knowledge Bases,以支持对全部架构文档语料的语义搜索和自然语言查询。这让你更清楚地看到架构的当前状态,并从这种可见性中释放业务价值。
关键组件
该方案集成多项 AWS 服务,以交付一条顺畅的工作流:
| 服务名称 | 职责 |
|---|---|
| Amazon Bedrock AgentCore | 为我们的自主文档智能体提供无服务器运行时环境。AgentCore 负责智能体生命周期管理、自动扩缩和工具编排,无需管理基础设施。 |
| AWS CodePipeline | 编排从代码提交到已发布文档的端到端工作流。流水线直接与 AWS CodeCommit 集成,在每次推送到主分支时触发生成文档。 |
| Amazon Simple Storage Service(Amazon S3) | 存储生成的图并托管文档网站,提供持久存储和全局可访问性。一个专用的架构图存储桶保存可缩放矢量图形(SVG)文件、Mermaid 源文件和图元数据。Amazon S3 也作为 Amazon Bedrock Knowledge Bases 的向量存储后端。 |
| AWS CodeBuild | 执行流水线阶段,包括依赖安装、智能体调用和产物准备。 |
| Amazon Bedrock Knowledge Bases | 作为已生成架构文档的检索与呈现层。存储在 Amazon S3 中的图元数据、Mermaid 源文件和描述,使用 Amazon Titan Text Embeddings 模型接入知识库。以 Amazon S3 作为向量存储,它支持语义搜索和自然语言查询。 |
下面的架构图展示整体系统设计:从把代码推入 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 智能体把产物上传到 Amazon S3 架构图存储桶,包括渲染后的 SVG 文件、Mermaid 源文件和图描述元数据(JSON)。
- Amazon Bedrock Knowledge Bases 从 Amazon 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 架构图存储桶。
这种迭代方法达到 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 文件一起存放在架构图存储桶中。
{
"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 架构图存储桶,范围限定为 metadata/ 和 mermaid/ 前缀,只索引语义丰富的内容,如图描述和源定义,而不是原始 SVG 二进制数据。
嵌入模型: Amazon Titan Text Embeddings v2 生成 1,024 维向量,每个分块最多支持 8,192 个令牌(token),为图内容提供高质量语义表示。
向量存储: 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 变得可发现的最新文档,会改善上手、合规和架构决策。
PRIMARY_SOURCE: https://aws.amazon.com/blogs/machine-learning/from-code-to-diagrams-agentic-architecture-documentation-with-amazon-bedrock-agentcore
- #架构文档
- #AgentCore
- #CodePipeline
- #成本回报
- #UML


