首页/新闻资讯/正文详情

关注点分离(Separation of Concerns)示例(AI Agent 架构、流程编排、数据契约、提示词工程)

发布时间:2026/11/11 13:21:50 来源:云帆数科 栏目:资讯中心
关注点分离(Separation of Concerns)示例(AI Agent 架构、流程编排、数据契约、提示词工程)
Agent 功能的架构约定图放 services/agent/graphs/必须定义显式 TypedDict 输入/输出 state schemaprompt 一律放 services/agent/prompts/不许内联在图代码里。为什么要这么设计文章目录这套 Agent 架构约定的设计意图1. Graph 放 services/agent/graphs/ 显式 TypedDict State Schema为什么不直接用 dict 或 TypedDict 内联在函数签名里2. Prompt 放 services/agent/prompts/禁止内联① 角色分离写 Prompt 的 ≠ 写 Graph 的② 版本管理 A/B 实验③ 可观测性 成本追踪④ 防止 Prompt 与逻辑耦合3. 整体目录结构的意图一句话总结这套 Agent 架构约定的设计意图你描述的这条规范本质上是在做关注点分离Separation of Concerns把 Agent 系统拆成了三个正交的维度流程编排、数据契约、提示词工程。下面逐条拆解为什么要这么做。1. Graph 放services/agent/graphs/ 显式 TypedDict State Schema为什么不直接用dict或TypedDict内联在函数签名里# ❌ 松散做法 — 上下游节点靠默契传字段defnode_a(state:dict)-dict:state[foo]barreturnstate# ✅ 规范做法 — 显式契约classAgentState(TypedDict):messages:list[BaseMessage]plan:strtool_results:list[dict]is_complete:bool好处说明编译期可检查Mypy / Pyright 能在 CI 里直接报出字段拼写错误、类型不匹配而不是等到运行时KeyError节点间契约清晰每个 node 的input → output一目了然新人不用顺着整个 graph 追数据流Graph 可视化/序列化LangGraph 等框架依赖显式 state 做 checkpoint、time-travel、状态恢复隐式 dict 做不到可测试性单测一个节点时TypedDict 就是 mock 数据的 schema不用猜该传什么2. Prompt 放services/agent/prompts/禁止内联这是整条规范里最实用的一条原因至少有四层① 角色分离写 Prompt 的 ≠ 写 Graph 的Prompt 工程师 / 产品人员 → 改 prompts/xxx.txt 后端工程师 → 改 graphs/xxx.pyPrompt 调优是高频迭代如果 prompt 写在 Python 代码里每次改个措辞都要触碰业务代码、跑完整 CI、有合并冲突风险。② 版本管理 A/B 实验prompts/ planner_v1.txt planner_v2.txt ← 灰度实验直接切文件 tool_router.txt summarizer.txt放在独立文件里可以用 Git 对 prompt 单独做 diff / blame / 回滚按版本命名做 A/B test未来迁移到 Prompt 管理平台LangSmith、Helicone 等零成本③ 可观测性 成本追踪集中管理后很容易加一层统一的 loader顺带做Token 计数 / 成本预估Prompt 注入检测变量注入审计哪些{variable}被填充了什么值如果 prompt 散落在各个.py文件里这些横切逻辑就没地方挂。④ 防止 Prompt 与逻辑耦合# ❌ 内联 — prompt 和流程控制混在一起改 prompt 可能误改逻辑defplanner_node(state):responsellm.invoke(f你是一个规划助手。 用户的请求是:{state[input]}如果涉及代码请调用 code_tool... # ← 这是 prompt 还是业务规则 )...# ✅ 分离 — 各管各的# prompts/planner.txt# graphs/planner.pydefplanner_node(state:PlannerInput)-PlannerOutput:promptload_prompt(planner,inputstate[input])responsellm.invoke(prompt)...3. 整体目录结构的意图services/agent/ ├── graphs/ ← 流程编排怎么走 │ ├── main_agent.py │ └── sub_graphs/ ├── prompts/ ← 提示词怎么说 │ ├── planner.txt │ └── tool_router.txt ├── tools/ ← 工具实现用什么做 └── schemas.py ← TypedDict 定义数据长什么样这四个目录对应了 Agent 系统的四个独立变化频率目录变化频率改动人graphs/低频架构定下来很少改后端schemas.py中频新增字段时改后端prompts/高频持续调优Prompt 工程师 / 产品tools/中频新增能力时改后端变化频率不同的东西不应该放在同一个文件里——这是软件设计里最朴素也最重要的原则之一。一句话总结这套约定的核心目的是让 prompt 调优、图编排、数据契约三件事可以独立演进、独立测试、独立 review互不拖累。在 Agent 系统这种 prompt 改动频率远高于代码的系统里这种分离不是洁癖而是生存需要。

