企业官网建设流程全解析

最近在推进Agent落地项目时，我把一个客服助手从“代码里编排Agent流程”整个改成了“配置文件里声明Agent行为”，踩了不少坑，也拿到了实打实的收益。今天这篇想结合这次实战，把“声明式Agent”这件事拆开揉碎讲清楚：它到底是什么，和传统代码式Agent差在哪，如何从零构建一份可运行的配置，以及你在落地时一定会遇到的那些坑怎么绕。

这篇内容适合三类人：正在做Agent技术选型、被流程编排折磨的开发者，以及想把Agent能力平台化、让业务方也能参与维护的工程师。看完你至少能获得三样东西：一份可以直接照着改的声明式配置示例、一套工具接入和状态管理的实操方法、以及一份真实场景下的问题排查清单。

1. 声明式Agent的本质：从“代码编排”到“配置编排”

1.1 一句话理解：告诉系统“要什么”，而不是手写“怎么做”

如果你想点一份外卖，命令式的表达是：你从冰箱拿出菜，切好，起锅烧油，倒菜翻炒，装盘。声明式的表达是：告诉服务员“我要一份鱼香肉丝”，厨房里怎么做是后厨的事，你只需要关心“端上来的菜符合预期”。

Agent开发里的命令式写法，就是你在主函数里写循环、写if/else、手动调用模型、判断返回值、决定下一步调用哪个工具。典型的伪代码长这样：

while True: msg = input() result = agent.run(msg) if result.need_tool: tool_result = call_tool(result.tool_name) agent.add_message(tool_result) else: print(result.reply)

这种写法的好处是灵活，坏处是逻辑散落在代码里，改一条流程就要动代码、发版、走测试。而声明式Agent的做法是：把“系统提示词、模型参数、工具清单、节点路由、分支条件、终止条件”全部写进一份YAML或JSON配置，由编排引擎负责解析和执行。

agents: - name: order_agent system_prompt: "你是订单助手..." tools: - get_order_by_id nodes: - id: router type: llm next: condition_router

模型怎么跑、节点怎么连接、分支怎么判断，都由配置文件描述，代码只做两件事：注册工具函数、启动引擎。这个转变带来的直接好处就是，流程改动不再需要动代码，改配置、校验、发布即可。

1.2 两种范式的关键差异：一张表看明白

我用一个表格把两种方式的核心差异列出来，方便你做技术选型时对照：

实际项目里，不是非要二选一。常见做法是主干流程用声明式配置，特殊逻辑通过“自定义节点”或者“动态工具”暴露出来。也就是说，声明式Agent不是取消代码，而是把代码收敛到“工具实现”和“自定义处理函数”这两个边界内，中间的控制流交给配置管理。

1.3 为什么这个话题最近被反复讨论

本质原因是LLM的行为存在不确定性，需要一套“稳定的骨架”来约束它。你直接让模型自由对话，它可能答得很好，也可能答偏，还可能反复调用同一个工具不放。声明式Agent做的就是把这种不稳定性限制在一个可控的轨道上：模型只负责“理解意图、生成输出、决定调用哪个工具”，至于流程走哪个分支、最多重试几次、什么情况下转人工，都由配置明确指定。

第二层原因在于团队协作。代码式流程只有工程师能维护，业务方想调整客服话术、加一个订单查询的兜底节点，只能提需求排队。声明式配置出来后，业务方至少能看懂流程，再配一个可视化面板，业务方自己就能改配置发布，大大降低了协作成本。

第三层是可复制性。一份成熟Agent的编排配置，可以像模版一样在不同项目间复制，只需要替换工具列表和提示词。代码复制的黏合度很高，配置复制的成本要低得多。这也是很多团队愿意在早期就引入声明式的原因。

2. 核心组成与方案设计：选对编排引擎是关键

2.1 一份声明式配置的四个必备要素

我在实战里总结下来，任何一份声明式Agent配置，无论用哪个引擎，都逃不开四个部分：角色设定、模型参数、工具清单、编排规则。

