1. 隔离内网先解决“模型从哪来”，连带解决“知识从哪进”
先说一个多数人容易误判的点：在隔离内网里做 AI Agent，最先卡住你的往往不是大模型有多聪明，而是模型根本进不来、数据也出不去。外网环境下我们习惯的方式——直接调云端大模型 API、用在线 Embedding 服务做向量化、把 PDF 丢给在线解析工具——在内网里统统失效。所以第一步想的不是 Agent 架构，而是怎么把“模型运行环境”和“知识输入通道”在内网里自闭环地搭起来。
模型这块，我在实际项目里首选的是开源权重模型，走本地部署。Qwen 系列、GLM 系列、DeepSeek 系列都有适合内网的尺寸和授权，商用也相对省心。部署工具上，如果你只是做原型验证或者团队规模不超过几十人，Ollama 是最快路径，一条命令就能把模型拉起来跑推理；但如果是生产级服务，并发量一旦上来，建议直接上 vLLM 或者 SGLang，吞吐量差距不是一星半点，尤其是在用张量并行跑 70B 级别模型的时候。
知识库的输入通道是个更隐蔽的坑。外网环境里，你丢一个在线 URL 给 Agent，它自己能抓取网页内容；内网里很多业务资料在内部 Wiki、Confluence、SharePoint 或者各种 OA 系统里，这些系统往往有独立的登录认证，爬虫跑不通，得走二次开发接口对接。更麻烦的是权限隔离，同一个知识库，不同角色能看的文档范围不一样，Agent 不能统一索引。
我当时的处理方式是先用离线工具把高频业务文档统一导出成结构化文本，切块后跑本地 Embedding 模型生成向量，存入内网的向量数据库（比如 Milvus 或 Qdrant）。这里有两个细节值得说：
- 纯内网环境下，Embedding 模型也不能用云端服务，本地至少要跑一个 bge-large-zh 或类似的中文向量模型。实践下来 bge-m3 效果更好，多语言和长文本都扛得住，缺点是显存占用高一些，建议单独分配一块卡，别和 LLM 抢。
- 权限过滤不能在检索后做，要在检索前做。也就是先用用户身份过滤出他有权访问的文档 ID 集合，再去向量库里做检索，否则会出现“检索结果很相关但用户根本没权限看”的尴尬局面。
模型和知识入口盘顺了，后面所有 Agent 逻辑才有扎根的地方。这一步做不好，后面谈什么架构、编排、工具调用都是空中楼阁。
2. Agent 的核心不是“调用模型”，而是构建一套可循环的决策骨架
模型就位之后，很多人以为 Agent 就是“接上大模型 API 然后写提示词”，这是最大的认知偏差。实际做过就知道，一个能稳定跑业务的 Agent，本质上是一套围绕“观察—思考—行动—观察反馈”的循环决策系统，也就是常说的 ReAct 模式。模型只负责其中的“思考”环节，其余观察、行动、记忆、终止判断，都需要你自己写代码来撑起来。
我拆解一下这套循环骨架里最容易出问题的四个环节：
状态管理。Agent 在执行一个复杂任务时，往往需要多轮工具调用，每轮结果都会改变上下文状态。如果你只是把历史消息全部拼进 Prompt，很快上下文就被撑爆，而且模型会被无关历史带偏。建议用一个结构化的状态对象，记录当前目标、已完成步骤、待办步骤、中间结果摘要、当前置信度，每轮循环只把“当前目标+关键中间结果摘要+本次观察”喂给模型，而不是全量历史。
工具注册与调用。内网环境里工具往往不是现成的，需要你自己封装。核心是设计一套统一的工具描述协议，比如每个工具都要有名称、描述、输入参数 Schema、返回结果 Schema。模型拿到这份描述后进行函数调用（function calling），你的代码负责真正的执行。这里最常见的坑是“描述写得太含糊”。比如“查询员工信息”这个工具，模型根本不知道它接受工号还是姓名，返回是 JSON 还是纯文本。我后来养成的习惯是：每个工具描述里都写清楚入参示例和出参结构，写不细的工具宁可不挂。
循环终止判断。Agent 经常会陷入“反复调用同一个工具但结果没变化”的死循环。必须设置最大轮次上限（一般 5~10 轮），同时每一轮结束后让模型输出当前任务状态——完成、进行中、还是遇到不可解决的障碍。是“进行中”才继续循环，其他情况直接跳出。
记忆分层。内网 Agent 需要处理大量临时信息，但并不是所有信息都值得喂给模型。我把记忆分成三层：短期缓冲（当前任务上下文）、工作记忆（任务过程中的重要中间结论）、长期记忆（跨会话可复用的业务知识）。前两层走 Redis 或内存，第三层走向量检索。
用一个简化版的代码来说明这套循环的骨架——这是我在 Python 里常用的结构，内网环境对 Python 生态支持最全，遇到问题也最容易找到解决方案：
class AgentLoop: def __init__(self, llm, tools, max_steps=8): self.llm = llm self.tools = {t.name: t for t in tools} self.max_steps = max_steps self.state = { "goal": None, "completed": [], "pending": [], "current_observation": None } def run(self, task: str) -> str: self.state["goal"] = task for step in range(self.max_steps): prompt = self.build_prompt(self.state) response = self.llm.chat(prompt) if response.status == "finished": return self.state["completed"] if response.status == "blocked": return f"任务受阻：{response.reason}" tool_name = response.action.name tool_args = response.action.args if tool_name not in self.tools: self.state["current_observation"] = "工具不存在，请重新选择" continue observation = self.tools[tool_name].execute(**tool_args) self.state["completed"].append({ "step": step, "action": tool_name, "args": tool_args, "result_summary": summarize(observation) }) self.state["current_observation"] = observation return "超过最大轮次，任务未完成"这套骨架最核心的地方在于build_prompt和summarize两个函数：前者决定你喂给模型什么信息，后者决定什么信息值得被留下。两个函数都做“减法”，只保留对当前目标最关键的内容。
还有一个容易翻车的地方：Token 计费与上下文窗口的工程化处理。内网跑模型通常是自建服务，没有云端按量计费，但上下文窗口长度依然是硬限制。Qwen2.5 系列支持 32K~128K 上下文，看起来很宽裕，但一旦工具返回的内容冗长，比如数据库查询返回几百行记录，几个来回就能把窗口打满。我的方案是给所有工具增加“结果截断”机制——默认只返回前 N 条记录和前若干字符摘要，同时提供一个get_full_result工具让 Agent 按需获取完整数据。这既控制了上下文占用，也保留了 Agent 深挖信息的能力。
3. 外网能力缺失时的替代方案，决定了你的 Agent 能“动”到什么程度
隔离内网最难受的一点是：很多在互联网上随手可得的服务，内网里全部没有。天气 API、地图服务、实时新闻、第三方 OCR——这些外网 API 在内网环境里统统调不通。这不只是“少几个工具”的问题，它直接改变了 Agent 能处理的任务类型。
我用一个朴素的标准来判断：凡是外部依赖超过 30% 的工具，在内网里都要找替代方案；找不到替代方案，就把这个任务从 Agent 的能力边界中划掉。
举几个我实际做过的替代方案，供参考：
- 外部搜索 → 内部知识库检索。外网 Agent 常用 “Search the web” 作为信息获取手段，内网里我用 Qdrant 向量检索 + 关键词检索（BM25）的双路召回，先粗排再精排。效果上虽然不如搜索引擎覆盖面广，但对业务内部问题，相关度往往更高。
- 在线 OCR → 本地 PaddleOCR 服务。把 PaddleOCR 封装成 HTTP 服务，Agent 通过工具调用传图片 URL 或 Base64，服务返回识别文本。内网环境对 OCR 模型没有外部依赖，可以完全自闭环。
- 外部数据源 → 内部数仓或业务库的只读账号。给 Agent 配置一个只读 MySQL/PG 账号，封装成 SQL 查询工具。这里要注意两个坑：一是必须做 SQL 白名单或注入拦截，防止模型生成的危险 SQL；二是要设置返回行数上限和超时时间，避免一条慢查询把 Agent 卡死。
- 公网回调 → 内网消息推送。Agent 完成任务后的通知，不能走公网 Webhook，就走内部办公系统的消息机器人接口或者企业微信/钉钉的内网版本。
这些替代方案的共性是：每一个都要你自己写代码做适配层。我在项目里维护了一个internal_tools包，里面统一了所有工具接口的入参和返回格式，工具内部实现五花八门（有 HTTP 调用的、有直接连数据库的、有读文件的），但对 Agent 来说，它们都是一样的“输入描述—参数校验—执行—返回结构化结果”。
再一个容易被忽视的点是“工具调用后的数据一致性”。外网环境下，工具调用的幂等性没那么敏感；内网里 Agent 一旦操作了业务数据库——比如更新工单状态、写入审批记录——调用失败或重复调用就会造成脏数据。我用的方案是：所有写操作工具强制要求传入request_id（幂等键），执行前先查这个 ID 是否处理过，处理过就直接返回上次结果。写操作完成后再通过专门的回执工具把执行结果回传给 Agent。这套逻辑我已经在多个项目里复用，强烈建议你在设计工具层时就内置进去。
还有一个安全边界问题。内网 Agent 能调用的工具越多，风险面就越大。我建议从一开始就做“工具分级”：
| 级别 | 工具示例 | 是否允许 Agent 自主调用 |
|---|---|---|
| L0 | 检索知识库、查询只读数据、获取时间 | 允许 |
| L1 | 发送消息到指定群组、创建低危工单 | 允许，但需记录审计日志 |
| L2 | 数据更新、执行写操作、删除/修改 | 需人工审批确认 |
| L3 | 涉及密码、密钥、支付、核心资产 | 永久禁止 |
列表里 L2 级别的工具，实际实现时让 Agent 先“提交意图”，系统生成一个带参数的审批链接推给管理员，管理员点击确认后工具才真正执行。这是我在隔离内网环境下的安全底线，不建议省掉。
4. 部署形态选型：单体 Java、脚本式 Python，还是 Rust 单二进制
内网部署最让人头疼的不是代码功能，而是“依赖地狱”。外网环境下 pip install 或 mvn dependency:resolve 失败了大不了重试，内网环境没有公共源镜像，每次拉依赖都是一场灾难。所以我强烈建议：内网项目的依赖越少越好，部署形态越简单越好。
三种主流方案的对比，我直接给出实测结论：
单体 Java 服务。适合已有 Java 技术栈、Agent 需要和现有 Spring Boot 业务系统深度融合的团队。好处是能和现有系统共享配置中心、注册中心、监控体系；坏处是重，动不动就要拉几百 MB 依赖，内网 Maven 私服如果没有提前搭好，光是环境准备就能耗掉两三天。
脚本式 Python。适合快速验证、小型工具、内部小范围使用。FastAPI 或 Flask 包一层 HTTP 服务，配合 LangChain 或直接自己写的 Agent 循环，开发效率最高。缺点也很明显：Python 的依赖管理在离线环境里特别痛，最好用构建机把依赖全部打进镜像或虚拟环境，然后整体搬进内网。还有性能瓶颈，同规格机器上 Python 的并发上限比 Java 和 Rust 低不少。
Rust 单二进制。这是我近一年在新项目里偏爱的方案。Rust 编译出来的二进制不依赖运行时环境，拷贝进去就能跑，在隔离内网里简直是降维打击。像 tokio 这类异步运行时在高并发场景下表现很稳，内存占用也比 Python 解释器低一个量级。缺点是对开发者要求高，开发周期比 Python 慢，而且生态相对小众。
我个人的建议是分场景：个人或小组工具用 Python，需要和公司现有 Java 体系融合用 Java，如果能控制开发节奏且对性能有要求，Rust 是长期更省心的选项。调研阶段先把 Python 原型跑通验证逻辑，然后根据规模化需要决定是否用 Rust 重写核心 Agent 循环。
不管选哪种语言，部署拓扑都要想清楚。我在隔离内网里的标准部署架构是这样：
- 模型服务单独一台 GPU 机，跑 vLLM，提供 OpenAI 兼容的
/v1/chat/completions接口； - Agent 逻辑（含工具调用、状态管理、循环控制）部署在应用服务器上，负责和模型服务、向量库、业务系统交互；
- 向量数据库（Qdrant 或 Milvus）部署在独立的存储节点，数据单独做备份；
- Redis 负责状态缓存和消息队列（也可以用 RabbitMQ 或 Pulsar，取决于队伍熟悉程度）；
- 管理后台负责 Agent 任务下发、审计日志查询、工具注册管理。
整个链路全部走内网域名，不要用 IP 直连。内网 DNS 虽然一开始要多花一点配置时间，但后续扩容、迁移的时候就知道它有多重要了。模型服务的地址我用了一个固定的内部域名llm.internal，Agent 代码里统一走这个域名，模型升级或换卡的时候改 DNS 指向即可，不用动代码。
5. 单 Agent 天花板有限，多 Agent 协作要借内网消息总线
当你把单 Agent 跑到稳定之后，会迅速遇到天花板：一个 Agent 要同时完成“查资料、写报告、调数据、发通知”这种复合任务时，要么上下文窗口不够，要么工具调度逻辑复杂到难以维护。这时候就该拆分了。把一个主任务分解成多个子任务，每个子任务由专门职责的 Agent 完成，主 Agent 负责任务编排和结果汇总。
多 Agent 的协作机制，我在内网环境里首选“消息总线”模式，而不是“Agent 直连调用”。原因很现实：内网环境服务多、网络拓扑复杂，直连调用会造成紧耦合，而且 Agent 之间互相等待容易死锁。
消息总线模式的做法是：定义一个统一的任务消息结构，包含 task_id、task_type、payload、callback_topic 等字段。主 Agent 把子任务发布到对应的消息主题（topic），专门的子 Agent 订阅自己的主题，处理后把结果发布到主 Agent 的回调主题。双方不直接通信，解耦干净，也天然支持异步。
我用一个结构体来描述任务消息的关键字段，Rust 版本大概长这样：
#[derive(Debug, Clone, Serialize, Deserialize)] pub struct AgentTask { pub task_id: String, pub task_type: TaskType, pub payload: Value, pub callback_topic: String, pub timeout_secs: u64, pub priority: i32, } pub enum TaskType { KnowledgeRetrieval, // 知识检索 DataQuery, // 数据查询 ReportGeneration, // 报告生成 Notification, // 消息通知 DecisionSupport, // 决策支持 }子 Agent 处理完任务后，构造一个 AgentResult 发回 callback_topic：
pub struct AgentResult { pub task_id: String, pub success: bool, pub data: Value, pub error: Option<String>, pub metrics: ResultMetrics, }实际落地要注意几个点：
超时控制。每条任务消息都要带
timeout_secs，主 Agent 侧用 tokio 的timeout包一层，到期没有收到结果就自动标记失败，并决定是否重试或降级。内网环境虽然有网络抖动相对较少，但模型推理时间波动很大，一个长任务跑几分钟很正常，超时设置不能太激进。我一般设为“预估正常耗时的两倍”。补偿机制。消息总线虽然解耦，但带来一个问题：子 Agent 执行到一半崩了怎么办？我的方案是引入“事务性消息队列”，也就是 Send 和 Execute 之间不直接同步，而是通过一条待办表驱动。子 Agent 启动时先查待办表里有没有未完成的任务，执行完再把状态改成完成。这样即使进程重启，任务也不会丢。
优先级。有些任务是实时的（比如“查一下某个订单现在什么状态”），有些是批量的（比如“每周生成一份运营周报”）。消息队列都支持优先级，但别滥用，优先级的本质是抢占，优先级太多会让低优先级任务饿死。我一般只分 High/Normal/Low 三档。
内网环境还有一个额外的好处：延迟低。外网环境下 Agent 编排调用子 Agent，一次往返可能几百毫秒以上；内网消息总线通常是微秒到毫秒级延迟，这让更深的编排层级成为可能——主 Agent 可以串行地做“检索—分析—再检索—再分析”这种多阶段循环，而不用过于担心时间成本。
不过也要提醒一句：多 Agent 不是越多越好。我见过有人把简单任务硬拆成五个 Agent，结果编排逻辑比原本的单 Agent 还复杂，调试起来欲仙欲死。判断标准很简单——当单 Agent 的上下文管理、工具数量、业务复杂度三者中至少两个成为明显瓶颈时，才值得拆。如果只是任务量大了，优先考虑加并行度而不是加 Agent 数量。
6. 两个隔离内网 Agent 实战案例复盘：踩过的坑和落地方案
理论说了这么多，最后分享两个我在真实项目里落地的案例，都带具体的实现思路和踩坑记录。
6.1 案例一：内部知识库问答 Agent
背景：公司有大量产品文档和运维手册，散落在内部 Wiki 和各类 Markdown 仓库中，员工找信息效率低，且文档更新后人记不住。目标是做一个“问产品问题，Agent 给答案并附上参考文档”的助手。
整体架构不复杂：文档离线入库 → 向量化 → Agent 检索 → LLM 生成回答。但三个环节都有坑。
文档入库环节，最大的坑是“文档格式混乱”。Wiki 导出来的内容经常带大量导航、页眉页脚、重复模板，直接切块会制造大量垃圾向量。我的做法是先做清洗，去掉导航和重复区块，再按 Markdown 标题结构切块，而不是按固定字符数切。切完的块还得做一遍去重，否则同一个知识点在不同页面出现多次，检索时相似块扎堆，影响精排效果。
检索环节，我用了“双路召回 + 重排”的标准方案。向量检索负责语义相似，BM25 负责关键词命中，两者合并后用交叉编码器模型（如 bge-reranker）精排。实测下来这种方案的召回准确率比单路向量检索高 20% 以上，尤其对专有名词多的内容（比如产品代号、版本号），BM25 的优势非常明显。
生成环节，一开始我直接让模型“基于检索结果回答”，但发现模型容易把检索结果中没有的信息也编进去（幻觉问题）。后来加了强约束：回答必须引用检索到的文档块 ID，每句话都尽量有对应出处。实现上就是要求模型输出时带上引用标注，程序侧对未引用的关键断言做抽查。虽然仍不能 100% 杜绝幻觉，但至少每个回答都有迹可循，用户能点进去核对原文。
评估指标我用了“检索命中率 + 答案可接受率 + 引用覆盖率”三个维度。检索命中率衡量 Top-5 里有没有正确答案；答案可接受率是抽人评分的，比较主观但重要；引用覆盖率衡量模型回答中关键信息点被引用覆盖的比例。
6.2 案例二：业务数据定时巡检 Agent
背景：业务方每天要人工检查一批核心运营指标，比如订单量、营收、转化率是否异常。人工盯数费时且容易遗漏，目标是做一个每天定时巡检的 Agent，自动查库、判断是否异常、生成简报并推送到工作群。
这个案例很有意思，因为它涉及 Agent 的“主动触发”模式，而不是“被动响应”模式。主流程是：定时任务触发 → Agent 按模板生成 SQL → 查询数仓 → 数据对比阈值 → 判断异常 → 生成简报 → 推送消息。
踩的坑主要在“Agent 生成 SQL 的稳定性”上。模型生成的 SQL 经常有各种小毛病，比如表名大小写不对、日期字段格式理解错误、忘记加分区过滤条件。直接让 Agent 把它生成的 SQL 拿去执行，轻则跑错返回空集，重则扫全表把集群搞挂。我的处理分两层：
第一层是“SQL 安全校验层”。Agent 生成 SQL 后，不直接执行，先经过一层规则引擎校验，检查关键词白名单（只允许 SELECT）、强制要求带上时间分区条件、禁止跨表 JOIN 超过两张等。校验不过就报错，并让 Agent 根据报错信息重新生成。
第二层是“执行结果反馈闭环”。查询执行后，返回给 Agent 的不只是数据，还包括“执行状态、耗时、返回行数、字段说明”等元信息。Agent 在解读数据前先看这些元信息，避免因为字段单位理解错误导致误判。有一次，Agent 把“销售额（元）”理解成“销售额（万元）”，结论写了“营收暴涨 100 倍”，后来加了“字段字典”进 Prompt 才解决。
推送简报时也有讲究：要区分“正常简报”和“异常报警”。正常简报汇总成表格推送到工作群，走低优先级；异常报警则要单独 @ 负责人，附上异常指标、建议排查方向、数据样本。这里用到了前面说的消息总线的优先级机制，异常报警走 High 优先级。
这两个案例做下来，我最大的感受是：内网 Agent 项目的重心其实不在“Agent 的新奇能力”上，而在于“把已有业务系统和工具链的稳定性打磨好”。Agent 的外壳是智能的，但内部全是工程问题——数据清洗、权限控制、幂等性、安全校验、超时重试。这些做扎实了，Agent 才能真正从 demo 变成工具，从“偶尔跑通”变成“每天稳定运行”。
另外一个很重要的感悟是：隔离内网的约束有时候反而是好事。因为不能随便调外部服务，你就必须把核心逻辑和依赖梳理清楚，限制反而让你更专注。外网项目的特点是“整合成本低但杂乱”，内网项目是“整合成本高但边界清晰”。经历过一次完整的内网 Agent 落地，你对 Agent 的每个环节——模型、工具、记忆、编排、部署——都会比那些只调云端 API 的人理解深得多。
