1. 为什么“隔离内网 AI Agent”是个真问题而不是伪需求先把场景说清楚。所谓隔离内网指的是物理或逻辑上与公网断开、只能通过跳板机或专线做受控数据交换的网络环境。银行核心机房、制造业产线控制网、政企办公专网、医院 HIS 系统所在网段基本都是这个形态。这类环境里做 AI Agent 工程和你在公网云主机上跑个 LangChain Demo 完全是两码事。公网环境下你习惯了pip install直接拉包、模型 API 随手调、MCP Server 想连就连。到了隔离内网这些默认前提全部失效没有外网 DNS、没有 PyPI 镜像、模型权重得靠离线包搬运、Agent 要调用的工具服务全在内网自建。很多人第一次进内网做 Agent卡在第一步——连 Python 环境都装不齐。那为什么还要在内网做 Agent因为真正的业务数据、真正的操作权限、真正的生产系统都在内网。你在公网搭的 Agent 再花哨碰不到核心数据就是玩具。内网 Agent 的价值在于它能直接读工单系统、查监控指标、调运维接口、走审批流。这才是“让 AI 真的下地干活”。这篇内容适合三类人一是被派到内网环境做 AI 落地的工程师二是想搞清楚 Agent 工程化到底难在哪的技术负责人三是已经会写 Agent Demo、但一上生产就翻车的开发者。我会把内网 Agent 从环境准备、协议选型、Skills 设计到并发扛压的完整链路拆开讲重点讲那些文档里不会写、只有踩过才知道的细节。需要先明确一个认知内网 Agent 工程的核心矛盾不是“模型够不够聪明”而是“在资源受限、网络隔离、运维管控严格的条件下如何让 Agent 稳定、可观测、可回滚地跑起来”。这个矛盾决定了后面所有的技术选型和架构设计。2. 内网 Agent 的运行时底座从 Python 环境到模型部署2.1 离线依赖搬运别指望 pip 能联网内网第一道坎就是依赖。我的做法是在一台能联网的机器上用pip download把整个依赖树拉下来再整体搬进内网。这里有个坑pip download默认只下当前平台的 wheel如果内外网机器架构或 Python 版本不一致装的时候会现场编译而内网往往没有编译工具链。# 在联网机器上指定平台和 Python 版本下载 pip download -r requirements.txt \ --platform manylinux2014_x86_64 \ --python-version 311 \ --only-binary:all: \ -d ./offline_packages # 内网机器上离线安装 pip install --no-index --find-links./offline_packages -r requirements.txt--only-binary:all:这个参数很关键它强制只下载预编译 wheel避免内网现场编译。如果某个包没有对应平台的 wheel你就得提前在内网准备好 gcc、make 这些工具链或者找替代包。我遇到过psycopg2没有 wheel 的情况最后换成了psycopg2-binary。提示把requirements.txt里的版本号全部锁死用pip freeze生成。内网环境最怕的就是“上次能跑这次不能跑”版本漂移是隐形杀手。2.2 模型部署本地推理还是内网 API 网关内网 Agent 的模型来源通常有两种一是本地部署开源模型Qwen、DeepSeek、GLM 等二是内网已有的模型 API 网关。选哪个取决于你的算力预算和延迟要求。本地部署的好处是数据不出网、延迟可控、不依赖其他团队。坏处是显存吃紧、模型能力受限于你买得起的卡。我的经验是7B 到 14B 的模型用 vLLM 或 SGLang 部署在单张 A100 或 4090 上跑 Agent 的规划、工具调用、结果总结这类任务够用。再大就得上多卡成本和运维复杂度陡增。如果内网已经有模型网关很多企业统一建了推理平台优先接网关。这样模型升级、扩缩容由平台团队负责你只管 Agent 逻辑。接网关时注意两点一是确认网关支持 function calling 或 tool use 的协议格式二是确认它的并发上限和超时策略这直接决定你 Agent 的吞吐。# 接内网模型网关的典型配置 from openai import OpenAI client OpenAI( base_urlhttp://model-gateway.intranet/v1, # 内网地址 api_keyintranet-token, # 内网鉴权 timeout60.0, # 内网延迟通常比公网高 max_retries2 ) # 关键确认网关是否支持 tools 参数 response client.chat.completions.create( modelqwen2.5-14b-instruct, messagesmessages, toolstool_schemas, # 不支持的话这里会报错或静默忽略 tool_choiceauto )2.3 内网 Agent 的进程模型别用单进程硬扛公网 Demo 里一个 Flask 进程跑 Agent 循环没问题。内网生产环境不行因为 Agent 的一次完整推理可能包含多轮工具调用单次耗时从几秒到几十秒不等。如果用同步单进程并发一上来全部阻塞。我的做法是把 Agent 执行和 HTTP 服务拆开HTTP 层用 FastAPI 或 Flask 接收请求把任务丢进消息队列内网常用 RabbitMQ 或 Redis Stream后台用独立的 Worker 进程池消费。这样 HTTP 层可以快速返回任务 IDWorker 按自己的节奏执行并发能力由 Worker 数量决定。# FastAPI 层只负责接收和入队 from fastapi import FastAPI import redis app FastAPI() r redis.Redis(hostredis.intranet, port6379) app.post(/agent/run) async def run_agent(payload: dict): task_id generate_task_id() r.xadd(agent_tasks, {task_id: task_id, payload: json.dumps(payload)}) return {task_id: task_id, status: queued} # Worker 层独立进程消费 def worker_loop(): while True: tasks r.xread({agent_tasks: $}, count1, block5000) for _, entries in tasks: for _, data in entries: execute_agent(data) # 这里跑完整的 Agent 循环这个拆分带来的好处是HTTP 层可以水平扩展Worker 层可以根据模型推理能力单独扩容任务积压时也不会拖垮接口。3. MCP 与 Skills内网 Agent 的能力扩展怎么设计3.1 MCP 到底是什么先把这个概念钉死热词里有人问“MCP 是软件协议还是硬件协议那个概念”。明确说MCPModel Context Protocol是一个软件层的通信协议不是硬件协议。它定义的是“模型/Agent 如何发现和调用外部工具、资源、提示模板”的标准接口。你可以把它理解成 Agent 世界的 USB 接口标准——只要工具实现了 MCP Server任何支持 MCP 的 Agent 都能接上。在内网环境MCP 的价值被放大了。因为内网工具服务五花八门有的是 REST API有的是 gRPC有的是数据库直连有的是老系统的 SOAP 接口。如果每个工具都让 Agent 单独适配代码会烂成一团。MCP 提供了一层统一抽象你为每个工具写一个 MCP ServerAgent 侧只需要一个 MCP Client 就能全部调通。MCP Server 的传输方式在内网要特别注意。公网常用 stdio本地进程和 SSEHTTP 长连接。内网如果 Agent 和工具不在同一台机器stdio 用不了得用 SSE 或 Streamable HTTP。但内网防火墙可能对长连接有超时限制我遇到过 SSE 连接 60 秒被切断的情况最后改成了短轮询加任务队列的模式。# 一个内网 MCP Server 的最小骨架SSE 模式 from mcp.server import Server from mcp.server.sse import SseServerTransport from starlette.applications import Starlette from starlette.routing import Route server Server(intranet-tools) server.tool() async def query_ticket(ticket_id: str) - str: 查询内网工单系统的工单详情 # 这里走内网数据库或内部 API return fetch_ticket_from_intranet(ticket_id) sse SseServerTransport(/messages) async def handle_sse(request): async with sse.connect_sse(request.scope, request.receive, request._send) as streams: await server.run(streams[0], streams[1], server.create_initialization_options()) app Starlette(routes[Route(/sse, endpointhandle_sse)])3.2 Skills 设计把“会做一件事”封装成可复用单元Skills 这个词在不同语境下含义不同。在 Agent 工程里我把它定义为“面向特定任务的能力封装”比单个工具调用更高一层。一个 Skill 可能包含多个工具调用、一段提示词模板、一套输出校验逻辑。举个例子内网有个“服务器巡检”Skill。它不是简单调一个 API而是先查监控系统拿 CPU/内存指标再查日志系统找异常关键字再对比基线阈值最后生成巡检报告。这一整套流程封装成一个 SkillAgent 只需要说“执行巡检”不用关心中间步骤。Skills 的设计原则我总结成三条单一职责一个 Skill 只做一类事。巡检就是巡检不要混进“顺便重启服务”。幂等优先内网操作很多是不可逆的Skill 要尽量设计成可重复执行不出错。查询类天然幂等写操作类要加确认机制。输出结构化Skill 返回的结果要结构化JSON方便 Agent 后续推理也方便日志审计。# Skill 的结构化定义 class InspectionSkill: name server_inspection description 对内网服务器执行健康巡检返回结构化报告 async def execute(self, server_id: str) - dict: metrics await self.get_metrics(server_id) logs await self.get_error_logs(server_id) baseline await self.get_baseline(server_id) issues [] if metrics[cpu] baseline[cpu_threshold]: issues.append({type: cpu_high, value: metrics[cpu]}) if logs[error_count] 0: issues.append({type: errors_found, count: logs[error_count]}) return { server_id: server_id, healthy: len(issues) 0, issues: issues, raw_metrics: metrics }3.3 内网 MCP 与 Skills 的权限边界这是内网特有的、公网教程几乎不会提的问题。公网 Agent 调工具最坏情况是 API 报错。内网 Agent 调工具如果权限没控好可能直接改生产数据、重启核心服务。我的做法是给 MCP Server 和 Skills 加三层管控第一层是工具白名单。Agent 能调用的工具列表在配置里写死不允许动态发现。内网环境不需要“自动发现新工具”这种花哨功能稳定可控优先。第二层是操作分级。把工具分成只读、写入、危险三类。只读类直接放行写入类需要 Agent 明确说明意图危险类如重启、删除必须走人工确认Agent 只能生成待确认工单。第三层是审计日志。每次工具调用记录谁调的、调了什么、参数是什么、返回什么、耗时多少。内网合规审计是硬要求日志格式要能直接对接企业日志平台。权限层级典型操作管控方式审计要求只读查询指标、读日志直接放行记录调用写入创建工单、更新配置意图确认记录参数危险重启服务、删除数据人工审批全链路留痕4. 并发扛压内网 Agent 最容易翻车的地方4.1 先搞清楚瓶颈在哪模型、工具还是编排“AI Agent 怎么扛并发”是热词里高频出现的问题。很多人一上来就加机器其实没找到瓶颈。Agent 的并发瓶颈通常在三处模型推理、工具调用、编排逻辑。模型推理是最大头。一次 Agent 循环可能调模型 3 到 10 次每次推理几百毫秒到几秒。如果模型服务本身并发只有 4你 Agent 层开 100 个 Worker 也没用全堵在模型那。所以第一步是压测模型服务的实际并发上限。工具调用是第二瓶颈。内网工具服务往往不是为高并发设计的一个查询接口可能只支持 10 QPS。Agent 并发一高工具服务先崩。这时候要么给工具服务加缓存要么在 Agent 侧做限流。编排逻辑本身很少成为瓶颈但如果你的 Agent 循环里有同步阻塞操作比如同步 HTTP 请求、同步数据库查询会白白浪费 Worker 时间。全部改成异步是基本要求。# 用信号量控制对模型服务的并发 import asyncio model_semaphore asyncio.Semaphore(8) # 根据压测结果设定 async def call_model(messages): async with model_semaphore: return await model_client.chat(messages) # 工具调用也加限流 tool_semaphore asyncio.Semaphore(16) async def call_tool(tool_name, args): async with tool_semaphore: return await tool_registry.execute(tool_name, args)4.2 任务队列 Worker 池内网最稳的并发模型前面提过 HTTP 层和 Worker 层拆分这里展开讲 Worker 池怎么设计。Worker 数量不是越多越好。每个 Worker 占内存、占模型并发额度。我的经验公式是Worker 数 min(模型并发上限, 工具服务 QPS 上限) × 0.8。留 20% 余量应对突发。任务队列要支持优先级。内网 Agent 的任务有轻重缓急用户交互式请求要快后台批量巡检可以慢。用 Redis 的多个 Stream 或者 RabbitMQ 的多个队列实现优先级高优先级 Worker 池单独跑。超时和重试必须做。内网网络抖动、工具服务偶发超时是常态。给每个任务设总超时比如 120 秒给每次模型/工具调用设单次超时比如 30 秒。重试要区分错误类型网络超时可以重试参数错误重试没意义。# Worker 池的启动脚本 import multiprocessing def start_workers(pool_name, count): for i in range(count): p multiprocessing.Process(targetworker_loop, args(pool_name,)) p.start() if __name__ __main__: # 高优先级池处理用户交互 start_workers(high_priority, 4) # 低优先级池处理后台任务 start_workers(low_priority, 8)4.3 背压与降级内网 Agent 的保命机制内网资源有限扛不住无限涌入的请求。背压机制是必须的当队列积压超过阈值新请求直接返回“系统繁忙”而不是无限排队。这听起来不友好但比整个系统雪崩好得多。降级策略也要提前设计。模型服务挂了怎么办可以降级到规则引擎处理简单请求。工具服务挂了怎么办返回缓存的上次结果并标注“数据可能过期”。这些降级逻辑要在 Agent 编排层写好不能等出事再补。注意内网环境做压测要提前报备。很多内网有流量监控和告警你突然打高并发可能触发安全告警甚至被误判为攻击。我第一次在内网压测就被安全团队找上门了。5. 可观测性内网 Agent 出问题时你怎么知道5.1 日志、指标、链路追踪三件套公网 Agent 出问题你可以随手加 print 或者接个云监控。内网不行你得提前把可观测性建好。日志要结构化用 JSON 格式包含 trace_id、task_id、step、tool_name、duration、status 这些字段。内网通常有统一的日志平台ELK 或 Loki你的日志格式要能直接对接。指标要暴露 Prometheus 格式。关键指标包括任务队列长度、Worker 利用率、模型调用延迟分布、工具调用成功率、Agent 循环轮数分布。这些指标能帮你快速定位瓶颈。链路追踪在内网 Agent 里特别重要因为一次任务跨多个服务。用 OpenTelemetry 做埋点每个 Agent 步骤生成一个 span工具调用生成子 span。出问题时能一眼看出卡在哪一步。# 结构化日志示例 import structlog logger structlog.get_logger() logger.info( agent_step, trace_idtrace_id, task_idtask_id, steptool_call, tool_namequery_ticket, duration_ms234, statussuccess )5.2 内网特有的排查难点内网排查和公网最大的区别是你不能随手curl外网、不能 Google 报错信息、不能随便装排查工具。所以要把常用排查手段提前准备好。我习惯在内网机器上常备这些tcpdump抓包看网络、strace看系统调用、py-spy看 Python 进程卡在哪。py-spy特别有用它能 dump 运行中 Python 进程的调用栈不用重启服务就能看 Worker 卡在哪个函数。# 用 py-spy 看 Worker 进程卡在哪 py-spy dump --pid worker_pid # 抓包看内网工具服务是否响应 tcpdump -i eth0 -nn port 8080 -c 100还有一个内网特有的坑DNS 解析。内网 DNS 可能不稳定或者配置有误导致工具服务域名解析失败。我的做法是在 Agent 配置里直接用 IP或者配 hosts 文件绕开 DNS。5.3 告警阈值怎么定告警不能太多也不能太少。太多会麻木太少会漏。我的经验是盯这几个核心指标任务队列长度持续 5 分钟超过 100说明消费能力不足模型调用 P99 延迟超过 10 秒说明模型服务压力大工具调用失败率超过 5%说明工具服务有问题Worker 全部忙碌持续 3 分钟说明需要扩容告警要能区分“需要立即处理”和“需要关注”。前者打电话后者发消息。内网环境半夜被叫起来处理告警很痛苦所以阈值要调准。6. 从 Demo 到生产内网 Agent 的落地检查清单6.1 上线前必须验证的几件事内网 Agent 上线前我会跑一遍这个清单离线依赖完整断网环境下能正常启动模型服务可达内网地址、鉴权、超时都验证过工具权限正确每个工具的最小权限都配对了队列和 Worker 正常压测过知道上限在哪日志能采集日志平台能收到结构化日志告警能触发手动造异常确认告警链路通降级能生效手动停模型服务确认降级逻辑工作回滚方案就绪出问题能快速回退到上一版本这个清单看起来简单但每一条我都见过翻车的。特别是“降级能生效”这条很多人写了降级代码但从来没测过真出事时降级逻辑本身有 bug。6.2 版本管理和灰度发布内网 Agent 的版本管理比公网更严格因为回滚成本高。我的做法是Agent 的提示词、Skills 配置、工具白名单全部版本化和代码一起管理。每次变更生成一个版本号部署时记录当前版本。灰度发布在内网同样适用。先在一个 Worker 池部署新版本观察一段时间指标正常再全量。如果内网有多个业务线共用 Agent可以按业务线灰度。# Agent 版本配置示例 agent_version: v2.3.1 prompt_version: prompt-20260115 skills: - name: server_inspection version: 1.2.0 - name: ticket_query version: 1.0.3 tools_whitelist: - query_metrics - query_logs - create_ticket6.3 我踩过的几个真实坑第一个坑内网时间不同步。Agent 服务、模型服务、工具服务的机器时间差了几分钟导致日志时间戳对不上排查时完全理不清顺序。后来统一配了内网 NTP。第二个坑模型网关的 token 限制。内网网关为了省资源把单次请求的 token 上限设得很低Agent 多轮对话到后面直接被截断。这个要在接入前就问清楚。第三个坑工具服务的连接池。内网工具服务很多是 Java 写的默认连接池很小。Agent 并发一高就报连接超时。要么让工具服务调大连接池要么在 Agent 侧控制并发。第四个坑日志把磁盘写满。Agent 调试期日志打得太详细内网机器磁盘又小跑了两天磁盘满了整个服务挂掉。后来加了日志轮转和磁盘监控。7. 内网 Agent 工程的长期演进思路内网 Agent 不是做完就完了它需要持续演进。我看到的合理路径是从单点工具调用到多工具编排再到 Skills 沉淀最后到 Agent 中台化。初期你可能是为一个具体场景做 Agent比如工单自动分类。这时候工具少、逻辑简单快速跑通最重要。中期场景变多你会发现很多能力可以复用这时候把通用能力抽成 Skills建立 Skills 库。后期多个业务线都要用 Agent就需要中台化统一的模型网关、统一的工具注册中心、统一的 Skills 市场、统一的监控和审计。中台化听起来美好但内网做中台要克制。不要为了中台而中台先把一个场景做深做透再考虑抽象。我见过太多团队一上来就搭中台结果中台没搭好业务场景也没落地。还有一个趋势值得关注Agent 的评测和持续优化。内网 Agent 上线后你需要一套评测机制来判断它到底好不好用。可以收集用户反馈、统计任务成功率、分析失败案例。这些数据反过来指导提示词优化和 Skills 改进。没有评测的 Agent就是在盲跑。最后说个务实的判断内网 Agent 工程的核心竞争力不在于你用了多新的框架而在于你对内网环境的理解深度——你知道哪里会卡、哪里会崩、哪里需要提前留后手。这些认知都是从一次次踩坑里攒出来的。