1. 为什么“隔离内网 AI Agent”是个真问题先把场景说清楚。所谓隔离内网就是一台或者一批机器物理上或者策略上跟公网断开装不了外网依赖拉不了镜像连 pip install 都得走内部源。很多做 AI Agent 的朋友第一反应是这玩意儿不是要调大模型 API 吗内网怎么玩其实真正在企业里落地的 Agent恰恰大量跑在内网——因为数据不能出去业务系统在内网数据库在内网连要操作的那台设备都在内网。我在几个不同规模的团队里都做过内网 Agent 的落地从最早用脚本硬拼到后来引入 MCP、Skills 这套工程化思路踩的坑基本能写一本书。这篇就把“隔离内网下 AI Agent 工程实战”这件事拆开讲透内网环境到底卡在哪、MCP 和 Skills 分别解决什么问题、模型怎么接、工具怎么挂、并发怎么扛、以及那些文档里不会写的实操细节。先给一个结论性的判断内网 Agent 的难点从来不是“模型聪不聪明”而是“工程链路能不能在断网环境下自洽”。模型可以本地部署也可以走内网网关转发但工具调用、依赖管理、状态持久化、并发调度这些工程问题才是真正决定项目能不能上线的分水岭。这篇文章适合三类人一是在企业内网做自动化、运维、数据处理的工程师二是想把 Agent 从 Demo 推到生产的技术负责人三是刚接触 MCP、Skills 这些概念想知道它们在内网场景下到底怎么用的开发者。下面我按实际落地的顺序一层层拆。2. 内网环境到底卡在哪四个绕不开的约束2.1 依赖获取pip、npm、镜像全都够不着内网最直接的痛点是装不了东西。你在公网机器上pip install langchain一行搞定内网机器上这行命令会直接超时。常见的应对方式有三种我按推荐度排内部私有源公司如果有 Nexus、Artifactory 这类制品库把需要的包提前同步进去这是最干净的方案。离线 wheel 打包在公网机器上用pip download把依赖连同依赖的依赖一起下下来拷进内网pip install --no-index --find-links./packages。注意一定要带--no-index否则它还是会去连外网。整机镜像直接把配好环境的机器做成镜像内网批量部署。适合环境固定的场景缺点是更新麻烦。这里有个坑我踩过pip download默认只下当前平台的 wheel如果你的内网机器是 ARM 架构公网打包机是 x86拷过去一堆包装不上。正确做法是加平台参数pip download langchain \ --platform manylinux2014_aarch64 \ --python-version 311 \ --only-binary:all: \ -d ./packages--only-binary:all:强制只下二进制包避免下到源码包在内网编译时又缺编译工具链。2.2 模型接入本地部署还是内网网关内网 Agent 的“大脑”怎么来是第一个架构决策。两条路本地部署开源模型。用 vLLM、TGI 或者 Ollama 在内网 GPU 机器上起一个推理服务Agent 通过内网 HTTP 调用。优点是数据完全不出内网缺点是模型能力受限于你能部署的规模7B、14B 级别的模型做复杂工具调用时稳定性明显不如大模型。内网网关转发。如果公司有统一的模型网关很多企业会搭一个内部的大模型服务平台Agent 直接调网关的内网地址。这种方式模型能力强但要注意网关的限流和鉴权策略别把网关打挂了。我的经验是工具调用密集、逻辑复杂的 Agent优先走网关纯文本处理、数据脱敏类的本地模型够用。判断标准很简单——如果你的 Agent 需要连续调用 5 个以上工具才能完成任务本地小模型的指令遵循能力大概率会让你抓狂。2.3 网络策略出站白名单和 DNS 的隐形坑内网机器通常有严格的出站策略。哪怕你模型网关在内网Agent 要访问的数据库、业务系统 API 也可能分布在不同网段。这时候要提前确认目标服务的 IP 和端口是否在防火墙白名单里内网 DNS 能不能解析目标域名很多内网服务只认 IP 不认域名有没有做 SNI 检查或者 TLS 拦截这会影响 HTTPS 调用。我遇到过一次特别隐蔽的问题Agent 调内网某个 API 一直超时ping 通、telnet 端口也通最后发现是那台机器配了物理 DHCP网关指向了一个不通的出口。排查这类问题traceroute和curl -v比什么都管用。2.4 可观测性日志出不去怎么排障公网环境出问题可以看云厂商的监控面板内网只能靠自己。我的做法是在 Agent 服务里内置一个本地日志轮转同时暴露一个内网的 metrics 端点Prometheus 格式用内网的 Grafana 看。关键指标至少要有每次工具调用的耗时、失败率、模型 token 消耗、并发队列长度。没有这些线上出问题你只能靠猜。3. MCP 与 Skills内网 Agent 工程化的两块拼图3.1 MCP 到底是什么为什么内网特别需要它MCP 全称 Model Context Protocol是一个让模型和外部工具、数据源之间标准化通信的协议。你可以把它理解成“AI 世界的 USB 接口”——以前每个工具都要写一套适配代码现在只要工具实现了 MCP Server任何支持 MCP 的 Agent 都能直接挂上去用。内网场景下 MCP 的价值被放大了。因为内网工具五花八门有的是老系统的 HTTP 接口有的是数据库有的是命令行工具如果每个都手写适配维护成本极高。用 MCP 统一封装之后Agent 侧只需要一个 MCP Client工具侧各自实现 Server解耦得非常干净。MCP 是软件协议不是硬件协议。经常有人问“MCP 是软件协议还是硬件协议那个概念”答案很明确它是应用层的软件协议通常走 stdio 或者 HTTP/SSE 传输。内网里我更推荐 stdio 方式因为不涉及端口暴露安全性更好如果工具要跨机器共享再用 HTTP 方式。3.2 Skills把“怎么做一件事”沉淀成可复用资产Skills 这个概念这两年很火本质是把一类任务的操作流程、提示词、工具组合打包成一个可复用的能力单元。比如“查数据库并生成报表”是一个 Skill“调用内部工单系统创建工单”是另一个 Skill。内网里 Skills 的意义在于知识沉淀。老员工知道某个业务系统的接口有个隐藏参数新人不知道把这个写进 Skill 里Agent 就永远知道。我一般会把 Skill 拆成三部分触发描述什么情况下该用这个 Skill写得越具体模型选错工具的概率越低执行步骤调哪些工具、按什么顺序、参数怎么填异常处理失败了怎么办重试还是降级。这里有个实操心得Skill 的触发描述不要写得太“聪明”。我见过有人写“当用户需要处理数据时使用”结果模型什么任务都往里套。正确写法是“当用户要求查询 MySQL 中 orders 表的订单状态时使用”边界清晰误触发率直线下降。3.3 内网里 MCP Server 的部署形态内网部署 MCP Server我总结了几种常见形态各有适用场景部署形态适用场景优点注意点stdio 本地进程单机 Agent工具在本机无网络暴露启动简单进程管理要自己搞HTTP 内网服务多 Agent 共享工具集中维护易扩展要做鉴权和限流容器化 SidecarK8s 环境生命周期统一管理镜像要提前进内网仓库网关聚合工具特别多统一入口网关本身成为瓶颈大部分内网项目我建议从 stdio 起步等工具有三五个以上、需要多 Agent 共享时再迁到 HTTP 服务。4. 从零搭一个内网 Agent完整落地路径4.1 技术选型为什么我倾向 FastAPI LangGraph内网 Agent 的框架选择核心看两点可控性和依赖复杂度。LangChain 生态全但依赖重内网打包时经常因为某个间接依赖卡住。我的组合是 FastAPI 做服务层LangGraph 做 Agent 编排。FastAPI 的好处是依赖轻、异步原生、自带 OpenAPI 文档内网调试时直接看/docs就能测接口。LangGraph 相比传统 Chain 的优势在于它把 Agent 执行建模成状态图每个节点是一个步骤边是流转条件特别适合需要多轮工具调用、有条件分支的复杂任务。而且它的状态是显式的出问题能精确定位到哪个节点。如果你团队已经在用 Spring 生态Spring AI Agent 也是内网可选项Java 系的内网部署经验更成熟但工具生态相比 Python 略少。选型没有绝对对错看团队栈。4.2 环境准备离线依赖清单怎么定内网打包最怕漏依赖。我的做法是先在一台能联网的干净机器上用虚拟环境装好所有依赖然后pip freeze requirements.txt再按这个清单下载。关键是要把运行时才动态加载的依赖也考虑进去比如某些库会在运行时 import 可选的加速包。一个实用的检查方法在联网机器上跑一遍完整的 Agent 流程把所有 import 到的包都记录下来。可以用python -X importtime -c import your_agent_module 21 | sort -k2 -n这样能看到实际加载了哪些模块避免遗漏。4.3 模型接入层统一封装方便切换不管后端是本地模型还是网关我都会在 Agent 和模型之间加一层薄封装。原因是内网环境经常变——今天用网关明天网关维护要切本地模型如果代码里到处是具体的 API 调用改起来要命。封装层至少要做三件事统一的消息格式转换、统一的错误重试、统一的 token 计数。重试策略尤其重要内网网络抖动比公网更常见我一般配指数退避最多重试 3 次。4.4 工具层MCP Server 的编写与注册写一个内网 MCP Server核心是实现工具的描述和调用。工具描述要包含名称、用途、参数 schema、返回值说明。参数 schema 用 JSON Schema 写模型靠它来决定怎么填参数。注册到 Agent 时我习惯做一个工具注册表把 MCP Server 暴露的工具统一收集起来加上内网特有的元信息比如“这个工具只能在工作时间调用”“这个工具会写数据库需要二次确认”。这些元信息在编排时非常有用。4.5 编排层用状态图管理多步任务LangGraph 的状态图里我一般会定义这么几类节点意图识别、工具选择、工具执行、结果校验、人工确认、结束。边上的条件决定流转方向。比如结果校验不通过就回到工具选择重新选涉及写操作就流转到人工确认节点。这里的关键设计是状态要可持久化。内网任务经常跑很久中间服务重启不能丢状态。LangGraph 支持 checkpointer可以存到内网的 Redis 或 PostgreSQL。5. 并发这道坎内网 Agent 怎么扛住压力5.1 先搞清楚瓶颈在哪“AI Agent 怎么扛并发”是热词但很多人一上来就想着加机器其实先要定位瓶颈。Agent 的请求链路通常是接收请求 → 模型推理 → 工具调用 → 再推理 → 返回。这里面最慢的往往是模型推理和工具调用而不是你的服务框架。我的做法是先压测用 locust 或者 wrk 打看 P99 延迟卡在哪个环节。如果模型推理占了 80% 的时间那你优化服务代码意义不大得从模型侧想办法。5.2 异步化把等待时间利用起来Agent 处理一个请求大量时间在等模型返回、等工具返回。如果用同步阻塞的方式一个请求占一个线程并发上不去。FastAPI 的异步能力在这里就体现出来了模型调用和工具调用都用 async等待期间可以处理其他请求。但要注意不是所有库都支持异步。有些内网老系统的 SDK 只有同步版本硬套 async 会阻塞事件循环。这种情况用run_in_executor丢到线程池里跑别让它卡住主循环。5.3 队列与限流保护后端不被打垮内网资源有限模型网关和数据库都经不起突发流量。我会在 Agent 前面加一层队列请求先入队worker 按能力消费。队列用 Redis 或者内存队列都行关键是要有背压机制——队列满了就快速失败返回“系统繁忙”而不是无限堆积把内存撑爆。限流按维度做全局 QPS 限制、单用户限制、单工具限制。特别是写操作类的工具一定要限流否则并发写数据库很容易出问题。5.4 缓存能省一次模型调用就省一次Agent 场景里有很多重复请求。比如“查一下今天的订单量”如果一分钟内多个人问没必要每次都走一遍完整推理。我会对意图明确、参数相同的请求做结果缓存缓存 key 用意图加参数哈希。但缓存要谨慎涉及实时数据的不能缓存涉及写操作的绝对不能缓存。我一般只对读操作、且数据时效性要求不高的场景开缓存。5.5 实测数据参考在一个中等规模的内网环境单台 8 卡 GPU 机器跑本地模型Agent 服务 4 核 8G我实测过一组数据供参考并发数平均延迟P99 延迟成功率52.1s4.3s100%203.8s9.2s99.8%508.5s22s97%100超时增多40s85%可以看到瓶颈明显在模型推理。后来加了请求队列和限流把并发控制在 30 左右P99 稳定在 12s 以内成功率回到 99.5% 以上。内网 Agent 的并发不是越高越好找到系统的稳定工作点更重要。6. 那些文档里不会写的踩坑记录6.1 工具描述写得太模糊模型乱调工具这是最高频的问题。模型选工具完全靠描述描述模糊它就开始猜。我见过一个“查询数据”的工具结果模型拿它去查天气。解决办法前面提过描述要具体到业务对象和操作类型。6.2 内网时间不同步导致 token 过期内网机器如果没配 NTP时间会漂移。如果 Agent 调用的服务用了时间敏感的 token时间一漂就鉴权失败。这个坑很隐蔽因为报错信息通常是“token invalid”你会以为是密钥问题。内网部署第一件事就是确认所有机器时间同步。6.3 长任务把连接池占满Agent 处理长任务时如果一直占着数据库连接或者 HTTP 连接不放连接池很快耗尽。正确做法是用完即还长任务分阶段执行每个阶段独立获取连接。6.4 日志里打印了敏感数据内网虽然相对安全但日志里打印用户数据、密钥、内部 IP 依然是坏习惯。我一般会在日志层做脱敏手机号、身份证、密钥这类字段统一打码。6.5 模型幻觉导致工具参数错误本地小模型填工具参数时经常幻觉比如把日期填成未来时间。防御手段是在工具执行前做参数校验校验不过就返回错误让模型重试而不是直接执行。7. 内网 Agent 的扩展方向与个人体会把基础链路跑通之后能扩展的方向不少。比如接入更多 MCP Server 把内网系统都串起来做 Agent 中台让多个业务线共享能力或者引入更细的 Skills 体系做领域知识沉淀。Browser Use 和 Playwright 这类浏览器自动化 MCP 在内网也有用武之地比如操作那些没有 API 的老系统区别在于 Browser Use 更偏自然语言驱动Playwright 更偏精确控制内网里我倾向 Playwright因为可控性更强。我个人最大的体会是内网 Agent 项目七分靠工程三分靠模型。模型能力固然重要但真正决定成败的是依赖管理、错误处理、并发控制、可观测性这些“不性感”的工程活。我见过太多团队模型选得很激进结果卡在离线依赖打包上两周动不了。另外一个建议是从小场景切入。别一上来就想做全能 Agent先挑一个边界清晰、价值明确的场景比如“自动查询工单状态并汇总”把它做扎实跑通整条链路再逐步扩展。内网环境试错成本高小步快跑比大干快上靠谱得多。最后分享一个实用技巧在内网 Agent 服务里内置一个“自检”接口启动时自动检查模型连通性、工具可用性、依赖完整性任何一项不过就拒绝启动并打印明确原因。这个接口能帮你省掉大量“服务起来了但用不了”的排查时间。