角色设定本质上是系统提示词，重要程度被我排在最前面。它定义了Agent的身份、语气、边界，以及遇到不确定情况时的默认行为。实践中建议把提示词中可能变化的业务信息（比如客服话术、商品退换货政策）抽成变量，不要硬编码进配置里的system_prompt。这样同一个配置模板可以服务多个业务线。

模型参数这块要区分“全局默认”和“节点级覆盖”。全局默认放在配置顶部，比如temperature 0.2、max_tokens 2048；但如果某个节点（比如代码生成节点）需要更高的temperature，可以在节点配置里单独覆盖。多数声明式引擎支持这种层级覆盖，设计配置时多用这个能力，而不是一刀切。

工具清单是Agent能力的边界。配置里每个工具都要有清晰的名称、描述、入参说明。很多新手只写工具名，结果模型根本不知道“这个工具是干什么的、什么时候该调用”，导致流程动不动就卡在意图识别上。工具描述的质量直接影响Agent的表现，值得花时间打磨。

编排规则是声明式配置的灵魂。它描述节点之间怎么连接，什么条件走哪条分支，循环上限是多少，遇到错误怎么降级。没有编排规则的配置只是“一个带了工具的聊天机器人”，本质上还是自由对话；有了明确的编排规则，Agent才真正变成一个“按流程执行任务的数字员工”。

2.2 编排引擎三条路线：自研、框架封装、平台化

我在项目里调研过三种实现声明式Agent的路线，各有取舍。

第一条路线是完全自研解析器。用JSON Schema定义配置格式，自己写解析和执行引擎。好处是完全可控，坏处是工程量很大。你不仅要处理节点状态机、条件表达式的求值、错误重试，还要做可视化调试工具。除非你的场景极度特殊，否则我不建议从零造轮子。

第二条路线是用现成的Agent编排框架做一层薄封装。框架本身支持图式编排（节点、边、状态），你只需要定义一套自己的配置schema，再写一个适配层把配置翻译成框架的调用形式。这套方案的好处是保留了框架的生态和调试能力，同时拿到了声明式配置的灵活性，适合有一定工程能力、想深度定制的团队。

第三条路线是直接用支持声明式DSL的Agent平台或工具，把流程做成DSL文件，再通过API运行。优点是有可视化编排界面、内置trace和日志，业务方也能参与维护；缺点是流程的可定制深度受限，特别复杂的节点逻辑还是得退回代码。不过对大多数业务型Agent来说，平台DSL已经覆盖了绝大部分场景。

我个人的建议是：超过一半的场景用第三条路线快速验证，等到出现平台满足不了的高阶需求时，再把部分流程迁移到第二条路线。不要一上来就自研，Agent领域变化太快，自研很容易变成“为了造轮子而造轮子”。

2.3 声明式流程的三种典型编排模式

我把实际项目中最高频出现的三种编排模式列出来，你可以对照自己的场景。

第一种是线性流水线，最常见也最简单：检索资料、生成回复、格式校验，一个接一个地执行。适合处理“信息固定、顺序明确”的任务，比如工作总结生成、周报整理、知识库问答。

第二种是分支路由：先用一个识别节点判断用户意图，再根据结果路由到不同子Agent或子流程。客服场景就是典型例子：用户问“我的订单到哪了”走到物流查询流程，问“怎么退货”走到售后流程，识别不出来就转人工。分支路由的关键是识别节点的输出要稳定，建议在配置里指定输出格式（比如JSON），不要给模型自由发挥的空间。

第三种是循环与人工介入：配置里允许某个节点被重复执行，直到满足终止条件，或者执行到指定次数后强制跳出，转交人工。比如售后场景里，Agent尝试补偿方案三次都不被用户接受，就自动转人工。这种模式能很好地平衡自动化和服务质量，把模型搞不定的边界情况交给人来接管。

3. 从零实战：一个可运行的声明式客服Agent

