1. 为什么需要AI Agent任务完成通知
当AI Agent完成预设任务后，如何及时获取执行结果？这个问题困扰着很多开发者。想象一下：你精心设计的Agent已经可以自动完成数据爬取、报表生成、系统监控等任务，但每次都需要手动登录服务器查看日志才能知道执行情况——这就像雇了个能干但沉默寡言的助手，干完活从不主动汇报。
传统解决方案通常有三种：
- 邮件通知：延迟高（可能进入垃圾箱），且不适合移动场景
- 短信提醒：成本高（每条收费），内容展示受限
- 自建Webhook：需要维护接收端服务，开发成本大
微信推送的独特优势在于：
- 即时到达（微信常驻内存）
- 高打开率（个人微信消息平均打开率超90%）
- 富文本支持（可带链接、图片、格式文本）
- 零成本（无需支付通道费用）
注意：个人微信没有官方机器人API，所有方案都基于逆向工程实现，存在一定封号风险。建议使用小号测试，避免主账号受到影响。
2. 微信推送服务的技术实现路径
2.1 核心架构设计
整个系统由三个模块组成：
- 任务监控模块：监听AI Agent的任务状态变更
- 消息处理模块：将任务结果转换为结构化消息
- 微信对接模块：通过微信协议推送消息
python复制# 伪代码示例：核心处理流程
def on_task_complete(task):
message = format_message(task) # 格式化消息内容
wechat_sender.send(
to_user="你的微信ID",
content=message,
msg_type="text" # 支持text/image/link等
)
2.2 微信协议选型对比
| 方案 | 稳定性 | 开发难度 | 封号风险 | 功能完整性 |
|---|---|---|---|---|
| 企业微信API | ★★★★★ | ★★☆☆☆ | ☆☆☆☆☆ | ★★★★☆ |
| 微信公众号模板消息 | ★★★★☆ | ★★★☆☆ | ☆☆☆☆☆ | ★★★☆☆ |
| Web微信协议模拟 | ★★☆☆☆ | ★★★★★ | ★★★☆☆ | ★★★★★ |
| 微信小程序云开发 | ★★★☆☆ | ★★★☆☆ | ☆☆☆☆☆ | ★★☆☆☆ |
经过实测，对于个人开发者而言，企业微信API+个人微信绑定是最稳妥的方案：
- 注册企业微信（免费）
- 创建自建应用获取AgentId/Secret
- 用个人微信绑定企业微信
- 通过官方API发送消息
bash复制# 企业微信API调用示例
curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=TOKEN" \
-H "Content-Type: application/json" \
-d '{
"touser": "UserID",
"msgtype": "text",
"agentid": 1000002,
"text": {"content": "你的AI任务已完成"}
}'
3. 实战：搭建企业微信推送服务
3.1 环境准备
需要准备：
- 企业微信管理员账号（免费注册）
- 实名认证的个人微信号
- 能访问公网的服务器（或云函数）
具体步骤：
- 登录企业微信后台
- 进入"应用管理" → "创建应用"
- 记录下三个关键参数：
- CorpID：企业标识
- AgentId：应用ID
- Secret：应用密钥
3.2 消息推送实现
Python实现示例：
python复制import requests
import json
class WeChatNotifier:
def __init__(self, corpid, corpsecret, agentid):
self.corpid = corpid
self.corpsecret = corpsecret
self.agentid = agentid
self.access_token = None
def _get_token(self):
url = f"https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={self.corpid}&corpsecret={self.corpsecret}"
resp = requests.get(url).json()
self.access_token = resp['access_token']
def send_text(self, content, to_user="@all"):
if not self.access_token:
self._get_token()
url = f"https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={self.access_token}"
payload = {
"touser": to_user,
"msgtype": "text",
"agentid": self.agentid,
"text": {"content": content},
"safe": 0
}
return requests.post(url, json=payload).json()
# 使用示例
notifier = WeChatNotifier(
corpid="wwxxxxxxxx",
corpsecret="xxxxxxxx",
agentid=1000002
)
notifier.send_text("AI Agent已完成数据分析任务\n结果已保存至：http://example.com/report")
3.3 消息模板优化技巧
好的通知消息应该包含：
- 任务名称（什么任务完成了）
- 执行状态（成功/失败）
- 关键数据（如耗时、记录数）
- 后续操作链接（如查看详情）
推荐格式：
code复制【任务完成通知】
任务名称：每日销售报表生成
执行状态：成功 ✅
任务耗时：2分15秒
处理数据：1,248条订单记录
报告查看：点击下载完整报表
生成时间：2023-08-20 09:30:15
4. 高级功能扩展
4.1 接收用户回复实现交互
企业微信支持消息回调，可以接收用户的回复消息：
- 在应用设置中配置回调URL
- 实现消息接收接口：
python复制from flask import Flask, request
app = Flask(__name__)
@app.route('/wechat/callback', methods=['POST'])
def handle_reply():
data = request.json
user_id = data['FromUserName']
reply_content = data['Content']
# 处理用户指令
if reply_content == "重新执行":
trigger_retry_task(user_id)
return {"code": 0}
return {"code": 1, "msg": "未知指令"}
4.2 消息卡片与富文本
除了纯文本，还支持更丰富的消息类型：
python复制def send_news(title, description, url, picurl):
payload = {
"touser": "@all",
"msgtype": "news",
"agentid": self.agentid,
"news": {
"articles": [{
"title": title,
"description": description,
"url": url,
"picurl": picurl
}]
}
}
# 发送逻辑同上
4.3 与AI Agent的深度集成
在Agent框架中添加通知模块：
python复制class TaskAgent:
def __init__(self, notifier):
self.notifier = notifier
def run_task(self, task_func):
try:
start = time.time()
result = task_func()
elapsed = time.time() - start
self.notifier.send_text(
f"任务执行成功\n耗时：{elapsed:.2f}s\n"
f"结果摘要：{str(result)[:100]}..."
)
return result
except Exception as e:
self.notifier.send_text(
f"任务执行失败\n错误类型：{type(e).__name__}\n"
f"错误详情：{str(e)}"
)
raise
5. 避坑指南与最佳实践
5.1 常见问题排查
消息发送失败可能原因：
- AccessToken过期（每2小时需要刷新）
- 用户未在企业微信激活
- 消息内容包含敏感词（如"红包"、"转账"等）
- 接口调用频率超限（默认每分钟最多200次）
解决方案：
python复制def safe_send(self, content, retry=3):
for i in range(retry):
try:
return self.send_text(content)
except Exception as e:
if "invalid token" in str(e):
self._get_token() # 刷新token
time.sleep(2**i) # 指数退避
raise Exception(f"发送失败，重试{retry}次后仍不成功")
5.2 安全防护建议
-
敏感信息脱敏：
python复制def sanitize_message(text): # 隐藏手机号、身份证等 text = re.sub(r'1[3-9]\d{9}', '<PHONE>', text) text = re.sub(r'[1-9]\d{5}(19|20)\d{2}[0-9Xx]', '<ID>', text) return text -
权限控制：
- 为不同Agent分配独立的企业微信应用
- 在代码中不要硬编码Secret
- 使用环境变量存储敏感信息
-
消息审计：
python复制def send_text(self, content): log_entry = { "timestamp": datetime.now().isoformat(), "content": sanitize_message(content), "receiver": to_user } write_audit_log(log_entry) # 写入数据库或文件 # ...原有发送逻辑
5.3 性能优化技巧
-
批量消息处理：
python复制def batch_send(messages): with ThreadPoolExecutor(max_workers=5) as executor: futures = [executor.submit(send_text, msg) for msg in messages] for future in as_completed(futures): try: future.result() except Exception as e: logging.error(f"发送失败: {e}") -
消息队列集成：
python复制# 使用Redis作为消息队列 def process_queue(): while True: _, msg = redis.brpop("wechat_messages") try: send_text(json.loads(msg)) except Exception as e: redis.lpush("failed_messages", msg) -
缓存AccessToken：
python复制from cachetools import TTLCache token_cache = TTLCache(maxsize=1, ttl=7000) # 比实际过期时间短 def get_token(): if 'token' not in token_cache: token_cache['token'] = _fetch_new_token() return token_cache['token']
这套微信推送服务已经在我们团队的多个AI Agent项目中稳定运行超过6个月，日均推送消息量在3000条左右。最关键的经验是：一定要实现完善的重试机制和消息去重，网络抖动时可能会出现发送成功但响应超时的情况，此时盲目重发会导致消息重复。我们的做法是为每条消息生成唯一ID，在接收端做幂等处理。