1. 隔离内网下的 AI Agent 工程化落地从零搭建到稳定运行很多做企业级交付的朋友都遇到过这种场景客户现场只有一台跳板机能连外网业务服务器全部在隔离内网里没有公网出口没有外部镜像源甚至连 pip install 都要走内部私有仓库。在这种环境下要把 AI Agent 跑起来难度不是模型本身而是整条工程链路怎么在断网条件下自洽。我前后在三个不同行业的隔离环境里落地过 AI Agent 项目从最早的纯脚本拼凑到后来用 MCP 协议做工具编排踩过的坑足够写一本小册子。这篇就把整套思路和实操细节摊开讲适合正在做内网交付的工程师、需要把 Agent 部署到生产隔离区的团队以及想搞清楚 MCP、Skills 这些概念在内网场景下到底怎么用的人。先说清楚一个前提隔离内网不等于完全离线。绝大多数企业内网是逻辑隔离——有内部镜像源、有内部 Git 服务、有内部模型推理服务只是不能访问公网。真正物理隔离的环境我也做过那种情况下连模型权重都要靠移动介质导入工程复杂度会再上一个台阶。下面讲的内容以逻辑隔离为主物理隔离的差异点我会单独标注。2. 为什么隔离内网下的 Agent 工程和公网完全不是一回事2.1 三个核心约束决定了架构走向在公网环境里搭 Agent你随手就能pip install langchain、npm install modelcontextprotocol/sdk模型直接调云端 API工具想接什么接什么。但隔离内网里这三个自由度全部被砍掉依赖获取受限。所有第三方包必须提前下载好 wheel 或 tarball通过内部制品库分发。版本冲突、传递依赖缺失、平台架构不匹配比如内网服务器是 ARM 而你的开发机是 x86这些问题会在部署阶段集中爆发。模型调用受限。云端 API 基本不可用只能用内网部署的推理服务。常见的是 vLLM、TGI 或者公司自研的推理网关接口协议可能是 OpenAI 兼容的也可能是私有的。这直接影响 Agent 框架的选型——有些框架强绑定特定厂商 SDK在内网就是死路。工具生态受限。MCP 这类协议的价值在内网反而更突出因为它把工具调用标准化了你不需要为每个工具写适配代码。但 MCP Server 本身也要在内网部署涉及进程管理、端口分配、权限隔离等一堆运维问题。2.2 架构选型的核心权衡我见过不少团队一上来就想上全套LangGraph 做编排、MCP 做工具、向量库做 RAG、再加一层网关做鉴权。结果在内网部署时发现光是依赖就装了两天最后砍到只剩核心功能。我的建议是分阶段推进。第一阶段只解决能跑一个轻量 Agent 循环 内网模型 两三个核心工具。第二阶段解决好用引入 MCP 标准化工具接口加上 Skills 做能力扩展。第三阶段解决稳定并发控制、超时重试、日志追踪、灰度发布。这个顺序不能反。我见过直接上第三阶段然后卡在第一阶段的团队最后项目延期两个月。2.3 内网环境下的技术栈对比维度公网常用方案内网推荐方案选择理由模型接入云端 API内网 vLLM/TGIOpenAI 兼容协议协议标准化框架适配成本低工具编排直接函数调用MCP 协议解耦工具与 Agent便于独立升级依赖管理pip/npm 直连内部制品库 离线 wheel 包可控、可审计、可回滚向量存储云服务本地 Milvus/Qdrant/FAISS数据不出内网可观测性SaaS 平台自建 Prometheus Loki无外部依赖这张表不是绝对的但基本覆盖了 80% 的隔离内网场景。下面逐个展开。3. 内网 Agent 工程的核心模块拆解3.1 模型接入层怎么让 Agent 用上内网模型内网模型服务通常有两种形态一种是标准的 OpenAI 兼容接口vLLM、TGI 都支持另一种是公司自研的私有协议。优先选前者因为几乎所有 Agent 框架都支持 OpenAI 协议改个 base_url 就能用。配置上要注意几个点。第一是max_tokens和context_length要和内网模型的实际能力对齐很多内网部署的模型是量化版本上下文窗口比原版小。第二是超时设置内网推理服务如果没做批处理优化单次响应可能到几十秒Agent 框架默认超时往往不够。第三是并发限制内网 GPU 资源有限Agent 如果并发调用会把推理服务打满。# 内网模型接入的典型配置 from openai import OpenAI client OpenAI( base_urlhttp://internal-llm-gateway:8000/v1, # 内网推理网关 api_keyinternal-token, # 内网通常用固定 token 或走 mTLS timeout120.0, # 内网推理慢超时要放宽 max_retries2, # 重试次数不宜多避免打爆推理服务 ) # 调用时显式控制并发 response client.chat.completions.create( modelqwen2.5-72b-instruct, # 内网部署的模型名 messages[{role: user, content: ...}], temperature0.1, # Agent 场景温度要低保证稳定性 max_tokens2048, )提示内网模型名不要硬编码在代码里放到配置文件或环境变量。不同环境开发/测试/生产的模型名可能不一样硬编码会导致部署时改代码。3.2 MCP 协议内网工具标准化的关键MCPModel Context Protocol本质是一套让 Agent 和工具之间通信的协议规范。它的价值在于工具提供方只需要实现 MCP ServerAgent 侧只需要实现 MCP Client双方通过标准协议通信不需要知道对方内部实现。在内网环境里MCP 的部署方式通常是 stdio 或 SSE。stdio 模式最简单MCP Server 作为子进程启动通过标准输入输出通信不需要开端口适合单机部署。SSE 模式需要开 HTTP 端口适合多 Agent 共享工具服务的场景。// MCP Server 配置示例stdio 模式 { mcpServers: { internal-db-query: { command: python, args: [/opt/mcp-servers/db_query_server.py], env: { DB_HOST: internal-db.internal, DB_PORT: 5432 } }, internal-file-search: { command: /opt/mcp-servers/file_search, args: [--index-path, /data/index] } } }内网部署 MCP Server 有几个坑要注意。第一是路径问题stdio 模式下 command 的路径必须是绝对路径相对路径在不同工作目录下会失效。第二是环境变量传递MCP Server 子进程不会自动继承父进程的所有环境变量需要显式配置。第三是日志stdio 模式下 stdout 被协议占用日志必须走 stderr 或文件否则会污染协议通信。3.3 Skills 机制让 Agent 能力可插拔Skills 这个概念在不同框架里叫法不一样有的叫 Tools有的叫 Actions本质都是Agent 可以调用的能力单元。在内网环境里Skills 的设计要考虑三个问题怎么注册、怎么发现、怎么隔离。注册方式推荐用声明式配置而不是硬编码。每个 Skill 用一个独立的配置文件描述包括名称、描述、参数 schema、执行入口。这样新增 Skill 不需要改 Agent 主程序只需要加配置文件。# skill 配置示例 name: query_internal_api description: 查询内网业务系统的订单信息 parameters: type: object properties: order_id: type: string description: 订单编号 date_range: type: string description: 日期范围格式 YYYY-MM-DD~YYYY-MM-DD required: - order_id executor: type: http url: http://internal-api.internal/order/query method: POST timeout: 30发现机制上内网环境建议用文件系统扫描 热加载。Agent 启动时扫描指定目录下的所有 skill 配置文件运行期间定期检查文件变化有更新就重新加载。这样运维人员新增 Skill 不需要重启 Agent。隔离方面不同 Skill 的权限要分开。查询类 Skill 只读操作类 Skill 需要审批高危 Skill比如执行 shell 命令要单独隔离到沙箱环境。我见过因为 Skill 权限没隔离导致 Agent 误删生产数据的案例这个坑一定要提前防。3.4 依赖管理离线环境下的包分发这是内网部署最烦人的环节。公网环境pip install一行命令搞定内网要提前把所有依赖下载好还要处理传递依赖和平台兼容性。我的做法是分三步。第一步在公网环境用pip download把所有依赖下载到本地目录包括传递依赖。第二步把下载的包上传到内网制品库Nexus、Artifactory 都行。第三步内网机器配置 pip 源指向内部制品库。# 公网环境下载所有依赖含传递依赖 pip download -r requirements.txt -d ./offline_packages \ --platform manylinux2014_x86_64 \ --python-version 311 \ --only-binary:all: # 内网环境从本地目录安装 pip install --no-index --find-links./offline_packages -r requirements.txt注意--platform和--python-version必须和内网目标环境完全一致否则下载的 wheel 装不上。如果内网是 ARM 架构要指定manylinux2014_aarch64。对于 Node.js 项目用npm pack或者yarn offline mirror做类似的事情。Rust 项目用cargo vendor把依赖 vendor 到本地目录。4. 完整实操从零在内网部署一个可用的 Agent4.1 环境准备与依赖导入假设内网环境是 CentOS 7 Python 3.11 无公网。第一步是准备离线依赖包。在公网机器上创建一个和内网一致的环境可以用 Docker 模拟然后执行依赖下载。这里有个技巧先用pip freeze导出完整依赖树再逐个下载避免遗漏传递依赖。# 1. 在公网机器创建虚拟环境 python3.11 -m venv build_env source build_env/bin/activate # 2. 安装项目依赖 pip install -r requirements.txt # 3. 导出完整依赖树 pip freeze full_requirements.txt # 4. 下载所有包 pip download -r full_requirements.txt -d ./offline_packages \ --platform manylinux2014_x86_64 \ --python-version 311 \ --only-binary:all: # 5. 打包 tar czf offline_packages.tar.gz offline_packages/把offline_packages.tar.gz通过内部文件传输通道传到内网解压后配置 pip 使用本地目录。# 内网机器上 tar xzf offline_packages.tar.gz pip install --no-index --find-links./offline_packages -r full_requirements.txt这一步最常见的失败原因是平台不匹配。如果内网是 CentOS 7glibc 版本比较老很多新版本的 wheel 依赖更高版本的 glibc。解决办法是下载源码包在内网编译或者用 manylinux2014 兼容的 wheel。4.2 Agent 主程序搭建主程序我推荐用 Python生态最成熟内网部署也最方便。核心结构分四层配置层、模型层、工具层、编排层。配置层负责读取环境配置包括模型地址、MCP Server 列表、Skill 目录等。用 YAML 文件 环境变量覆盖的方式方便不同环境切换。# config.py import os import yaml from dataclasses import dataclass dataclass class AgentConfig: model_base_url: str model_name: str model_api_key: str mcp_config_path: str skill_dir: str max_concurrency: int request_timeout: int def load_config(path: str config.yaml) - AgentConfig: with open(path) as f: raw yaml.safe_load(f) # 环境变量覆盖 raw[model_base_url] os.getenv(MODEL_BASE_URL, raw[model_base_url]) raw[model_api_key] os.getenv(MODEL_API_KEY, raw[model_api_key]) return AgentConfig(**raw)模型层封装内网模型调用统一处理超时、重试、并发控制。这里的关键是加一个信号量控制并发避免打爆推理服务。# model_client.py import asyncio from openai import AsyncOpenAI class ModelClient: def __init__(self, config): self.client AsyncOpenAI( base_urlconfig.model_base_url, api_keyconfig.model_api_key, timeoutconfig.request_timeout, ) self.model config.model_name self.semaphore asyncio.Semaphore(config.max_concurrency) async def chat(self, messages, toolsNone): async with self.semaphore: response await self.client.chat.completions.create( modelself.model, messagesmessages, toolstools, temperature0.1, ) return response工具层负责加载 MCP Server 和本地 Skill统一成 Agent 可调用的格式。编排层是 Agent 的主循环负责决策、调用工具、处理结果。4.3 MCP Server 内网部署实操MCP Server 的部署方式取决于工具类型。数据库查询类用 stdio 模式最简单Web 服务类用 SSE 模式更方便多 Agent 共享。以数据库查询 MCP Server 为例用 Python 实现一个最小可用的版本# db_query_server.py import asyncio import json import sys from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import asyncpg app Server(db-query) app.list_tools() async def list_tools(): return [ Tool( namequery_orders, description查询订单信息, inputSchema{ type: object, properties: { order_id: {type: string}, }, required: [order_id], }, ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name query_orders: conn await asyncpg.connect( hostinternal-db.internal, databasebusiness, userreadonly, password***, ) rows await conn.fetch( SELECT * FROM orders WHERE order_id $1, arguments[order_id], ) await conn.close() return [TextContent(typetext, textjson.dumps([dict(r) for r in rows]))] async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: asyncio.run(main())部署时要注意数据库连接用只读账号避免 Agent 误操作。查询加超时和行数限制避免大查询拖垮数据库。日志走 stderr不要污染 stdout。4.4 并发控制与稳定性保障内网 Agent 最容易出问题的地方就是并发。公网环境模型 API 有弹性扩容内网 GPU 资源固定并发一高就排队甚至超时。我的做法是三层限流。第一层是 Agent 级别的信号量控制同时进行的对话数。第二层是模型调用级别的信号量控制同时发给推理服务的请求数。第三层是工具调用级别的限流不同工具根据后端承载能力设置不同阈值。# 三层限流示例 class RateLimiter: def __init__(self, agent_limit10, model_limit5, tool_limitsNone): self.agent_sem asyncio.Semaphore(agent_limit) self.model_sem asyncio.Semaphore(model_limit) self.tool_sems { name: asyncio.Semaphore(limit) for name, limit in (tool_limits or {}).items() } async def acquire_agent(self): await self.agent_sem.acquire() async def acquire_model(self): await self.model_sem.acquire() async def acquire_tool(self, name): if name in self.tool_sems: await self.tool_sems[name].acquire()除了限流还要加熔断。当模型调用连续失败超过阈值时暂时停止调用给推理服务恢复时间。熔断恢复用半开模式放少量请求试探成功后再全量放开。5. 内网 Agent 常见问题与排查实录5.1 依赖安装类问题问题一pip install 报 No matching distribution found这是内网部署最高频的问题。原因通常是下载的 wheel 平台不匹配或者传递依赖没下载全。排查方法是先看报错的具体包名然后在公网环境用相同平台参数单独下载这个包对比版本。# 排查某个包为什么装不上 pip download package_name -d ./debug \ --platform manylinux2014_x86_64 \ --python-version 311 \ --only-binary:all: -v如果这个包没有对应平台的 wheel就需要下载源码包在内网编译。编译前要确保内网有 gcc、make、python-devel 等基础工具。问题二安装成功但 import 报错通常是动态链接库缺失。用ldd检查 so 文件的依赖缺什么补什么。CentOS 7 上常见的是 glibc 版本不够需要升级或者用兼容版本重新编译。5.2 模型调用类问题问题一请求超时内网推理服务如果没做批处理单次请求可能很慢。先确认推理服务本身的响应时间用 curl 直接测。如果推理服务就慢Agent 侧只能加大超时。如果推理服务快但 Agent 慢检查是不是并发太高导致排队。问题二返回内容截断内网模型如果是量化版本输出质量可能下降表现为回答不完整或者格式错乱。解决办法是降低 temperature、增加 max_tokens、在 prompt 里明确要求输出格式。问题三并发调用打爆推理服务这个前面讲过用信号量限流。但要注意信号量的位置如果放在模型客户端内部每个客户端实例一个信号量多实例就失效了。要放在全局单例里。5.3 MCP 工具类问题问题一MCP Server 启动失败stdio 模式下最常见的是路径问题。command 必须是绝对路径args 里的路径也要绝对路径。另外 Python 脚本要有可执行权限或者用python作为 command脚本路径作为 args。问题二工具调用返回空先看 MCP Server 的 stderr 日志通常有详细报错。常见原因是环境变量没传进去比如数据库连接信息。stdio 模式下子进程不继承父进程环境变量要在配置里显式声明。问题三工具调用卡住不返回检查 MCP Server 内部是不是有阻塞操作。比如数据库查询没设超时或者 HTTP 请求没设超时。所有工具调用都要设超时超时后返回错误而不是一直等。5.4 排查速查表现象可能原因排查方法解决方案pip 装不上平台不匹配/依赖缺失单独下载该包看报错下载源码包内网编译import 报错动态库缺失ldd 检查 so 依赖补齐系统库模型超时推理慢/并发高curl 直测推理服务加大超时/限流输出截断量化模型质量下降对比原版输出降温度/加 max_tokensMCP 启动失败路径/权限问题看 stderr 日志用绝对路径/加权限工具返回空环境变量缺失检查配置显式声明环境变量工具卡住内部阻塞无超时加日志定位所有调用加超时6. 内网 Agent 工程化的经验与避坑6.1 配置管理要前置我最早做内网项目时配置散落在代码各处部署到新环境要改十几个文件。后来统一用 YAML 环境变量覆盖所有环境相关的东西都抽出来。这个习惯在内网场景下价值翻倍因为内网环境往往有多个开发、测试、生产配置管理不好就是灾难。配置文件的组织建议按环境分目录公共配置放一份环境差异放各自目录。启动时根据环境变量加载对应配置。6.2 日志要能定位问题内网环境没法用外部日志平台所有日志要落到本地文件并且要能按请求追踪。我的做法是每个请求生成一个 trace_id所有相关日志都带上这个 id。排查问题时用 grep 一把捞出来。日志级别也要控制好。DEBUG 级别日志量太大内网磁盘有限。生产环境用 INFO排查问题时临时开 DEBUG。6.3 灰度发布不能省内网 Agent 更新不像公网可以随时回滚一旦出问题影响面很大。我的做法是先在测试环境跑通然后生产环境先放 10% 流量观察一天没问题再全量。灰度期间重点看错误率、响应时间、工具调用成功率。6.4 工具权限要最小化Agent 能调用的工具越多出问题的风险越大。每个工具都要按最小权限原则配置。查询类工具用只读账号操作类工具加审批高危工具隔离到沙箱。我见过 Agent 因为工具权限过大误删数据的案例这个坑一定要提前防。6.5 模型降级要有预案内网推理服务可能因为各种原因不可用Agent 要有降级预案。最简单的降级是返回固定话术告诉用户服务暂时不可用。好一点的降级是切换到备用模型虽然质量差一点但能用。7. 内网 Agent 的扩展方向7.1 多 Agent 协作单 Agent 能力有限复杂任务需要多 Agent 协作。内网环境下多 Agent 的通信可以用内部消息队列比如 RabbitMQ 或者 Redis Stream。每个 Agent 负责一个子任务通过消息队列传递中间结果。多 Agent 的难点是任务分解和结果聚合。任务分解可以用一个 Planner Agent 负责结果聚合用一个 Aggregator Agent 负责。中间的执行 Agent 只关注自己的子任务。7.2 RAG 增强内网 Agent 接内部知识库是刚需。向量库用 Milvus 或者 Qdrant部署在内网。文档解析、切分、向量化用本地模型避免依赖外部服务。RAG 的关键是检索质量。内网文档往往格式不统一PDF、Word、Excel 都有解析要分别处理。切分策略也要根据文档类型调整技术文档按章节切会议纪要按段落切。7.3 可观测性建设内网 Agent 的可观测性靠自建。Prometheus 采集指标Loki 收集日志Grafana 做展示。关键指标包括请求量、响应时间、错误率、模型调用次数、工具调用成功率、Token 消耗量。指标采集用埋点方式在 Agent 主循环的关键节点打点。埋点要轻量不能影响主流程性能。7.4 安全加固内网不等于安全Agent 的安全加固不能省。输入要做注入检测避免 prompt 注入攻击。输出要做敏感信息过滤避免泄露内部数据。工具调用要做权限校验避免越权操作。安全加固的另一个维度是审计。所有 Agent 的操作都要留痕包括谁在什么时候调用了什么工具、传了什么参数、返回了什么结果。审计日志单独存储定期归档。8. 一些实操中的个人体会做内网 Agent 这几年最大的体会是工程复杂度远大于算法复杂度。模型本身的能力已经够用真正难的是怎么在受限环境里把整条链路跑通、跑稳。另一个体会是不要追求一步到位。我见过太多团队想一开始就上全套架构结果卡在依赖安装阶段。正确的做法是先跑通最小闭环再逐步增强。先能回答一个问题再能调用一个工具再能处理多轮对话再能并发再能容错。每一步都验证通过再往下走。还有一点是文档要跟着代码走。内网环境人员流动时新人接手全靠文档。部署文档、配置说明、排查手册、架构图这些看起来费时间但关键时刻能救命。我的习惯是每完成一个模块就写文档不等到项目结束再补。最后分享一个小技巧内网环境准备一个应急包里面放常用的排查工具、依赖包、配置文件模板。遇到问题时不用临时找直接解压就能用。这个习惯帮我省过好几次通宵。