3.1 目标场景先定清楚：一个带路由和人工兜底的客服助手

抽象场景比直接堆配置更能说清设计思路。我这里设计一个最小但完整的Demo：用户输入消息后，先经过意图识别节点，判断用户是想查订单、查物流还是需要人工帮助；然后路由到对应子Agent处理；如果子Agent拿不到必要信息（比如缺订单号），则触发一个“追问补全”节点；连续两次补全仍未成功，转人工。

选择这个场景是因为它完整覆盖了声明式Agent最常见的能力要素：意图识别、条件路由、工具调用、循环上限、人工介入。你把这个Demo跑通后，换成自己的业务工具和提示词，就可以直接改成类客服、类审核、类助手等各种项目。

3.2 核心配置文件逐段拆解

下面这份YAML配置是实际可运行的，只是字段做了简化。不同引擎的字段名会有差异，但设计思路通用。我按段拆解。

先看全局基本信息：

# demo-agent/agent.yaml name: customer-service-assistant description: 商城客服助手，支持订单查询、物流查询、人工兜底 variables: business_name: "示例商城" manual_queue_url: "http://localhost:8000/handoff" model: provider: openai-compatible name: gpt-4o-mini temperature: 0.2 max_tokens: 2048 timeout_seconds: 30

这里把业务名和人工队列地址抽成了variables，目的是让配置在不同环境（测试、生产）之间复用时不改业务逻辑。模型参数放在全局，后面节点如果不需要改变，就不用重复配置。

然后是Agent和工具声明：

agents: - name: router system_prompt: | 你是{ { business_name } }的意图识别器。 只输出JSON，格式： { "intent": "order_query | logistics_query | manual" } 如果用户消息中带有订单号且询问物流状态，intent为logistics_query。 tools: [] - name: order_agent system_prompt: | 你是{ { business_name } }订单助手。查询订单前必须先拿到订单号。 如果没有订单号，主动向用户索要。 查询结果返回后，用简洁中文说明订单状态。 tools: - get_order_by_id - name: logistics_agent system_prompt: | 你是{ { business_name } }物流助手。使用物流查询工具时，必须同时提供订单号。 tools: - track_logistics - name: manual_agent system_prompt: | 你是客服人工坐席的接引人。告知用户正在转接人工，并请用户稍候。 tools: - notify_manual_handoff

这里有一个细节：router的system_prompt明确指定了JSON输出格式。很多路由不准的问题不是模型能力差，而是提示词里没有给出“输出格式约束”，模型自由发挥的空间太大。声明式配置里尽量把格式要求写死，越死越稳。

接下来是流程节点定义：

nodes: - id: start type: input next: router - id: router type: llm agent: router input: "{{ user_message }}" output: intent_json - id: check_intent type: condition input: "{{ intent_json.intent }}" conditions: - case: "order_query" to: order_agent_node - case: "logistics_query" to: logistics_agent_node - case: "manual" to: manual_node default_to: manual_node - id: order_agent_node type: llm agent: order_agent tools: [get_order_by_id] input: "{{ user_message }}" loop: max_retries: 2 exit_condition: "{{ has_order_id }}" on_exceed: manual_node - id: logistics_agent_node type: llm agent: logistics_agent tools: [track_logistics] input: "{{ user_message }}" loop: max_retries: 2 exit_condition: "{{ has_order_id }}" on_exceed: manual_node - id: manual_node type: llm agent: manual_agent tools: [notify_manual_handoff]

语法上我只是定义了两类节点：普通处理节点和条件节点。每个节点通过input字段声明“它要消费之前哪一步的输出”，这就把节点间的数据流显式地写了出来，调试时能很清楚看到哪里断的。

edges这段我没有单独写，因为节点里的next、conditions已经隐含了连接关系。如果引擎支持显式edges，你可以把连接关系单独列出来，比如：

edges: - from: start to: router - from: check_intent conditions: - if: "{{ intent_json.intent == 'order_query' }}" to: order_agent_node

