
production-grade-agentic-system
七层拆解,把智能体 Demo 变成能上线的系统
项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-11-21 · 当前星标 ★ 1023
使用教程
环境要求
- 已安装 Git
- 已安装 Docker 与 Docker Compose v2(旧版 v1 需设置 DOCKER_COMPOSE=docker-compose)
- Python 环境可用,并可通过 pip 安装 uv(Makefile 的 install 目标会执行 pip install uv 与 uv sync)
- 本地运行测试需要可用的 PostgreSQL 服务器,并启用 pgvector 扩展
- 准备模型与外部服务的密钥,填入按环境命名的 .env 文件
安装与启动步骤
-
1克隆仓库
把项目代码拉到本地并进入目录,后续所有命令都在该目录执行。
git clone https://github.com/FareedKhan-dev/production-grade-agentic-system cd production-grade-agentic-system -
2安装依赖
安装 uv 后按其锁文件同步依赖;Makefile 的 install 目标就是这两条命令。
pip install uv uv sync -
3准备环境文件
以 .env.example 为模板复制出对应环境的文件,不要把示例文件直接当运行配置。
cp .env.example .env.development -
4本地启动服务
按 development 环境加载变量并启动 FastAPI,带热重载,监听 8000 端口。
make dev -
5Docker 启动全栈
用指定环境的 env 文件构建并后台启动 db 与 app 两个服务。
make docker-run-env ENV=development -
6运行测试
执行 tests 目录用例,会用到真实 PostgreSQL 与 LangGraph 检查点。
make test -
7运行评估
以交互模式运行 evals 评估入口,默认使用 development 环境变量。
make eval
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
ENV | 是 | make docker-run-env 的必填参数,决定使用哪个 .env 文件 | development |
.env.development | 是 | 按环境隔离的配置文件,由 .env.example 复制后填写真实值 | .env.development |
APP_ENV | 是 | 容器入口据此加载 .env.${APP_ENV},并校验必需变量是否齐全 | development |
JWT 密钥 | 是 | 必须替换为足够长的随机值,应用会拒绝过短或已公开的默认密钥 | 9f2c7a41d8b34e6fa0c5b7e2d9146c83 |
metrics_path | 否 | Prometheus 抓取 FastAPI 指标的路径,目标为 app:8000 | /metrics |
如何确认成功
浏览器访问 http://localhost:8000/metrics 能看到指标输出,且在 Prometheus 中 fastapi 抓取目标状态为 UP,即表示服务正常。
常见问题
Q:直接用 .env.example 能启动吗?
A:不能。项目会检查必需变量是否齐全,使用未修改的示例文件或旧版公开默认密钥时,整套服务会拒绝启动。
Q:为什么不用单个 .env 文件?
A:README 建议按 development、staging、production 分别维护配置文件,便于同时保留多套隔离配置而无需反复改同一个文件。
Q:make test 报数据库连接失败怎么办?
A:测试依赖真实 PostgreSQL(含 pgvector),请先启动数据库服务并确认连接配置,再执行 make test。
Q:Grafana 面板不显示怎么办?
A:预置的面板 JSON 需要把 dashboard 模型(uid、title、panels)放在顶层,使用带 dashboard 外层包装的格式不会被加载。
Q:本地开发和 Docker 方式选哪个?
A:本地 make dev 适合改代码热重载;需要连数据库和监控组件一起跑时用 make docker-run-env ENV=development。
注意事项
- 运行前务必把示例配置中的密钥替换为随机长字符串,避免使用任何公开过的默认值。
- Docker Compose 使用 v2 语法,若本机仍是旧版 v1,需要通过 DOCKER_COMPOSE=docker-compose 覆盖。
- 仓库 CI 只在 master 推送与 PR 时运行,包含 lint(ruff check .)、测试与镜像构建三步,可作本地检查参考。
- Prometheus 与 Grafana 配置分别位于 prometheus/ 与 grafana/ 目录,按文件预置方式加载,无需手工建面板。
核心亮点
- 按七个层次组织代码,架构边界清晰,可直接对照检查自家智能体系统的缺失环节
- 基于 LangGraph 实现图式编排,多步骤流程与状态流转有明确落点,便于扩展
- 定位生产级,涉及状态管理、工具调用与流程校验等工程化关注点,不止于对话演示
不足之处
- 作为架构参考项目,具体业务场景的落地细节需自行补齐
- 文档与社区活跃度仍在成长期,遇到问题可参考的案例有限
适用场景
- 团队搭建智能体应用前,用作架构设计与分层评审的参考蓝本
- 把已有的单轮对话 Demo 改造为多步骤、可维护的智能体流程
- 教学或内部分享中讲解生产级智能体系统的组成要素
替代项目
LangGraph、AutoGen、CrewAI
上一篇:q-agent-harness
下一篇:Nexus
同类项目推荐
adminforth
开源
几分钟搭好带 AI 智能体的管理后台,按需扩展不重写
Admin panels for humans and AI agents. Let agents search, update, and act on your da···
qinyan-academic-skills
开源
装182个AI技能,学术研究全流程开挂
A curated, multilingual library of 182 installable AI agent skills for end-to-end ac···
agents
开源
用 AI 智能体自动跑通数据管道,减少手工编码
AI agent tooling for data engineering workflows.
DeepSeekGUI
开源
把 DeepSeek 智能体装进桌面,聊天、改代码、管 Git 一站搞定
基于 DeepSeek Harness(DSH)的稳定桌面端,集成Git、内置浏览器与记忆功能 | DeepSeek H···
solvent-agent
开源
会赚钱、会付账、绝不亏本的自主分析智能体
Offline-first Python AI agent that runs a tiny research business: quotes each job ag···
loopgain
开源
让 Agent 循环该停就停,省 token 还不掉质量
An open-source cost controller for AI agent loops — stops a loop when it's actually···
AurixAgent
开源
终端里跑多智能体,自动写码、研究、操作浏览器,连验证码都能过。
Autonomous Multi-Agent AI Workspace in your terminal. Codes, researches, and execute···
AutoHarness
开源
自动构建智能体安全护栏,让AI行为可控可信
AutoHarness: Automated Harness Engineering for AI Agents
xiaobei
开源
让自媒体获客全自动,一人也能高效接单
为OPC/中小微企业量身打造的自媒体获客智能体