AI Agent工程化实战：从单体到可控架构升级-代码聚汇网

AI Agent工程化实战：从单体到可控架构升级

昂图

1. 从单体到可控：MiniAgent架构升级实战

作为一位经历过多次AI Agent从原型到生产落地的工程师，我深知从0到1构建一个基础Agent只是万里长征第一步。今天要分享的是如何将一个基础版错误诊断Agent升级为更稳定、更可控的0.5版本——这个阶段往往决定了Agent项目能否真正存活下来。

1.1 初始架构的问题诊断

我们最初的MiniAgent设计极其简单：接收接口错误信息→拉取最近N分钟日志→生成三句话诊断结论。这种设计在验证阶段表现良好，但随着真实场景的深入，四个典型问题开始浮现：

输出不可控：自由格式的自然语言回答导致前端展示困难，不同模型版本输出风格差异大
安全无保障：偶尔会产生"重启服务"等危险建议，缺乏过滤机制
集成能力弱：业务方希望将有效诊断结果自动转化为工单，但当前架构不支持安全写入
调试黑洞：当用户反馈"昨天有个诊断结果不对"时，缺乏追踪手段

这些问题本质上都是工程化过程中必须解决的"最后一公里"问题。下面我将分步骤展示如何用最小改动解决这些痛点。

2. 结构化输出改造

2.1 双模输出设计

原始Agent直接输出自然语言，虽然人类可读性强，但机器处理困难。我们的改造目标是实现人机双模输出：

python复制{
    "human_readable": "【根因】数据库连接池耗尽\n【建议】1. 增加连接池大小\n2. 检查是否有连接泄漏\n【风险】高峰期可能导致请求堆积",
    "machine_readable": {
        "root_cause": "数据库连接池耗尽",
        "suggestion": ["增加连接池大小", "检查连接泄漏"],
        "risk": "高峰期请求堆积"
    }
}

这种设计带来三个显著优势：

前端可以解析JSON实现分栏展示
下游系统能直接消费结构化数据
保留自然语言便于人工复核

2.2 渐进式Prompt工程

直接要求模型输出JSON容易导致格式错误。我们采用两阶段训练法：

阶段一：结构化自然语言模板

markdown复制请按以下格式输出：
【根因】<一句话说明>
【建议】
1. <首要建议>
2. <次要建议|空>
【风险】<风险说明|无明显风险>

阶段二：JSON补充输出

python复制{
    "prompt": "在自然语言回答后，追加如下JSON：",
    "example": {
        "root_cause": "字符串",
        "suggestions": ["字符串1", "字符串2"],
        "risk": "字符串"
    },
    "constraints": [
        "禁用换行和注释",
        "键名严格匹配"
    ]
}

实测显示，这种渐进式训练能使GPT-4类模型的格式合规率从直接输出JSON时的65%提升到92%。

3. 安全与稳定性增强

3.1 输出清洗与兜底机制

即使有严格Prompt约束，模型输出仍可能出现：

JSON格式错误（多余逗号、单引号）
包含解释性文字
键名不匹配

我们实现了一个轻量级解析器：

python复制def safe_parse(json_str: str) -> dict:
    try:
        # 预处理：移除可能存在的代码注释
        cleaned = re.sub(r'//.*?$|/\*.*?\*/', '', json_str, flags=re.MULTILINE)
        # 处理单引号等非标准JSON
        normalized = cleaned.replace("'", '"')
        return json.loads(normalized)
    except json.JSONDecodeError:
        # 提取疑似JSON部分做二次尝试
        if match := re.search(r'\{.*\}', cleaned, re.DOTALL):
            return safe_parse(match.group())
        return {"error": "Invalid JSON"}

3.2 危险操作过滤

我们建立了分级关键词库：

python复制SAFETY_FILTERS = {
    "critical": ["drop table", "truncate", "reboot"],
    "warning": ["restart", "kill process"],
    "info": ["clear cache", "flush"]
}

def check_safety(text: str) -> dict:
    lower_text = text.lower()
    return {
        level: any(kw in lower_text for kw in keywords)
        for level, keywords in SAFETY_FILTERS.items()
    }

前端根据危险等级采取不同措施：

critical：隐藏建议并告警
warning：显示但添加确认步骤
info：正常展示但标记

