企业官网建设流程全解析

说实话，第一次接触"声明式Agent"这个词的时候，我下意识觉得又是包装出来的新概念。直到自己维护的Agent项目膨胀到完全失控，才真正体会到"声明式"这三个字的分量。那时候我们做一个多场景智能客服Agent，核心逻辑全堆在Python代码里：Prompt用f-string现场拼，工具调用靠几十层if-else分发，换一个业务场景就要复制一整套代码然后手动改两三个分支。最崩溃的一次，只是加了一个"查物流"的工具，足足花了三个小时梳理调用链，还漏改了一个分支，线上出了事故。

后来我下决心重构，把Agent的"行为边界、角色设定、可用工具、流程约束"全部从代码里抽出来，写进一份配置文件。代码只保留一个通用的执行引擎，业务逻辑全在配置层表达。这套方案从设计到落地踩了不少坑，现在把完整的思路、代码和排错记录整理出来，希望能给同样被Agent工程化折磨的朋友一点参考。

1. 为什么需要声明式Agent：先聊清楚再动手

1.1 命令式Agent的日常之痛

先把概念说破。所谓命令式（Imperative），就是传统编程的思维方式：你告诉计算机每一步做什么、按什么顺序做。放到Agent开发里，最常见的写法长这样：

def run_agent(user_input: str, session: dict): if "订单" in user_input: order_id = extract_order_id(user_input) result = query_order(order_id) return f"您的订单{result['status']}，预计{result['eta']}送达" elif "物流" in user_input: order_id = extract_order_id(user_input) result = query_logistics(order_id) return f"物流信息：{result['tracking']}" elif "退款" in user_input: ...

这套代码在工具只有两三个的时候没什么问题，逻辑直接、性能也好。但一旦工具数量涨上去、意图类型变多、业务规则开始叠楼层，问题就全来了。

第一，分支复杂度指数级上升。意图匹配、参数抽取、异常兜底、多轮追问，每一种情况都要一个分支，函数从100行膨胀到400行只用了一个月。第二，Prompt和业务逻辑耦合死在代码里。产品经理想改一句客服话术，都要找开发改代码重新发版，完全违背了敏捷迭代的初衷。第三，复用性几乎为零。换个场景做类似的Agent，你只能复制整个文件再删改，改完还要担心改漏了什么。第四，行为不可观测。Agent为什么调这个工具、为什么停下、为什么答非所问，全靠日志猜，因为"决策路径"本身淹没在代码分支里。

我踩过最真实的一个坑是：某次重构，把所有工具调用从if-else改成了for循环遍历一个工具列表，结果有个工具的参数是在循环外临时构造的，线上有一类请求永远拿不到参数，报错率直接飙升。这类问题在命令式架构下很难预防，因为_工具间的关系、调用顺序、参数依赖全部藏在代码结构里_，看不见也摸不着。

1.2 声明式与命令式的本质差别

声明式（Declarative）的核心是：你只管描述"要什么"，不要关心"怎么做到"。还是拿刚才的客服场景做例子，用声明式的方式，我不写"如果用户说订单就调用query_order"，而是写一份配置：我的角色是售后客服、我能用的工具包括query_order和query_logistics、我最多执行6步、我在用户没给订单号的时候必须追问。至于模型怎么理解用户的话、怎么决定调哪个工具、怎么编排回答，那是执行引擎的事。

用一个更贴近生活的类比。你要去一个陌生的地方，命令式是：出小区门左转，步行200米到公交站，坐52路车，到人民路口下车再走300米。声明式是：我要从当前位置到目的地，希望半小时内到达，预算不超过30元。具体怎么走，交通系统自己规划。

放到Agent里的差别，可以整理成一张表：

注意，声明式并不代表"没有逻辑"。它只是把逻辑从业务代码层搬到了配置声明和通用引擎层。原来你手写的if-else，现在变成了引擎的解析循环、工具注册表、状态转移规则。编程并没有消失，只是变成了一次性的、通用的、与业务无关的工程。

1.3 什么场景适合声明式，什么场景不适合

声明式不是万能的。先说我建议用声明式的场景：

