1. 电商购物助手为什么总在“能跑”和“能用”之间卡住AI Agent 在电商场景里最容易出现一种尴尬Demo 阶段看起来什么都能聊一上真实流量就开始胡言乱语、乱推商品、超预算、答非所问。核心检索词先摆清楚——AI Agent Harness Engineering 是一套把“业务控制权”从大模型手里拿回来的工程方法它能让电商购物助手从“会聊天”变成“能按规则办事”适合谁适合已经用 LangChain、Claude、OpenAI 或本地模型跑过购物助手原型但被成本、稳定性、可观测性折磨过的开发者。我见过太多购物助手项目死在同一个地方所有业务逻辑都塞进 Prompt。用户问“200 以内、杭州发货、明天到北京的红色 L 码牛仔裤”模型要么漏掉“杭州发货”要么把 260 元的商品也推出来要么在没库存时直接沉默。问题不在模型不够聪明而在于我们把“缰绳”也交给了模型。Harness Engineering 的思路是模型只负责理解非结构化语言和生成自然语言库存、价格、时效、优惠、权限这些硬规则全部由代码和工具控制。这篇内容聚焦电商购物助手场景给你一套可复制的配置骨架settings.json和config.toml两个文件怎么组织如何通过 TaoToken 统一 Key 和 API 通道接入不同 AI 工具最后附上本地验证动作确认购物助手能正常调用与响应。你可以把它当成一个“最小可运行骨架”先跑通再往里面填业务。2. 前置准备用 TaoToken 统一 Key 与 API 通道在搭骨架之前先把“通道”理顺。购物助手通常要调用多个模型一个便宜的小模型做意图识别一个强一点的模型做推荐文案生成可能还要一个模型做售后分类。如果每个模型都单独配 Key、单独改 base_url配置会迅速失控。TaoToken 在这里的角色是统一入口你可以在一个地方管理 Key通过统一的 API 通道接入不同 AI 工具减少在多个配置文件里反复粘贴密钥的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。操作上分三步。第一步进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后先复制保存页面刷新后通常不再完整显示。第二步如果你要长期跑编码类或 Agent 类任务可以看 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续调用的场景。第三步接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面会说明 base_url 和鉴权头的写法。注意Key 只放在本地.env或系统环境变量里不要提交到 Git。骨架文件里用占位符真实值走环境变量注入。如果你用的是 Claude Code 这类工具Anthropic 兼容接入可以参考 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。模型对话调试可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先确认通道通不通再写进购物助手配置。3. 可复制配置settings.json 与 config.toml 骨架下面给出一套双文件骨架。settings.json管“运行时敏感配置和模型通道”config.toml管“业务规则和工具开关”。这样拆分的好处是换 Key 不动业务改业务不动密钥。3.1 settings.json 骨架{ app: { name: ecom-shopping-agent, env: dev, host: 0.0.0.0, port: 8000, log_level: INFO }, llm_gateway: { provider: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, timeout_seconds: 30, max_retries: 2 }, models: { intent: { name: claude-3-haiku, temperature: 0.1, max_tokens: 256 }, recommend: { name: claude-3-haiku, temperature: 0.4, max_tokens: 1024 }, fallback: { name: qwen2:7b-instruct-q4_K_M, base_url: http://localhost:11434/v1, temperature: 0.3, max_tokens: 512 } }, storage: { redis_url: redis://localhost:6379/0, mysql_dsn: mysqlpymysql://user:passlocalhost:3306/shop, vector_dir: ./data/chroma } }这里的关键点是llm_gateway.base_url指向 TaoToken 的 API 入口api_key_env只写环境变量名不写真实 Key。models里区分了 intent、recommend、fallback 三个角色购物助手按任务挑模型而不是所有请求都打同一个大模型。3.2 config.toml 骨架[agent] name 电商购物助手 persona 友好、专业、像导购一样给建议但不夸大 max_turns 8 [scene] # 场景识别标签命中后走对应流程 labels [售前推荐, 库存查询, 运费时效, 优惠码, 售后处理, 物流查询] [guardrails] budget_strict true # 超预算商品默认不推荐 stock_required true # 无库存不推荐 shipping_required true # 时效不满足不推荐 forbidden_claims [绝对正品, 百分百不褪色, 全网最低] [tools] enable_stock_query true enable_shipping_query true enable_coupon_query true enable_vector_search false # 默认关闭结构化查询优先 [tools.stock_query] type mysql table sku fields [sku_id, title, price, size, color, stock, ship_from] [tools.shipping_query] type http provider sf timeout_seconds 5 [fallback] on_llm_timeout template_reply on_stock_empty recommend_similar on_shipping_fail estimate_by_regionguardrails是缰绳的核心预算、库存、时效三条硬规则由代码执行模型无权绕过。tools.enable_vector_search默认关闭是因为在购物助手里绝大多数查询都能用结构化 SQL 完成向量检索只在“商品描述模糊匹配”时才开能显著降成本。3.3 加载配置的 Python 片段import json, os, tomllib from pathlib import Path def load_settings(pathsettings.json): data json.loads(Path(path).read_text(encodingutf-8)) key_env data[llm_gateway][api_key_env] data[llm_gateway][api_key] os.environ.get(key_env, ) if not data[llm_gateway][api_key]: raise RuntimeError(f缺少环境变量 {key_env}) return data def load_config(pathconfig.toml): with open(path, rb) as f: return tomllib.load(f) settings load_settings() config load_config() print(gateway:, settings[llm_gateway][base_url]) print(guardrails:, config[guardrails])运行前先导出 Keyexport TAOTOKEN_API_KEY你的Key python load_config_demo.py预期输出里能看到gateway: https://taotoken.net/api和 guardrails 字典说明配置骨架加载正常。4. 验证请求确认购物助手能调用与响应配置写完不算完必须做一次端到端验证。分两层先验证模型通道再验证购物助手业务链路。4.1 验证模型通道import os, requests base https://taotoken.net/api key os.environ[TAOTOKEN_API_KEY] resp requests.post( f{base}/v1/chat/completions, headers{ Authorization: fBearer {key}, Content-Type: application/json, }, json{ model: claude-3-haiku, messages: [ {role: user, content: 只回复两个字通了} ], max_tokens: 16, }, timeout30, ) print(resp.status_code) print(resp.json()[choices][0][message][content])如果返回 200 且内容包含“通了”说明 Key 和通道没问题。若返回 401检查 Key 是否复制完整若返回 404检查 base_url 是否写成了带路径的错误形式。4.2 验证购物助手业务链路用一个最小函数模拟“用户问预算内商品”的流程重点看 guardrails 是否生效。def query_skus(conn, budget, size, color, ship_from): sql SELECT sku_id, title, price, stock, ship_from FROM sku WHERE price %s AND size %s AND color %s AND ship_from %s AND stock 0 ORDER BY price ASC with conn.cursor() as cur: cur.execute(sql, (budget, size, color, ship_from)) return cur.fetchall() def build_reply(rows, budget): if not rows: return 这个条件下暂时没有现货我帮你看看相近的款式 lines [f- {r[1]}{r[2]}元库存{r[3]}发货地{r[4]} for r in rows] return 按你的预算和条件找到这些\n \n.join(lines)把query_skus的结果交给模型生成自然语言时模型只做“润色”不做“筛选”。这样即使模型偶尔跑偏也不会推出超预算或无库存的商品。实测下来这种“代码筛选 模型表达”的组合比纯 Prompt 控制的准确率高出一大截。4.3 验证响应结构{ scene: 售前推荐, guardrails_passed: true, items: [ {sku_id: 10003, price: 179, stock: 2, ship_from: 杭州} ], reply: 按你的预算和条件找到这些... }返回结构里保留scene和guardrails_passed方便后续做日志和 A/B 测试。如果guardrails_passed为 false前端就不展示推荐直接走兜底话术。5. 本篇常见错排查5.1 401 或鉴权失败最常见原因是环境变量没导出或者 Key 里混入了空格。先在终端echo $TAOTOKEN_API_KEY | wc -c看长度是否正常。另一个坑是把 Key 写进了settings.json又提交了仓库建议立刻在控制台轮换 Key地址 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。5.2 模型返回空内容或截断检查max_tokens是否太小。意图识别给 256 够用推荐文案建议 1024。如果用了 fallback 本地模型确认 Ollama 服务在跑curl http://localhost:11434/v1/models能列出模型。5.3 购物助手推荐了超预算商品九成是 guardrails 没接进主流程。检查config.toml里budget_strict true是否被读取以及 SQL 里是否真的带了price %s。不要依赖模型“自觉”遵守预算必须代码过滤。5.4 运费时效查询超时外部 API 超时要有降级。config.toml里on_shipping_fail estimate_by_region就是干这个的查不到实时时效时用“江浙沪到北京默认次日达”这类预置规则兜底而不是直接报错。5.5 场景识别总串场售后问题被识别成售前推荐通常是场景标签太少或意图模型太弱。先把config.toml的scene.labels补全再用几条真实用户问法做回归测试。如果还是不稳把意图识别换成更强的模型但只在这一步用强模型控制成本。6. 继续往下走把骨架变成你的购物助手到这里你已经有了一个能跑通的骨架settings.json管通道config.toml管规则TaoToken 统一 Key 和 API 入口本地验证覆盖了模型通道和业务链路。接下来可以做的扩展包括接入真实商品库、增加优惠码计算、把日志打到 Elasticsearch、用 Prometheus 统计工具调用成功率。如果你在接入过程中遇到鉴权或通道问题优先看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 想先验证模型是否可用去模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 试一条如果是长期跑编码或 Agent 任务Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 有更合适的方案。骨架已经给你了剩下的就是往里面填你自己的业务规则。