用 Amazon Bedrock AgentCore 搭建高精度 AI 代码审查 Agent——Baz 的实战拆解

Spec Document ──► AgentCore Orchestrator
                      │
                      ├── Step 1: SpecParser Tool → 提取条目清单
                      ├── Step 2: CodeFetcher Tool → 按条目拉取相关代码片段
                      ├── Step 3: ClauseValidator Tool → 逐条比对并记录结果
                      └── Step 4: ReportGenerator → 汇总结构化报告
                      │
                 Amazon Bedrock (Claude 3.5 Sonnet)

# agent_spec_review.py
# 前置依赖：pip install boto3 agentcore-sdk
# 需要 AWS 凭证配置（~/.aws/credentials 或环境变量）
# 需要 Amazon Bedrock 模型访问权限（Claude 3.5 Sonnet）

import boto3
from agentcore_sdk import Agent, Tool, ToolInput

# ---- 工具定义 ----

class SpecParserInput(ToolInput):
    spec_text: str  # 需求文档原文

@Tool(name="SpecParser", description="从需求文档中提取可验证的条目清单")
def parse_spec(input: SpecParserInput) -> dict:
    """
    实际生产中这里会调用 Bedrock 做结构化提取，
    示例用简化逻辑演示流程。
    """
    # 将 spec 拆分为条目列表（生产环境用 LLM 提取）
    clauses = [
        {"id": "C1", "text": "用户登录必须使用 OAuth2.0"},
        {"id": "C2", "text": "密码长度不少于 12 位"},
        {"id": "C3", "text": "登录失败需记录审计日志"},
    ]
    return {"clauses": clauses, "total": len(clauses)}


class CodeFetcherInput(ToolInput):
    clause_id: str       # 要验证的条目 ID
    repo_path: str       # 代码仓库本地路径

@Tool(name="CodeFetcher", description="根据条目关键词拉取相关代码片段")
def fetch_code(input: CodeFetcherInput) -> dict:
    """
    生产环境会做语义搜索（如向量检索），
    示例用关键词匹配简化。
    """
    # 模拟：根据 clause_id 返回相关代码片段
    code_snippets = {
        "C1": "auth/oauth_login.py: def oauth2_login(client_id, redirect_uri): ...",
        "C2": "auth/password_policy.py: MIN_PASSWORD_LENGTH = 12",
        "C3": "auth/audit_logger.py: def log_failed_attempt(user_id, timestamp): ...",
    }
    return {
        "clause_id": input.clause_id,
        "snippet": code_snippets.get(input.clause_id, "未找到相关代码"),
    }


class ClauseValidatorInput(ToolInput):
    clause: dict     # 条目详情
    code_snippet: str  # 对应代码片段

@Tool(name="ClauseValidator", description="比对单条需求与代码实现，判定覆盖状态")
def validate_clause(input: ClauseValidatorInput) -> dict:
    """
    生产环境调用 Bedrock 做语义比对，
    示例用关键词包含判断简化。
    """
    clause_text = input.clause["text"]
    snippet = input.code_snippet

    # 简化判定逻辑（实际应由 LLM 语义判断）
    keywords = clause_text.lower().split()
    matched = any(kw in snippet.lower() for kw in keywords if len(kw) > 3)

    status = "COVERED" if matched else "MISSING"
    return {
        "clause_id": input.clause["id"],
        "clause_text": clause_text,
        "status": status,
        "evidence": snippet,
    }


# ---- Agent 定义 ----

bedrock_client = boto3.client("bedrock-runtime", region_name="us-east-1")

spec_review_agent = Agent(
    name="SpecReviewAgent",
    model_id="anthropic.claude-3-5-sonnet-20241022-v2:0",
    instruction=(
        "你是一个代码规格审查 Agent。工作流程：\n"
        "1. 调用 SpecParser 从需求文档提取条目清单\n"
        "2. 对每条条目，调用 CodeFetcher 拉取相关代码\n"
        "3. 对每条条目，调用 ClauseValidator 比对验证\n"
        "4. 汇总所有条目结果，输出结构化审查报告\n"
        "报告格式：每条列出 id、状态(COVERED/MISSING/PARTIAL)、证据代码位置。\n"
        "最后给出覆盖率百分比和缺失条目清单。"
    ),
    tools=[parse_spec, fetch_code, validate_clause],
    bedrock_client=bedrock_client,
)

# ---- 运行 ----

if __name__ == "__main__":
    spec_text = """
    需求文档 v2.3：
    - 用户登录必须使用 OAuth2.0
    - 密码长度不少于 12 位
    - 登录失败需记录审计日志
    """

    result = spec_review_agent.run(
        input_text=f"请审查以下需求文档与代码的覆盖情况：\n{spec_text}",
        # 传入代码仓库路径供 CodeFetcher 使用
        context={"repo_path": "/path/to/your/repo"},
    )

    print(result.output)

# cloudformation-snippet.yaml
# AgentCore Agent 的基础设施定义（简化版）

Resources:
  SpecReviewAgent:
    Type: AWS::Bedrock::Agent
    Properties:
      AgentName: spec-review-agent
      FoundationModelId: anthropic.claude-3-5-sonnet-20241022-v2:0
      Instruction: !Ref AgentInstructionText  # 上述 instruction 内容
      AgentResourceRoleArn: !GetAtt AgentRole.Arn

  SpecParserAction:
    Type: AWS::Bedrock::AgentActionGroup
    Properties:
      AgentId: !Ref SpecReviewAgent
      ActionGroupName: SpecParser
      ActionGroupExecutor:
        Lambda: !GetAtt SpecParserLambda.Arn
      FunctionSchema:
        Functions:
          - Name: parseSpec
            Description: 从需求文档提取条目清单
            Parameters:
              specText:
                Type: string
                Required: true
                Description: 需求文档原文

  AgentRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: bedrock.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AmazonBedrockFullAccess