1. 背景与核心概念为什么需要工作流智能体在AI应用开发领域一个长期存在的矛盾是大模型虽然能力强大但单次对话的上下文有限难以处理复杂、多步骤的业务逻辑。例如一个简单的“查询天气并推荐穿搭”的需求就需要先调用天气API获取数据再根据温度、天气状况进行逻辑判断最后生成文本建议。如果全靠大模型“自由发挥”结果可能不稳定且难以集成外部工具或数据库。这正是Coze扣子平台及其工作流Workflow功能要解决的核心问题。Coze是字节跳动推出的AI Bot开发平台它允许开发者通过可视化拖拽的方式将大模型、代码、条件判断、API调用等节点连接起来构建出确定性的、可复用的复杂AI应用流程。而工作流智能体就是将这种可视化编排的能力与一个具备特定身份和目标的AI智能体Agent相结合使其能够自动化执行一系列任务。简单来说你可以把工作流想象成一个“流程图”把智能体想象成“执行这个流程图的机器人”。本次教程聚焦的Coze扣子3.0在工作流能力上进行了显著增强支持更复杂的逻辑分支、循环和数据处理并且打通了Web、移动端通过豆包App和API接口实现了真正的“三端打通”。更激动人心的是它支持接入本地Agent这意味着你可以让Coze工作流调用部署在你自己服务器上的私有化模型或服务兼顾了公有云的便捷与私有部署的安全可控。对于开发者而言掌握Coze工作流意味着降低开发门槛无需深厚编程基础通过拖拽即可实现复杂逻辑真正“无代码”或“低代码”。提升应用可靠性工作流是确定性的避免了纯LLM输出的随机性确保关键业务流程稳定执行。加速集成与部署可视化界面让API集成、数据库查询、条件分支一目了然并且能快速发布到多个渠道。保护数据隐私通过本地Agent能力敏感数据处理、内部系统调用可以留在本地环境只与Coze交换必要信息。接下来我们将从零开始手把手搭建一个功能完整的工作流智能体并实现三端打通与本地Agent接入。2. 环境准备与前置条件在开始动手之前请确保你已满足以下条件。本文的演示将基于这些通用环境但核心思路适用于所有配置。2.1 基础账号与环境Coze平台账号访问Coze官网注册并登录。确保你使用的是支持工作流3.0版本的区域通常国际站和国内站均已更新。网络环境能够正常访问Coze平台及相关API服务。基础概念了解什么是API接口HTTP请求、JSON数据格式这将有助于理解节点配置。2.2 本地Agent环境准备可选但推荐本地Agent不是必选项但它是实现混合云架构、调用私有能力的关键。我们将以一个简单的Python HTTP服务为例。Python环境本地需安装Python 3.8或以上版本。可在命令行输入python --version检查。必要Python库我们将使用flask和requests库来创建Web服务。# 在命令行中执行安装 pip install flask requests网络要求你的本地开发机需要有一个能被Coze云端服务访问到的公网IP或域名。对于开发测试我们强烈推荐使用内网穿透工具如ngrok、localtunnel或frp。本文将以ngrok为例进行演示。前往 ngrok 官网注册获取你的Authtoken。下载ngrok客户端并配置。# 解压后在终端配置你的token ./ngrok config add-authtoken 你的Authtoken2.3 明确我们的实战目标我们将构建一个“智能旅行助手”工作流智能体。它的功能是用户输入一个城市名。工作流首先调用一个本地Agent模拟私有服务来验证该城市是否在可服务列表内并返回一些基础信息。如果城市有效则并行调用两个云端API一个获取该城市模拟天气一个获取模拟景点推荐。将本地Agent返回的信息与两个云端API的结果进行合成。最终由大模型节点生成一份格式友好、包含天气、景点和旅行建议的完整回复。将此智能体发布可在Web端、豆包App及通过API调用。这个流程涵盖了条件判断、并行处理、数据合成、本地调用等关键工作流概念。3. Coze工作流核心节点与设计思想拆解开始拖拽之前理解几个核心节点的用途至关重要。Coze工作流3.0的节点主要分为以下几类3.1 触发器与输入/输出开始节点工作流的唯一入口定义了智能体被触发时接收的用户输入参数。例如我们可以在这里定义一个名为city_name的字符串变量。结束节点工作流的出口定义了返回给用户的结果。通常会将前面节点处理好的最终内容赋值给结束节点的output变量。3.2 逻辑控制条件判断根据条件表达式如city_info.is_valid true决定流程走向不同的分支。这是实现业务逻辑的核心。循环用于遍历列表或重复执行某段流程直到条件满足。并行执行允许同时发起多个互不依赖的请求如同时查询天气和景点极大缩短整体响应时间。3.3 功能节点LLM大模型核心的文本生成与理解节点。你可以选择平台提供的多种模型如GPT-4、豆包模型等并通过“系统提示词”赋予其角色和任务。在工作流中LLM节点通常被用作“信息合成器”或“格式化工匠”而不是唯一的知识来源。代码节点支持Python和JavaScript。用于执行简单的数据转换、计算或逻辑处理。例如从API返回的复杂JSON中提取某个字段。知识库可以让工作流检索你上传的文档内容实现基于私有知识的问答。插件/API调用这是与外部世界交互的桥梁。Coze提供了大量预置插件如搜索、日历、翻译也支持通过HTTP请求节点自定义调用任何第三方API或你的本地Agent。3.4 设计思想确定性流程驱动与传统聊天机器人完全依赖大模型“即兴发挥”不同工作流智能体的设计思想是“确定性流程驱动”。输入标准化通过开始节点明确定义输入参数。过程结构化用条件、循环、并行节点控制流程骨架。能力外部化专业任务数据查询、计算、业务规则交给API、代码或知识库节点。LLM角色化大模型主要负责它最擅长的自然语言理解、信息整合和格式化输出而不是记忆事实或执行精确计算。 这种架构使得智能体行为可预测、可调试、可优化。4. 保姆级搭建教程从零创建智能旅行助手现在让我们进入实操环节。请跟随步骤一步步操作。4.1 步骤一创建智能体与工作流登录Coze平台点击“创建智能体”。为智能体起名如“旅行小助手”并填写简单的描述和系统提示词例如“你是一个专业的旅行规划助手。”。注意工作流会覆盖智能体的主要逻辑此处的提示词作用会减弱但可以保留一些基础设定。在智能体编辑页面找到并点击“工作流”标签页然后点击“创建工作流”。你将进入一个空白的画布。4.2 步骤二搭建本地Agent服务模拟在编排Coze工作流之前我们先在本地准备好一个可供调用的服务。创建一个名为local_agent.py的Python文件。写入以下代码。这个服务提供了一个/city/check接口接收城市名返回一个包含验证结果和模拟信息的JSON。# local_agent.py from flask import Flask, request, jsonify app Flask(__name__) # 模拟一个可服务的城市数据库 SERVICEABLE_CITIES { 北京: {country: 中国, timezone: UTC8}, 上海: {country: 中国, timezone: UTC8}, 巴黎: {country: 法国, timezone: UTC1}, 纽约: {country: 美国, timezone: UTC-5}, } app.route(/city/check, methods[POST]) def check_city(): data request.json city_name data.get(city_name, ).strip() if not city_name: return jsonify({error: 城市名不能为空}), 400 city_info SERVICEABLE_CITIES.get(city_name) if city_info: response { is_valid: True, message: f城市 {city_name} 在我们的服务范围内。, country: city_info[country], timezone: city_info[timezone] } else: response { is_valid: False, message: f抱歉我们暂未提供 {city_name} 的旅行服务。, country: None, timezone: None } return jsonify(response) if __name__ __main__: # 在本地5000端口启动服务 app.run(host0.0.0.0, port5000, debugTrue)在终端运行此服务python local_agent.py你应该看到服务在http://127.0.0.1:5000启动。关键一步暴露本地服务到公网。打开另一个终端运行ngrok./ngrok http 5000ngrok会生成一个临时的公网URL例如https://abcd-1234.ngrok-free.app。请记下这个https://开头的 Forwarding URL这就是Coze工作流将要调用的地址。4.3 步骤三编排Coze工作流核心逻辑回到Coze工作流画布我们开始拖拽节点。设置开始节点从左侧节点库拖入“开始”节点。在右侧属性面板点击“添加输入参数”创建一个名为city_name、类型为“字符串”的变量。这代表用户输入的城市。添加HTTP节点调用本地Agent拖入“HTTP请求”节点。将开始节点的输出连线到此节点。配置该节点请求方式POSTURL填写你的ngrok地址 端点例如https://abcd-1234.ngrok-free.app/city/check请求体选择“JSON”并配置为{“city_name”: “{{city_name}}”}。这里的{{city_name}}会引用开始节点的变量。输出变量名设为local_agent_resp方便后续节点引用。添加条件判断节点拖入“条件判断”节点。将HTTP节点的输出连线到此节点。配置条件我们需要根据本地Agent的返回结果决定流程走向。在“条件表达式”中输入local_agent_resp.body.is_valid true。这表示检查HTTP返回体的is_valid字段是否为真。并行处理天气与景点查询在“是”分支从条件节点的“是”分支引出我们需要同时执行两个操作。Coze工作流支持并行这里我们通过先后添加两个HTTP节点并将它们都连到条件节点的“是”分支来实现逻辑上的并行实际执行顺序由系统优化。HTTP节点1模拟天气APIURL:https://api.weatherapi.com/v1/current.json?keydemoq{{city_name}}(此处使用免费演示API实际项目需换用可靠源或模拟)方法: GET输出变量名:weather_respHTTP节点2模拟景点API我们可以用一个“代码节点”来模拟。拖入“代码节点”语言选Python。在代码框中输入# 模拟景点数据 def main(city_name): attractions { “北京”: [“故宫”, “长城”, “天坛”], “上海”: [“外滩”, “迪士尼乐园”, “东方明珠”], “巴黎”: [“埃菲尔铁塔”, “卢浮宫”, “凯旋门”], “纽约”: [“自由女神像”, “时代广场”, “中央公园”] } return { “city”: city_name, “attractions”: attractions.get(city_name, [“暂无推荐景点”]) } # city_name 会自动从上游传入输出变量名:attractions_resp添加LLM节点合成信息将天气节点和景点节点的输出都连线到一个新的“LLM”节点。配置LLM节点选择模型例如选择“GPT-4”或“Doubao-pro”。系统提示词这里至关重要它指导模型如何整合信息。你是一个专业的旅行助手。请根据提供的以下信息生成一段热情、 informative 的旅行建议回复。 信息包括 1. 城市基本信息{{local_agent_resp.body}} 2. 当前天气情况{{weather_resp.body.current}} 3. 推荐景点{{attractions_resp.attractions}} 请将以上信息有机地整合成一段连贯的文字直接面向用户输出。如果城市无效你不会收到天气和景点信息。用户提示词可以简单写为“请生成旅行建议。”。输出变量名设为final_advice。设置结束节点成功流程将LLM节点的输出连线到“结束”节点。在结束节点的属性中将“输出内容”设置为{{final_advice.content}}。这样LLM生成的内容就会作为智能体的最终回复。处理无效城市“否”分支从条件节点的“否”分支连线到另一个“结束”节点。在这个结束节点的“输出内容”中直接引用本地Agent返回的错误信息{{local_agent_resp.body.message}}。至此一个完整的工作流就搭建完毕了。你的画布应该包含开始 - HTTP(本地Agent) - 条件判断 - (是分支) - HTTP(天气) 代码(景点) - LLM - 结束以及条件判断的(否分支) - 结束。4.4 步骤四调试与测试点击画布右上角的“调试”按钮。在调试面板的输入框中为city_name填写测试值如“巴黎”。点击“运行”。下方会显示执行过程你可以展开每个节点查看其输入和输出这对于排查问题极其有用。观察最终输出应该是一段整合了本地信息、天气和景点的旅行建议。再测试一个不在列表的城市如“东京”应该会直接返回本地Agent定义的错误消息。5. 实现三端打通与发布工作流调试通过后如何让用户用起来5.1 发布到Web与豆包App返回智能体编辑页的“发布”选项卡。在“发布渠道”中确保“豆包”和“Web”是开启状态。你可以自定义智能体的头像、欢迎语等。点击“发布”。发布后你可以Web端直接在Coze网站或你嵌入的Web页面中与智能体对话。豆包App在豆包App中搜索你智能体的名字即可直接使用。这是“三端打通”中最便捷的移动端体验。5.2 通过API调用实现系统集成这是将智能体能力嵌入到你自己的业务系统的关键。在智能体编辑页点击“API访问”选项卡。你会看到该智能体专属的API密钥API Key和接口地址Endpoint。请妥善保管API Key。调用示例使用Python的requests库import requests import json url “你的智能体API Endpoint” api_key “你的智能体API Key” headers { “Authorization”: f”Bearer {api_key}“, “Content-Type”: “application/json” } # 注意payload的结构需要匹配你工作流开始节点定义的输入参数 payload { “parameters”: { “city_name”: “纽约” # 参数名与工作流中定义的变量名一致 } } response requests.post(url, headersheaders, datajson.dumps(payload)) result response.json() print(result[“content”]) # 输出智能体的回复通过API任何能发送HTTP请求的系统你的网站、APP、内部OA等都可以调用这个智能工作流。6. 常见问题与排查思路在搭建和使用过程中你可能会遇到以下问题问题现象可能原因排查与解决思路工作流调试时HTTP节点报“连接超时”或“连接错误”。1. 本地Agent服务未启动。2. ngrok隧道未建立或地址错误。3. 本地防火墙/安全软件阻止了连接。1. 检查python local_agent.py是否在运行。2. 检查ngrok终端是否显示Online并确认复制的URL无误。3. 临时关闭防火墙或检查5000端口是否开放。调用本地Agent返回了结果但条件判断节点无法正确解析。HTTP节点的输出变量结构引用错误。body字段可能不存在或者JSON结构不符合预期。在调试面板中展开HTTP节点仔细查看其完整的输出对象结构。条件表达式应基于变量名.body.字段名的路径编写。LLM节点生成的回复未包含预期的天气或景点信息。系统提示词中引用变量的语法错误或变量名与上游节点输出名不匹配。1. 检查提示词中{{weather_resp.body.current}}等变量引用是否正确。2. 确认上游“天气HTTP节点”的输出变量名确实是weather_resp。通过API调用智能体返回错误或非预期回复。1. API Key或Endpoint错误。2. 请求Payload的格式不正确未按{“parameters”: {...}}包裹。3. 参数名与工作流开始节点定义的名称不匹配。1. 核对API访问页面的信息。2. 使用Postman等工具测试确保Payload格式完全符合文档。3. 检查工作流开始节点的输入参数定义。豆包App中找不到已发布的智能体。1. 发布后同步有延迟。2. 智能体设置了“私密”可见性。3. 登录的豆包账号与发布Coze智能体的账号不同。1. 等待几分钟后重试搜索。2. 在发布设置中将可见性改为“公开”或“通过链接访问”。3. 确保使用同一账号体系。7. 最佳实践与进阶建议掌握了基础搭建后遵循以下实践能让你的工作流智能体更健壮、更强大。7.1 工作流设计最佳实践模块化设计将一个复杂的长工作流拆分成多个子工作流。Coze支持工作流嵌套调用这有助于复用逻辑如“用户身份验证”和降低主流程复杂度。充分利用并行对于互不依赖的IO操作如调用多个外部API务必使用并行分支可以显著降低整体响应时间。详尽的错误处理不仅要在条件判断中处理业务逻辑错误如城市无效更要在HTTP节点、代码节点后添加“错误处理”分支。Coze节点支持配置“错误时转向”可以捕获网络超时、API限流、代码异常等并给出友好的用户提示而不是让整个流程崩溃。变量命名清晰使用weather_api_response,user_query_parsed这类有意义的变量名而不是resp1,data2便于后期维护和调试。7.2 本地Agent安全与性能身份验证上述示例的本地Agent是开放的存在安全风险。在生产环境中必须在HTTP请求头或参数中加入签名验证。Coze的HTTP节点支持添加自定义Header你可以在本地Agent端验证一个预共享的密钥或Token。超时与重试在Coze的HTTP节点配置中设置合理的“请求超时”时间。对于关键业务可以考虑在工作流层面实现重试逻辑。负载与监控本地Agent服务需考虑并发能力和资源监控。对于高并发场景需要使用生产级WSGI服务器如Gunicorn替代Flask开发服务器并部署在可靠的云主机或容器中。7.3 提示词工程在工作流中的运用在工作流中LLM提示词的角色发生了变化系统提示词侧重于定义角色和整合信息的规则。应清晰列出所有可用的输入变量{{variable}}并明确指示模型如何使用它们。少样本示例如果输出格式要求严格如JSON、特定报告模板可以在系统提示词中提供1-2个输入输出的示例Few-Shot引导模型遵循格式。上下文管理工作流本身已经通过节点处理了上下文因此通常不需要在提示词中要求模型“记住”之前的对话。焦点应放在当前节点的具体合成任务上。7.4 版本管理与迭代在Coze中修改智能体或工作流是实时生效的。对于重要的生产智能体建议重大修改前先复制在智能体设置中使用“复制”功能创建一个新版本进行测试。利用调试历史调试面板会记录每次运行的输入输出是排查线上问题和优化流程的宝贵资料。灰度发布对于通过API服务大量用户的智能体可以通过路由逻辑将部分流量导向新版本的工作流进行测试验证无误后再全量切换。从拖拽第一个节点开始到构建出能处理复杂业务、安全可靠、支持多端访问的智能体Coze工作流极大地降低了AI应用开发的门槛。它不仅仅是一个工具更是一种将大模型能力工程化、产品化的新范式。 Coze工作流智能体实战：从零构建三端打通AI应用
1. 背景与核心概念为什么需要工作流智能体在AI应用开发领域一个长期存在的矛盾是大模型虽然能力强大但单次对话的上下文有限难以处理复杂、多步骤的业务逻辑。例如一个简单的“查询天气并推荐穿搭”的需求就需要先调用天气API获取数据再根据温度、天气状况进行逻辑判断最后生成文本建议。如果全靠大模型“自由发挥”结果可能不稳定且难以集成外部工具或数据库。这正是Coze扣子平台及其工作流Workflow功能要解决的核心问题。Coze是字节跳动推出的AI Bot开发平台它允许开发者通过可视化拖拽的方式将大模型、代码、条件判断、API调用等节点连接起来构建出确定性的、可复用的复杂AI应用流程。而工作流智能体就是将这种可视化编排的能力与一个具备特定身份和目标的AI智能体Agent相结合使其能够自动化执行一系列任务。简单来说你可以把工作流想象成一个“流程图”把智能体想象成“执行这个流程图的机器人”。本次教程聚焦的Coze扣子3.0在工作流能力上进行了显著增强支持更复杂的逻辑分支、循环和数据处理并且打通了Web、移动端通过豆包App和API接口实现了真正的“三端打通”。更激动人心的是它支持接入本地Agent这意味着你可以让Coze工作流调用部署在你自己服务器上的私有化模型或服务兼顾了公有云的便捷与私有部署的安全可控。对于开发者而言掌握Coze工作流意味着降低开发门槛无需深厚编程基础通过拖拽即可实现复杂逻辑真正“无代码”或“低代码”。提升应用可靠性工作流是确定性的避免了纯LLM输出的随机性确保关键业务流程稳定执行。加速集成与部署可视化界面让API集成、数据库查询、条件分支一目了然并且能快速发布到多个渠道。保护数据隐私通过本地Agent能力敏感数据处理、内部系统调用可以留在本地环境只与Coze交换必要信息。接下来我们将从零开始手把手搭建一个功能完整的工作流智能体并实现三端打通与本地Agent接入。2. 环境准备与前置条件在开始动手之前请确保你已满足以下条件。本文的演示将基于这些通用环境但核心思路适用于所有配置。2.1 基础账号与环境Coze平台账号访问Coze官网注册并登录。确保你使用的是支持工作流3.0版本的区域通常国际站和国内站均已更新。网络环境能够正常访问Coze平台及相关API服务。基础概念了解什么是API接口HTTP请求、JSON数据格式这将有助于理解节点配置。2.2 本地Agent环境准备可选但推荐本地Agent不是必选项但它是实现混合云架构、调用私有能力的关键。我们将以一个简单的Python HTTP服务为例。Python环境本地需安装Python 3.8或以上版本。可在命令行输入python --version检查。必要Python库我们将使用flask和requests库来创建Web服务。# 在命令行中执行安装 pip install flask requests网络要求你的本地开发机需要有一个能被Coze云端服务访问到的公网IP或域名。对于开发测试我们强烈推荐使用内网穿透工具如ngrok、localtunnel或frp。本文将以ngrok为例进行演示。前往 ngrok 官网注册获取你的Authtoken。下载ngrok客户端并配置。# 解压后在终端配置你的token ./ngrok config add-authtoken 你的Authtoken2.3 明确我们的实战目标我们将构建一个“智能旅行助手”工作流智能体。它的功能是用户输入一个城市名。工作流首先调用一个本地Agent模拟私有服务来验证该城市是否在可服务列表内并返回一些基础信息。如果城市有效则并行调用两个云端API一个获取该城市模拟天气一个获取模拟景点推荐。将本地Agent返回的信息与两个云端API的结果进行合成。最终由大模型节点生成一份格式友好、包含天气、景点和旅行建议的完整回复。将此智能体发布可在Web端、豆包App及通过API调用。这个流程涵盖了条件判断、并行处理、数据合成、本地调用等关键工作流概念。3. Coze工作流核心节点与设计思想拆解开始拖拽之前理解几个核心节点的用途至关重要。Coze工作流3.0的节点主要分为以下几类3.1 触发器与输入/输出开始节点工作流的唯一入口定义了智能体被触发时接收的用户输入参数。例如我们可以在这里定义一个名为city_name的字符串变量。结束节点工作流的出口定义了返回给用户的结果。通常会将前面节点处理好的最终内容赋值给结束节点的output变量。3.2 逻辑控制条件判断根据条件表达式如city_info.is_valid true决定流程走向不同的分支。这是实现业务逻辑的核心。循环用于遍历列表或重复执行某段流程直到条件满足。并行执行允许同时发起多个互不依赖的请求如同时查询天气和景点极大缩短整体响应时间。3.3 功能节点LLM大模型核心的文本生成与理解节点。你可以选择平台提供的多种模型如GPT-4、豆包模型等并通过“系统提示词”赋予其角色和任务。在工作流中LLM节点通常被用作“信息合成器”或“格式化工匠”而不是唯一的知识来源。代码节点支持Python和JavaScript。用于执行简单的数据转换、计算或逻辑处理。例如从API返回的复杂JSON中提取某个字段。知识库可以让工作流检索你上传的文档内容实现基于私有知识的问答。插件/API调用这是与外部世界交互的桥梁。Coze提供了大量预置插件如搜索、日历、翻译也支持通过HTTP请求节点自定义调用任何第三方API或你的本地Agent。3.4 设计思想确定性流程驱动与传统聊天机器人完全依赖大模型“即兴发挥”不同工作流智能体的设计思想是“确定性流程驱动”。输入标准化通过开始节点明确定义输入参数。过程结构化用条件、循环、并行节点控制流程骨架。能力外部化专业任务数据查询、计算、业务规则交给API、代码或知识库节点。LLM角色化大模型主要负责它最擅长的自然语言理解、信息整合和格式化输出而不是记忆事实或执行精确计算。 这种架构使得智能体行为可预测、可调试、可优化。4. 保姆级搭建教程从零创建智能旅行助手现在让我们进入实操环节。请跟随步骤一步步操作。4.1 步骤一创建智能体与工作流登录Coze平台点击“创建智能体”。为智能体起名如“旅行小助手”并填写简单的描述和系统提示词例如“你是一个专业的旅行规划助手。”。注意工作流会覆盖智能体的主要逻辑此处的提示词作用会减弱但可以保留一些基础设定。在智能体编辑页面找到并点击“工作流”标签页然后点击“创建工作流”。你将进入一个空白的画布。4.2 步骤二搭建本地Agent服务模拟在编排Coze工作流之前我们先在本地准备好一个可供调用的服务。创建一个名为local_agent.py的Python文件。写入以下代码。这个服务提供了一个/city/check接口接收城市名返回一个包含验证结果和模拟信息的JSON。# local_agent.py from flask import Flask, request, jsonify app Flask(__name__) # 模拟一个可服务的城市数据库 SERVICEABLE_CITIES { 北京: {country: 中国, timezone: UTC8}, 上海: {country: 中国, timezone: UTC8}, 巴黎: {country: 法国, timezone: UTC1}, 纽约: {country: 美国, timezone: UTC-5}, } app.route(/city/check, methods[POST]) def check_city(): data request.json city_name data.get(city_name, ).strip() if not city_name: return jsonify({error: 城市名不能为空}), 400 city_info SERVICEABLE_CITIES.get(city_name) if city_info: response { is_valid: True, message: f城市 {city_name} 在我们的服务范围内。, country: city_info[country], timezone: city_info[timezone] } else: response { is_valid: False, message: f抱歉我们暂未提供 {city_name} 的旅行服务。, country: None, timezone: None } return jsonify(response) if __name__ __main__: # 在本地5000端口启动服务 app.run(host0.0.0.0, port5000, debugTrue)在终端运行此服务python local_agent.py你应该看到服务在http://127.0.0.1:5000启动。关键一步暴露本地服务到公网。打开另一个终端运行ngrok./ngrok http 5000ngrok会生成一个临时的公网URL例如https://abcd-1234.ngrok-free.app。请记下这个https://开头的 Forwarding URL这就是Coze工作流将要调用的地址。4.3 步骤三编排Coze工作流核心逻辑回到Coze工作流画布我们开始拖拽节点。设置开始节点从左侧节点库拖入“开始”节点。在右侧属性面板点击“添加输入参数”创建一个名为city_name、类型为“字符串”的变量。这代表用户输入的城市。添加HTTP节点调用本地Agent拖入“HTTP请求”节点。将开始节点的输出连线到此节点。配置该节点请求方式POSTURL填写你的ngrok地址 端点例如https://abcd-1234.ngrok-free.app/city/check请求体选择“JSON”并配置为{“city_name”: “{{city_name}}”}。这里的{{city_name}}会引用开始节点的变量。输出变量名设为local_agent_resp方便后续节点引用。添加条件判断节点拖入“条件判断”节点。将HTTP节点的输出连线到此节点。配置条件我们需要根据本地Agent的返回结果决定流程走向。在“条件表达式”中输入local_agent_resp.body.is_valid true。这表示检查HTTP返回体的is_valid字段是否为真。并行处理天气与景点查询在“是”分支从条件节点的“是”分支引出我们需要同时执行两个操作。Coze工作流支持并行这里我们通过先后添加两个HTTP节点并将它们都连到条件节点的“是”分支来实现逻辑上的并行实际执行顺序由系统优化。HTTP节点1模拟天气APIURL:https://api.weatherapi.com/v1/current.json?keydemoq{{city_name}}(此处使用免费演示API实际项目需换用可靠源或模拟)方法: GET输出变量名:weather_respHTTP节点2模拟景点API我们可以用一个“代码节点”来模拟。拖入“代码节点”语言选Python。在代码框中输入# 模拟景点数据 def main(city_name): attractions { “北京”: [“故宫”, “长城”, “天坛”], “上海”: [“外滩”, “迪士尼乐园”, “东方明珠”], “巴黎”: [“埃菲尔铁塔”, “卢浮宫”, “凯旋门”], “纽约”: [“自由女神像”, “时代广场”, “中央公园”] } return { “city”: city_name, “attractions”: attractions.get(city_name, [“暂无推荐景点”]) } # city_name 会自动从上游传入输出变量名:attractions_resp添加LLM节点合成信息将天气节点和景点节点的输出都连线到一个新的“LLM”节点。配置LLM节点选择模型例如选择“GPT-4”或“Doubao-pro”。系统提示词这里至关重要它指导模型如何整合信息。你是一个专业的旅行助手。请根据提供的以下信息生成一段热情、 informative 的旅行建议回复。 信息包括 1. 城市基本信息{{local_agent_resp.body}} 2. 当前天气情况{{weather_resp.body.current}} 3. 推荐景点{{attractions_resp.attractions}} 请将以上信息有机地整合成一段连贯的文字直接面向用户输出。如果城市无效你不会收到天气和景点信息。用户提示词可以简单写为“请生成旅行建议。”。输出变量名设为final_advice。设置结束节点成功流程将LLM节点的输出连线到“结束”节点。在结束节点的属性中将“输出内容”设置为{{final_advice.content}}。这样LLM生成的内容就会作为智能体的最终回复。处理无效城市“否”分支从条件节点的“否”分支连线到另一个“结束”节点。在这个结束节点的“输出内容”中直接引用本地Agent返回的错误信息{{local_agent_resp.body.message}}。至此一个完整的工作流就搭建完毕了。你的画布应该包含开始 - HTTP(本地Agent) - 条件判断 - (是分支) - HTTP(天气) 代码(景点) - LLM - 结束以及条件判断的(否分支) - 结束。4.4 步骤四调试与测试点击画布右上角的“调试”按钮。在调试面板的输入框中为city_name填写测试值如“巴黎”。点击“运行”。下方会显示执行过程你可以展开每个节点查看其输入和输出这对于排查问题极其有用。观察最终输出应该是一段整合了本地信息、天气和景点的旅行建议。再测试一个不在列表的城市如“东京”应该会直接返回本地Agent定义的错误消息。5. 实现三端打通与发布工作流调试通过后如何让用户用起来5.1 发布到Web与豆包App返回智能体编辑页的“发布”选项卡。在“发布渠道”中确保“豆包”和“Web”是开启状态。你可以自定义智能体的头像、欢迎语等。点击“发布”。发布后你可以Web端直接在Coze网站或你嵌入的Web页面中与智能体对话。豆包App在豆包App中搜索你智能体的名字即可直接使用。这是“三端打通”中最便捷的移动端体验。5.2 通过API调用实现系统集成这是将智能体能力嵌入到你自己的业务系统的关键。在智能体编辑页点击“API访问”选项卡。你会看到该智能体专属的API密钥API Key和接口地址Endpoint。请妥善保管API Key。调用示例使用Python的requests库import requests import json url “你的智能体API Endpoint” api_key “你的智能体API Key” headers { “Authorization”: f”Bearer {api_key}“, “Content-Type”: “application/json” } # 注意payload的结构需要匹配你工作流开始节点定义的输入参数 payload { “parameters”: { “city_name”: “纽约” # 参数名与工作流中定义的变量名一致 } } response requests.post(url, headersheaders, datajson.dumps(payload)) result response.json() print(result[“content”]) # 输出智能体的回复通过API任何能发送HTTP请求的系统你的网站、APP、内部OA等都可以调用这个智能工作流。6. 常见问题与排查思路在搭建和使用过程中你可能会遇到以下问题问题现象可能原因排查与解决思路工作流调试时HTTP节点报“连接超时”或“连接错误”。1. 本地Agent服务未启动。2. ngrok隧道未建立或地址错误。3. 本地防火墙/安全软件阻止了连接。1. 检查python local_agent.py是否在运行。2. 检查ngrok终端是否显示Online并确认复制的URL无误。3. 临时关闭防火墙或检查5000端口是否开放。调用本地Agent返回了结果但条件判断节点无法正确解析。HTTP节点的输出变量结构引用错误。body字段可能不存在或者JSON结构不符合预期。在调试面板中展开HTTP节点仔细查看其完整的输出对象结构。条件表达式应基于变量名.body.字段名的路径编写。LLM节点生成的回复未包含预期的天气或景点信息。系统提示词中引用变量的语法错误或变量名与上游节点输出名不匹配。1. 检查提示词中{{weather_resp.body.current}}等变量引用是否正确。2. 确认上游“天气HTTP节点”的输出变量名确实是weather_resp。通过API调用智能体返回错误或非预期回复。1. API Key或Endpoint错误。2. 请求Payload的格式不正确未按{“parameters”: {...}}包裹。3. 参数名与工作流开始节点定义的名称不匹配。1. 核对API访问页面的信息。2. 使用Postman等工具测试确保Payload格式完全符合文档。3. 检查工作流开始节点的输入参数定义。豆包App中找不到已发布的智能体。1. 发布后同步有延迟。2. 智能体设置了“私密”可见性。3. 登录的豆包账号与发布Coze智能体的账号不同。1. 等待几分钟后重试搜索。2. 在发布设置中将可见性改为“公开”或“通过链接访问”。3. 确保使用同一账号体系。7. 最佳实践与进阶建议掌握了基础搭建后遵循以下实践能让你的工作流智能体更健壮、更强大。7.1 工作流设计最佳实践模块化设计将一个复杂的长工作流拆分成多个子工作流。Coze支持工作流嵌套调用这有助于复用逻辑如“用户身份验证”和降低主流程复杂度。充分利用并行对于互不依赖的IO操作如调用多个外部API务必使用并行分支可以显著降低整体响应时间。详尽的错误处理不仅要在条件判断中处理业务逻辑错误如城市无效更要在HTTP节点、代码节点后添加“错误处理”分支。Coze节点支持配置“错误时转向”可以捕获网络超时、API限流、代码异常等并给出友好的用户提示而不是让整个流程崩溃。变量命名清晰使用weather_api_response,user_query_parsed这类有意义的变量名而不是resp1,data2便于后期维护和调试。7.2 本地Agent安全与性能身份验证上述示例的本地Agent是开放的存在安全风险。在生产环境中必须在HTTP请求头或参数中加入签名验证。Coze的HTTP节点支持添加自定义Header你可以在本地Agent端验证一个预共享的密钥或Token。超时与重试在Coze的HTTP节点配置中设置合理的“请求超时”时间。对于关键业务可以考虑在工作流层面实现重试逻辑。负载与监控本地Agent服务需考虑并发能力和资源监控。对于高并发场景需要使用生产级WSGI服务器如Gunicorn替代Flask开发服务器并部署在可靠的云主机或容器中。7.3 提示词工程在工作流中的运用在工作流中LLM提示词的角色发生了变化系统提示词侧重于定义角色和整合信息的规则。应清晰列出所有可用的输入变量{{variable}}并明确指示模型如何使用它们。少样本示例如果输出格式要求严格如JSON、特定报告模板可以在系统提示词中提供1-2个输入输出的示例Few-Shot引导模型遵循格式。上下文管理工作流本身已经通过节点处理了上下文因此通常不需要在提示词中要求模型“记住”之前的对话。焦点应放在当前节点的具体合成任务上。7.4 版本管理与迭代在Coze中修改智能体或工作流是实时生效的。对于重要的生产智能体建议重大修改前先复制在智能体设置中使用“复制”功能创建一个新版本进行测试。利用调试历史调试面板会记录每次运行的输入输出是排查线上问题和优化流程的宝贵资料。灰度发布对于通过API服务大量用户的智能体可以通过路由逻辑将部分流量导向新版本的工作流进行测试验证无误后再全量切换。从拖拽第一个节点开始到构建出能处理复杂业务、安全可靠、支持多端访问的智能体Coze工作流极大地降低了AI应用开发的门槛。它不仅仅是一个工具更是一种将大模型能力工程化、产品化的新范式。