最近两年做企微二次开发的同行聚会，话题十有八九会拐到 AI Agent 上。但聊深了会发现一个尴尬的现象：大家口中的"Agent"完全是两种东西。一种是套了层 prompt 的对话机器人，问什么答什么；另一种是真的能让大模型自己拆任务、自己调接口、自己判断要不要继续。前者本质上还是 2023 年那波智能客服的升级版，后者才配得上"Agent"这个词。这篇聊聊怎么用 Eyun 企业微信 API 把一个真正的 Agent 接进来，重点讲背后的接口开发思路，不是怎么写 prompt。

一、Agent 和智能客服的根本区别

很多人把两个概念混着用，做出来的东西自然四不像。先把边界划清楚：

维度	智能客服	AI Agent
工作模式	一问一答	目标驱动，自拆步骤
工具使用	固定流程触发	动态决定调哪个工具
终止条件	客户结束对话	Agent 判断目标达成
失败处理	转人工	自己换思路再试
上下文	单轮或几轮	长期任务状态

智能客服收到"帮我查下订单 12345 的状态"，会查一个接口返回结果。Agent 收到"我上周下的单还没收到，你帮我处理下"，会自己去查订单、判断是否超期、决定要不要催物流、给客户更新进度、必要时建工单。差别的本质是：Agent 拿到目标后自己规划工具调用链，不是按写死的 if-else 跑。

这个差别决定了接口开发的思路完全不同。给智能客服做接口，是写死触发条件；给 Agent 做接口，是把每个能力都包装成它能理解、能选择、能组合的"工具"。

二、把企微能力包装成工具

Agent 调用接口的形式是 function calling：大模型读到工具描述，自己决定调用哪个工具、传什么参数。所以你要做的第一件事，是把 Eyun 企业微信 API 的接口按 Agent 能理解的方式重新包装。

一个工具的三要素：

{
  "name": "send_text_message",
  "description": "给指定客户发送一条文本消息。需要知道客户的会话ID和要发送的内容。",
  "parameters": {
    "appid": "当前账号实例ID",
    "conversationId": "目标会话ID，单聊为客户userId，群聊为roomId",
    "content": "要发送的文本内容"
  }
}

包装的关键不是接口本身，是 描述。Agent 选择工具靠的就是 description 这段文字，描述不清它就用错。要点：

• 用大白话写，不要照搬接口文档的技术描述。把"发送文本消息"说成"向指定客户或群发送一条文字消息，用于沟通或通知"，Agent 更容易选对。

• 说明边界条件。"此工具一次只发一条消息，群发请用 group_send 工具"——这种反向边界让 Agent 知道什么时候不该用它。

• 参数语义解释清楚。conversationId 不要只说"会话ID"，要说"单聊传客户userId，群聊传roomId，自己给自己发用账号的uin"。

企微侧的能力大致要包装成这几组工具：

工具组	包含能力	Agent 典型用途
消息收发	发文本/富文本/图片/文件、撤回	主动通知客户、回复咨询
联系人管理	查询客户资料、搜索客户、加好友	客户身份核验、主动建联
群管理	建群、拉人、群公告、踢人	为客户拉专属服务群
标签管理	打标、改标、查标签	客户分层触达
群发助手	群发消息、查群发记录	批量通知
工单集成（自定义）	建工单、查工单、流转工单	服务闭环

最后那组是你自己业务侧的接口，也要按同样的方式包装。

三、Agent 的工作循环

接进来的 Agent 不是被动等用户问一句回一句，它跑的是一个 感知-决策-执行-观察 的循环：

循环开始
  ├─ 感知：从消息回调拿最新消息 / 从内部事件拿任务信号
  ├─ 决策：把历史上下文 + 可用工具描述喂给大模型
  ├─ 执行：按模型决策调用一个或多个工具
  ├─ 观察：拿到工具返回值，更新上下文
  └─ 判断：目标是否达成？未达继续循环，达成则结束

这个循环有几个工程上必须想清楚的点：

循环终止条件。Agent 最容易出的 bug 是无限循环——模型反复调用同一个工具、或者一直说"我再确认一下"。要设硬限制：单次任务最多调用工具 N 次、单次执行时长 M 分钟、相同工具连续调用 3 次强制中断转人工。

上下文管理。每次循环都会往上下文里加新内容，工具返回值也可能很长。要把上下文做 压缩和摘要：旧的工具返回值只保留关键字段，长文本截断或摘要，避免 token 爆炸。