相关推荐

Fan-out(扇出)介绍(一个分布式系统 / 消息队列中的常见模式,指一条消息触发后,自动派生出多条并行的下游调用)fan out
Fan-out(扇出)介绍(一个分布式系统 / 消息队列中的常见模式,指一条消息触发后,自动派生出多条并行的下游调用)fan out

本地栈是 platform 模式 真实 DashScope key——每次上传简历会真调 embedding,一次 discovery run 会对每个职位 fan-out LLM 分析(历史事故:143 职位 ≈ 300 次调用清空预算)。触发任何流程前先追查 MQ 消费者的下游 fan-out。… · 2026/11/1 7:24:23

GitHub界面汉化插件:3分钟告别英文困扰,让编程更丝滑
GitHub界面汉化插件:3分钟告别英文困扰,让编程更丝滑

GitHub界面汉化插件:3分钟告别英文困扰,让编程更丝滑 【免费下载链接】github-chinese GitHub 汉化插件,GitHub 中文化界面。 (GitHub Translation To Chinese) 项目地址: https://gitcode.com/gh_mirrors/gi/github-chinese 还在为Gi… · 2026/9/18 4:58:49

视觉语言模型在实体导航中的应用与优化
视觉语言模型在实体导航中的应用与优化

1. 项目概述:当视觉语言模型遇上实体导航 VLingNav这个项目名称拆解开来,实际上揭示了三个关键技术要素:"V"代表视觉(Visual),"Ling"代表语言(Linguistic)&… · 2026/9/18 22:57:10

之前考的证在外省能不能转过来?报建要电工证值不值得考
之前考的证在外省能不能转过来?报建要电工证值不值得考

之前考的证在外省能不能转过来?报建要电工证值不值得考 之前考的证在外省能不能转过来?这个问题我听得太多了,特别是那些在工地、工厂、建筑工地转岗的兄弟姐妹,你们可能也在问:我手里这张电工证,在老家考的,现在在外地上班, 报建要电工证… · 2026/11/11 13:21:36

安监规定电工作业人员必须知道的上岗必备信息
安监规定电工作业人员必须知道的上岗必备信息

安监规定电工作业人员必须知道的上岗必备信息 你是不是刚毕业就急着找工作?或者正在准备换工作?但用人单位一开口就问你有没有 特种作业操作证 ?这可不是开玩笑, 安监规定电工作业人员… · 2026/11/11 13:21:36

特种作业工的年终总结:多久拿证才能拿到手,别被中介坑了
特种作业工的年终总结:多久拿证才能拿到手,别被中介坑了

特种作业工的年终总结:多久拿证才能拿到手,别被中介坑了 不知道去哪报名怕被中介坑,这几乎是每个想考特种作业操作证的工友心里最怕的。今年我转岗到了平顶山的一家建筑工地,从电焊工转成高压电工,中间的弯路可不少,最头疼的就是证书的事。很多人以为拿… · 2026/11/11 13:21:36

特种作业工的年终总结:怎么通过官方报名入口拿到证,明年涨薪不愁
特种作业工的年终总结:怎么通过官方报名入口拿到证,明年涨薪不愁

特种作业工的年终总结:怎么通过官方报名入口拿到证,明年涨薪不愁 年底了,很多特种作业工都在盘算着自己的年终总结,但有个现实问题卡在心头: 急需特种作业证才能上岗找工作 。没有证,连面试资格都拿不到,更别提谈涨薪了。所以,… · 2026/11/11 13:21:36

柳州电工证哪里换证别怕学历低 网上查询搞定一切
柳州电工证哪里换证别怕学历低 网上查询搞定一切