用显式edges还是隐式next，取决于你选型的引擎。建议统一用隐式next，配置更短；但要注意，隐式next在节点多的时候可读性会下降，这时显式edges更合适。

3.3 工具注册与函数绑定：配置怎么找到代码

声明式配置本身不含业务逻辑，所有真实操作都落在“工具函数”上。这里的关键问题是：配置文件里写了一个get_order_by_id，运行时引擎怎么知道该调哪个函数？这就需要一个注册机制。

我习惯在代码里用装饰器实现工具注册，保持代码和配置的一一对应。伪代码如下：

# tools.py from agent_engine import tool_registry @tool_registry.register( name="get_order_by_id", description="根据订单号查询订单状态和商品信息", parameters={ "order_id": { "type": "string", "description": "用户提供的订单号，例如 XA123456" } } ) def get_order_by_id(order_id: str) -> dict: # 模拟查询，实际项目这里会调订单服务 return { "order_id": order_id, "status": "shipped", "items": ["手机", "充电器"] } @tool_registry.register( name="track_logistics", description="根据订单号查询物流轨迹", parameters={ "order_id": { "type": "string", "description": "订单号" } } ) def track_logistics(order_id: str) -> dict: return {"location": "上海转运中心", "status": "运输中"}

运行时，引擎解析配置里的tools字段，去tool_registry里按名字找到对应函数，再按照配置中的参数描述生成给模型使用的function schema。整个过程对上层业务透明。

有一点要特别注意：工具描述里必须写清楚“什么时候不该调用”以及“需要什么前置条件”。比如track_logistics如果不在描述里说明“必须先拿到订单号”，模型就可能凭空编一个订单号传进去，导致查询失败。工具描述建议按“功能说明 + 触发条件 + 参数约束 + 失败兜底”四段式来写，尤其是失败兜底：工具报错后模型应该做什么，是转人工还是提示用户重新输入，最好在描述里写明确。

3.4 运行与调试：从节点trace定位问题

配置写好后，启动运行时跑一轮对话，你会看到类似下面的trace输出：

[1] input_node : user_message="我想查一下我的洗面奶到哪了" [2] router : intent_json={"intent":"logistics_query"} [3] track_logistics: order_id=None, error="缺少订单号" [4] logistics_agent: "请提供您的订单号" [5] user : "订单号是 XA20250112" [6] track_logistics: order_id="XA20250112", result="上海转运中心" [7] logistics_agent: "您的商品正在运往上海转运中心..."

这份trace的价值在于：每一个节点的输入输出都被记录，条件判断结果、工具调用参数、错误原因都能直接看到。上线后遇到用户反馈异常，不要问“模型是不是变笨了”，而是先拉trace看问题出在哪个节点。

如果引擎不支持trace，至少要在工具函数和节点流转处加结构化日志，包含节点ID、输入摘要、输出摘要、耗时。我踩过的坑里，至少有三次线上问题都是靠trace定位到“工具调用参数错误”，而不是模型本身的问题。没有trace就去猜模型行为，效率极低。

4. 难点攻坚：工具接入、状态管理与多轮记忆

4.1 工具接入的三种主流方式，选型要按场景走

声明式Agent的一大优势是“工具可插拔”，但接入方式不同，落地成本和灵活度差异很大。我把它分成三种。

第一种是内部函数直接注册，也就是上面例子里的方式。工具函数和Agent服务在同一个进程内，通过装饰器注册。适合内部服务调用、数据库查询、规则策略判断等场景。优点是延迟低、链路简单；缺点是每次加工具都要改代码发版，业务方没法自助操作。

第二种是HTTP API封装。把外部系统已有的REST接口，用OpenAPI描述导入到工具清单中，引擎自动生成function schema。适合对接内部订单服务、支付网关、第三方SaaS等场景。你不需要写太多代码，但要处理好接口鉴权和超时。