• 任务边界清晰、目标重复性强的场景，比如客服问答、订单售后、内容分类、信息抽取。这类场景每天处理的问题都差不多，变的是用户表达，非常适合让模型自由发挥，用配置约束范围。
• 工具数量多、经常增改的场景。加一个工具，在命令式下要改代码、改分支、改测试；在声明式下只需要注册一个工具描述，配置里加一行工具名。
• 需要跨团队协作的场景。产品经理、运营专家不需要懂代码，他们只需要写好YAML或者JSON配置，描述角色和工具，就能驱动Agent工作。
• 需要批量产出多个同类Agent的场景。比如你有50个品牌的客服，逻辑结构一样，只差角色设定和商品知识库，用声明式就是50份配置的事。

不适合用声明式的场景也很明显：

• 高度定制、每步都必须是确定逻辑的科研计算流程，比如特定算法流水线，直接用代码写更可控。
• 对延迟和成本极度敏感的极简场景。一个固定映射函数就能解决的需求，硬套一个Agent引擎反而白白增加模型推理开销。
• 长期记忆和复杂多轮状态主导的场景。声明式擅长"单次任务的完成"，如果Agent需要长期维护用户画像、在不同会话间共享上下文，那需要的是持久化状态服务，而不是一份静态配置。

我的体感是：声明式Agent本质上是工程化手段，它解决的是"Agent开发混乱、复用难、协作差"的问题，而不是"Agent能力不够"的问题。想清楚这一点，选型就不会跑偏。

2. 声明式Agent的骨架：配置、工具、执行引擎

整个声明式Agent由三层组成：配置层（声明人）、工具层（能力人）、引擎层（执行人）。下面一层一层拆开讲。

2.1 配置Schema：角色、模型、参数、边界

一份Agent配置，本质上是给这个Agent写的一份"岗位说明书"。我在项目里用的最小Schema长这样：

agent: name: after_sales_assistant # Agent唯一标识 description: 处理售后咨询，包括订单查询、物流跟踪、退款申请 system_prompt: | 你是电商平台的售后客服助手。 你只能处理售后相关问题，其他问题一律告知用户转人工。 如果用户没有提供订单号，必须首先引导用户提供订单号，不要猜测或编造。 使用工具前，请先检查参数是否完整。 model: api_type: chat_completions model_name: chat-model-001 temperature: 0.2 max_tokens: 1024 tools: - query_order - query_logistics - create_refund_ticket - confirm_refund max_steps: 6 error_policy: max_retries: 2 on_error: notify_human

字段的用意逐个说。

system_prompt是Agent的人设和行为准则。声明式的关键是_把提示词当作一等公民_，它不再是代码里的f-string片段，而是配置里的一段独立文本。这样产品同学可以直接改话术，不需要碰代码。

model字段里，api_type声明用的是哪种协议（chat_completions是当前最常见的对话补全协议），model_name是模型标识，temperature控制随机性——客服场景我习惯压到0.2以下，减少胡说八道的概率。max_tokens控制单次回复长度上限。

tools是一个工具名列表。注意，这里只是"声明允许使用"，引擎会拿着这份列表去工具注册表里找对应实现。如果列表里的工具名没有注册，启动时应该直接报错。

max_steps限定了Agent最多自动调用多少轮工具。这是声明式Agent的安全气囊，没有这个字段，模型有可能陷入自我对话的死循环，Token烧完都没察觉。

error_policy声明出错时的策略：重试几次，失败后怎么办。这些原本散落在代码里的容错逻辑，都被收进了配置。

2.2 工具注册与调用的声明方式

工具是实现层的东西，它仍然是用命令式代码写的——计算逻辑不可能声明出来，必须明确。但工具在Agent面前暴露的不是函数，而是一份描述元数据。我的工具注册表长这样：

