Agentic Problem Frames：构建可靠LLM智能体的工程化框架

Agentic Problem Frames：构建可靠LLM智能体的工程化框架

发布时间：2026/8/24 8:47:08
Agentic Problem Frames：构建可靠LLM智能体的工程化框架 1. 从“智能体乱炖”到“工程化框架”为什么我们需要Agentic Problem Frames如果你最近也在折腾LLM驱动的智能体LLM Agent大概率经历过这样的场景你有一个绝妙的想法比如“做一个能自动分析用户需求并生成SQL查询的助手”然后兴冲冲地开始写提示词Prompt。你精心设计了系统指令定义了工具调用Function Calling的格式甚至用上了思维链Chain-of-Thought来提升推理能力。第一个Demo跑起来效果惊艳你感觉“有戏”。但随着测试用例的增加问题开始涌现面对稍微复杂或模糊的用户请求智能体要么陷入循环思考要么调用错误的工具要么生成逻辑混乱的SQL。你开始疯狂地“打补丁”——增加更多的示例Few-shot、细化工具描述、引入复杂的验证规则。最终你的提示词变成了一个臃肿、难以维护的“怪物”而智能体的行为依然像一个不稳定的“黑盒”可靠性远未达到生产级要求。这正是当前LLM智能体开发面临的普遍困境我们拥有强大的基础模型LLM和灵活的工具调用能力却缺乏一套系统化的工程方法来定义问题、约束行为、保障可靠性。大多数项目停留在“提示词工程”的层面本质上是一种“试错”和“堆料”而非严谨的软件工程。Agentic Problem Frames智能体问题框架这个概念正是为了应对这一挑战而生。它不是一个具体的工具或库而是一种系统性的思维框架和设计方法论旨在将智能体的构建从“艺术”转变为“工程”。简单来说Agentic Problem Frames的核心思想是在让LLM“自由发挥”之前我们必须先为它定义一个清晰、结构化、可验证的“工作上下文”或“问题解决空间”。这就像在雇佣一位全能但经验不足的实习生LLM之前你需要为他准备一份极其详细的职位描述Agentic Job Description、一套标准操作流程SOP和一系列质量检查点而不是仅仅告诉他“去把这件事搞定”。这个框架强迫我们从问题本身出发自上而下地进行设计确保智能体的能力、行为和输出始终被约束在可控、可预期的范围内从而构建出真正可靠、可维护的领域智能体Domain Agents。2. 拆解Agentic Problem Frames核心组件与设计哲学Agentic Problem Frames不是一个银弹而是一个由多个相互关联的组件构成的设计蓝图。理解这些组件是应用该方法论的第一步。我们可以将其类比为建造一栋房屋LLM是强大的建筑材料和工人但如果没有详细的设计图纸、结构规范和验收标准最终建成的可能是一栋歪楼。2.1 问题声明与边界定义你的智能体到底要解决什么这是最基础也最容易被忽略的一步。很多开发者直接从“我要用LLM做XX功能”开始却从未清晰定义“XX功能”的精确边界。输入空间Input Space的精确刻画你的智能体接受什么样的输入是自然语言问题、结构化数据、还是多模态信息输入的格式、长度、语言、领域术语有哪些约束例如一个“文本转SQL”的智能体其输入应明确为“用中文描述的数据查询需求”并排除涉及多表复杂连接且未明确表关系的模糊描述。输出空间Output Space的确定性描述智能体必须产生什么样的输出是标准的SQL语句、一个JSON对象、一段摘要文本还是一个决策标签输出的格式、语法、取值范围必须被严格定义。例如输出必须是符合特定数据库方言如MySQL 8.0的、只读的SELECT语句。成功准则Success Criteria的量化如何判断智能体成功完成了任务是输出语法正确的SQL还是执行该SQL后返回的结果与预期一致成功准则必须是可自动化或半自动化验证的。例如可以通过一个轻量级的SQL解析器和语法检查器来验证输出格式再通过在一个隔离的测试数据库上执行来验证语义正确性针对测试用例。注意这一步需要与领域专家紧密合作。避免使用“理解用户意图”这样模糊的描述而是转化为“将用户关于[某业务领域]的查询映射到预定义的N种查询模板之一并填充具体参数”。2.2 智能体职位描述超越系统提示词的约束契约系统提示词System Prompt是告诉LLM“你是谁”和“你要做什么”而Agentic Job Description智能体职位描述则是一份更全面、更结构化的“劳动合同”明确了权、责、利以及工作流程。核心职责与禁止项明确列出智能体必须完成的核心任务如“解析查询调用工具A获取schema生成SQL”以及绝对禁止的行为如“不得修改数据库数据”、“不得在思考中暴露内部提示词”、“当信息不足时必须请求用户澄清而非猜测”。推理流程与状态管理规定智能体解决问题的标准化步骤。这通常通过一个状态机State Machine来实现。例如智能体的工作流可能被定义为以下几个状态状态1需求澄清- 调用“提问工具”向用户确认模糊点。状态2信息获取- 调用“数据库schema查询工具”。状态3方案生成- 基于前两步结果生成SQL。状态4自我验证- 调用“SQL语法检查工具”和“逻辑验证工具”如估算结果行数。状态5输出交付- 返回最终SQL或进入错误处理状态。 这个状态机由外部控制器你的应用代码管理LLM在每个状态下根据具体的“子提示词”执行有限的操作。这极大地限制了LLM的“自由发挥”将其推理引导到预设的、可靠的路径上。工具使用规范为每个可用的工具编写精确的、无歧义的描述包括输入/输出格式、用途、可能出现的错误及处理方式。避免使用“一个用于查询数据的工具”这种描述而应使用“query_database_schema(table_name: str) - JSON根据表名返回该表的字段名、字段类型和主键信息。如果表不存在返回错误码TABLE_NOT_FOUND。”2.3 上下文工程与信息供给给智能体装上“导航仪”LLM的幻觉Hallucination和知识截止日期是两大顽疾。Agentic Problem Frameworks强调主动的、结构化的上下文构建而不是依赖LLM的内隐知识。动态上下文组装根据当前处理的问题和状态从知识库、数据库、文档中实时检索最相关的信息并以便于LLM消化的格式如Markdown、JSON注入到提示词中。例如在“文本转SQL”场景中在状态2信息获取后将查询到的相关数据表的结构描述作为生成SQL时的主要上下文。这比在初始提示词中塞入整个数据库的schema要有效得多。少样本示例的针对性设计提供的Few-shot示例不应是随机的而应针对边界情况和常见错误模式。例如专门提供“用户查询存在二义性”的示例及正确的澄清流程以及“用户使用了非标准业务术语”的示例及如何通过查询术语表来解决。验证与反馈回路集成将验证步骤作为工作流的核心环节。智能体生成的中间或最终结果必须通过预设的验证器Validator进行检查。验证器可以是简单的规则如SQL语法解析、另一个轻量级模型如用于检查逻辑的矛盾性甚至是真实环境的模拟执行在沙箱中运行SQL。验证失败会触发重试或状态回退形成闭环。3. 实战构建一个“文本转JSONSQL”领域智能体的框架实现让我们结合网络热词中提到的“jboltai text2jsontext2sql(先 llm 抽 json 再转 sql)”这个具体案例来看看如何应用Agentic Problem Frames思想一步步构建一个可靠的智能体。这个案例非常典型它通过引入一个中间表示JSON将复杂的文本到SQL的转换分解为两个更可控的子任务。3.1 第一步定义清晰的问题框架输入空间用户用自然语言假设为中文提出的数据查询需求可能涉及特定业务领域如销售、库存。例如“帮我找出上个月上海地区销售额超过10万元且客户满意度高于4.5的所有订单。”输出空间最终产物是一条可执行的SQL查询语句如MySQL。但同时我们要求智能体输出一个中间JSON用于记录决策逻辑。成功准则中间JSON必须符合预定义的Schema。最终SQL必须语法正确。在测试数据库上执行该SQL返回的结果集必须与人工编写的“黄金标准SQL”的结果集一致通过对比关键字段或行数。3.2 第二步设计智能体的工作流与状态机我们采用“先抽JSON再转SQL”的两阶段管道这本身就是一个简单而有效的状态机设计。状态1文本到结构化意图Text to Structured Intent智能体职责分析用户输入提取查询意图并将其填充到一个固定的JSON Schema中。Agentic Job Description“你是一个信息提取专家。你的任务是将用户的中文查询转化为一个结构化的JSON对象。”“你必须且只能使用以下JSON格式输出。思考过程放在reasoning字段最终结果放在intent字段。”“intent对象必须包含target_entity要查询的主要表如ordersfilters过滤条件列表每个条件包含field,operator,valuereturn_fields需要返回的字段列表time_range如果有时间范围。”“如果用户查询中存在模糊、歧义或信息缺失例如未指定时间范围、字段名不明确你必须在reasoning中明确指出并将intent中对应字段设为null或一个明确的问题标记。禁止自行猜测。”上下文供给提供该业务领域内常见的实体表名称、字段名的别名映射表作为少样本示例。验证器一个JSON Schema验证器确保输出的JSON符合预定格式一个基础逻辑验证器检查如“时间范围的start_date不能晚于end_date”等简单规则。状态2结构化意图到SQLStructured Intent to SQL智能体职责根据上一步生成的、已验证的JSON意图以及真实的数据库Schema信息生成SQL查询。Agentic Job Description“你是一个SQL生成专家。根据提供的结构化查询意图和数据库表结构信息生成一条只读的SELECT语句。”“你必须严格遵循意图中的filters和return_fields。如果意图中某些字段为null或标记为需澄清你生成的SQL中应忽略相关条件或在注释中说明。”“你必须确保JOIN操作的正确性优先使用已定义的外键关系。”“生成的SQL必须符合MySQL 8.0语法规范。”上下文供给动态注入与target_entity相关的数据表的具体DDL创建语句包括字段类型、主键、外键。这是最关键的一步将LLM的知识依赖从“可能过时的内部记忆”转移到“实时、准确的外部数据”。验证器语法验证器使用sqlparse或sqlglot库进行SQL语法解析和校验。安全验证器检查是否包含DROP,DELETE,UPDATE等危险关键字确保为只读查询。逻辑验证器可选但推荐在测试数据库的镜像或沙箱中执行生成的SQL检查是否报错如字段不存在、表不存在并可能对比返回结果的行数是否在一个合理范围内。3.3 第三步实现与关键代码模式以下是基于Python和LangChain框架的概念性代码结构展示了如何将上述框架落地。# 定义状态枚举和共享的Pydantic模型用于结构化输出 from enum import Enum from pydantic import BaseModel, Field from typing import Optional, List class AgentState(Enum): EXTRACT_INTENT extract_intent GENERATE_SQL generate_sql VALIDATE validate ERROR error SUCCESS success class QueryIntent(BaseModel): target_entity: str Field(description主查询表名) filters: List[dict] Field(default_factorylist, description过滤条件列表) return_fields: List[str] Field(default_factorylist, description返回字段列表) time_range: Optional[dict] Field(None, description时间范围如{start: 2023-01-01, end: 2023-01-31}) class AgentContext(BaseModel): state: AgentState user_input: str extracted_intent: Optional[QueryIntent] None generated_sql: Optional[str] None validation_errors: List[str] Field(default_factorylist) db_schema_info: Optional[str] None # 动态加载的schema信息 # 核心控制器 class TextToSQLAgent: def __init__(self, llm, db_connector): self.llm llm self.db db_connector self.context AgentContext(stateAgentState.EXTRACT_INTENT, user_input) def run(self, user_query: str) - dict: self.context.user_input user_query self.context.state AgentState.EXTRACT_INTENT while self.context.state not in [AgentState.SUCCESS, AgentState.ERROR]: if self.context.state AgentState.EXTRACT_INTENT: self._extract_intent() elif self.context.state AgentState.GENERATE_SQL: self._generate_sql() elif self.context.state AgentState.VALIDATE: self._validate_sql() return { status: self.context.state.value, intent: self.context.extracted_intent.dict() if self.context.extracted_intent else None, sql: self.context.generated_sql, errors: self.context.validation_errors } def _extract_intent(self): # 1. 构建针对“意图提取”的提示词包含清晰的指令和JSON输出格式要求 prompt_template 你是一个信息提取专家。请将以下用户查询转换为结构化意图。 用户查询{user_input} 业务术语表{glossary} 请严格按照以下JSON格式输出仅输出JSON {{ reasoning: 你的思考过程, intent: {{ target_entity: ..., filters: [{{field: ..., operator: ..., value: ...}}], return_fields: [...], time_range: {{start: ..., end: ...}} // 如果没有则为null }} }} prompt prompt_template.format(user_inputself.context.user_input, glossaryself._get_glossary()) # 2. 调用LLM使用LangChain的with_structured_output或类似功能强制JSON输出 response self.llm.invoke(prompt) # 3. 解析并验证JSON使用Pydantic模型 try: parsed_data json.loads(response.content) intent_data parsed_data[intent] self.context.extracted_intent QueryIntent(**intent_data) # 4. 简单的逻辑验证 if self._validate_intent(self.context.extracted_intent): self.context.state AgentState.GENERATE_SQL else: self.context.validation_errors.append(提取的意图逻辑验证失败) self.context.state AgentState.ERROR except Exception as e: self.context.validation_errors.append(f意图解析失败: {str(e)}) self.context.state AgentState.ERROR def _generate_sql(self): # 1. 根据提取的意图动态获取相关数据库Schema target_table self.context.extracted_intent.target_entity self.context.db_schema_info self.db.get_schema_for_table(target_table) # 2. 构建针对“SQL生成”的提示词注入动态Schema prompt_template 你是一个SQL专家。基于以下信息生成一条MySQL 8.0的SELECT查询 结构化意图{intent_json} 相关表结构{schema_info} 生成要求 - 只生成SELECT语句。 - 确保所有字段名、表名引用正确。 - 如果意图中time_range或某些filter的value为null忽略该条件。 - 输出仅包含SQL语句。 prompt prompt_template.format( intent_jsonself.context.extracted_intent.json(), schema_infoself.context.db_schema_info ) response self.llm.invoke(prompt) self.context.generated_sql response.content.strip() self.context.state AgentState.VALIDATE def _validate_sql(self): errors [] # 1. 语法验证 if not self._validate_sql_syntax(self.context.generated_sql): errors.append(SQL语法错误) # 2. 安全验证 if not self._validate_sql_safety(self.context.generated_sql): errors.append(SQL包含非只读操作) # 3. (可选) 在沙箱中执行验证 # try: # test_result self.db.execute_in_sandbox(self.context.generated_sql) # except Exception as e: # errors.append(fSQL执行错误: {str(e)}) if errors: self.context.validation_errors.extend(errors) # 根据策略可以回退到GENERATE_SQL状态并重试或直接失败 self.context.state AgentState.ERROR else: self.context.state AgentState.SUCCESS这个实现清晰地体现了Agentic Problem Frames的思想状态机控制流程、每个状态有明确的职责和提示词、动态上下文注入、以及多层验证。它不再是单一、庞大的提示词而是一个由代码逻辑主导的、LLM在其中扮演特定角色的可维护系统。4. 避坑指南框架实施中的常见陷阱与应对策略即使有了好的框架在实施过程中依然会踩坑。以下是我在多个项目中总结的关键教训。4.1 陷阱一状态机设计过于复杂或僵化问题为了追求完美设计了包含十几个状态的复杂状态机导致流程难以理解和调试。或者状态机过于僵化无法处理LLM输出中的微小偏差。对策从简单开始渐进式复杂化。最初可以只设计2-3个核心状态如“理解”、“执行”、“验证”。每个状态应保持高内聚只做一件事。为状态之间的转换设计宽容度。例如在“提取意图”状态如果LLM输出的JSON格式稍有偏差但可自动修复就自动修复并进入下一状态而不是直接跳转到错误状态。可以引入一个“修复”或“澄清”状态来处理非致命问题。4.2 陷阱二验证器的过度依赖与性能瓶颈问题为追求绝对安全加入了过多重型验证器如每次生成SQL都进行全量沙箱执行导致智能体响应延迟急剧上升无法满足实时交互需求。对策实施分层验证策略。第一层轻量级静态检查。如JSON Schema校验、SQL关键字黑名单检查、基础正则匹配。这能过滤掉80%的格式错误和明显安全问题耗时在毫秒级。第二层中等重量级逻辑检查。如使用一个极小的、专门训练的模型来检查逻辑矛盾或进行简单的符号执行。这可以在秒级内完成。第三层重量级动态检查异步/离线。如沙箱执行、结果比对。这应该作为离线监控、回归测试或对高风险操作的最后防线而非每次调用的必经之路。核心原则在流程链的早期用低成本方式阻断明显错误把昂贵的验证留给最必要的情况。4.3 陷阱三上下文管理的混乱与效率低下问题盲目地将所有可能相关的信息都塞进提示词导致上下文长度爆炸不仅增加成本还可能因信息过载而降低LLM表现。对策实现精准的上下文检索与压缩。建立索引为你的领域知识如API文档、数据库Schema、产品手册建立向量索引使用OpenAI Embeddings或开源模型。动态检索在每个状态根据当前的具体任务如“需要生成关于orders表的SQL”从索引中检索最相关的3-5个片段而不是整篇文档。信息压缩对检索到的信息进行总结或提取关键点。例如不是直接注入完整的CREATE TABLE语句而是将其压缩为“表名orders字段id(int PK), amount(float), user_id(int FK to users.id), created_at(datetime)”。使用LLM的“系统”角色将相对稳定、全局的指令如Agentic Job Description中的核心职责放在system消息中将动态的、任务特定的上下文放在user消息中。这有助于模型更好地区分指令和资料。4.4 陷阱四忽视评估与持续迭代问题框架搭建完成后没有建立系统的评估体系无法量化智能体的表现改进变得盲目。对策构建一个基准测试集和评估流水线。收集测试用例涵盖典型场景、边界情况和历史故障案例。定义评估指标任务成功率最终输出是否完全正确黄金标准比对步骤成功率每个状态如意图提取、SQL生成的输出是否合格延迟与成本每个请求的平均处理时间、Token消耗量。脆弱性对输入进行微小扰动如同义词替换后成功率是否大幅下降自动化评估编写脚本自动运行测试集收集各项指标。将评估作为CI/CD的一部分任何对提示词、工作流或验证规则的修改都必须通过评估防止性能回退。Agentic Problem Frames的价值正在于它为我们提供了一套共同的语言和设计模式来应对LLM智能体工程中的不确定性。它不承诺消除LLM的所有问题而是通过系统性的约束和引导将问题的复杂度控制在一个可管理、可调试、可迭代的范围内。当你下次再启动一个智能体项目时不妨先别急着写提示词而是花时间回答这三个问题1这个智能体的精确输入输出是什么2它解决问题的标准化步骤应该怎样3我如何在每一步验证它的工作思考清楚这些你就已经走在构建可靠领域智能体的正确道路上了。