构建真正能用的 AI 代理

一个 AI 代理 是一个具有采取行动能力的 LLM。它不只是生成文本,还能调用 API、查询数据库、发送消息、触发工作流,在循环中做决策。承诺是自动化:一个在无持续人工监督下处理任务的系统。

现实更微妙。代理在范围清晰、边界明确的任务上表现出色。当被给予模糊目标、不受限的工具访问和零护栏时,它们会壮观地崩溃。Demo 代理 和生产 代理 的区别不是 LLM — 是围绕 LLM 的一切。

代理到底是什么

去掉炒作,一个代理 有四个组件:

LLM 接收输入(用户消息、计划触发、事件)。它决定调用哪些工具。通过 MCP 服务器调用它们。接收结果。决定下一步做什么。这个循环持续到任务完成或代理 决定停止。

理论上简单。魔鬼在每个细节里。

在 Zubnet 构建代理

在平台上,创建代理 涉及四个步骤。每一步的决定都将决定你的代理 是可靠运行,还是成为凌晨 3 点电话的来源。

1. 创建代理

给它一个名字,选一个模型,写一个系统提示词。

模型比你想的重要。对于需要可靠调用工具的代理,使用强推理 模型。Claude Sonnet 4、GPT-4.1 或 Gemini 2.5 Pro。更小的模型省钱,但工具调用决策更差,代理 中的错误工具调用不只是错误答案 — 是错误的行动。

系统提示词 是你代理 的宪法。对以下明确说明:

• 代理 应该做什么(以及绝不做什么)
• 何时使用每个工具、何时跳过
• 如何处理错误和歧义
• 何时让用户澄清 vs. 做决策
• 消息中使用什么语气

2. 连接通道

通道是代理 与世界交流的方式。在 Zubnet,你可以连接:

• Telegram — 粘贴 @BotFather 的 bot token
• Discord — 粘贴 Discord Developer Portal 的 bot token
• Webhook — 任何能发送/接收 JSON 的 HTTP 端点

通道决定代理 住在哪里。Telegram bot 代理 在 Telegram 聊天里回应。Discord bot 代理 住在你的 Discord 服务器。Webhook 代理 响应 API 调用。

先选一个通道开始。第一天别想构建跨通道代理。先让它在一个平台上可靠工作。

3. 添加工具(MCP 服务器)

工具是让代理 超越聊天机器人的东西。在 Zubnet,工具由 MCP 服务器(Model Context Protocol)提供。我们有 117 个。一些示例:

• GitHub — 搜索仓库、创建 issue、读取文件、列出 PR
• PostgreSQL / MySQL — 查询数据库(如果你聪明就设为只读)
• Brave Search — 网页搜索
• Filesystem — 读写文件
• Slack — 发送消息、读取频道

激活你需要的服务器,配置其凭证(API 密钥、DB URL),代理 就能使用它们。

4. 配置触发器

触发器决定代理 何时激活:

• 用户消息 — 有人给 bot 发消息时响应(聊天代理 的默认)
• Cron 计划 — 在固定时间运行(如 “每天早上 9 点”)
• 事件 — 特定事情发生时触发(webhook 载荷匹配某模式)

Cron 触发的代理 很适合重复任务:每日站会总结、每周分析报告、监控检查。事件触发的代理 处理响应式工作流:新 GitHub issue → 分类并贴标签,新支持工单 → 起草回复。

困难的部分

构建代理 需 20 分钟。让它可靠需数周。以下是生产代理 真正失败的地方:

错误处理:当 LLM 幻觉出一个工具调用

LLM 有时会用错误参数调用工具、调用不存在的工具,或在错误上下文调用正确工具。你的代理 需要优雅地处理这一切。

在 Zubnet,失败的工具调用会把错误消息返回给 LLM,然后它可以决定怎么做。但你需要在系统提示词 里告诉它怎么做:

If a tool call fails:
1. Do NOT retry the same call with the same parameters
2. Analyze the error message
3. If it is a permission error, tell the user you cannot do that
4. If it is a rate limit, wait and try once more
5. If it is an unknown error, summarize what happened and ask for help
6. Never retry more than twice total

没有这些指令,代理 会陷入重试循环,在同一个失败调用上反复烧掉 token 和时间。