第三种是MCP（Model Context Protocol）服务方式。把工具封装成标准的MCP服务，Agent运行时通过协议动态发现和调用工具。适合团队内多项目共享工具资产、工具数量多且更新频繁的场景。这是目前工具接入效率最高的方式之一，但要求你对MCP的规范有一定了解，初期配置成本也更高。

三种方式没有绝对的好坏，我建议遵循“就近接入”原则：工具离Agent服务近，用函数注册；跨团队，用HTTP或MCP；需要动态扩展，优先MCP。实际项目里经常是三种混用。比如我的Demo里，订单查询用函数注册，物流接口用HTTP封装，而人工转接队列就是走HTTP回调。混用完全没问题，只要在配置里标明每个工具的接入类型就行。

4.2 状态管理和多轮记忆，放进配置前要想清楚

声明式配置描述的是流程，但Agent跑起来之后，节点和节点之间是需要传数据的。这个数据流设计不好，就会出现“router判断完意图，order_agent却看不到判断结果”的尴尬情况。

我推荐的做法是显式声明状态传递：每个节点明确写出它消费哪些数据、产出哪些数据。你在配置里看到input字段，就知道它依赖什么。引擎在每次节点执行前把指定数据从全局状态里取出来，执行后把输出放回全局状态。这种做法比隐式全局变量好在两点：一是并发执行多个对话时不会串数据，二是trace可以看到每个节点的输入输出快照。

多轮记忆又是另一层问题。声明式Agent的每个节点默认是无状态的，只处理当前输入。但用户会说“那我的另一个订单呢”，这时候你需要在上下文里保留多轮关键信息。我的做法分成两步：配置里指定memory区块，声明保留最近几轮摘要、提取哪些关键实体（订单号、收件人），然后运行时把摘要注入到每个LLM节点的system_prompt之后的位置。如果只有最后一轮信息，很多对话都续不上，所以记忆配置不要省。

4.3 流程设计里的几个高频坑

第一是死循环。循环节点如果没有设置max_retries，模型可能在“追问订单号”和“用户重复给错”之间无限循环。配置里必须给每个循环节点设置上限，同时把上限耗尽后的行为指向兜底节点。

第二是工具超时。外部API难免变慢，如果工具超时没有处理，整个对话会卡在原地。我习惯在每个工具调用上配置超时时间和失败重试策略，并给模型一个降级说明：查询工具超时后，回复“查询服务暂时繁忙，请稍后再试”。

第三是分支条件不命中。条件节点如果既没有匹配的case，也没配置default_to，运行时就会报错或悄悄结束流程。这个我在早期反复踩过：字段名写错了，condition一直不成立，用户被莫名转到人工。后来加了default_to，同时在trace里输出条件判定明细，问题才彻底解决。

5. 常见问题与排查技巧实录

5.1 一张问题速查表，覆盖我遇到的大部分线上状况

这张表里最值得重视的是第一行：配置字段不生效。绝大多数情况不是引擎问题，而是你手写了自定义字段，引擎根本不认识，静默忽略了。所以每次改动配置，第一步永远是跑校验，不要直接上线。

5.2 一条实用的调试路径：先看trace，再改配置，最后才动代码

我调试声明式Agent的顺序基本固定。先拉trace看整个流程走到哪个环节断的；然后对照配置确认断的这个节点是否符合预期；如果节点行为不符合预期，先调整配置（提示词、条件表达式、工具描述）；只有当配置层面无法解决时，才考虑写自定义代码。

举个例子，之前线上出现“用户明明在问物流，Agent却回答订单状态”，trace显示router的输出intent是order_query。问题很明显是意图识别不准。我当时没有去改模型，而是调整了router的system_prompt，加了一句“只要用户提到物流位置、快递、到哪了，一律视为logistics_query”，效果立竿见影。

这条路径的核心思想是：声明式Agent的模型行为是可以通过配置等价控制的，大多数问题在配置层就能解决。动代码修复的周期长、风险大，应该作为最后手段。

5.3 声明式不是银弹：哪些场景应该回退到代码式

