1. 为什么要在隔离内网里折腾 AI Agent先把场景说清楚。所谓隔离内网就是那种物理上跟公网断开、或者只允许单向数据流入的办公网、生产网、研发网。很多做金融、制造、政企项目的团队日常开发机根本连不上外网npm、pip、docker hub 全部走不通更别提调用云端大模型 API 了。在这种环境里谈 AI Agent第一反应往往是不可能——模型跑不起来、依赖装不上、MCP 服务连不通三座大山压下来很多人直接放弃。但我实际做下来发现隔离内网反而是 AI Agent 最能体现价值的场景。原因很简单内网里沉淀了大量私有知识、内部工具链、业务系统接口这些东西恰恰是通用云端 Agent 碰不到的。一个能读懂内部代码库、能调用内部工单系统、能自动生成符合内部规范的文档的 Agent对团队的效率提升是实打实的。关键在于你得把整套工程链路拆开把必须联网的部分替换成内网自洽的方案。这篇文章面向的是有基本开发经验、正在或即将在隔离内网环境里落地 AI Agent 的工程师。我会把整体架构思路、核心组件选型、MCP 与 Skills 的落地方式、实操步骤、以及我踩过的坑全部摊开讲。读完你应该能拿到一套可以直接抄作业的工程方案而不是停留在概念很美好的阶段。需要提前说明的是内网环境千差万别有的完全物理隔离有的允许通过跳板机做有限的数据同步。我会以完全隔离 定期离线同步这个最严格的场景为基准来展开其他场景可以按需放宽。2. 整体架构设计与选型思路2.1 隔离内网 AI Agent 的分层结构在公网环境里搭 Agent大家习惯性地把所有东西都往云上堆模型用 API、向量库用托管服务、工具调用走远程 MCP。但内网里这套逻辑完全失效必须重新分层。我最终落地的架构分成四层从下往上依次是模型层本地部署的开源大模型负责推理和生成。这是整个系统的地基模型选错了后面全白搭。能力层包括 MCP 服务、Skills 技能包、工具函数库。这一层决定了 Agent 能干什么活。编排层Agent 的主循环、任务规划、工具调度、上下文管理。这一层是大脑。接入层对内提供 HTTP 接口或命令行入口对接内部业务系统。这个分层的好处是每一层都可以独立替换和测试。比如模型层从 7B 换成 14B只要接口协议不变上层完全无感。能力层新增一个 MCP 服务也不用动编排逻辑。2.2 模型选型为什么我不建议一上来就上大参数内网部署模型第一个绕不开的问题就是显存。我见过太多团队一上来就想部署 70B结果发现要 4 张 A100预算直接卡死。我的建议是分阶段来第一阶段用 7B 到 14B 的量化模型跑通全链路验证 Agent 的编排逻辑、工具调用、MCP 通信是否正常。这个阶段模型能力弱一点没关系因为你要验证的是工程链路不是模型智商。等链路稳了再根据实际业务需求决定是否升级到 32B 或更大。选型上我实测下来比较稳的几个方向通用对话和工具调用能力均衡的模型适合做 Agent 主控代码理解能力强的模型适合做代码库问答类 Agent。具体型号这里不展开因为模型迭代太快你按参数量 量化等级 上下文长度三个维度去评估就行。注意内网部署模型一定要提前确认推理框架对量化格式的支持情况。我遇到过 GGUF 格式在某个推理框架上加载失败折腾半天才发现是版本不匹配白白浪费一天。2.3 MCP 在内网里的定位与改造MCP 是 Model Context Protocol 的缩写本质是一套让模型和外部工具、数据源通信的标准协议。公网环境下大家用现成的 MCP Server 连各种 SaaS但内网里你得自己写 MCP Server把内部系统包装成模型能调用的工具。我为什么坚持用 MCP 而不是自己定义一套工具调用格式因为 MCP 的协议设计已经把工具描述、参数 schema、调用结果返回这些细节标准化了。你按 MCP 写一次换模型、换编排框架都能复用。自己造轮子短期省事长期维护成本极高。内网里 MCP 的改造重点有两个一是传输方式公网常用的 SSE 在内网里其实可以用但更稳的是 stdio 本地进程通信省去网络层的不确定性二是工具注册内网工具往往需要鉴权MCP Server 里要把内部 token 管理做好不能让模型直接接触敏感凭证。2.4 Skills 机制把会做的事沉淀成资产Skills 这个概念最近很火说白了就是把 Agent 完成某类任务的流程、提示词、工具组合打包成一个可复用的技能单元。比如生成周报是一个 Skill代码审查是一个 Skill查询工单状态是一个 Skill。在内网环境里Skills 的价值被放大了。因为内网的业务逻辑高度定制化通用模型根本不知道你们内部的审批流程长什么样。把这些流程固化成 SkillAgent 每次执行都按既定套路走稳定性和准确率都会大幅提升。我的做法是每个 Skill 用一个目录管理里面放三样东西一份描述文件说明这个 Skill 干什么、什么时候触发一份提示词模板定义执行时的指令一份工具清单列出需要调用的 MCP 工具。这样新增 Skill 就是加一个目录不需要改核心代码。3. 核心组件落地与实操要点3.1 离线依赖同步把公网资源搬进内网这是整个工程里最枯燥但最不能省的一步。内网装不了 pip 包、拉不了 docker 镜像所有依赖都得提前在公网机器上准备好再通过合规的离线通道搬进去。我的标准流程是这样的先在公网机器上建一个跟内网同版本的操作系统环境把所有 Python 依赖用pip download下载成 wheel 包把所有 docker 镜像用docker save导出成 tar 文件把所有模型权重文件单独打包。然后列一份清单记录每个包的版本号、来源、校验值。# 公网机器上导出 Python 依赖 pip download -r requirements.txt -d ./offline_packages --platform manylinux2014_x86_64 --python-version 310 --only-binary:all: # 导出 docker 镜像 docker save -o model_server.tar model-server:1.0 docker save -o mcp_server.tar mcp-server:1.0搬进内网后用pip install --no-index --find-links./offline_packages -r requirements.txt安装用docker load -i xxx.tar导入镜像。提示一定要在公网环境里把依赖装一遍验证能跑通再打包。我踩过的坑是下载的 wheel 包在目标平台架构不匹配进内网才发现装不上又得重新走一遍离线流程非常浪费时间。3.2 MCP Server 的内网实现细节写一个内网 MCP Server核心是把内部能力包装成标准工具。我以查询内部工单系统为例讲一下实现要点。首先定义工具的输入输出 schema。MCP 要求每个工具都有明确的参数描述模型才能正确调用。工单查询工具需要工单号作为输入返回工单状态、处理人、创建时间等字段。schema 写清楚模型调用准确率会高很多。然后是鉴权。内网系统通常有自己的认证机制MCP Server 里要维护一个凭证池模型调用工具时由 Server 层去取凭证而不是让模型直接传 token。这样既安全也避免模型把敏感信息写进对话历史。传输方式我推荐 stdio。Agent 编排层启动时把 MCP Server 作为子进程拉起通过标准输入输出通信。这种方式没有网络开销也不受内网防火墙策略影响稳定性最好。如果确实需要跨机器调用再用 SSE 或 HTTP 传输。# MCP Server 工具注册的简化示意 from mcp.server import Server from mcp.types import Tool server Server(internal-ticket) server.list_tools() async def list_tools(): return [ Tool( namequery_ticket, description根据工单号查询工单状态和处理人, inputSchema{ type: object, properties: { ticket_id: {type: string, description: 工单编号} }, required: [ticket_id] } ) ] server.call_tool() async def call_tool(name, arguments): if name query_ticket: # 内部鉴权逻辑在这里处理不暴露给模型 result internal_api.query(arguments[ticket_id]) return {status: result.status, owner: result.owner}3.3 Skills 的设计与触发机制Skills 设计的关键是触发条件和执行流程要分离。触发条件决定 Agent 什么时候用这个 Skill执行流程决定用了之后怎么一步步做。触发条件我一般用两种方式一种是关键词匹配简单直接适合流程固定的场景另一种是让模型自己判断把 Skill 的描述放进系统提示词里模型根据用户意图决定是否调用。前者稳定但死板后者灵活但可能误触发。实际项目里我通常两者结合关键词做初筛模型做确认。执行流程用提示词模板加工具序列来实现。比如代码审查这个 Skill流程是先读取目标文件再按内部编码规范逐条检查最后生成审查报告。每一步对应一个 MCP 工具调用提示词里把顺序和判断逻辑写清楚。注意Skill 的提示词不要写得太长太细否则会挤占上下文窗口。我的经验是每个 Skill 的提示词控制在 500 字以内把关键约束写清楚就行细节交给模型自己发挥。3.4 编排层Agent 主循环怎么写才稳编排层是整个系统的心脏。我见过不少实现把主循环写成一个巨大的 while 循环里面塞满了 if-else最后根本没法维护。我的做法是把主循环拆成几个独立阶段意图理解、任务规划、工具执行、结果整合。意图理解阶段模型判断用户想干什么是否需要调用 Skill。任务规划阶段把复杂任务拆成子步骤。工具执行阶段按规划调用 MCP 工具处理返回结果。结果整合阶段把工具返回的原始数据加工成用户能看懂的回复。每个阶段之间用明确的数据结构传递不要用裸字符串。我定义了一个 Task 对象包含任务描述、已执行步骤、当前状态、待执行步骤等字段。这样调试的时候一眼就能看出卡在哪一步。并发处理是另一个重点。内网 Agent 经常要同时查多个系统串行调用太慢。我的做法是把无依赖的工具调用并行化用异步任务池管理。但要注意有依赖关系的调用必须串行比如先查工单号再查工单详情顺序不能乱。4. 完整实操流程与关键环节4.1 环境准备清单在动手之前先把环境清单列清楚。我按必须项和可选项分类你可以对照自己的内网情况勾选。类别项目说明是否必须硬件GPU 服务器显存至少 24G跑 14B 量化模型必须硬件存储空间模型权重加依赖包预留 200G必须软件操作系统主流 Linux 发行版内核版本别太老必须软件推理框架支持目标模型格式的推理服务必须软件Python 环境3.10 及以上与离线包版本一致必须软件容器运行时用于跑 MCP Server 和业务服务可选数据离线依赖包公网下载后搬入必须数据模型权重提前下载并校验必须4.2 模型部署与验证模型部署这一步我建议先用最小配置跑通再逐步加负载。启动推理服务后先用一个简单的 curl 请求验证接口通不通再测工具调用格式能不能正确解析。# 验证推理服务是否正常 curl -X POST http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: local-model, messages: [{role: user, content: 你好}], max_tokens: 100 }返回正常后再测工具调用。构造一个带 tools 参数的请求看模型能不能正确输出工具调用格式。这一步很关键因为不同模型对工具调用的支持程度差异很大有的模型需要特定的提示词模板才能触发。4.3 MCP Server 启动与联调MCP Server 写好后先单独测试再跟 Agent 联调。单独测试时用 MCP 官方的调试工具或者自己写个脚本模拟工具调用请求确认返回结果符合预期。联调阶段最容易出问题的是进程管理。如果 MCP Server 作为子进程启动要处理好启动顺序、超时、异常退出重启这些情况。我的做法是给每个 MCP Server 配一个健康检查启动后先 ping 一下确认就绪再让 Agent 调用。# MCP Server 健康检查示意 async def wait_for_mcp_ready(process, timeout30): start time.time() while time.time() - start timeout: if await ping_mcp(process): return True await asyncio.sleep(1) raise TimeoutError(MCP Server 启动超时)4.4 Skills 加载与测试Skills 加载我做成动态扫描目录的方式。Agent 启动时扫描 skills 目录读取每个 Skill 的描述文件注册到 Skill 注册表。这样新增 Skill 不用重启服务热加载就行。测试 Skill 时我准备了一组标准测试用例每个 Skill 至少覆盖三种情况正常触发、边界输入、不该触发时是否误触发。特别是误触发很多 Skill 描述写得模糊导致 Agent 在不该用的时候用了结果答非所问。4.5 端到端联调与压测全链路打通后做一轮端到端测试。我一般准备 20 到 30 个真实业务场景的问题覆盖单工具调用、多工具串联、Skill 触发、异常处理等场景。记录每个问题的响应时间、工具调用次数、结果准确率。压测方面内网 Agent 的并发压力通常不大但也要测一下。重点看模型推理的排队情况、MCP Server 的并发处理能力、以及长时间运行后内存是否泄漏。我遇到过 MCP Server 跑一天后内存涨到几个 G 的情况最后发现是连接池没释放。5. 常见问题与排查技巧实录5.1 模型不调用工具怎么办这是最高频的问题。模型明明有能力调工具但就是不用直接自己编答案。排查思路分三步第一检查工具描述是否清晰。工具名和参数描述要具体别用处理数据这种模糊表述。第二检查提示词里有没有明确要求必须使用工具获取信息不要凭记忆回答。第三检查模型本身对工具调用的支持程度有些小模型工具调用能力很弱换模型可能比调提示词更有效。5.2 MCP 通信超时或断连内网环境里 MCP 通信出问题八成是进程管理或资源限制导致的。先看 MCP Server 进程还在不在再看系统资源是否吃紧。如果是 stdio 传输检查子进程的标准输出有没有被阻塞。我遇到过一次是 MCP Server 里有个 print 语句把 stdout 污染了导致协议解析失败找了很久才发现。5.3 Skill 误触发或漏触发误触发通常是描述太宽泛漏触发通常是描述太窄或者触发条件写死了。我的调优方法是把 Skill 描述当成给新员工的说明书来写既要让人知道什么时候用也要让人知道什么时候不用。可以在描述里加一句当用户询问 X 时使用当用户询问 Y 时不要使用。5.4 常见问题速查表问题现象可能原因排查方向解决思路模型不调工具描述模糊/提示词缺失检查工具 schema 和系统提示细化描述加强制调用指令MCP 超时进程卡死/资源不足查进程状态和系统负载重启进程加健康检查Skill 误触发描述过宽看触发日志收窄描述加否定条件响应慢串行调用/模型排队看各阶段耗时并行化无依赖调用内存泄漏连接未释放长时间运行后看内存检查连接池和缓存结果不准上下文丢失看对话历史优化上下文管理策略5.5 我踩过的几个坑第一个坑是模型量化等级选太高导致工具调用格式经常输出错误。后来降到 Q4 量化稳定性明显提升。量化不是越高越好要在效果和稳定性之间找平衡。第二个坑是 MCP Server 的日志直接打到 stdout污染了 stdio 协议。后来所有日志统一走 stderr 或者文件问题解决。第三个坑是 Skill 目录扫描时没做异常处理某个 Skill 的描述文件格式错误导致整个加载流程崩溃。后来加了 try-catch单个 Skill 出错只跳过它不影响其他 Skill。6. 内网 Agent 的扩展方向与个人体会跑通基础链路之后可以往几个方向扩展。一是接入更多内部系统把 MCP 工具库做厚Agent 能干的活就越多。二是做 Skill 的版本管理让 Skill 可以迭代升级而不是改一次就覆盖。三是加一层评估机制定期用测试用例跑一遍看 Agent 的表现有没有退化。我个人在实际操作中的体会是内网 AI Agent 的难点从来不在模型本身而在工程链路的完整性和稳定性。模型能力差一点用户能感知到但能容忍工具调用失败、响应超时、结果错乱这些工程问题才是真正劝退用户的。所以我的建议是前期把 80% 的精力花在链路稳定性上模型选型够用就行别本末倒置。最后分享一个小技巧在内网环境里给 Agent 加一个降级模式。当模型推理服务不可用或者 MCP 工具全部超时时Agent 自动切换到纯规则匹配的简单问答模式至少保证基础功能可用。这个降级开关在演示和应急场景下特别有用能避免整个系统因为单点故障而完全瘫痪。