production-grade-agentic-system

七层拆解,把智能体 Demo 变成能上线的系统

开源 🏷️完全免费 🔧 仅开源项目,无在线服务,需自行部署 智能体 🍴 复刻 241 👀 关注 8
GitHub ↗
GitHub 星标 ★ 1023
维护状态 活跃
是否开源 开源
定价模式 🏷️完全免费 开源免费,无付费信息

项目预览

production-grade-agentic-system 项目界面预览图
图片来源:GitHub 官方仓库名片

项目数据

分类智能体
开发团队FareedKhan-dev
定价模式🏷️完全免费
价格说明开源免费,无付费信息
访问状态🔧 仅开源项目,无在线服务,需自行部署
是否开源是
开源协议MIT
主要语言Python
技术栈/模型agentic-ai,langchain,langgraph,production
GitHub 星标★ 1023
上线时间2025-12-18 00:00:00
代码更新2026-11-16
仓库体积422 KB
本站数据更新2026-11-21
维护状态活跃
收录时间2026-11-21
浏览次数0

项目介绍

该项目是一个面向生产环境的智能体系统参考实现,用 Python 编写,基于 LangChain 与 LangGraph 构建。它把生产级智能体拆解为七个核心层次,覆盖从模型调用、工具接入、状态与记忆管理、编排调度到可观测性与安全防护等关键环节,帮助开发者理解一个可上线的智能体系统需要哪些组成部分,而不是停留在单轮对话 Demo。核心能力包括:用图结构编排多步骤智能体流程、管理会话状态与上下文、接入外部工具、在关键节点加入校验与回退机制,并提供分层清晰的代码结构便于按需裁剪和二次开发。适合作为团队搭建智能体应用的架构蓝本,用来对照检查自身系统在可靠性、可维护性上的缺口。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整

数据来源:GitHub API 逐日快照 · 收录于 2026-11-21 · 当前星标 ★ 1023

使用教程

难度:进阶 约 25 分钟 部署方式:Docker 7 步

环境要求

  • 已安装 Git
  • 已安装 Docker 与 Docker Compose v2(旧版 v1 需设置 DOCKER_COMPOSE=docker-compose)
  • Python 环境可用,并可通过 pip 安装 uv(Makefile 的 install 目标会执行 pip install uv 与 uv sync)
  • 本地运行测试需要可用的 PostgreSQL 服务器,并启用 pgvector 扩展
  • 准备模型与外部服务的密钥,填入按环境命名的 .env 文件

安装与启动步骤

  1. 1克隆仓库

    把项目代码拉到本地并进入目录,后续所有命令都在该目录执行。

    git clone https://github.com/FareedKhan-dev/production-grade-agentic-system
    cd production-grade-agentic-system
  2. 2安装依赖

    安装 uv 后按其锁文件同步依赖;Makefile 的 install 目标就是这两条命令。

    pip install uv
    uv sync
  3. 3准备环境文件

    以 .env.example 为模板复制出对应环境的文件,不要把示例文件直接当运行配置。

    cp .env.example .env.development
  4. 4本地启动服务

    按 development 环境加载变量并启动 FastAPI,带热重载,监听 8000 端口。

    make dev
  5. 5Docker 启动全栈

    用指定环境的 env 文件构建并后台启动 db 与 app 两个服务。

    make docker-run-env ENV=development
  6. 6运行测试

    执行 tests 目录用例,会用到真实 PostgreSQL 与 LangGraph 检查点。

    make test
  7. 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···

★ 388 2026-08-09
qinyan-academic-skills 开源

装182个AI技能,学术研究全流程开挂

A curated, multilingual library of 182 installable AI agent skills for end-to-end ac···

★ 1054 2026-08-09
agents 开源

用 AI 智能体自动跑通数据管道,减少手工编码

AI agent tooling for data engineering workflows.

★ 464 2026-08-09
DeepSeekGUI 开源

把 DeepSeek 智能体装进桌面,聊天、改代码、管 Git 一站搞定

基于 DeepSeek Harness(DSH)的稳定桌面端,集成Git、内置浏览器与记忆功能 | DeepSeek H···

★ 281 2026-10-18
solvent-agent 开源

会赚钱、会付账、绝不亏本的自主分析智能体

Offline-first Python AI agent that runs a tiny research business: quotes each job ag···

★ 114 2026-10-09
loopgain 开源

让 Agent 循环该停就停,省 token 还不掉质量

An open-source cost controller for AI agent loops — stops a loop when it's actually···

★ 127 2026-09-12
AurixAgent 开源

终端里跑多智能体,自动写码、研究、操作浏览器,连验证码都能过。

Autonomous Multi-Agent AI Workspace in your terminal. Codes, researches, and execute···

★ 62 2026-08-09
AutoHarness 开源

自动构建智能体安全护栏,让AI行为可控可信

AutoHarness: Automated Harness Engineering for AI Agents

★ 470 2026-08-09
xiaobei 开源

让自媒体获客全自动,一人也能高效接单

为OPC/中小微企业量身打造的自媒体获客智能体

★ 8744 2026-08-10