4. 安全写操作设计

4.1 工单草稿模式

为避免直接写生产环境，我们设计了三层防护：

只允许创建状态为"draft"的工单
工单必须包含人工确认环节
所有写操作记录详细审计日志

python复制class TicketDraft(BaseModel):
    service: str = Field(..., max_length=50)
    root_cause: str = Field(..., max_length=500)
    suggestions: List[str] = Field(max_items=3)
    risk_assessment: str = Field("无显著风险")
    status: Literal["draft"] = "draft"
    created_by: Literal["agent"] = "agent"
    requires_review: bool = True

4.2 调用权限控制

通过装饰器实现权限管控：

python复制def require_confirm(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        if kwargs.get("user_confirmed", False):
            return func(*args, **kwargs)
        raise PermissionError("需要人工确认")
    return wrapper

@require_confirm
def create_ticket_draft(**data):
    # 实际创建逻辑

5. 可观测性增强

5.1 全链路追踪设计

我们采用分层trace方案：

每次调用生成唯一trace_id
关键步骤记录检查点
输入输出全量快照

python复制class AgentTracer:
    def __init__(self):
        self.traces = {}
        
    def start_span(self, operation: str):
        span_id = f"span_{uuid.uuid4().hex[:8]}"
        self.traces[span_id] = {
            "operation": operation,
            "start": time.time(),
            "end": None,
            "logs": []
        }
        return span_id
    
    def log(self, span_id: str, message: str, level: str = "info"):
        if span_id in self.traces:
            self.traces[span_id]["logs"].append({
                "timestamp": time.time(),
                "level": level,
                "message": message
            })

5.2 回放调试系统

基于trace数据构建的调试界面包含：

请求参数重现
中间结果查看
执行耗时分析
错误追溯

mermaid复制graph TD
    A[用户请求] --> B[Trace记录]
    B --> C[输入存储]
    B --> D[工具调用记录]
    B --> E[模型输出存储]
    C --> F[回放调试器]
    D --> F
    E --> F

6. 性能优化实践

6.1 结构化缓存策略

对常见错误模式建立缓存：

python复制class DiagnosisCache:
    def __init__(self, max_size=1000):
        self.cache = LRUCache(max_size)
        self.signature_fn = hashlib.md5
        
    def make_key(self, error_log: str) -> str:
        # 提取错误特征作为缓存键
        features = [
            re.search(r"ERROR\s\d+", error_log),
            re.search(r"at\s(.+?\.\w+)", error_log)
        ]
        return self.signature_fn("|".join(
            f.group() if f else "" for f in features
        ).encode()).hexdigest()

6.2 负载测试结果

在4核8G的实例上测试：

并发数	平均响应时间	错误率
10	1.2s	0%
50	2.8s	0%
100	4.5s	3%
200	8.1s	15%

建议生产环境控制在50并发以内。

7. 部署架构建议

7.1 最小生产配置

yaml复制services:
  agent:
    image: miniagent:v0.5
    ports:
      - "8000:8000"
    environment:
      LOG_LEVEL: "INFO"
      MAX_CONCURRENT: 50
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  redis_data:

7.2 监控指标设计

必备监控项包括：

模型调用P99延迟
工具调用成功率
输出解析失败率
危险建议触发次数
工单创建成功率

使用Prometheus示例配置：

yaml复制- name: agent_metrics
  metrics_path: /metrics
  static_configs:
    - targets: ['agent:8000']
  relabel_configs:
    - source_labels: [__address__]
      target_label: __param_target
    - source_labels: [__param_target]
      target_label: instance
    - target_label: __address__
      replacement: prometheus:9090

8. 演进路线规划

8.1 短期优化方向

增强解析器：引入JSON5支持更宽松的格式
丰富安全规则：建立正则模式匹配而不仅是关键词
模板多样化：根据不同错误类型适配输出结构

8.2 中长期演进

自动评估系统：基于历史trace构建效果评估闭环
多Agent协作：将诊断、修复建议拆分为独立Agent
知识库集成：自动将验证过的诊断结果转化为知识条目

这个0.5版本的核心价值在于：用20%的工程投入解决了80%的生产环境适配问题。在实际落地中，这类适度优化的MiniAgent往往比过度设计的复杂系统更容易产生持续价值。