1. 项目缘起为什么要在隔离内网里折腾 AI Agent第一次接到“在内网环境里跑 AI Agent”这个需求时我的第一反应是这不是自找麻烦吗外网环境里各种大模型 API 随手就能调MCP 服务生态也丰富为什么非要把自己关进一个没有外网出口的笼子里但真正做过几个项目之后我才明白隔离内网下的 AI Agent 工程实战恰恰是最能检验一个工程师架构能力的场景。金融、政务、军工、医疗、能源这些行业的研发环境出于数据安全和合规要求物理隔离是硬性条件你不可能把代码、日志、业务数据往外部服务上送。这时候AI Agent 到底还能不能干活答案是能而且能干得很漂亮前提是你得把整套工程链路重新设计一遍。这篇文章我想聊的就是这件事在一个完全没有外网出口的内网环境里从零搭建一套可用的 AI Agent 系统。涉及的核心关键词包括AI Agent、MCP、内网、工程实战、Skills。我会把整个项目的设计思路、技术选型、踩过的坑、可复现的操作步骤全部摊开讲。适合的读者是有一定后端或运维基础正在或即将面对内网 AI 落地需求的工程师也适合对 MCP 协议、Agent Skills 机制感兴趣想搞清楚“离线环境下这套东西怎么跑”的技术爱好者。文章里不会出现任何绕过网络管控的内容所有方案都建立在“内网就是内网我们只在内网里解决问题”这个前提上。先说结论内网 AI Agent 的核心矛盾只有一个——模型能力与工具能力都被切断外网供给后如何在内网内部重建一套自洽的推理与执行闭环。这个闭环由四部分组成内网可部署的模型推理服务、内网 MCP 工具服务集群、Agent 编排框架、以及 Skills 技能包的分发与加载机制。下面我按这个逻辑一层层拆。2. 整体架构设计把外网那套东西“搬进来”再“改一遍”2.1 内网 Agent 的四层架构拆解外网环境下一个典型 AI Agent 的调用链是这样的Agent 框架 → 大模型 API云端→ MCP 工具服务可能也在云端→ 业务系统。这条链路里模型和工具都依赖公网。内网环境下这条链路的每一环都要替换成内网自建版本。我最终落地的架构分四层。第一层是模型推理层用内网 GPU 服务器部署开源大模型通过兼容 OpenAI 接口规范的推理框架对外提供服务这样上层 Agent 框架的代码几乎不用改只换 base_url 就行。第二层是 MCP 工具服务层把内网里需要被 Agent 调用的能力数据库查询、文件检索、内部 API、代码仓库操作等封装成标准 MCP Server统一注册到内网的服务发现里。第三层是 Agent 编排层负责对话管理、工具调用决策、多轮任务拆解这一层是 Agent 的“大脑”。第四层是 Skills 技能层把高频、固定的任务流程沉淀成可复用的技能包Agent 按需加载避免每次都用自然语言重新描述。这四层里第一层和第三层是必须自建的第二层和第四层是决定 Agent 好不好用的关键。很多人内网 Agent 做出来“能聊天但不能干活”问题基本都出在第二层和第四层没做扎实。2.2 为什么选 MCP 作为工具接入标准内网里接工具传统做法是给每个工具写一个适配函数Agent 框架里硬编码调用。这种做法在工具有三五个的时候还行一旦超过十个维护成本就爆炸了。MCPModel Context Protocol的价值在于它把“工具怎么描述、怎么调用、怎么返回结果”标准化了。Agent 只需要知道“有一个 MCP Server 提供了哪些 tool”不需要关心这个 tool 背后是数据库还是脚本。在内网环境里MCP 还有一个额外好处它的传输层可以完全走内网。MCP 支持 stdio 和 SSE 两种传输方式stdio 适合本地进程SSE 适合跨主机调用。内网里我用 SSE 方式把 MCP Server 部署在独立主机上Agent 通过内网地址连接整个通信不出内网。这一点非常关键因为很多内网安全策略是禁止任何进程主动向外发起连接的SSE 走内网地址完全合规。2.3 Skills 机制在内网场景下的特殊价值Skills 这个概念最近很热但很多人没想清楚它在内网场景下为什么特别重要。外网环境下模型本身能力强很多任务直接对话就能完成Skills 是锦上添花。内网环境下你部署的开源模型能力通常弱于云端旗舰模型这时候 Skills 就是雪中送炭——它把“模型需要自己想明白的事”变成“模型只需要按模板执行的事”。举个例子内网里要做一个“根据需求文档生成数据库建表语句”的任务。如果纯靠模型推理弱模型很容易漏字段、搞错类型。但如果把它做成一个 Skill先让模型提取实体和属性再按固定模板映射到 SQL 类型最后用校验规则检查一遍成功率能从 60% 提到 95% 以上。Skills 的本质是把领域知识固化下来降低对模型通用推理能力的依赖。内网模型越弱Skills 越重要。3. 模型推理层内网部署开源模型的实操要点3.1 模型选型的三个硬指标内网部署模型选型不能只看榜单分数。我总结下来有三个硬指标显存占用、推理速度、指令遵循能力。显存占用决定你能不能在现有硬件上跑起来推理速度决定 Agent 的交互体验指令遵循能力决定工具调用和 Skills 执行的准确率。以我实际项目为例内网有两台 4 卡 A100 40G 的服务器。最终选的是一个 32B 参数量的开源模型做主力7B 模型做轻量任务比如意图分类、参数提取。32B 模型用 4 卡张量并行INT8 量化后显存占用约 36G单次推理首 token 延迟在 800ms 左右生成速度约 25 token/s。这个速度做 Agent 交互是可以接受的但如果做实时对话就偏慢所以轻量任务全部路由到 7B 模型。提示内网模型选型时优先选有成熟量化方案和推理框架支持的模型。有些模型虽然效果好但量化后精度掉得厉害或者推理框架不支持张量并行单卡放不下就彻底没戏。3.2 推理服务的接口兼容设计Agent 框架通常默认对接 OpenAI 接口规范。内网部署推理服务时一定要选支持 OpenAI 兼容接口的推理框架这样上层代码零改动。我用的推理框架对外暴露/v1/chat/completions和/v1/embeddings两个端点Agent 框架里只需要把base_url从云端地址改成内网地址api_key随便填一个非空字符串即可。这里有个细节要注意流式输出stream的支持。Agent 在执行长任务时流式输出能让用户看到进度体验好很多。但不是所有推理框架的流式实现都稳定我遇到过流式输出到一半连接断开、或者 token 边界切分错误的问题。上线前一定要用长文本压测流式接口确认在 4096 token 输出长度下不会断流。3.3 多模型路由的配置方法内网里通常不会只部署一个模型。我的做法是在 Agent 编排层加一个轻量路由模块根据任务类型分发到不同模型。路由规则可以很简单比如意图识别、实体提取、参数校验 → 7B 模型复杂推理、代码生成、长文档理解 → 32B 模型向量化 → 专用 embedding 模型路由配置我放在一个 YAML 文件里格式如下routes: - name: intent_classify model: qwen-7b endpoint: http://10.0.1.10:8000/v1 max_tokens: 256 - name: complex_reasoning model: qwen-32b endpoint: http://10.0.1.11:8000/v1 max_tokens: 4096 - name: embedding model: bge-large endpoint: http://10.0.1.12:8000/v1这样调整模型或增减路由都不用改代码改配置重启即可。实测下来这套路由机制让整体响应速度提升了约 40%因为大量简单任务不再占用大模型资源。4. MCP 工具服务层内网工具接入的标准化实践4.1 MCP Server 的内网部署模式MCP Server 在内网有两种部署模式我两种都用过各有适用场景。第一种是 stdio 模式MCP Server 作为 Agent 框架的子进程启动通过标准输入输出通信。这种模式适合工具逻辑简单、不需要独立扩缩容的场景部署最简单但缺点是 Agent 和工具耦合在一起工具崩溃可能拖垮 Agent。第二种是 SSE 模式MCP Server 作为独立服务部署通过内网 HTTP SSE 端点对外提供服务。这种模式适合工具较多、需要独立维护的场景也是我最终采用的方案。SSE 模式下每个 MCP Server 是一个独立进程监听内网某个端口Agent 通过配置文件里的 URL 连接。我一般把同类工具合并到一个 Server 里比如“数据库工具 Server”包含查询、建表、索引管理等多个 tool“代码仓库工具 Server”包含文件读取、搜索、提交历史查询等 tool。这样 Server 数量可控一般 5 到 8 个就够覆盖大部分场景。4.2 工具描述的编写技巧MCP 工具的调用准确率很大程度上取决于工具描述写得好不好。模型是根据工具的名称、描述、参数 schema 来决定调不调、怎么调的。我踩过的坑是描述写得太简略模型经常调错工具或者传错参数。好的工具描述应该包含四要素这个工具做什么、什么时候用、参数含义、返回值格式。举个例子一个查询数据库的工具描述不能只写“查询数据库”而要写成“根据 SQL 语句查询内网业务数据库仅支持 SELECT 语句返回 JSON 格式的结果集。当用户需要获取业务数据时使用此工具”。参数描述也要具体比如sql参数要注明“标准 SQL SELECT 语句表名需使用完整限定名如 db.table”。注意内网 MCP 工具一定要做权限校验和 SQL 注入防护。模型生成的 SQL 不可信必须在 MCP Server 层做白名单校验只允许 SELECT禁止任何写操作除非该工具明确设计为写工具且有独立审批流程。4.3 工具调用链的编排单个工具调用简单难的是多工具协同。比如一个“生成月度报表”的任务需要先查数据库拿数据再调计算工具做汇总最后调文档工具生成报告。这种调用链我是在 Agent 编排层用“计划-执行”模式实现的先让模型输出一个调用计划哪些步骤、每步用哪个工具然后逐步执行每步结果作为下一步输入。这里的关键是计划的可修正性。执行过程中如果某步失败Agent 要能重新规划。我在编排层加了一个重试和回退机制单步失败重试 2 次仍失败则触发重新规划最多重新规划 3 次。实测下来这套机制能把多步任务的完成率从 70% 左右提升到 90% 以上。5. Skills 技能层让弱模型也能干精细活5.1 Skills 的目录结构与加载机制Skills 在内网环境下的组织方式我参考了社区里常见的做法每个 Skill 是一个独立目录包含一个描述文件和若干资源文件。目录结构大致如下skills/ generate_sql/ SKILL.md templates/ create_table.sql.j2 rules/ type_mapping.yaml review_code/ SKILL.md prompts/ review_prompt.txtSKILL.md是这个技能的“说明书”包含技能名称、触发条件、执行步骤、依赖工具。Agent 启动时扫描 skills 目录把所有技能的元信息加载到上下文里。当用户请求匹配某个技能的触发条件时Agent 加载该技能的完整内容并按步骤执行。这种设计的妙处在于技能是文件不是代码。新增或修改技能不需要改 Agent 框架只需要在目录里加文件、改文件重启 Agent 即可生效。内网环境里运维人员可以通过内网文件共享或配置管理工具分发技能包非常方便。5.2 技能触发条件的写法技能触发条件写得好不好直接决定 Agent 会不会在正确的时机加载正确的技能。我一般用“关键词 意图”双重匹配。关键词是硬匹配比如技能描述里写“当用户提到‘建表’、‘DDL’、‘数据库表结构’时触发”意图是软匹配用轻量模型判断用户请求是否属于该技能的适用范围。两者结合的好处是关键词匹配快且准但覆盖不全意图匹配覆盖全但可能误触发。我的策略是关键词命中直接触发关键词未命中但意图匹配度高超过阈值也触发但会在日志里标记方便后续优化。实测这套机制下技能误触发率控制在 5% 以内。5.3 技能与 MCP 工具的配合Skills 和 MCP 工具不是二选一的关系而是配合关系。Skill 定义“怎么做”MCP 工具提供“用什么做”。比如“生成建表语句”这个 Skill它的步骤是提取实体 → 映射类型 → 生成 SQL → 校验。其中“校验”这一步会调用一个 MCP 工具把生成的 SQL 拿到内网数据库里做语法检查用 EXPLAIN 但不执行。这种配合让 Skill 既有流程的确定性又有工具的动态能力。我建议在设计 Skill 时把“需要实时数据或外部状态”的步骤都交给 MCP 工具把“纯逻辑处理”的步骤留在 Skill 内部用模板或规则完成。这样 Skill 的可移植性最好换个内网环境只要 MCP 工具接口一致Skill 不用改。6. 实操过程从零到一搭建内网 Agent 的完整步骤6.1 环境准备与依赖清单假设你拿到的是两台内网服务器一台带 GPU推理用一台普通 CPU 服务器跑 Agent 和 MCP 服务。操作系统是内网常见的 Linux 发行版。需要准备的依赖包括推理框架、Agent 框架、MCP SDK、Python 运行环境、以及内网 pip 源如果没有内网源需要提前把 wheel 包下载好拷进去。我列一个最小依赖清单组件用途部署位置推理框架提供模型 APIGPU 服务器Agent 框架编排对话与工具调用CPU 服务器MCP SDK开发 MCP ServerCPU 服务器向量数据库知识库检索CPU 服务器内网 pip 源依赖安装内网任意主机提示内网部署最大的坑是依赖缺失。建议在外网环境用pip download把所有依赖包及其依赖树下载到本地再整体拷入内网。不要指望内网能临时装包很多时候一个缺失的底层库就能卡你半天。6.2 模型服务启动与验证模型服务启动后第一件事是验证接口可用。用 curl 发一个最简单的请求curl http://10.0.1.11:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen-32b, messages: [{role: user, content: 你好}], max_tokens: 64 }能正常返回就说明推理服务通了。然后测试流式接口把stream设为true观察输出是否连续、是否有中断。最后测试长上下文发一个 3000 token 左右的输入确认模型能正常处理不报错。这三步过了模型层就算就绪。6.3 MCP Server 开发与注册开发一个 MCP Server核心是实现工具列表和工具调用两个接口。以 Python 为例用 MCP SDK 大概几十行代码就能起一个 Server。关键是把工具的逻辑写清楚参数校验做严格。开发完后在 Agent 的 MCP 配置里注册{ mcpServers: { database: { url: http://10.0.1.20:9001/sse, description: 内网数据库工具集 }, code_repo: { url: http://10.0.1.20:9002/sse, description: 代码仓库工具集 } } }注册后重启 Agent用“列出所有可用工具”的指令验证 Agent 能否正确识别到这些工具。如果识别不到检查网络连通性和 SSE 端点是否正常响应。6.4 Skills 包的制作与分发制作一个 Skill先写SKILL.md把技能的目标、触发条件、执行步骤、依赖工具写清楚。然后准备模板文件和规则文件。做完后在 Agent 里测试触发和执行效果。测试通过后把整个技能目录打包通过内网文件共享分发到 Agent 服务器的 skills 目录下重启 Agent 生效。我一般会维护一个内网技能仓库用 Git 管理技能包的版本。每次更新技能走内网 Git 提交然后通过部署脚本自动同步到 Agent 服务器。这样技能迭代有记录、可回滚比手工拷贝文件靠谱得多。7. 常见问题与排查技巧实录7.1 模型调用超时与并发瓶颈内网 Agent 最常见的性能问题是模型调用超时。原因通常有两个一是模型推理本身慢二是并发请求把推理服务打满了。排查时先看推理服务的 GPU 利用率和请求队列长度。如果 GPU 利用率长期 100%说明算力不够要么加卡要么把更多任务路由到小模型。如果 GPU 利用率不高但请求排队说明推理框架的并发配置有问题需要调整 worker 数量。我遇到过的一个坑是Agent 框架默认并发调用模型但推理框架的批处理配置没开导致每个请求单独推理吞吐量极低。后来在推理框架里开启连续批处理continuous batching吞吐量提升了 3 倍多。这个配置项在推理框架的文档里通常都有但容易被忽略。7.2 MCP 工具调用失败排查MCP 工具调用失败按这个顺序排查先确认 Agent 能否列出工具说明连接正常再确认工具参数是否符合 schema说明调用格式正确最后看工具内部逻辑是否报错看 MCP Server 日志。我遇到最多的问题是参数类型不匹配比如模型传了个字符串但 schema 要求整数。解决办法是在工具描述里把参数类型写得更明确同时在 Server 层做类型转换兜底。还有一个隐蔽的坑是 SSE 连接超时。内网如果有多层网络设备长连接可能被中间设备断开。解决办法是在 MCP Server 和 Agent 两侧都加心跳机制定期发送空事件保持连接活跃。7.3 Skills 不触发或触发错误Skills 不触发先检查技能目录是否被 Agent 正确扫描到看启动日志再检查触发条件是否匹配用户请求。如果触发条件写得太窄可以适当放宽关键词范围。如果触发错误说明意图匹配阈值太低需要调高阈值或增加排除条件。我踩过的一个坑是两个技能的触发关键词有重叠导致 Agent 随机选一个执行。解决办法是在技能描述里明确优先级或者在 Agent 编排层加一个技能冲突检测当多个技能同时匹配时让模型根据上下文选最合适的那个。7.4 内网环境特有的依赖与权限问题内网环境里权限问题比外网复杂得多。Agent 进程可能没有权限访问某些内网资源MCP 工具可能没有权限连接某些数据库。这类问题的排查思路是先用命令行工具如 curl、psql以相同身份手动测试确认是权限问题还是代码问题。如果是权限问题找内网管理员开通不要试图绕过。另一个常见问题是内网 DNS 解析。有些内网环境没有 DNS只能用 IP 地址。这时候所有配置里的主机名都要换成 IP包括模型服务地址、MCP 服务地址、数据库地址。我建议在内网部署时统一用 IP避免 DNS 解析带来的不确定性。8. 一些实操心得与后续扩展方向做内网 AI Agent 这段时间我最大的体会是内网不是限制而是约束条件下的重新设计。外网环境下你可以堆资源、调 API、用最新模型内网环境下你必须把每一层都做扎实反而逼出了更清晰的架构。MCP 让工具接入标准化Skills 让领域知识可沉淀这两者结合即使模型能力有限Agent 也能干出不错的活。后续我打算在这几个方向继续扩展一是把 Skills 做成可组合的一个复杂技能可以调用多个简单技能像搭积木一样拼出复杂流程二是给 MCP 工具加调用审计所有工具调用记录到内网日志系统方便追溯和优化三是探索多 Agent 协作让不同 Agent 分别负责不同领域通过内网消息队列协同完成任务。这些方向在内网环境下都有落地价值等有新的实践结果再跟大家分享。最后分享一个小技巧内网 Agent 的调试一定要把每次对话的完整上下文用户输入、模型输出、工具调用、工具返回都落盘到内网日志里。内网环境没法像外网那样随手接个调试工具日志是你唯一的排查依据。日志格式建议用 JSON Lines每行一条记录方便后续用脚本分析。这个习惯能帮你省下大量排查时间。