1. 为什么隔离内网里的 AI Agent 工程是另一套玩法先把场景说清楚。所谓隔离内网指的是开发机、构建机、运行环境全部处在一个无法直接访问公网的封闭网络里外部的模型 API、包管理源、镜像仓库、在线文档统统够不着。很多团队一开始的想法很朴素不就是把公网那套 AI Agent 工程搬进来吗真搬的时候才发现公网环境下那些一行命令搞定的操作在内网里每一步都要重新设计。我在这种环境里做过几轮 AI Agent 的落地最大的感受是内网 AI Agent 工程的核心矛盾不是模型够不够强而是依赖怎么进来、状态怎么管、能力怎么扩展。公网环境下你可以随手pip install、随手调一个云端 MCP 服务、随手拉一个 Skills 市场里的现成能力内网里这些路径全部断掉你必须自己搭一套可离线运转的工程体系。这篇文章面向的是这样几类人一是在金融、制造、政企等强隔离环境里做 AI 应用落地的工程师二是想把 AI Agent 从玩具 Demo做成能进生产的团队三是已经用过 MCP、Skills 这些概念但一到内网就卡壳的开发者。我会围绕依赖离线化、MCP 服务自建、Skills 工程化管理、并发与稳定性这几条主线把内网 AI Agent 工程实战里真正会踩的坑和能复用的方案讲透。需要先明确一个前提内网 AI Agent 不是公网 Agent 的阉割版而是一套约束条件完全不同的工程形态。公网拼的是模型能力和生态丰富度内网拼的是可控性、可审计性和可复现性。理解了这个差异后面所有的技术选型才有依据。2. 内网 AI Agent 的依赖困境与离线化改造2.1 公网开发习惯在内网会全面失效在公网做 AI Agent你的典型工作流是这样的装个 Python 环境pip install langchain openai mcp配个 API Key跑起来。整个过程依赖三个外部条件——包管理源可达、模型服务可达、扩展能力MCP/Skills可在线获取。内网把这三个条件同时掐断。我见过最常见的翻车场景团队在内网机器上敲pip install卡在Looking in indexes半天然后超时或者代码里写死了某个云端模型的 endpoint一进内网直接连接拒绝再或者用了一个在线 MCP 服务做文件操作内网里这个服务根本注册不上。这些问题的本质都一样——你的工程隐含依赖了公网可达性而这个假设在内网不成立。所以内网 AI Agent 工程的第一步不是写 Agent 逻辑而是做依赖盘点与离线化。把所有需要联网才能拿到的东西列出来逐个找离线替代方案。2.2 依赖离线化的三层拆解我把内网 AI Agent 的依赖分成三层每层的处理方式不同依赖层级公网典型做法内网替代方案关键注意点运行时依赖pip/npm 在线安装内网私有源如 devpi、Nexus、Verdaccio需提前在能联网的机器上做依赖快照模型服务调用云端 API内网自部署推理服务vLLM、TGI、Ollama 等显存与并发要提前压测扩展能力在线 MCP/Skills 市场自建 MCP Server 本地 Skills 仓库协议版本要对齐避免不兼容第一层是运行时依赖。核心思路是外网打包、内网还原。具体做法是在一台能联网的机器上用pip download把整个依赖树下载成 wheel 包或者用pip freeze导出精确版本再通过内网私有源分发。这里有个容易忽略的点很多包在安装时会触发编译比如某些带 C 扩展的库内网机器如果没有对应的编译工具链和头文件装到一半就失败。稳妥的做法是尽量下载预编译好的 wheel而不是源码包。第二层是模型服务。内网不可能调云端 API必须自部署。选型上如果追求吞吐和并发vLLM 是当前比较主流的选择如果只是小规模验证Ollama 上手最快。这里的关键不是选哪个框架而是提前压测显存和并发上限。我踩过的坑是本地测试单条请求响应很快一上并发就 OOM因为没算 KV Cache 的显存占用。经验公式是显存需求大致等于模型权重 并发数 × 单请求 KV Cache后者随上下文长度线性增长长上下文场景要特别小心。第三层是扩展能力也就是 MCP 和 Skills。这是内网 AI Agent 工程里最容易被低估的部分。公网环境下你可以直接连一个现成的 MCP 服务内网里必须自己实现。下一节专门讲。2.3 依赖快照的可复现性设计内网工程有个硬要求今天能跑起来的环境三个月后换台机器还得能跑起来。这就要求依赖快照必须精确到版本号甚至到哈希。我的做法是维护一份requirements.lock里面锁定每个包的确切版本和来源。同时把下载好的 wheel 包按目录归档配合一个内网的pip.conf指向私有源。这样新机器接入时只需要配置源地址一条命令就能还原环境不依赖任何外网。提示不要用pip install -U这种会拉取最新版的命令。内网环境里最新版意味着不可控一旦某个依赖悄悄升级可能整个 Agent 链路就崩了。锁定版本是内网工程的基本纪律。3. MCP 在内网的自建与协议对齐3.1 MCP 到底解决了什么问题MCPModel Context Protocol本质上是一套让模型和外部工具之间标准化通信的协议。在没有它之前你给 Agent 接一个数据库、接一个文件系统、接一个内部 API每个都要写一套自定义的胶水代码工具一多就乱成一团。MCP 把这些能力抽象成统一的 ServerAgent 作为 Client 按协议去调用工具的实现和 Agent 的逻辑就解耦了。在内网环境里MCP 的价值反而更大。因为内网的工具生态是封闭的你更需要一套统一协议来管理这些内部能力——数据库查询、日志检索、配置读取、内部工单系统全部包装成 MCP ServerAgent 侧只认协议不认具体实现。这样新增一个内部工具只要实现一个 MCP ServerAgent 不用改代码。3.2 内网自建 MCP Server 的实操路径自建 MCP Server 有两种主流方式stdio 模式和SSE/HTTP 模式。选哪种取决于你的部署形态。stdio 模式适合单机、进程内启动的场景Agent 直接拉起 Server 进程通过标准输入输出通信。优点是简单、无网络依赖缺点是每个 Agent 实例都要拉一个 Server 进程资源占用高不适合多实例共享。SSE/HTTP 模式适合服务化部署MCP Server 作为独立服务跑在内网某台机器上多个 Agent 通过内网地址连接。优点是能力共享、便于统一管理缺点是要处理网络通信的稳定性。内网生产环境我一般推荐HTTP 模式因为内网本身就是可信网络网络通信不是瓶颈而服务化带来的可管理性收益很大。一个典型的 MCP Server 骨架大概长这样# 基于官方 mcp SDK 的简化示例 from mcp.server import Server from mcp.server.models import InitializationOptions import mcp.types as types server Server(internal-tools) server.list_tools() async def list_tools(): return [ types.Tool( namequery_internal_db, description查询内网业务数据库, inputSchema{ type: object, properties: { sql: {type: string, description: 只读 SQL} }, required: [sql] } ) ] server.call_tool() async def call_tool(name: str, arguments: dict): if name query_internal_db: # 这里接内网数据库注意做只读和权限校验 result run_readonly_query(arguments[sql]) return [types.TextContent(typetext, textstr(result))]这段代码的关键不在语法而在两个工程细节一是权限校验必须做在 Server 侧不能指望 Agent 侧自觉二是工具描述要写清楚因为模型是靠 description 来决定调不调这个工具的描述含糊会导致误调用。3.3 协议版本对齐这个坑MCP 协议本身在演进不同版本的 SDK 在消息格式、能力声明上可能有差异。内网环境里最尴尬的情况是Agent 侧用的 SDK 版本和 Server 侧不一致握手阶段就失败而且报错信息往往很含糊看不出是版本问题。我的经验是在内网里Agent 侧和所有 MCP Server 侧的 SDK 版本必须统一锁定并且记录在工程文档里。升级时要么全升要么全不升不要出现混用。另外MCP 的能力协商capabilities要在启动日志里打出来方便排查为什么某个工具没被识别到这类问题。注意内网自建 MCP Server 时工具的数量不要一次性堆太多。工具过多会导致模型在选择时犹豫反而降低准确率。我一般把同类工具控制在 10 个以内超过就做分组按场景加载不同的工具集。4. Skills 的工程化管理从散装提示词到可维护资产4.1 Skills 不是提示词是可复用的能力单元很多人把 Skills 理解成一段写好的提示词这个理解太浅。在内网 AI Agent 工程里Skills 应该是可版本管理、可测试、可组合的能力单元。一个 Skill 通常包含触发条件什么时候用、执行逻辑怎么做、依赖工具需要哪些 MCP 能力、输出规范结果长什么样。公网环境下你可以从各种市场下载现成 Skills内网里必须自建 Skills 仓库。这个仓库不是简单放几个 markdown 文件而是要有一套管理机制命名规范、版本号、依赖声明、测试用例。4.2 内网 Skills 仓库的目录结构设计我用的目录结构大致是这样skills/ ├── registry.json # 技能注册表声明所有可用技能 ├── code_review/ │ ├── skill.md # 技能定义触发条件、执行逻辑 │ ├── deps.json # 依赖的 MCP 工具 │ └── tests/ # 测试用例 ├── log_analysis/ │ ├── skill.md │ ├── deps.json │ └── tests/ └── db_query/ ├── skill.md ├── deps.json └── tests/registry.json是核心它让 Agent 知道内网里有哪些技能可用。deps.json声明这个技能依赖哪些 MCP 工具加载技能时先检查依赖是否满足避免运行到一半才发现工具缺失。tests/目录放测试用例保证技能改动后行为不漂移。这套结构看起来有点重但内网工程的现实是技能一旦上线会被多个 Agent 复用改动的爆炸半径很大。没有版本管理和测试改一个技能可能悄悄影响好几个业务线。4.3 技能加载与按需注入内网 Agent 不可能把所有技能一次性塞进上下文那样既浪费 token 又干扰模型判断。正确做法是按需加载Agent 先根据用户意图匹配候选技能再把匹配到的技能定义注入上下文。匹配逻辑可以很简单比如基于关键词或向量相似度也可以复杂一点用一个轻量模型做意图分类。内网环境下我倾向于用规则 向量的混合方式规则处理高频明确意图向量兜底长尾。这样既保证常见场景的准确率又不至于完全依赖模型判断。加载技能时有个细节要注意技能定义里的工具调用示例要写具体。模型看到调用 query_internal_db 查询数据这种模糊描述可能不知道怎么填参数写成调用 query_internal_dbsql 参数形如SELECT id, name FROM orders WHERE statuspending模型就能照着模仿。这个技巧在内网自建技能时特别管用因为内网没有大量公开示例供模型参考。5. 并发、稳定性与内网特有的工程约束5.1 AI Agent 怎么扛并发AI Agent 怎么扛并发是个高频问题内网环境下这个问题更尖锐因为你的模型服务是自部署的算力上限是硬的。先说结论Agent 的并发瓶颈通常不在 Agent 框架本身而在模型推理服务。Agent 逻辑是轻量的编排真正吃资源的是每次模型调用。所以扛并发的核心是优化模型服务的吞吐。几个实操手段请求排队与限流在 Agent 和模型服务之间加一层队列控制并发请求数不超过模型服务的承载上限。超过就排队而不是直接打爆。批处理batchingvLLM 这类框架支持连续批处理把多个请求合并推理显著提升吞吐。要确保你的调用方式能利用上这个特性。缓存对于重复性高的查询比如固定的系统提示、常见问题做结果缓存减少模型调用次数。降级策略并发高峰时把非关键请求路由到小模型保证核心链路可用。我踩过的一个坑是Agent 侧用了异步并发一口气发了 50 个请求给模型服务结果模型服务 OOM 直接挂掉。后来加了信号量控制把并发压到模型服务能承受的范围稳定性立刻上来了。并发控制的责任在 Agent 侧不能指望模型服务自己扛住。5.2 内网环境的稳定性设计内网虽然网络稳定但有自己的稳定性挑战服务发现靠静态配置、没有云端的弹性伸缩、故障恢复靠人工。所以内网 Agent 的稳定性设计要更保守。几个原则超时和重试要显式配置。内网服务偶尔重启是常态Agent 调用 MCP 工具或模型服务时必须有超时和有限重试避免一个卡死的调用拖垮整个链路。关键路径要有降级。模型服务不可用时Agent 应该能返回一个明确的错误提示而不是无限等待。日志要足够详细。内网排查问题没有云端那些可观测性工具全靠日志。每次模型调用、每次工具调用输入输出都要落盘方便事后复盘。5.3 内网特有的安全与审计约束内网 AI Agent 往往涉及内部数据安全和审计是硬要求。几个必须做的点工具调用要留痕。哪个 Agent、什么时间、调用了哪个工具、传了什么参数、返回了什么全部记录。这既是审计要求也是排查问题的依据。敏感操作要二次确认。比如写数据库、发消息这类有副作用的操作Agent 不能自主执行要经过人工确认或走审批流。数据不出内网。所有模型推理、工具调用都在内网完成不涉及任何外部传输。这也是内网部署的核心价值。提示内网 Agent 的审计日志建议单独存储不要和业务日志混在一起。审计日志的保留周期通常比业务日志长混存会导致清理策略冲突。6. 从 Demo 到生产内网 AI Agent 的落地节奏6.1 分阶段推进别想一步到位内网 AI Agent 落地最容易犯的错是一上来就做全功能。正确的节奏是分阶段第一阶段打通单点能力。选一个明确的场景比如内网日志查询助手把模型服务、一个 MCP Server、一个 Skill 跑通验证整条链路。这个阶段的目标不是功能多而是链路通。第二阶段扩展工具与技能。在跑通的链路上增加更多 MCP 工具和 Skills验证技能加载、依赖管理、并发控制这些机制是否可靠。第三阶段接入真实业务并做稳定性加固。这时候才会暴露真实的并发压力、异常场景、审计需求针对性地加固。我见过太多团队跳过第一阶段直接做全能 Agent结果每个环节都没打磨好最后变成一个谁都不敢用的半成品。6.2 内网工程的文档与交接内网环境人员流动时交接成本特别高因为外部查不到资料。所以工程文档必须写得像给三个月后的自己看依赖怎么还原、MCP Server 怎么启动、Skills 怎么新增、常见故障怎么排查全部写清楚。我的习惯是维护一份RUNBOOK.md里面记录所有出问题时该怎么办的操作步骤。比如模型服务无响应对应哪几条排查命令MCP 工具调用失败先看哪个日志。这份文档的价值在内网环境里远超你的想象。6.3 一个真实的落地体会最后分享一个我在内网落地 AI Agent 时体会最深的点内网工程的成败八成取决于依赖管理和协议对齐两成才是 Agent 逻辑本身。公网环境下大家把精力花在提示词调优、模型选型上因为基础设施是现成的内网里基础设施要自己搭这部分工作枯燥但决定生死。我现在的做法是任何内网 Agent 项目启动前先花时间把依赖清单、MCP 协议版本、Skills 管理规范这三件事定下来再动手写 Agent。前期多花两天后期能省两周。这个投入产出比在内网环境里是实打实算得过来的。如果你也在做内网 AI Agent建议先从最小链路跑通开始把 MCP 和 Skills 的管理机制搭起来再逐步扩展。别被公网那些花哨的 Agent 框架带偏内网要的是稳、可控、可复现这三点做到了Agent 才真正能进生产。