提示词工作流怎样约定接口和错误工作台一侧的花盆里绿植在阳光下舒展着叶片。构建一个令人满意的自主 Agent 系统时很多人都会被一个经典的难题所困扰到底应该把多大程度的决策权交给 Prompt提示词又该在什么时候把控制权交还给工程化的 Tool工具早期摸索 Agent 的开发者经常走两个极端要么试图写出一个上千字的巨型 Prompt希望模型凭空凭理解解决所有业务逻辑要么把所有规则都写死在固定的代码框架里把大模型降级为一个单纯的文本格式化工具。真正成熟的 Agent 架构讲究的是“提示词负责意图解构与策略选择工具负责确定性执行与数据安全”。别把提示词当成脚本给 AI 划分明确的职责边界我们需要清楚地认识到LLM大语言模型善于理解自然语言中的模糊意图、归纳上下文以及做非确定性推理但在涉及精确数值计算、数据库事务提交、格式严格校验以及外部系统状态变更时它的表现往往非常脆弱。因此在分工原则上Prompt 的边界定义 Agent 的性格特征、明确当前任务的总体目标、提供思维链CoT推理范式、指引下一步选择哪个工具以及在出现歧义时向用户发起温和的澄清询问。Tool 的边界封装明确的输入输出 Schema处理与外部 API 的网络交互执行带状态校验的业务动作并在发生错误时抛出标准化的错误结构。接口契约与数据模型让 Agent 听懂工程语言在 Agent 和工具交互的过程中最脆弱的一环就是参数传递。模型吐出的 JSON 参数经常出现字段少传、类型传错或者包含无关注释的情况。为了打破这种脆弱性我们需要为每一个工具定义严格的数据模型Data Model与接口契约Interface Contract。通过声明式的 Pydantic Schema或 TypeScript 接口既可以自动生成让模型阅读的工具描述参数又可以在运行时强行拦截非法参数。错误语义的设计同样关键。工程工具不能只简单地返回一个500 Internal Server Error而必须将错误分为三种语义明确的类型输入校验错误ValidationError告知 Agent 参数缺少什么、格式何处不对引导 Agent 自行修复参数重试。工具执行异常ToolExecutionError告知 Agent 外部系统暂时不可用建议 Agent 采用备用工具或通知用户。资源配额枯竭TokenOrQuotaExhausted立刻终止循环触发全局安全兜底。构造具备强类型校验与容错的 Agent 调度引擎下面的 Python 代码展示了一个完整的 Agent 调度器实现。它包含了强类型 Schema 校验、动态工具注册、高阶错误捕获与多轮自纠错循环。import json import logging from typing import Dict, Any, Callable, Type, Optional from pydantic import BaseModel, Field, ValidationError logging.basicConfig(levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s) logger logging.getLogger(AgentScheduler) # 定义自定义异常类型 class AgentBaseException(Exception): Agent 体系基础异常 pass class ToolExecutionError(AgentBaseException): 工具运行内部抛出的工程异常 pass # 定义真实业务工具的参数 Schema class RemindTimerInput(BaseModel): title: str Field(description提醒的具体事项名称如给阳台的花浇水) delay_minutes: int Field(gt0, le1440, description延迟触发分钟数必须大于0且小于等于1440分钟) priority: str Field(defaultnormal, description优先级: low, normal, high) class WeatherQueryInput(BaseModel): city_name: str Field(description需要查询的城市名称如杭州) class ToolRegistry: Agent 工具注册中心与安全执行阀 def __init__(self): self._tools: Dict[str, Dict[str, Any]] {} def register_tool(self, name: str, description: str, schema_cls: Type[BaseModel], func: Callable): 注册工具并自动抽离 Schema 描述 self._tools[name] { description: description, schema_cls: schema_cls, func: func, json_schema: schema_cls.model_json_schema() } logger.info(f成功注册 Agent 工具: [{name}]) def get_tools_manifest(self) - str: 生成供 Prompt 使用的结构化工具清单说明 manifest [] for name, meta in self._tools.items(): manifest.append({ tool_name: name, description: meta[description], parameters: meta[json_schema].get(properties, {}) }) return json.dumps(manifest, ensure_asciiFalse, indent2) def execute_tool(self, name: str, raw_args_json: str) - Dict[str, Any]: 强类型校验并执行工具严格捕获并分流处理异常 if name not in self._tools: raise KeyError(f未找到指定的工具 [{name}]请检查工具名称是否拼写正确。) tool_meta self._tools[name] schema_cls tool_meta[schema_cls] func tool_meta[func] # 1. JSON 解析校验 try: parsed_dict json.loads(raw_args_json) except json.JSONDecodeError as e: logger.error(f工具 [{name}] 接收到非法 JSON 参数: {raw_args_json}) return { success: False, error_type: InvalidJSON, message: f参数不是合法的 JSON 格式: {str(e)}请重新格式化参数。 } # 2. Pydantic 强类型 Schema 校验 try: validated_args schema_cls(**parsed_dict) except ValidationError as val_err: logger.warning(f工具 [{name}] 参数强校验失败: {val_err.errors()}) return { success: False, error_type: ValidationError, message: f参数未通过模式校验: {val_err.errors()}请修改参数后重试。 } # 3. 真实逻辑执行与异常兜底 try: logger.info(f正式执行工具 [{name}]校验后的参数: {validated_args.model_dump()}) result_data func(validated_args) return { success: True, data: result_data } except Exception as exec_err: logger.error(f工具 [{name}] 执行期间发生底层崩溃: {str(exec_err)}) return { success: False, error_type: ToolExecutionError, message: f工具运行遇到意外状况: {str(exec_err)} } # --- 真实工具业务逻辑实现 --- def set_reminder_action(args: RemindTimerInput) - Dict[str, Any]: # 模拟真实提醒设置 if args.delay_minutes 720: raise ToolExecutionError(数据库定时任务排期已满暂不支持超过 12 小时的提醒。) return {status: created, reminder_id: rem_89021, notify_at_minutes_later: args.delay_minutes} # --- 调度测试演示 --- if __name__ __main__: registry ToolRegistry() registry.register_tool( nameset_reminder, description用于设定定时提醒事项, schema_clsRemindTimerInput, funcset_reminder_action ) print(\n生成给 LLM 阅读的工具清单 Manifest) print(registry.get_tools_manifest()) # 场景 1: 参数非法输入负数延迟校验拦截 bad_json {title: 喝水提醒, delay_minutes: -10} res_1 registry.execute_tool(set_reminder, bad_json) logger.info(f场景1拦截结果: {res_1}) # 场景 2: 参数合法成功执行 good_json {title: 拉伸休息, delay_minutes: 30, priority: high} res_2 registry.execute_tool(set_reminder, good_json) logger.info(f场景2执行结果: {res_2})这套机制通过将数据校验逻辑收拢在离工具最近的工程门禁处确保了 LLM 在尝试错误调用时能够收到明确的错误重试反馈ValidationError避免了直接引发全局崩溃。错误语义的温柔收尾从工具故障到优雅降级当真实的生产环境出现数据库故障或网络超时等ToolExecutionError时Prompt 系统需要展现出足够的弹性与温度。系统不应该把技术性的 Traceback 或冷冰冰的错误代码原封不动展示给用户而是由 Agent 根据工具返回的结构化错误报告用关怀的口吻向用户做解释。比如当日历同步失败时Agent 可以这样向用户回应“提醒事项已经在本地记录好了不过因为网络暂时有些拥堵我会在网络恢复后第一时间为您同步到云端日历中。”提示词的柔性与工程工具的硬朗在这样的架构中形成了互补。有了强类型 Schema 的把关Prompt 才能安心放开手脚去理解复杂的世界而有了提示词的润滑冰冷的代码工具才能真正拥有打动人心的力量。
提示词工作流怎样约定接口和错误工作台一侧的花盆里绿植在阳光下舒展着叶片。构建一个令人满意的自主 Agent 系统时很多人都会被一个经典的难题所困扰到底应该把多大程度的决策权交给 Prompt提示词又该在什么时候把控制权交还给工程化的 Tool工具早期摸索 Agent 的开发者经常走两个极端要么试图写出一个上千字的巨型 Prompt希望模型凭空凭理解解决所有业务逻辑要么把所有规则都写死在固定的代码框架里把大模型降级为一个单纯的文本格式化工具。真正成熟的 Agent 架构讲究的是“提示词负责意图解构与策略选择工具负责确定性执行与数据安全”。别把提示词当成脚本给 AI 划分明确的职责边界我们需要清楚地认识到LLM大语言模型善于理解自然语言中的模糊意图、归纳上下文以及做非确定性推理但在涉及精确数值计算、数据库事务提交、格式严格校验以及外部系统状态变更时它的表现往往非常脆弱。因此在分工原则上Prompt 的边界定义 Agent 的性格特征、明确当前任务的总体目标、提供思维链CoT推理范式、指引下一步选择哪个工具以及在出现歧义时向用户发起温和的澄清询问。Tool 的边界封装明确的输入输出 Schema处理与外部 API 的网络交互执行带状态校验的业务动作并在发生错误时抛出标准化的错误结构。接口契约与数据模型让 Agent 听懂工程语言在 Agent 和工具交互的过程中最脆弱的一环就是参数传递。模型吐出的 JSON 参数经常出现字段少传、类型传错或者包含无关注释的情况。为了打破这种脆弱性我们需要为每一个工具定义严格的数据模型Data Model与接口契约Interface Contract。通过声明式的 Pydantic Schema或 TypeScript 接口既可以自动生成让模型阅读的工具描述参数又可以在运行时强行拦截非法参数。错误语义的设计同样关键。工程工具不能只简单地返回一个500 Internal Server Error而必须将错误分为三种语义明确的类型输入校验错误ValidationError告知 Agent 参数缺少什么、格式何处不对引导 Agent 自行修复参数重试。工具执行异常ToolExecutionError告知 Agent 外部系统暂时不可用建议 Agent 采用备用工具或通知用户。资源配额枯竭TokenOrQuotaExhausted立刻终止循环触发全局安全兜底。构造具备强类型校验与容错的 Agent 调度引擎下面的 Python 代码展示了一个完整的 Agent 调度器实现。它包含了强类型 Schema 校验、动态工具注册、高阶错误捕获与多轮自纠错循环。import json import logging from typing import Dict, Any, Callable, Type, Optional from pydantic import BaseModel, Field, ValidationError logging.basicConfig(levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s) logger logging.getLogger(AgentScheduler) # 定义自定义异常类型 class AgentBaseException(Exception): Agent 体系基础异常 pass class ToolExecutionError(AgentBaseException): 工具运行内部抛出的工程异常 pass # 定义真实业务工具的参数 Schema class RemindTimerInput(BaseModel): title: str Field(description提醒的具体事项名称如给阳台的花浇水) delay_minutes: int Field(gt0, le1440, description延迟触发分钟数必须大于0且小于等于1440分钟) priority: str Field(defaultnormal, description优先级: low, normal, high) class WeatherQueryInput(BaseModel): city_name: str Field(description需要查询的城市名称如杭州) class ToolRegistry: Agent 工具注册中心与安全执行阀 def __init__(self): self._tools: Dict[str, Dict[str, Any]] {} def register_tool(self, name: str, description: str, schema_cls: Type[BaseModel], func: Callable): 注册工具并自动抽离 Schema 描述 self._tools[name] { description: description, schema_cls: schema_cls, func: func, json_schema: schema_cls.model_json_schema() } logger.info(f成功注册 Agent 工具: [{name}]) def get_tools_manifest(self) - str: 生成供 Prompt 使用的结构化工具清单说明 manifest [] for name, meta in self._tools.items(): manifest.append({ tool_name: name, description: meta[description], parameters: meta[json_schema].get(properties, {}) }) return json.dumps(manifest, ensure_asciiFalse, indent2) def execute_tool(self, name: str, raw_args_json: str) - Dict[str, Any]: 强类型校验并执行工具严格捕获并分流处理异常 if name not in self._tools: raise KeyError(f未找到指定的工具 [{name}]请检查工具名称是否拼写正确。) tool_meta self._tools[name] schema_cls tool_meta[schema_cls] func tool_meta[func] # 1. JSON 解析校验 try: parsed_dict json.loads(raw_args_json) except json.JSONDecodeError as e: logger.error(f工具 [{name}] 接收到非法 JSON 参数: {raw_args_json}) return { success: False, error_type: InvalidJSON, message: f参数不是合法的 JSON 格式: {str(e)}请重新格式化参数。 } # 2. Pydantic 强类型 Schema 校验 try: validated_args schema_cls(**parsed_dict) except ValidationError as val_err: logger.warning(f工具 [{name}] 参数强校验失败: {val_err.errors()}) return { success: False, error_type: ValidationError, message: f参数未通过模式校验: {val_err.errors()}请修改参数后重试。 } # 3. 真实逻辑执行与异常兜底 try: logger.info(f正式执行工具 [{name}]校验后的参数: {validated_args.model_dump()}) result_data func(validated_args) return { success: True, data: result_data } except Exception as exec_err: logger.error(f工具 [{name}] 执行期间发生底层崩溃: {str(exec_err)}) return { success: False, error_type: ToolExecutionError, message: f工具运行遇到意外状况: {str(exec_err)} } # --- 真实工具业务逻辑实现 --- def set_reminder_action(args: RemindTimerInput) - Dict[str, Any]: # 模拟真实提醒设置 if args.delay_minutes 720: raise ToolExecutionError(数据库定时任务排期已满暂不支持超过 12 小时的提醒。) return {status: created, reminder_id: rem_89021, notify_at_minutes_later: args.delay_minutes} # --- 调度测试演示 --- if __name__ __main__: registry ToolRegistry() registry.register_tool( nameset_reminder, description用于设定定时提醒事项, schema_clsRemindTimerInput, funcset_reminder_action ) print(\n生成给 LLM 阅读的工具清单 Manifest) print(registry.get_tools_manifest()) # 场景 1: 参数非法输入负数延迟校验拦截 bad_json {title: 喝水提醒, delay_minutes: -10} res_1 registry.execute_tool(set_reminder, bad_json) logger.info(f场景1拦截结果: {res_1}) # 场景 2: 参数合法成功执行 good_json {title: 拉伸休息, delay_minutes: 30, priority: high} res_2 registry.execute_tool(set_reminder, good_json) logger.info(f场景2执行结果: {res_2})这套机制通过将数据校验逻辑收拢在离工具最近的工程门禁处确保了 LLM 在尝试错误调用时能够收到明确的错误重试反馈ValidationError避免了直接引发全局崩溃。错误语义的温柔收尾从工具故障到优雅降级当真实的生产环境出现数据库故障或网络超时等ToolExecutionError时Prompt 系统需要展现出足够的弹性与温度。系统不应该把技术性的 Traceback 或冷冰冰的错误代码原封不动展示给用户而是由 Agent 根据工具返回的结构化错误报告用关怀的口吻向用户做解释。比如当日历同步失败时Agent 可以这样向用户回应“提醒事项已经在本地记录好了不过因为网络暂时有些拥堵我会在网络恢复后第一时间为您同步到云端日历中。”提示词的柔性与工程工具的硬朗在这样的架构中形成了互补。有了强类型 Schema 的把关Prompt 才能安心放开手脚去理解复杂的世界而有了提示词的润滑冰冷的代码工具才能真正拥有打动人心的力量。
