做智能体开发,起步阶段不需要把整套企业基础设施一次备齐。先准备一个能接收问题、调用一个工具、返回结果的最小环境,再按上线要求补齐知识库、权限、观测和部署。具体清单取决于团队选择本地 SDK、低代码平台还是云端平台,也取决于哪些智能体开发工具需要自己维护。
如果目标是把智能体放进企业业务流程,开发环境还要考虑后续的账号体系、数据权限和统一管理。这时可以把环境接到企业级 AI Agent 平台上,避免每个项目各自维护一套密钥、日志和权限。
一、智能体开发环境通常包含六个部分
一次完整的智能体运行,会经过模型推理、任务编排、知识与记忆、工具调用、运行观测和部署治理。六个部分可以分开建设,但立项时要一起考虑,否则容易出现模型能回答、工具调不动、出了问题查不到的情况。
| 环境层 | 负责什么 | 常见工具 | 最小验证是否必需 |
|---|---|---|---|
| 模型接入 | 提供推理与生成能力 | 模型 API、私有化推理服务 | 必需 |
| 编排运行时 | 拆解任务、保存状态、处理重试和多 Agent 协作 | LangGraph、OpenAI Agents SDK、低代码工作流平台 | 必需 |
| 知识与记忆 | 检索企业文档、指标口径和历史会话 | 向量数据库、企业知识库、会话存储 | 视任务而定 |
| 工具连接 | 查询数据、调用业务系统、执行动作 | 函数调用、REST API、MCP 服务 | 至少接入一个 |
| 运行观测 | 记录调用链、耗时、Token 和失败原因 | Trace 工具、日志平台、Agent 观测平台 | 建议从第一天开始 |
| 部署治理 | 处理权限、审计、沙箱、扩容和私有化 | 容器、网关、权限系统、私有化部署 | 上线前必需 |
最小验证只需要模型接入、编排和一个工具,再加运行记录。 知识库、权限、评测和私有化可以按场景逐步补上。项目启动时如果六层一起铺开,容易在模型还没接通时,先让向量库和监控进入采购清单。
二、本地 SDK、低代码和云端,环境差别在哪
三种方式都能做出可用的智能体,差别在于团队要维护哪一层。选择智能体开发平台时,先看三件事,数据能不能出内网、团队有没有工程能力、上线时间有多紧。
| 开发方式 | 需要准备什么 | 适合的团队 | 主要限制 |
|---|---|---|---|
| 本地 SDK | 代码仓库、语言运行时、依赖管理、模型密钥、调试工具 | 有研发团队,需要深度定制流程 | 部署、观测和权限都要自己搭 |
| 低代码平台自部署 | 服务器、Docker、数据库、向量库、对象存储、HTTPS | 希望可视化搭建,数据要留在内网 | 需要基础设施运维,复杂逻辑受平台边界限制 |
| 云端平台 | 账号、工作区、模型供应商授权、网络和配额 | 快速验证,跨团队试用 | 数据出网、长期成本和供应商依赖要评估 |
团队负责维护的层级越多,前期投入越高。 三种方式可以组合使用,比如先用云端验证流程,再把编排和知识库迁到内网。
1. 本地 SDK 适合需要深度定制的团队
本地 SDK 的代码和数据都在团队手里,能接入内部系统、改写编排逻辑、做细粒度权限。代价是环境要自己维护,模型升级、依赖冲突、日志收集都要有人负责。
框架选择上,LangGraph 偏图编排和状态管理,适合任务步骤多、需要条件分支和中断恢复的场景。OpenAI Agents SDK 偏轻量 Agent、工具调用和多 Agent 任务转移,适合先把单条任务链跑通。框架负责组织调用,模型负责推理,两者可以分开替换。
2. 低代码平台适合先搭流程再逐步扩展
低代码平台把可视化编排、知识库、工具插件和发布渠道打包在一起,业务人员能参与搭建,开发人员负责接口和权限。自部署时仍要准备服务器和依赖服务,平台省掉的是应用层开发,不是基础设施。
Dify 官方部署文档显示,默认 Docker Compose 部署自带 PostgreSQL、Weaviate 和其他服务,最低需要 2 核 CPU、4 GiB 内存,并安装 Docker、2.35.0 以上版本的 Docker Compose、Git 和 OpenSSL。生产环境还要替换默认凭据、配置 HTTPS、规划备份。数据不能出内网时,私有化部署要作为方案的一部分提前评估。
3. 云端平台适合验证和部门级试点
云端平台注册账号、创建工作区、配置模型供应商密钥就能开始,适合在两周内验证一个场景是否值得做。选型时要确认数据存放位置、日志保留策略、导出能力、配额和计费方式。
试点结束后,评估迁移到自部署或私有化的成本。云端平台省掉基础设施,代价是数据边界和长期成本需要单独核算,尤其是调用量稳定增长之后。
三、用本地 SDK 跑通第一个智能体,最少要准备什么
以 Python 技术栈为例,最小环境包含运行时、隔离环境、依赖清单、模型密钥和一个能启动的本地服务。下面的命令和版本以官方文档为准,框架升级后要及时复核。
- 安装语言运行时。LangGraph 的本地运行文档要求 Python 3.11 及以上。其他框架的要求可能不同,安装前核对官方说明,团队内部统一版本。
- 创建项目与虚拟环境。用 venv、uv 或 conda 隔离依赖,把依赖写入 requirements.txt 或 pyproject.toml,并锁定版本范围。这样新成员拉下代码后,能装出接近一致的环境。
- 配置模型接入。准备模型 API 密钥、服务地址和模型名称,写入 .env 或系统环境变量。OpenAI Agents SDK 的快速开始使用 OPENAI_API_KEY 环境变量。.env 要加入 .gitignore,密钥不能进代码仓库。
- 安装编排框架。OpenAI Agents SDK 用 pip install openai-agents 安装。LangGraph 安装 langgraph 包,并用 langgraph-cli 启动本地服务。包名和版本以官方页面为准。
- 启动本地调试。LangGraph 的 langgraph dev 以内存模式启动 Agent Server,适合开发和测试。官方文档同时提示,生产环境要接持久化存储。先在本地跑通,再考虑部署。
- 记录运行过程。打开框架的追踪面板,确认每次运行能看到模型调用、工具调用、耗时和 Token。没有运行记录的环境,不建议直接交给业务试用。
这六步完成后,团队应该能重复运行同一个任务,并能说清每次调用用了哪个模型、哪个工具、花了多少时间。达不到这个状态,先不要急着接第二个业务系统。
四、自部署低代码平台,基础设施怎么配
自部署把平台软件和依赖服务一起放到你的服务器上。准备顺序按依赖关系来,先确认硬件和容器,再配置依赖服务与安全项。
- 确认服务器规格。Dify 文档给出的最低配置是 2 核 CPU、4 GiB 内存,适合试用。生产环境要按并发、文档量、日志留存重新估算,并给向量检索和模型调用留出余量。
- 安装容器环境。安装 Docker 和 Docker Compose 2.35.0 或更高版本,确认 Docker 守护进程正在运行。用 docker compose version 检查版本。
- 准备代码与密钥。用 Git 克隆对应版本的发行包,把 .env.example 复制为 .env,生成沙箱令牌并写入配置。模板里的默认密码不能直接用于生产。
- 启动依赖服务。默认 Compose 会启动 PostgreSQL、Weaviate 和其他服务。运行 docker compose up -d 后,持续运行的服务应显示 Up 或 healthy,init_permissions 只运行一次,完成后显示 Exited。
- 初始化与访问。浏览器打开 http://localhost/install 创建管理员账户。远程部署时换成服务器 IP 或域名,默认 HTTP 端口为 80。端口冲突时修改 EXPOSE_NGINX_PORT,并在访问地址中带上新端口。
- 做安全加固。开放访问前配置 HTTPS,替换数据库、Redis、代码执行沙箱、Weaviate 和插件守护进程的默认凭据。数据库密码要在数据库初始化后先改数据库,再同步 .env。
- 规划备份与升级。备份 docker/.env、自定义 Compose 文件、docker/volumes 和外部数据库。升级前保存 docker compose config 的输出,升级后逐项对比配置,确认数据卷和连接设置没有被覆盖。
自部署的难点集中在升级和排错。建议在测试环境先跑一遍版本升级,再动生产环境。
五、模型之外,还要接上知识与工具
模型能回答通用问题,不代表能完成企业任务。知识与工具决定智能体能不能拿到正确的信息、能不能把动作执行完。
1. 知识检索决定回答能不能用
企业文档、报表、工单、指标定义需要先治理,再接入检索。要准备的除了向量数据库,还包括文档解析、切分策略、嵌入模型、权限过滤和版本管理。指标口径不统一时,同一个问题在不同业务线可能得到不同答案。
ThinkingAI 企业知识库通过统一口径和版本溯源处理这类问题,适合客服问答、SQL 生成和数据分析等场景。上线前先选一个知识边界清楚、答案可以核对的任务,不要一开始就把全部文档倒进知识库。
2. 工具连接要处理鉴权、超时和失败
Agent 调用业务系统,常见做法是函数调用或 REST API。系统多、接口杂时,可以用 MCP 统一接入。MCP 是模型上下文协议,官方规范使用 JSON-RPC 2.0 在 Host、Client 和 Server 之间通信,Server 可以向模型提供 Resources、Prompts 和 Tools。
接入前要确认鉴权方式、调用配额、超时与重试、返回结构,以及高风险动作是否需要人工确认。对工具的描述和调用权限,要按不可信输入对待。 通过标准协议接入,可以减少每接一个系统就写一套适配代码的重复工作,ThinkingAI 的 MCP 服务就承担这一层连接。
六、环境是否跑通,看这五项检查
最小环境是否可用,主要看能不能稳定复现一次完整任务,界面是否漂亮不是判断标准。下面五项都能通过,再进入业务试用。
| 检查项 | 通过标准 |
|---|---|
| 模型调用 | 同一条输入连续运行三次,都能返回结构完整的回答 |
| 工具调用 | Agent 能选中正确工具,参数符合 schema,失败时有明确错误信息 |
| 状态与重试 | 中断后能从保存的状态继续,重复调用不会产生重复副作用 |
| 运行记录 | 能按会话查到模型、工具、耗时和 Token |
| 成本可见 | 能按任务或团队统计调用量,异常增长有告警 |
五项都通过,再进入业务试用。 缺哪一项,先补哪一项,再扩大使用范围。只验证一次成功,不足以说明环境可用,至少要覆盖正常输入、空输入、工具超时和权限不足四种情况。
七、上线前还要补哪些企业级能力
开发环境跑通,只说明智能体能完成任务。进入生产,还要处理权限、审计、隔离、评测和部署方式,让结果可控、过程可查、版本可回滚。
- 权限与审计。按角色控制数据访问,记录谁在什么时间调用了哪个工具,保留操作日志。ThinkingAI 的 Agent 管理提供权限控制、任务调度和运行监控,可以作为统一管理入口。
- 沙箱与隔离。代码执行、文件读写和外部调用放在隔离环境,限制网络出口和文件范围,避免一次错误调用影响生产系统。
- 评测与回归。为关键任务建立测试集,记录准确率、完成率和平均耗时。每次修改提示词、模型或工具后重跑,确认旧场景没有被破坏。
- 观测与诊断。用 Trace 查看调用关系、执行状态、耗时和 Token。ThinkingAI Agentic SDK 支持 Trace 采集,AI Monitor 可以从失败、长耗时和 Token 波动中定位问题,再下钻到单次会话。
- 部署与数据主权。金融、医疗等对数据位置敏感的行业,优先评估私有化部署,把模型、知识库和日志留在内网,并明确数据删除和备份责任。
- 灰度与回滚。新版本先对少量用户开放,保留旧版本入口和回滚方案。高风险动作设置人工确认,失败后能够撤销。
如果团队希望把开发、知识、观测和治理放进同一套平台长期运营,可以了解 ThinkingAI 的 Agentic Engine。它支持私有化部署和多 Agent 协作,ThinkingAI 目前已服务全球超 1500 家企业,接入产品超 8000 款。
常见问题
智能体开发一定要会写代码吗
用低代码或云端平台,可以通过可视化编排完成常见任务,业务人员也能参与搭建。需要自定义工具、复杂状态管理或私有化集成时,仍然需要开发人员。团队里至少有一个人能读懂日志和接口,排错会顺利很多。
本地开发智能体需要 GPU 吗
调用云端模型 API 时,本地不需要 GPU。只有在本地部署和运行大模型时,才需要按模型规模准备显存和推理框架。多数企业先用 API 做试点,确认场景有效后再评估私有化推理的硬件投入。
MCP 是智能体开发的必选项吗
取决于工具数量。只有一个或两个工具时,直接写函数调用更简单。系统多、需要跨团队复用工具时,MCP 的标准化接入更有价值。引入前要评估服务端可信度、鉴权方式和人工确认流程。
云端和本地可以混用吗
可以。常见做法是开发阶段用云端模型和云端平台验证,生产阶段把模型、知识库和日志迁到内网。混用时要做数据分级,敏感数据不出内网,调用链和权限体系统一,避免两套环境各记一份日志。
一个人能维护一套智能体开发环境吗
小规模试点可以。需要持续更新依赖、跟进模型版本、维护知识库和观测告警时,建议至少两人分工,一人负责平台与基础设施,一人负责业务编排和评测。单点维护的主要风险是出问题时,没有人能同时看懂平台和业务。
参考资料
- Dify 文档,使用 Docker Compose 部署 Dify,
- LangChain 文档,在本地运行 LangGraph 应用,
- OpenAI Agents SDK 文档,快速入门,
- Model Context Protocol 规范,






