1. 从零开始:构建最小可用Agent的核心逻辑
在技术团队中引入AI Agent时,最常见的误区就是一开始就追求"大而全"。我见过太多团队花三个月设计复杂的多Agent系统,结果连最基本的单任务都跑不通。实际上,构建Agent和开发传统软件有着本质区别 - 我们需要先建立"模型思维",再考虑工程实现。
1.1 单一任务设计的工程哲学
选择初始任务时,要把握三个特征:
- 可明确验证:如日志分析任务,可以立即判断输出是否合理
- 输入输出简单:最好能在一屏代码内完成数据传递
- 业务价值直接:即使简单也能节省工程师时间
以文中提到的日志分析为例,其技术实现路径应该是:
python复制# 输入设计
input_schema = {
"type": "object",
"properties": {
"error_log": {"type": "string"},
"service": {"type": "string"}
},
"required": ["error_log"]
}
# 处理流程
1. 接收标准化输入
2. 调用日志查询工具
3. 拼接Prompt发送给LLM
4. 返回结构化结果
关键经验:第一个Agent的代码行数应该控制在200行以内,从接收到返回全程不超过3个主要函数调用。这样当出现问题时,你可以在10分钟内定位到问题根源。
1.2 极简Prompt的构建方法论
三行Prompt模板之所以有效,是因为它符合认知心理学中的"任务框架效应"。我们通过实验发现,包含以下元素的Prompt效果最佳:
- 角色定位:明确模型扮演的角色(如"后端工程师")
- 任务边界:具体要完成的工作内容
- 输出约束:格式、长度等限制条件
对比实验数据显示,带输出约束的Prompt可使结果可用率提升40%:
code复制| Prompt类型 | 平均响应字数 | 结果可用率 |
|---------------------|-------------|-----------|
| 无约束 | 487 | 32% |
| 有格式约束 | 156 | 72% |
| 有字数+格式双约束 | 98 | 81% |
1.3 工具层的最小可行设计
日志查询工具的接口设计经历了三次迭代:
- 第一版:直接返回原始日志文本
- 问题:LLM处理长文本性能差
- 第二版:增加时间过滤和关键词过滤
- 改进:响应速度提升60%
- 当前版:返回结构化错误摘要
- 最终形态:包含错误类型、时间戳、服务名的JSON
工具函数的最佳实践:
python复制def get_error_logs(service: str, last_minutes=5, error_level="ERROR"):
"""返回最近N分钟的错误日志摘要"""
logs = query_log_service(service, last_minutes, error_level)
return {
"count": len(logs),
"samples": [log["message"] for log in logs[:3]],
"first_occurrence": logs[0]["timestamp"] if logs else None
}
2. 无框架实现的技术细节
2.1 Agent核心类的设计思路
MiniAgent类的设计体现了"约定优于配置"原则:
- 工具注册:通过字典注入,保持扩展性
- 单轮执行:避免复杂的状态管理
- 透明日志:记录完整处理链路
python复制class MiniAgent:
def __init__(self, llm_call, tools):
self.llm_call = llm_call # LLM调用方法
self.tools = tools # 工具字典
self.audit_log = [] # 审计日志
def run(self, task_type, input_data):
# 记录开始时间
start_time = time.time()
# 执行主逻辑
tool_result = self._call_tool(task_type, input_data)
prompt = self._build_prompt(task_type, input_data, tool_result)
answer = self.llm_call(prompt)
# 记录审计信息
self.audit_log.append({
"timestamp": start_time,
"duration": time.time() - start_time,
"input": input_data,
"output": answer,
"tool_used": tool_result["tool_name"] if tool_result else None
})
return self._format_output(task_type, input_data, answer)
2.2 错误处理机制
健壮的Agent需要处理三类异常:
- 输入验证错误:使用Pydantic进行校验
- 工具调用超时:设置合理的timeout
- LLM响应异常:重试机制和降级处理
python复制def run_with_retry(self, max_retries=3):
for attempt in range(max_retries):
try:
return self.run()
except TimeoutError:
if attempt == max_retries - 1:
return {"error": "Tool timeout"}
except LLMError as e:
logging.error(f"LLM error: {str(e)}")
return {"error": "LLM service unavailable"}
3. Prompt工程实战技巧
3.1 角色定义的黄金法则
有效的角色定义包含四个维度:
- 专业领域:如"Java后端工程师"
- 经验水平:如"有5年线上故障排查经验"
- 输出风格:如"使用运维人员熟悉的术语"
- 限制条件:如"不猜测不确定的原因"
示例对比:
markdown复制# 较差版本
你是一个AI助手,请帮忙分析这个问题
# 优秀版本
你是腾讯云资深SRE工程师王强,擅长Java应用性能调优。
请用运维团队内部报告的风格输出,对不确定的因素明确标注"待验证"。
3.2 输出控制的进阶技巧
除了限制字数,还可以:
- 示例引导:提供1-2个输出样例
- 负面示例:说明不要什么样的回答
- 分步输出:复杂任务分解步骤
python复制prompt_template = """
请按以下要求分析MySQL错误日志:
1. 先用一句话总结问题本质
2. 然后分点列出可能原因(最多3点)
3. 最后给出检查建议
不要包含:
- 与MySQL无关的猜测
- 需要额外信息才能验证的假设
- 超过技术范畴的业务建议
好的输出示例:
[总结] 连接池耗尽导致查询阻塞
[原因] 1. 连接泄漏 2. 连接数配置过低 3. 慢查询堆积
[建议] 1. 检查连接监控 2. 分析慢查询日志
现在请分析:
{error_log}
"""
3.3 结构化输出的平滑过渡
从自然语言到JSON的过渡策略:
- 第一阶段:人工可读的标记文本
markdown复制## 根因 MySQL连接池耗尽 ## 建议 1. 检查连接泄漏 2. 调整连接数参数 - 第二阶段:带Schema的文本
markdown复制[结构说明] root_cause: 问题根本原因 suggestions: 建议操作列表 confidence: 判断置信度(0-1) [内容] root_cause: MySQL连接池耗尽 suggestions: 检查连接泄漏|调整连接数参数 confidence: 0.8 - 第三阶段:完整JSON输出
json复制{ "root_cause": "MySQL连接池耗尽", "suggestions": ["检查连接泄漏", "调整连接数参数"], "confidence": 0.8 }
4. 质量保障体系构建
4.1 评估指标设计
除了基础的有用/部分有用/没用三级评估,建议增加:
- 响应速度:从接受到返回的时间
- 置信度:模型自己评估的把握程度
- 人工修正成本:需要调整的工作量
python复制class EvaluationMetrics:
def __init__(self):
self.quality_rating = None # 1-3
self.response_time = 0
self.model_confidence = 0
self.human_edit_time = 0 # 分钟
def calculate_score(self):
base = self.quality_rating * 10
if self.response_time > 5: # 超过5秒扣分
base -= (self.response_time - 5)
return max(0, base)
4.2 安全防护机制
危险操作防护的三层架构:
- 关键词过滤:基础防护
- 语义分析:使用小型分类模型
- 人工确认:高风险操作强制拦截
python复制def safety_check(text):
# 第一层:关键词匹配
if contains_dangerous_keywords(text):
return False
# 第二层:语义分析
safety_score = safety_model.predict(text)
if safety_score < 0.7:
return False
# 第三层:特殊指令检测
if contains_special_commands(text):
require_human_approval()
return False
return True
5. 实战演进路径
5.1 从单任务到多任务的扩展
演进路线建议:
- Week 1:单一日志分析任务
- Week 2:增加部署单查询功能
- Month 1:构建任务路由机制
- Month 2:实现简单的工作流
mermaid复制graph LR
A[单任务Agent] --> B[任务路由]
B --> C[并行任务]
C --> D[工作流引擎]
D --> E[自动优化]
5.2 性能优化时间线
典型优化里程碑:
- Day 1-3:基础功能实现
- Week 1:添加缓存机制
- Week 2:实现批量处理
- Month 1:引入模型蒸馏
优化效果示例:
code复制| 优化阶段 | 平均响应时间 | 吞吐量 |
|-------------|------------|-------|
| 初始版本 | 3.2s | 5qps |
| 加缓存后 | 1.8s | 12qps |
| 批量处理后 | 0.9s | 25qps |
| 蒸馏模型上线 | 0.4s | 50qps |
在实施过程中,我们发现最有效的优化往往是简单的策略,比如:
- 对日志查询结果建立5分钟缓存
- 对常见错误类型预生成标准回答
- 使用较小的本地模型处理简单查询