柳州电工证哪里换证别怕学历低 网上查询搞定一切 学历不高怕报不上名?这事儿其实真不难,关键是你得知道怎么走流程。最近不少在柳州的朋友都在问【柳州电工证哪里换证】,其实只要流程清楚、资料齐全,学历并不是绊脚石。而且,现在连 网上查询… · 2026/11/11 13:21:36

特种信号工报名处值不值得考?鹤壁公路工程从业者必看的实操指南
特种信号工报名处值不值得考?鹤壁公路工程从业者必看的实操指南

特种信号工报名处值不值得考?鹤壁公路工程从业者必看的实操指南 急需特种作业证才能上岗找工作,特种信号工证到底值不值得考?作为鹤壁从事公路工程的你,可能正被这个问题困扰。特种信号工证不是“锦上添花”,而是“雪中送炭”,尤其是在项目现场、工地施… · 2026/11/11 13:20:36

电工证丢失还能补吗?千万别踩坑,丢了证等于失业
电工证丢失还能补吗?千万别踩坑,丢了证等于失业

电工证丢失还能补吗?千万别踩坑,丢了证等于失业 你正在找工作,但手里的电工证突然丢了,这下怎么办?别急,先别慌, 电工证丢失还能补吗 ?答案是肯定的,但 千万别踩坑 ,补办流程如果不了解,可能会耽误你上岗、甚至影响到你的收入。… · 2026/11/11 12:18:07

电力电缆作业证直播报名入口与办理流程良心建议
电力电缆作业证直播报名入口与办理流程良心建议

电力电缆作业证直播报名入口与办理流程良心建议 你是不是也担心学历不高报不了名?别急,今天就给你讲讲 电力电缆作业证直播 的报名流程和那些你必须知道的干货, 良心建议 在这里,别错过。 电力电缆作业证直播报名需要什么条件?… · 2026/11/10 17:46:39

英德电工证报考费多少钱,怕考不过白交培训费?看完这篇别再踩坑
英德电工证报考费多少钱,怕考不过白交培训费?看完这篇别再踩坑

英德电工证报考费多少钱,怕考不过白交培训费?看完这篇别再踩坑 怕考不过白交培训费?英德电工证报考费多少钱,你真的了解吗?现在市面上培训机构五花八门,价格参差不齐,很多人一不小心就花了冤枉钱,结果还考不过。别急,今天就来给你说清楚英德电工证的… · 2026/11/10 17:11:43

_中职电工证最新政策解读
_中职电工证最新政策解读

中职电工证在哪考?工地太忙根本没时间复习考试的救星来了 工地太忙根本没时间复习考试,这是很多正在备考 中职电工证 的建筑工友的真实写照。你不是不想考,而是真的没时间。但别担心,这期内容是 新乡初次报考人员… · 2026/11/11 0:00:52

昆明电工证培训价格值不值得考?老电工告诉你真相
昆明电工证培训价格值不值得考?老电工告诉你真相

昆明电工证培训价格值不值得考?老电工告诉你真相 之前考的证在外省能不能转过来?这个问题是很多在外地打工、换城市生活、或者是想在昆明发展的朋友最关心的。尤其是现在云南发展快,很多企业都在招持证上岗的电工,如果你手头有证但不在本地,那这个证是不… · 2026/11/11 0:00:52

特种电缆张工网上查询全攻略:外省证如何转过来
特种电缆张工网上查询全攻略:外省证如何转过来

特种电缆张工网上查询全攻略:外省证如何转过来 之前考的证在外省能不能转过来?这是很多特种作业从业者最关心的问题,尤其是像特种电缆张工这类证书,直接关系到日常工作是否合规、能否顺利晋升。很多小伙伴因为证书归属地的问题,陷入职业发展的瓶颈,甚至… · 2026/11/11 0:00:52

双极步进电机控制实战:DRV8818PWPR与PIC18F86K22驱动调试
双极步进电机控制实战:DRV8818PWPR与PIC18F86K22驱动调试

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/10 20:19:29

STM32F207ZG + DRV8818PWPR 步进电机驱动实战解析
STM32F207ZG + DRV8818PWPR 步进电机驱动实战解析

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/10 19:22:45

DRV8818PWPR+dsPIC30F4013工业级双极步进电机控制方案
DRV8818PWPR+dsPIC30F4013工业级双极步进电机控制方案

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/10 17:00:47

了解更多?预约专属演示

我们的顾问将为您一对一讲解产品与方案

企业微信二维码