1. 为什么隔离内网里的 AI Agent 是另一场游戏先把场景说清楚。所谓隔离内网就是一台或者一批机器物理上或者逻辑上跟公网断开没有外网出口DNS 解析不了外部域名pip、npm、apt 这些包管理器全部失效甚至连时间同步都得靠内网 NTP。你在这种环境里要跑一个 AI Agent 工程第一反应往往是把公网那套搬进来不就行了然后你会发现搬进来的每一步都在撞墙。我在几个不同类型的隔离环境里落地过 Agent 项目从最开始的能跑起来就行到后来要求可复现、可交付、可维护中间踩的坑足够写一本小册子。这篇东西不讲虚的就讲隔离内网这个约束条件下AI Agent 工程到底该怎么搭、怎么选型、怎么排错、怎么交付。核心关键词就几个AI Agent、MCP、Skills、内网、工程实战。如果你正在或者即将在一个没有外网的环境里做 Agent这篇基本能帮你省掉至少两周的试错时间。先明确一个认知隔离内网不是网速慢一点或者访问受限一点它是整个依赖生态的断裂。公网环境下你敲一行pip install就解决的事在内网里可能意味着你要手动下载 wheel 包、处理依赖树、解决版本冲突、再通过某种受控方式传进去。Agent 工程比普通项目更麻烦的地方在于它天然依赖三类外部资源模型服务、工具协议MCP、以及技能包Skills。这三样在公网都是拉一下就有在内网全是问题。所以这篇的定位很明确给已经懂一点 Agent 概念、但没在隔离环境里真正落地过的人一份工程视角的实战记录。我会把架构选择、依赖处理、MCP 和 Skills 的内网适配、并发与稳定性、以及最终的交付打包一层层拆开讲。每一块都会说清楚为什么这么选和我当时踩了什么坑。2. 内网 Agent 的架构选型先想清楚哪些东西必须进来2.1 模型服务本地推理还是内网网关Agent 的大脑是模型。公网环境下你调个 API 就完事内网里第一个要决策的就是模型怎么来。常见的有两条路一是内网自建推理服务把开源模型部署在内网的 GPU 机器上二是内网里已经有一个统一的模型网关你只需要对接它的接口。我个人的经验是如果内网已经有模型网关优先对接网关不要自己另起炉灶。原因很实际网关通常已经解决了模型版本管理、鉴权、限流、日志这些脏活你自己部署一套等于把这些活重做一遍而且内网的 GPU 资源往往是稀缺且被统一调度的你私自占一块卡运维那边迟早找你。如果确实没有网关必须自建那选型上要注意几点。模型大小要跟内网硬件匹配别看着公网上动辄几百 B 的模型眼馋内网一张卡跑不动就是跑不动。量化版本是内网的好朋友INT4 或者 INT8 量化能在几乎不损失可用性的前提下把显存需求砍下来一大截。推理框架方面vLLM 和 TGI 是内网部署里比较常见的选择前者吞吐好后者部署简单看你更看重哪个。提示内网自建推理服务时一定要提前确认 CUDA 驱动版本和推理框架要求的版本是否匹配。我见过太多次因为驱动版本差一个小版本整个部署卡半天的案例而内网里升级驱动往往要走审批流程代价极高。2.2 Agent 框架轻量优先别把公网的重型框架硬搬Agent 框架的选择在内网里有个反直觉的原则越轻越好。公网环境下大家喜欢用功能全、生态大的框架因为装依赖方便。内网里每多一个依赖就多一份手动搬运和解决冲突的成本。我的建议是如果团队有能力核心的 Agent 循环感知、规划、调用工具、观察结果、再规划自己写控制在几百行以内。这样依赖极少通常只需要一个 HTTP 客户端库和一个 JSON 处理库内网适配成本最低。如果一定要用现成框架优先选那些依赖树浅、纯 Python 实现、不强依赖特定云服务的。这里要提一个热词里反复出现的概念AI Agent 主流架构。目前主流的分两类一类是 ReAct 风格的思考-行动-观察循环一类是 Plan-and-Execute 风格的先规划再执行。内网环境下我更倾向 ReAct因为它对模型的单步推理能力要求相对低容错性好某一步工具调用失败可以重试不会像 Plan-and-Execute 那样一步规划错、后面全崩。2.3 依赖清单内网工程的第一份资产在公网依赖清单是requirements.txt或者package.json敲个命令就装好了。在内网这份清单是你最重要的资产之一因为你要拿着它去离线采购。我的做法是在公网环境里先把整个依赖树完整导出包括间接依赖和精确版本号。Python 用pip download把所有 wheel 包下到一个目录Node 用npm pack或者直接打包node_modules。关键是版本要锁死不能有这种模糊约束否则内网装的时候解析出来的版本可能跟公网测试的不一样行为就有差异。# 在公网环境导出完整依赖并下载所有包 pip download -r requirements.txt -d ./offline_packages --no-binary :all: # 或者只下 wheel速度更快 pip download -r requirements.txt -d ./offline_packages下载完之后在内网里用pip install --no-index --find-links./offline_packages -r requirements.txt来安装。--no-index这个参数很关键它强制 pip 不去联网找包只用本地目录避免内网里 pip 卡在超时上。3. MCP 在内网协议本身不难难的是它想连的东西3.1 MCP 到底是什么为什么内网要特别对待MCP全称 Model Context Protocol是给 Agent 和外部工具之间定的一套通信规范。你可以把它理解成Agent 世界的 USB 接口——只要工具实现了 MCPAgent 就能用统一的方式去调用它不用为每个工具写一套适配代码。在内网里MCP 的协议本身没有任何问题它就是个基于 JSON-RPC 的通信规范跑在本地进程或者内网服务之间完全不需要外网。真正的问题在于很多现成的 MCP Server 实现默认会去连外网。比如某些搜索类、地图类、云服务类的 MCP Server启动时就要访问外部 API内网里直接卡死或者报错。所以内网用 MCP 的第一原则是只选那些纯本地、无外网依赖的 MCP Server。文件操作、数据库查询、内网 API 调用、代码执行这类工具天然适合内网。凡是需要连公网服务的要么找内网替代品要么自己写一个。3.2 自己写一个内网 MCP Server 的最小骨架内网里最靠谱的做法往往是自己写 MCP Server。因为你对内网有什么、能调什么最清楚写出来的东西也最贴合实际需求。一个最小的 MCP Server 骨架其实很简单核心就是注册几个工具函数然后通过标准输入输出或者 HTTP 跟 Agent 通信。# 一个极简的内网 MCP Server 示例stdio 模式 import json import sys def handle_request(req): method req.get(method) if method tools/list: return { tools: [ { name: query_internal_db, description: 查询内网数据库, inputSchema: { type: object, properties: { sql: {type: string} } } } ] } elif method tools/call: tool_name req[params][name] if tool_name query_internal_db: sql req[params][arguments][sql] # 这里接内网的数据库连接 result run_sql(sql) return {content: [{type: text, text: str(result)}]} return {error: unknown method} def main(): for line in sys.stdin: req json.loads(line) resp handle_request(req) print(json.dumps(resp), flushTrue) if __name__ __main__: main()这段代码看着简陋但它把 MCP 的核心逻辑讲清楚了接收请求、分发到对应工具、返回结果。内网里你不需要花哨的功能需要的是稳定、可控、无外网依赖。我见过太多团队一上来就想搞个大而全的 MCP 工具集结果每个工具都要处理外网依赖最后没一个能跑通。3.3 MCP 工具流式输出到文件的实战细节热词里有个很具体的需求使用 MCP 工具流式输出内容到文件。这个在内网场景里其实很常见比如 Agent 生成的内容要落盘、要写日志、要产出报告。流式输出的难点在于你不能等全部内容生成完再写那样内存占用大而且中途失败就全丢了。我的做法是MCP 工具里维护一个文件句柄每收到一块内容就 flush 一次。这里有个坑flush 太频繁会拖慢速度flush 太少又可能丢数据。实测下来按行 flush 或者按固定大小比如 4KBflush 是比较平衡的选择。def stream_to_file(content_chunk, filepath): with open(filepath, a, encodingutf-8) as f: f.write(content_chunk) f.flush() # 关键确保内容真正落盘注意内网环境里如果文件是写在网络挂载盘上flush 的语义可能跟本地盘不一样极端情况下断电还是会丢。如果数据重要写完关键节点后手动调一次os.fsync。4. Skills 体系内网里怎么让 Agent 学会新本事4.1 Skills 和 MCP 的分工别搞混很多人把 Skills 和 MCP 混为一谈其实它们解决的是不同层面的问题。MCP 解决的是Agent 怎么连上工具是通信层的事。Skills 解决的是Agent 知道在什么场景下该怎么做是知识和流程层的事。打个比方MCP 像是给 Agent 装了一双手能操作工具了Skills 像是给 Agent 一本操作手册告诉它遇到什么情况该用哪只手、按什么顺序操作。内网里这两样都要有但它们的适配方式完全不同。MCP 的适配重点是去掉外网依赖Skills 的适配重点是把知识本地化。4.2 内网 Skills 的存放与加载公网环境下Skills 往往是从某个市场或者仓库动态拉取的。内网里没有这个条件所以 Skills 必须提前打包、随项目一起交付。我的做法是在项目里建一个skills/目录每个 Skill 一个子目录里面放描述文件和相关的脚本或模板。加载的时候Agent 启动时扫描这个目录把 Skill 的元信息名称、描述、触发条件读进内存需要用到具体内容时再按需读取。这样既保证了启动速度又避免了把所有 Skill 内容一次性塞进上下文。import os import json def load_skills(skills_dir): skills [] for name in os.listdir(skills_dir): skill_path os.path.join(skills_dir, name) meta_file os.path.join(skill_path, meta.json) if os.path.exists(meta_file): with open(meta_file, encodingutf-8) as f: meta json.load(f) meta[path] skill_path skills.append(meta) return skills这里有个经验Skill 的描述要写得像给新同事的交接文档说清楚什么时候用、怎么用、有什么坑。我见过很多 Skill 描述写得极其简略结果 Agent 根本判断不出该不该触发等于白写。4.3 Skill 的测试内网里没有试错自由公网环境下Skill 写错了大不了改一改再试。内网里每次改动都要走一遍打包、传输、部署的流程成本高得多。所以内网的 Skill 必须在公网环境充分测试后再进内网。我的测试方法是构造一批典型的用户输入看 Agent 是否能正确触发对应的 Skill触发后执行结果是否符合预期。这里要特别注意边界情况比如输入模糊时 Agent 会不会乱触发 Skill多个 Skill 都可能适用时会不会选错。这些在公网测试阶段就要覆盖到别指望进内网再调。5. 并发与稳定性内网 Agent 扛并发的真实做法5.1 内网并发为什么比公网更难热词里有个问题很扎眼AI Agent 怎么扛并发。这个问题在内网里比公网更难原因有几个。第一内网的模型推理资源通常是固定的不像公网可以弹性扩容并发一上来推理服务就是瓶颈。第二内网的网络带宽和延迟虽然稳定但总量有限大量并发请求可能把内网带宽打满。第三内网里排查问题的手段少出了并发问题往往不好定位。所以内网 Agent 的并发策略核心不是扛更高的并发而是在有限资源下稳定地服务。这个思路的转变很重要别拿公网那套加机器就行的思路来套内网。5.2 请求队列与限流把并发变成可控的排队最实用的做法是加一层请求队列。所有 Agent 请求先进队列然后由固定数量的工作协程从队列里取任务执行。这样无论外面来多少请求实际并发执行的数量是可控的不会把模型服务打垮。import asyncio class AgentQueue: def __init__(self, worker_count4, max_queue100): self.queue asyncio.Queue(maxsizemax_queue) self.worker_count worker_count async def worker(self): while True: task await self.queue.get() try: await self.process(task) finally: self.queue.task_done() async def process(self, task): # 实际的 Agent 处理逻辑 pass async def start(self): for _ in range(self.worker_count): asyncio.create_task(self.worker())worker_count设多少合适这取决于你的模型推理服务能同时处理多少请求。我的经验是先设成推理服务并发能力的 70% 左右留点余量然后根据实际压测结果调整。max_queue则是保护机制队列满了就直接拒绝新请求返回系统繁忙总比让所有请求都超时强。5.3 超时与重试内网里更要小心内网环境稳定但一旦出问题往往是大问题。超时设置上我建议比公网环境更宽松一点因为内网的模型推理可能比公网 API 慢设太短会导致大量误超时。但也不能无限长否则一个卡死的请求会一直占着工作协程。重试要谨慎。Agent 的很多操作是有副作用的比如写文件、调内网 API盲目重试可能导致重复操作。我的做法是只对幂等的读操作做自动重试写操作失败就报错让人来判断。操作类型是否自动重试原因模型推理是最多 2 次无副作用失败多为临时问题内网查询是最多 3 次幂等重试安全文件写入否可能重复写入内网 API 调用视情况幂等的可重试非幂等的不重试6. 内网交付怎么把 Agent 工程完整搬进去6.1 交付包的结构设计内网交付最怕的就是少了个文件进去跑不起来。所以交付包的结构要设计得清清楚楚让人一看就知道每个目录是干嘛的。我的标准结构是这样的agent-delivery/ ├── app/ # Agent 主程序 ├── skills/ # 所有 Skill ├── mcp_servers/ # 内网 MCP Server ├── offline_packages/ # 离线依赖包 ├── models/ # 模型文件如果自建推理 ├── config/ # 配置文件模板 ├── scripts/ # 安装、启动、检查脚本 └── README.md # 部署文档scripts/目录特别重要里面要有安装脚本、启动脚本、健康检查脚本。内网里运维人员往往不熟悉你的项目脚本写得越傻瓜越好。6.2 配置与密钥的处理内网里配置和密钥的处理有个原则代码里绝对不能硬编码任何环境相关的信息。数据库地址、模型服务地址、端口这些全部走配置文件。交付包里给一份配置模板运维人员按实际情况填。密钥方面内网里相对安全但也不建议明文写在配置文件里。可以用环境变量或者内网自己的密钥管理服务。如果都没有至少把配置文件权限设紧一点别让所有人都能读。6.3 部署后的验证清单交付进去不等于完事必须有一套验证清单确认每个环节都正常。我的清单通常包括模型服务能通、MCP Server 能启动、Skill 能加载、一个端到端的 Agent 请求能跑通、日志能正常输出、并发压测能过。这套清单最好写成脚本一键跑完输出每一项的通过情况。这样每次部署后跑一遍心里有底。7. 那些只有踩过才知道的内网 Agent 经验7.1 时间同步问题会坑死你内网机器如果时间不同步Agent 的日志时间戳会乱更严重的是如果 Agent 逻辑里涉及时间判断比如这个缓存是否过期时间不一致会导致各种诡异问题。我遇到过一次两台内网机器时间差了十几分钟导致 Agent 判断缓存永远过期疯狂重新请求把模型服务打挂了。所以内网部署前务必确认所有机器的时间是同步的。7.2 日志要足够详细但别把磁盘写满内网排查问题难所以日志要详细。但 Agent 的日志量可能很大尤其是开了 debug 级别。我的做法是分级输出正常运行时 info 级别出问题时能动态调到 debug。同时加日志轮转别让日志把磁盘写满内网里磁盘满了清理起来很麻烦。7.3 给 Agent 加一个紧急停止开关这个经验来自一次事故。当时 Agent 因为一个 Skill 的逻辑 bug陷入了循环调用不断消耗模型资源。内网里没法快速改代码重启最后是手动 kill 进程才停下来的。从那以后我所有的内网 Agent 都会加一个紧急停止机制比如监听一个特定文件文件出现就停止所有任务。简单但救命。7.4 版本管理在内网里更重要公网里版本乱了重新拉一下就行。内网里版本乱了你都不知道该用哪个包。所以内网交付的每个组件都要有明确的版本号交付包里带一份版本清单记录每个组件的版本。下次更新时对比版本清单清楚知道改了什么。8. 从公网到内网一套可复用的迁移流程把上面这些串起来其实可以总结成一套可复用的流程。第一步在公网环境把 Agent 工程完整跑通包括模型对接、MCP、Skills、并发处理全部验证过。第二步导出完整依赖树下载所有离线包锁死版本。第三步把所有外网依赖替换成内网版本MCP Server 该重写的重写Skill 该本地化的本地化。第四步打包成标准交付包写好部署脚本和文档。第五步进内网部署跑验证清单。第六步根据内网实际情况微调配置记录所有改动。这套流程我在几个项目里用过基本能把内网落地的周期从不可控压缩到可预期。当然每个内网环境都有自己的特殊性具体问题还得具体分析但大框架是通用的。最后说一句实在话隔离内网做 Agent 工程技术难度其实不是最高的最高的是工程纪律。公网环境里可以随意试错、随意拉包、随意改配置内网里每一个随意都会变成成本。把依赖锁死、把配置外置、把流程固化、把验证自动化这四件事做到位内网 Agent 就能稳稳跑起来。