并发安全。Agent 决定调多个工具时，可能同时触发多个 消息模块 调用。要保证这些调用不会互相打架——比如不能同时给同一客户发 5 条消息、不能同时建两个一样的群。并发工具执行要加锁，按"目标资源"维度互斥。

四、感知层：让 Agent 看到企微的世界

Agent 的"感知"靠的是事件。Eyun 企业微信 API 推过来的回调是 Agent 的眼睛：

• message.received：客户说话了

• friend.added：来了新客户

• 群成员变动、群公告变更

• 外部联系人资料变更（contentType=2131）

但只把原始回调丢给 Agent 还不够，要做一层 事件归一化和增强：

原始事件 → 归一化（统一格式）→ 上下文增强（附客户档案、当前状态、最近互动）→ Agent 输入

客户发了句"退款怎么办"，直接给 Agent 它要查知识库、查订单、查客户档案——三次工具调用。如果在事件增强阶段就附上"该客户 7 天前下过订单、当前在退款流程中"，Agent 一次决策就能完成。增强做得到位，工具调用次数和延迟都成倍下降。

五、决策层：模型选型与约束

Agent 的决策质量 70% 取决于模型能力、30% 取决于约束设计。模型选型看任务复杂度：

• 简单工具调用（≤3 个工具、单步）：中等参数量模型够用，速度快、成本低。

• 多步规划：必须用强推理模型，弱模型会跳步、会忘记中间结果。

• 长期任务：要支持大上下文窗口的模型，否则任务还没完上下文已经塞满。

约束设计的核心是 system prompt 里写清楚 Agent 的角色和边界：

• 你是谁（客服助手 / 销售助理 / 内部办公助手）

• 你能做什么、不能做什么（不能直接承诺折扣、不能删除客户、不能给非授权客户查数据）

• 什么时候必须转人工（涉及金额超 X 的退款、客户明确要求人工、连续 2 次没解决问题）

• 什么时候必须二次确认（建群、群发、改标签这类影响多人的操作）

这些约束不能只靠模型自觉，要在工具执行层加 守卫：高风险工具调用前强制走人工审批或二次确认弹窗，Agent 说"我建好群了"也别直接信，看执行结果再更新上下文。

六、执行层：工具网关与失败处理

Agent 决定调工具后，实际执行要走一个独立的 工具网关，不要让 Agent 直接调 Eyun API。网关负责：

• 鉴权：确认这次调用是否在 Agent 权限范围内。

• 限流：单 Agent 单位时间内的调用次数限制，防止模型决策出错时疯狂调接口。

• 幂等：同一任务同一工具相同参数只执行一次，避免循环里的重复副作用。

• 审计：每次工具调用记录"哪个任务、调用哪个工具、传了什么参数、返回什么"，事后复盘 Agent 行为。

• 失败处理：接口返回错误时，把错误语义化后告诉 Agent——不是把 -3004|参数错误 丢给它，而是说"参数格式不对，缺少 conversationId"，让 Agent 知道下一步该怎么修正。

工具网关是 Agent 和真实业务系统之间的安全气囊。没有这层，Agent 决策一旦出错直接打到生产接口上，事故率会高到无法接受。

七、安全边界：让 Agent 不越界

Agent 自主性越强，越界风险越高。几条硬边界：

• 数据权限：Agent 拿到的客户档案、订单数据要按当前会话客户的范围过滤，不能因为它能调"查所有客户"接口就真的把全量客户数据暴露给它。

• 操作权限：高风险接口（解散群、删联系人、批量外发）不能直接给 Agent，要走人工审批。

• 内容审核：Agent 决定发出去的消息文本，发之前过敏感词和合规审核，不能信 Agent 说"这段内容合规"。

• 行为审计：每次任务执行完整链路留痕，方便事后复盘"Agent 为什么这么决策"。

写在最后

接入 AI Agent 不是把对话机器人换个大模型就完事。本质上是用大模型当决策大脑，把 Eyun 企业微信 API 平台 的原子能力包装成它能理解、能选择、能组合的工具，再设计感知-决策-执行-观察的工作循环、约束边界、工具网关、安全审计。这套东西搭好，Agent 才是真的"会做事"，而不是只会说人话。技术细节每一个都不深奥，但少了任何一环，Agent 上线就翻车。