TOOL_REGISTRY = { "query_order": { "executor": query_order_impl, "schema": { "type": "function", "function": { "name": "query_order", "description": "根据订单号查询订单的当前状态、商品信息、预计送达时间。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "完整的订单号，通常由数字和字母组成" } }, "required": ["order_id"] } } } } }

这里最反直觉也最重要的一点：工具的描述文本（description）比工具的实现还重要。大模型选择工具靠的是语义匹配，它并不知道你的函数里做了什么，它只看到一段描述和一个参数Schema。我的经验是，description要写清楚三件事：这个工具是干什么的、什么时候应该调用、参数的含义和格式。写得含糊，模型就会在相似工具之间犹豫甚至用错。

参数Schema同样关键。它必须精确描述每个参数的类型、含义、是否必填。比如order_id如果只有数字，就写成string配合pattern限定，否则模型可能传一个带中文的字符串进来，你的工具解析直接崩。

工具注册表是整个引擎的能力清单。引擎本身不认识任何业务工具，它只会在自己注册表里查名字，找到就执行，找不到就返回错误信息让模型重新规划。这种设计让工具的增删变成一个纯粹的注册动作。

2.3 执行引擎：循环、解析、回填

执行引擎是整个声明式架构的心脏。它只负责一件事：在"模型推理"和"工具执行"之间来回切换，直到任务结束。核心循环用大白话描述是：

1. 加载配置，读入system_prompt、模型参数、工具列表。
2. 初始化消息序列，开头是system_prompt，再加上用户输入。
3. 调用模型，拿到返回结果。
4. 解析结果，判断是"直接回复文本"还是"请求调用工具"。
5. 如果是工具调用，从注册表取出工具，把参数填进去执行。
6. 把工具执行结果作为一条"工具回复"消息，追加进消息序列。
7. 带着新的消息序列再次调用模型，回到第4步。
8. 直到模型直接输出文本，或达到max_steps上限。

伪代码长这样：

async def run(config, user_input): messages = [system_message(config), user_message(user_input)] for _ in range(config.max_steps): resp = await model_client.chat(messages, tools=config.tools) if resp.is_tool_call: messages.append(resp.tool_call_message) tool_result = execute_tool(resp.tool_name, resp.tool_args) messages.append(tool_result_message(tool_result)) else: return resp.text raise MaxStepsExceeded()

这个循环是通用型的，它不关心你调用的是query_order还是search_product，它只负责让模型决定"下一步做什么"。这个"让模型决定"的机制，就是声明式Agent和传统脚本的本质区别——决策权交给了模型，模型则受你的配置约束。

我在实现里特别留意一件事：工具调用的结果给回模型之后，模型应该能据此继续回答或调用下一个工具。这就要求工具结果的消息格式足够清晰，通常包含工具名、原始返回和必要的错误信息。如果工具返回一个大的JSON结构，我会截断摘要后再回填，防止上下文窗口被撑爆。

2.4 用状态机管理复杂流程

单纯的模型-工具循环，适合"一次性问答"型Agent。但现实业务往往有明确的流程状态：比如退款流程，必须先验证订单、再确认状态、然后发起申请、最后要用户二次确认才能执行退款。这种流程如果不显式建模，模型很容易跳步或重复操作。

我的做法是在配置层引入一个轻量状态机描述。下面是一个售后流程的状态声明：

state_machine: initial: waiting_order states: waiting_order: on: order_provided -> verifying verifying: on: order_valid -> choosing_action on: order_invalid -> waiting_order choosing_action: on: action_refund_requested -> confirming_refund on: action_logistics_queried -> answering confirming_refund: on: user_confirmed -> executing_refund executing_refund: on: refund_success -> done

引擎维护一个当前状态，根据"事件"（通常来自于模型的决策或工具执行结果）做状态转移。状态转移的逻辑集中在这份声明里，而不是散落在代码里。好处有两个：一是流程肉眼可见，产品经理可以看懂；二是可以阻止非法跳转，比如从waiting_order直接跳到executing_refund，引擎会拒绝。

不过也要提醒一句：状态机增加了引擎的复杂度，不是所有Agent都需要。如果你的Agent只是"带工具的单轮问答"，强行上状态机属于过度设计。我一般等Agent的配置开始出现"场景细分逻辑"时，再考虑把workflow声明加上。

3. 完整实战：一个售后助手从配置到运行

理论说了一堆，不如跑通一个真实麻雀。下面是一个可复现的轻量实现。

3.1 场景设定与配置编写

目标Agent是一个电商售后助手，处理这几件事：查订单、查物流、发起退款工单、执行退款（需要用户确认）。我在项目里的实际配置文件没有这么纯粹，但结构是同一套。给一个简化版：

agent: name: after_sales_assistant description: 电商售后助手，负责订单查询、物流跟踪和退款处理 system_prompt: | 你是电商平台售后客服助手。 请遵循以下规则： 1. 用户没有提供订单号时，先请用户提供订单号，不要尝试猜测。 2. 只有拿到有效订单号后才能使用任何工具。 3. 退款操作必须由用户明确表达并确认金额后，才允许调用create_refund_ticket。 4. 每次回答保持简洁礼貌，不要输出Markdown以外的格式。 model: model_name: chat-model-001 temperature: 0.2 max_tokens: 1024 tools: - query_order - query_logistics - create_refund_ticket max_steps: 6

为什么把"退款必须确认"写进system_prompt而不是代码里？因为这是一个业务规则，约束的是模型行为。在命令式架构里，这种约束通常表现为一段代码拦截逻辑，和业务捆绑；在声明式架构里，它是一句可以被随时修改的自然语言描述。但也要承认，自然语言约束不如代码约束可靠，所以我在工具实现层还会做一道参数校验兜底。

3.2 工具层实现

工具实现仍然用Python写，但每个函数都尽量保持"输入参数干净、返回结构固定"。以订单查询为例：

def query_order(order_id: str) -> dict: # 模拟查询逻辑 if not order_id or len(order_id) < 6: return {"ok": False, "reason": "订单号格式不正确"} order = fake_db.get(order_id) if order is None: return {"ok": False, "reason": "订单不存在"} return { "ok": True, "order_id": order["id"], "status": order["status"], "items": order["items"], "eta": order["eta"] }

工具返回值我用一个统一的包壳结构，ok字段表示是否成功，reason表示失败原因，成功时再附带业务数据。为什么不用裸返回？因为引擎拿到结果后，会原样把这段结构回填给模型。如果失败时是一个空dict，模型就分不清"订单不存在"和"查询失败"的区别，会继续瞎猜。

工具实现需要自己加上防御逻辑。不要指望引擎能帮你处理业务参数，引擎只负责把模型生成的参数传进来。我在create_refund_ticket里强制校验退款金额为正数、订单状态必须是可退款状态，不合法就直接抛业务异常，异常信息会作为工具结果回传给模型，让模型修正自己的行为。

3.3 执行引擎核心代码

引擎部分，我给出一个可运行的极简实现，保存为engine.py：

import asyncio from dataclasses import dataclass class ToolRegistry: def __init__(self): self._tools = {} def register(self, name, executor, schema): self._tools[name] = {"executor": executor, "schema": schema} def get_schemas(self): return [self._tools[name]["schema"] for name in self._tools] def execute(self, name, args): tool = self._tools.get(name) if not tool: return {"ok": False, "error": f"tool {name} not found"} try: return tool["executor"](**args) except Exception as e: return {"ok": False, "error": str(e)}

这里我把注册表独立成类，方便后面在多个Agent间复用，也方便做统一埋点。模型客户端我封装了一个简单接口：

class ModelClient: def __init__(self, model_name, temperature=0.2, max_tokens=1024): pass # 接入你常用的大模型API async def chat(self, messages, tools): # 调用对话补全接口 # 返回对象需要包含 two 种可能： # 1. text: 直接回复 # 2. tool_calls: [{name, arguments}] pass

引擎主循环：

async def run_agent(config, registry, user_input): messages = [ {"role": "system", "content": config["system_prompt"]}, {"role": "user", "content": user_input} ] for step in range(config["max_steps"]): tools = registry.get_schemas() resp = await model_client.chat(messages=tools) if resp.has_tool_calls(): messages.append({"role": "assistant", "content": None, "tool_calls": resp.tool_calls}) for call in resp.tool_calls: result = registry.execute(call.name, call.arguments) messages.append({"role": "tool", "tool_call_id": call.id, "content": format_result(result)}) else: return resp.text return "抱歉，问题处理超时，请转人工客服。"

我特别说明一个细节：模型返回工具调用后，要先追加一条assistant消息（内容为空、带tool_calls字段），再追加工具结果消息。这是对话补全协议的要求，顺序颠倒会导致部分模型服务拒绝请求。我第一次实现时就踩了这个坑，一直报序列错误。

3.4 运行效果与行为验证

我用两个模拟输入跑了一下，结果很能说明问题。

第一个输入："我的订单什么时候到？"

引擎日志大概是这样的：

step 1: model call... response: tool_call(query_order, {"order_id": null})

注意，模型试图调用query_order，但没有参数。这在我的预期内，因为用户没提供订单号。system_prompt里的规则1在这里只起到"引导"作用，并不能强制模型不这么干。

我的处理方案不是在引擎层拦截，而是让工具自己报错，把"缺少order_id参数"作为结果回传给模型。模型收到这个结果后，下一轮就会转为直接回复"您好，请提供您的订单号"。

第二个输入："我的订单号是ABC123456，想退款"

理想流程是：

step 1: query_order("ABC123456") -> 订单有效 step 2: create_refund_ticket(order_id="ABC123456", reason="用户要求退款") -> 工单创建 step 3: model 回复：已为您创建退款工单，退款将原路返回

如果配置里的system_prompt没有写"退款需要用户确认"，模型可能直接创建工单甚至执行退款，这就是业务事故。所以声明式配置在业务约束上，确实不能只看Prompt，还要在工具实现层和后续的状态机层做硬校验。配置负责"软约束"，代码负责"硬校验"，两者缺一不可。

4. 配置、调试与踩坑实录

声明式Agent把复杂度从代码搬到了配置，但配置本身也会犯错。这一节专门讲坑。

4.1 Schema校验与版本管理

配置文件写错，通常不会像代码一样直接报编译错误，而是会在运行时暴露成奇怪的行为。比如tools列表里把工具名写错了，启动时引擎不会报错，等到模型某一次想用这个工具，才发现查无此工具。这属于典型的"晚失败"。

我的做法是加一道启动自检：配置加载后，立刻校验所有声明字段，工具名必须存在于注册表，模型名必须不为空，max_steps必须是正整数。写个简单的校验函数：

def validate_config(config): errors = [] required = ["name", "system_prompt", "model", "tools"] for field in required: if field not in config["agent"]: errors.append(f"missing agent.{field}") for tool_name in config["agent"]["tools"]: if tool_name not in registry._tools: errors.append(f"unknown tool: {tool_name}") if config["agent"]["max_steps"] < 1: errors.append("max_steps must >= 1") if errors: raise ConfigError(errors)

另外，配置建议纳入Git管理。每次改动都留下记录，这样线上行为异常时，可以直接对比最近一次配置变更，快速定位问题。我在项目里吃过亏——有人直接在生产服务器上手改配置没留痕，出了问题只能靠猜。

4.2 工具描述与真实参数不一致

这是声明式Agent最常见的故障源，我几乎每周都会遇到一次。

原因是工具函数的签名改了，比如order_id改叫order_no，但注册表里那份给模型看的Schema没同步更新。于是模型按照旧Schema生成{"order_id": "..."}，引擎拿着这个参数调用新签名函数，直接TypeError。

解决办法是加一道自动化测试：在工具注册时，把Schema里的属性名集合和函数签名的参数名集合做比对，不一致立刻告警。代码很简单：

def check_signature(name, schema, func): schema_params = set(schema["parameters"]["properties"].keys()) func_params = set(signature(func).parameters.keys()) assert schema_params == func_params, f"tool {name} mismatch"

还有一类问题是描述写得过于笼统，导致模型把"查订单"和"查物流"搞混。这种不是硬故障，但会影响体验。我建议在description里写明"什么时候不要用这个工具"，比如query_order的描述可以补一句："仅用于查询订单基本信息，不包含物流轨迹，查询物流请使用query_logistics。"这种负面约束对模型选型非常有效。

4.3 模型返回不稳定怎么办

模型不是程序，不会每次100%按照Schema返回。常见的不稳定表现有三个：

一是生成不存在的工具名。模型脑补了一个工具，引擎里查不到。处理方式我已经写进引擎：查不到就返回一条错误工具消息，让模型自己修正。

二是参数缺漏。模型只传了必填参数的一部分，或者传了个空值。我的兜底逻辑是：如果参数缺了必填项，不直接调用工具，而是返回"缺少参数xxx，请补充"，引导模型修正。

三是返回无法解析的内容。模型把工具调用和正文混在一起，或者JSON格式坏了。这种情况下，我会把原文原样作为错误信息回给模型，并要求它重新生成，同时把temperature临时调低。实测这个策略基本上两个来回就能恢复。

def safe_parse_tool_call(raw): try: return json.loads(raw) except Exception: return None

4.4 死循环与超时的防守

有一次测试中，我故意不给max_steps赋值，结果模型在"查询订单-发现订单无效-再查询订单-又发现无效"之间循环了十几轮，直到Token配额耗尽。声明式架构里，max_steps就是防止这类问题的主要手段。

除了总的max_steps，我还会做三步防守：

• 单步工具超时。用一个带超时的调用包装函数，比如5秒没返回就抛超时异常，把错误回填给模型。
• 总运行时长限制。Agent整体任务最长执行时间，超过就强制终止，返回一个兜底话术。
• 重复动作检测。如果模型连续调用同一个工具、传入同一组参数，且结果没有变化，说明它在原地打转，直接中断。

这些防守规则可以直接写进引擎，也可以声明在配置里。我的建议是：重复动作检测这种通用规则放引擎，超时和重试次数放配置，因为不同场景对容错的容忍度不一样。

5. 进阶：让声明式Agent真正可靠

跑通一个Demo不算什么，生产环境能用才是真本事。最后分享几个我后期的优化方向。

5.1 配置模板与继承

当Agent数量多起来后，会发现大量配置是重复的：同一套模型参数、同一套超时策略、只是system_prompt和工具列表不一样。这时候我会引入一个基础模板，子配置继承它，只覆盖需要改的字段。

extends: base_support_agent overrides: system_prompt: | 你是3C数码品类的售后客服... tools: - query_order - query_warranty

实现继承逻辑很简单：先把两个配置合并成一份，子配置的字段覆盖父模板，然后再做Schema校验。这套机制极大减少了重复配置，也让"新开一个Agent"变成了5分钟的事。但要注意，继承层级不要超过两层，否则嵌套覆盖的语义会让人很难排查问题。

5.2 可观测性：让Agent行为可追踪

Agent的问题是决策不透明，黑盒一样。我在引擎里加了结构化的日志埋点，每一步都输出：

{ "event": "tool_call", "agent": "after_sales_assistant", "step": 2, "tool": "query_order", "args": {"order_id": "ABC123456"}, "latency_ms": 312, "tokens": 87 }

这些日志统一进采集系统，后面用看板展示。排查问题时，按会话ID拉出整个链条，一眼就能看出模型在哪一步做了错误决策。没有这套观测体系，遇到线上问题只能让用户复现，体验极差。

5.3 多Agent协作的声明式编排

单Agent搞不定所有场景时，可以声明多个Agent，让他们分工协作。比如一个路由Agent负责判断用户意图，把请求转给售后Agent或售前Agent；售后Agent内部再由专门的退款子Agent处理高风险操作。

声明式编排在这里的体现是：每个子Agent都有自己的配置，而编排关系单独用一份拓扑声明描述，列出哪些Agent可以调用哪些Agent、传递什么参数、哪些操作需要人工审批节点。引擎在这个模式下，既要管理模型-工具循环，还要管理Agent间的消息传递。

我的建议是不要一上来就搞多Agent，先把单Agent的配置、观测、防守都做扎实，再考虑编排。否则问题会成倍增加——排查一个跨Agent的Bug，难度和排查一个分布式系统的Bug差不多。

5.4 一些个人心得

最后说说我自己的体会。

声明式Agent这条路，我认为最核心的价值不是"少写代码"，而是让人和系统之间的契约变得清晰。过去业务规则藏在代码分支里，只有开发知道；现在规则明明白白写在配置文件里，产品、运营、测试都能看懂，都能参与修改。这带来的协作效率提升，远比省的那几千行代码重要。

同时必须清醒：声明式不是银弹。它把复杂度从代码转移到了配置、引擎和模型行为管理上。如果引擎本身写得粗糙，配置再规范也会出乱子。我建议想入手的读者，先拿一个小场景，把配置、工具、引擎、观测四件套完整做一遍，再逐步扩大。这样踩坑成本低，积累的经验也能复用。

我的最后一个建议是：给配置里每个字段都写清楚注释。配置文件会活很久，三个月后自己都可能忘了某个字段为什么存在。好的注释，就是给未来的自己留的路标。这个细节，我觉得比任何技术选型都重要。