速率限制:频率上限

连接到一个有 500 活跃用户的繁忙 Discord 服务器的代理 可能每分钟收到数百条消息。没有速率限制,它会:

• 几小时内耗尽你的 API token 预算
• 触发提供商速率限制并开始返回错误
• 生成如此多的回复,以至于频道无法使用

配置频率上限。在 Zubnet 你可以设置:

• 每分钟最多回复(按通道)
• 每小时最多 token(预算控制)
• 同一用户回复之间的冷却期
• 队列深度上限(太落后时丢弃消息)

权限:限制代理能做什么

这会把你从灾难中救出来。代理应该拥有做好工作的最少权限。

• DB 工具:除非明确需要写入,否则只读
• GitHub 工具:读取 + 创建 issue,但不能关闭/合并/删除
• Filesystem 工具:只限特定目录,绝不是 /
• 消息工具:只限特定频道,绝不给高管发私信

这样想:这个代理 用它的工具能做最糟糕的事是什么?如果答案让你紧张,就降低权限。

优雅降级

当一个工具宕机,代理 不应崩溃。它应该识别限制并在没有该工具的情况下做能做的事。把它包含在系统提示词 里:

If a tool is unavailable or returning errors:
- Acknowledge it to the user: "I cannot access GitHub right now"
- Do what you can without that tool
- Never make up data to compensate for a missing tool
- Suggest the user try again later

真实示例

示例 1:支持机器人

一个使用你知识库回答客户问题的 Telegram bot。

• 模型:Claude Sonnet 4(擅长遵循指令)
• 工具:Brave Search(文档)、PostgreSQL(只读,账号查询)
• 通道:Telegram
• 触发器:用户消息
• 速率限制:每分钟 30 条回复,每用户 2 秒冷却

系统提示词聚焦于:优先从文档回答、不确定时升级给人类、绝不分享其他客户数据、绝不对功能或时间线做承诺。

示例 2:每日总结代理

一个在早晨发布过去一夜发生事情总结的 Discord bot。

• 模型:GPT-4.1(擅长结构化总结)
• 工具:GitHub(读 PR 和 issue)、Slack(读频道)
• 通道:Discord(#daily-summary 频道)
• 触发器:cron,每工作日早上 9:00
• 速率限制:每次触发 1 条消息(只触发一次)

系统提示词聚焦于:总结已合并的 PR、开/关闭的 issue 和 Slack 关键讨论。控制在 500 字以内。使用要点。标记相关团队成员。

示例 3:内容监控

一个监视特定事件并提醒团队的代理。

• 模型:Gemini 2.5 Pro(快速,擅长分类)
• 工具:Brave Search(监控提及)、Slack(发警报)
• 通道:webhook(由监控服务触发)
• 触发器:事件(带搜索结果的 webhook)
• 速率限制:每小时 10 次警报(防止警报疲劳)

系统提示词聚焦于:把提及分类为正面/负面/中立,只对负面或关键的发出警报,包含源 URL 和一句话摘要。

测试:从小开始

Zubnet 代理 有两种模式:

• 快速模式 — 简化设置,适合测试。工具配置有限,基础触发器。用它验证你的代理 概念是否可行。
• 高级模式 — 完整配置,生产就绪。详细系统提示词、细粒度速率限制、权限控制、多个触发器。

总是从快速模式开始。让基本行为良好运行。然后升级到高级模式并添加护栏。

关于代理不方便的真相

代理不是魔法。它们是带工具访问的循环 LLM。它们会犯错。有时会做错事。问题不是 “我的代理 会犯错吗?” — 是 “出错时会发生什么?”

在生产中能工作的代理 都有:

• 紧凑的范围(“把这一件事做好”)
• 明确的边界(“永远不做这些事”)
• 有限的权限(最小权限,始终)
• 速率限制和预算上限(防止失控成本)
• 人工升级路径(“不确定时问人”)
• 监控和日志(为了知道发生了什么)

---

Zubnet 上的代理对所有用户开放。从一个简单的 Telegram 或 Discord bot 开始,把它做对,再扩展。基础设施处理困难部分 — 你专注系统提示词、工具和护栏。

准备构建?在 zubnet.com 创建你的第一个代理