说了这么多优点，我也要泼一盆冷水。声明式Agent不是所有场景都适用。如果你的流程需要高强度动态变化，比如每个用户的流程都由模型实时生成，或者多个Agent之间的协作关系非常复杂且需要相互动态协商，这种情况下用声明式配置描述反而会比写代码更痛苦。因为你要把所有可能的分支都枚举出来，配置会膨胀到难以维护。

遇到这类场景，我的建议是退回代码式编排，或者采用“代码为主、声明式为辅”的混合模式。比如保留一个主流程Agent用代码写，内部某些子流程（如固定工具链调用）再用声明式配置。这样既能保证复杂逻辑的自由度，也能享受声明式配置的可读性和可维护性。

我见过不少团队为了用声明式而用声明式，把本来很简单的流程搞成几百行的配置，维护成本反而更高。判断标准只有一个：如果你改需求时需要动配置的比例超过50%，说明这个场景不适合声明式；反之，如果大部分需求只是调顺序、改文字、增删工具，那就应该坚定走声明式。

6. 落地经验：声明式Agent到底该用在哪些场景

6.1 从一个边界清晰的小场景开始切，而不是一上来就重构

如果你想在现有系统里引入声明式Agent，我的建议是先找一个边界清晰、流程相对稳定的小场景做试点。比如客服助手里的“物流查询”子流程，这比直接重构整套对话系统稳妥得多。试点验证两件事：一是声明式配置能否覆盖你80%以上的分支逻辑，二是业务方能不能看懂并独立修改配置。

试点阶段不要追求大而全，做一个小而深的闭环比铺很多半成品有价值。我见过最成功的引入案例，是一个团队只花两周时间做了一个“差评分类提醒”流程，覆盖从用户问题识别到自动打标转给对应客服的全链路，之后才逐步扩展到售前咨询、订单处理等更大场景。

6.2 配置治理：schema校验、版本管理和灰度发布不能省

配置也是代码，需要像代码一样被管理。至少要建立三件事：第一个是配置的schema校验，任何配置上线前必须通过引擎的validate命令，防字段拼错；第二个是配置的版本管理，用配置文件而不是数据库去管理版本，这样每次变更都能diff；第三个是灰度发布，不要一把全量，先让配置在5%的流量上跑几小时，看trace的异常率再逐步放量。

另一个容易被忽略的点是配置的可观测性。我建议在trace里埋三个指标：节点平均耗时、异常节点占比、条件分支命中分布。这三个指标能回答“哪个节点最慢”“哪个分支最容易走到异常”“用户最常触发哪些意图”，是优化Agent流程的数据基础。

6.3 声明式Agent适合谁，不适合谁，心里要有数

适合的情况是：你已经有明确的业务路径，比如客服流程、审批流程、审核流程，希望把流程从代码里搬出来，让业务方参与维护；团队有多个同类Agent项目需要复用统一骨架；或者你需要对外输出Agent能力，给不同客户提供可配置的模板。

不适合的情况是：你在做纯探索型的研究项目，流程每天都在变且没有固定形态；你的Agent依赖复杂的并发协作和博弈；或者你的场景对时延极其敏感，agent的每一步都需要极低延迟，这个时候配置解析和引擎调度的开销反而是负担。

我个人的体会是，声明式Agent不是把Agent变笨，而是把不稳定性关进笼子里。真正聪明的Agent，反而需要一个稳定可控的外壳。先用声明式把骨架确定下来，再在节点内部释放模型的能力，这个“外稳内活”的组合，目前看是Agent落地性价比最高的打法。

最后分享一个自己在实战中特别有感的细节：每次修改声明式配置，我都会先跑一遍最小回归测试集，把用户最常见的那二三十个问题跑一遍，对比改动前后的trace差异。不要小看这一步，它能帮你拦住很多“本地能跑、线上就崩”的隐性回归问题。做一个稳定的Agent，往往不是把模型调得多聪明，而是把配置治理得多扎实。