企业官网建设流程全解析

1. 从单 Agent 到多 Agent 协作，HarnessAgent 项目初始化到底卡在哪

如果你正在用 Spring AI 搭企业级 HarnessAgent 项目，大概率会遇到这样一个尴尬局面：单 Agent 跑对话没问题，工具调用也能通，但一旦把多 Agent 协作、RAG 检索、工具生态三条线同时塞进一个工程，配置就开始散架。模型 Key 写在三个不同的 yaml 里，子 Agent 各自读一份环境变量，RAG 的向量检索和全文检索走两套凭证，工具调用超时了不知道是网络问题还是 Key 配额问题。项目还没跑起来，光是对齐配置就耗掉半天。

这篇要解决的就是这个初始化阶段的骨架问题。我会围绕 HarnessAgent 多 Agent 协作、RAG 设计、工具生态三条主线，给出 Spring AI 工程里接入 TaoToken 统一 Key/API 通道的settings.json与config.toml可复制配置骨架，然后演示一次多 Agent 调用链的验证动作。适合已经跑通过 Spring AI 基础对话、准备把项目往企业级方向推进的开发者。读完你能拿到一套可以直接落到工程里的配置模板，以及一条能验证多 Agent 协作是否真正跑通的请求链路。

TaoToken 在这里的角色是统一模型通道：多 Agent 场景下每个子 Agent 可能用不同模型，RAG 的查询改写和重排也可能调模型，工具生态里的 MCP 客户端同样需要模型能力。如果每个环节各自配一套 Key，运维和排障成本会成倍上升。把模型入口收敛到一个通道，是 HarnessAgent 项目从 demo 走向可维护的第一步。

2. TaoToken 前置准备：统一 Key 与 API 通道

在动手写配置之前，先把 TaoToken 的接入信息准备好。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数，配置里填这个就行。

你需要先在控制台创建一个 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建好之后把 Key 复制出来，后面配置里会用到。

这里有个容易踩的坑：HarnessAgent 项目里子 Agent 数量多，如果每个子 Agent 都硬编码一份 Key，轮换的时候要改十几处。正确做法是让所有子 Agent、RAG 管线、MCP 工具共用同一个 Key 来源，通过环境变量注入，配置文件里只引用变量名。这样 Key 轮换只需要改一处环境变量。

模型选择上，多 Agent 协作场景建议至少准备两个模型档位：一个推理能力强的用于 Supervisor 调度和复杂选型分析，一个响应快的用于资讯整理和格式转换。TaoToken 的模型对话入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，可以先在页面上确认你要用的模型标识符，配置里填对模型名很关键，填错了请求会直接报模型不存在。

如果你后续要做长期编码或 Agent 自动化任务，可以了解 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到参数不确定的时候翻文档比猜快。

3. 可复制配置骨架：settings.json 与 config.toml

HarnessAgent 项目里配置分两层：settings.json管模型通道和 Agent 声明，config.toml管工具生态和 RAG 管线参数。下面这套骨架可以直接复制改。

3.1 settings.json：模型通道与子 Agent 声明

{ "model": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "defaultModel": "gpt-4o-mini", "timeoutSeconds": 60, "maxRetries": 2 }, "agents": { "supervisor": { "model": "gpt-4o", "maxIters": 15, "workspaceMode": "SHARED" }, "subagents": [ { "name": "product-advisor", "description": "机器人产品选型顾问，根据预算、场景、品牌做推荐和对比", "model": "gpt-4o-mini", "maxIters": 10, "workspaceMode": "SHARED", "tools": ["searchRobots", "queryRobots", "getRobotDetail", "queryKnowledge"] }, { "name": "troubleshooter", "description": "故障排查助手，根据错误码和现象定位问题", "model": "gpt-4o-mini", "maxIters": 8, "workspaceMode": "SHARED", "tools": ["queryKnowledge", "searchErrorCodes"] }, { "name": "writer", "description": "把资料整理成结构化报告", "model": "gpt-4o-mini", "maxIters": 6, "workspaceMode": "SHARED", "tools": ["queryKnowledge"] } ] }, "rag": { "enabled": true, "topK": 5, "recallMultiplier": 2, "rewriteModel": "gpt-4o-mini", "rerankModel": "gpt-4o-mini", "conflictDetection": true, "contextCompression": true } }

几个关键点说明。baseUrl填https://taotoken.net/api，不要带尾部斜杠。apiKey用${TAOTOKEN_API_KEY}引用环境变量，不要写死。Supervisor 用强模型，子 Agent 用快模型，这是成本和效果的平衡点。每个子 Agent 的tools列表要按最小权限原则裁剪，产品顾问不需要文章发布能力，写作 Agent 不需要产品查询能力。

3.2 config.toml：工具生态与 RAG 管线

[tool.execution] timeout_seconds = 5 max_retries = 3 retry_interval_ms = 200 circuit_breaker_threshold = 5 circuit_breaker_recovery_seconds = 30 idempotency_cache_ttl_seconds = 300 [tool.mcp] enabled = true server_name = "lingnova-tools" expose_tools = ["searchRobots", "queryRobots", "queryKnowledge"] [rag.pipeline] query_rewrite = true hybrid_retrieval = true vector_store = "pgvector" fulltext_store = "postgresql" rrf_rank_constant = 60 chunk_size = 512 chunk_overlap = 64 [rag.indexing] knowledge_dir = "workspace/knowledge" incremental = true content_hash_check = true [subagent.loop_guard] enabled = true fingerprint_algorithm = "sha256" max_consecutive_duplicates = 2

tool.execution这一段把超时、重试、熔断、缓存收敛到统一包装器，业务工具只关心查什么。rag.pipeline里rrf_rank_constant用 60 是常见默认值，chunk_overlap保留 64 个字符是为了避免故障原因和解决步骤被切在两个分片边界。subagent.loop_guard是防止多 Agent 互相绕圈的关键，连续两次相同指纹就终止委派。

3.3 环境变量注入

export TAOTOKEN_API_KEY="你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

Spring AI 工程里通过application.yml读取：

spring: ai: openai: base-url: ${TAOTOKEN_BASE_URL} api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.3

这样配置的好处是：多 Agent、RAG、工具生态三条线共用同一个模型通道，Key 轮换只改环境变量，排障时看 requestId 就能串起整条链路。

4. 验证请求：跑通一次多 Agent 调用链

配置写好了，接下来验证多 Agent 协作是否真正跑通。验证目标是：用户提一个需要选型加写作的复合任务，Supervisor 判断委派给 product-advisor，拿到结果后再委派给 writer，最终返回结构化报告。

4.1 启动与健康检查

先确认 Spring AI 工程能连上 TaoToken 通道：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'

返回里有choices字段就说明通道通了。如果返回 401，检查 Key 是否复制完整；返回 404，检查 baseUrl 是否多了斜杠。

4.2 发起多 Agent 调用

HarnessAgent 的入口是/api/agent/v1/sessions/*，不是轻量对话的/api/ai/chat/*。发起一个会话：

curl -X POST http://localhost:8080/api/agent/v1/sessions \ -H "Content-Type: application/json" \ -d '{ "sessionId": "test-multi-agent-001", "message": "按50万预算调研几款焊接机器人，比较参数，写一份选型报告" }'

4.3 观察调用链

预期日志里能看到这样的委派顺序：

[supervisor] received task, analyzing delegation [supervisor] delegate to product-advisor, reason: 需要产品选型和对比 [product-advisor] tool call: searchRobots, args: {budget: 500000, category: welding} [product-advisor] tool call: queryKnowledge, args: {query: 焊接机器人参数对比} [product-advisor] completed, result fingerprint: a3f8... [supervisor] delegate to writer, reason: 需要整理成报告 [writer] completed, result fingerprint: b7c2... [supervisor] final response assembled

如果看到HUMAN_INTERVENTION_REQUIRED: repeated subagent result，说明 loop guard 触发了，同一个子 Agent 连续返回了相同结果，这时候要检查子 Agent 的工具是否返回了空数据。

4.4 验证 RAG 检索

单独验证 RAG 管线：

curl -X POST http://localhost:8080/api/agent/v1/rag/retrieve \ -H "Content-Type: application/json" \ -d '{ "query": "E-203错误码怎么处理", "topK": 5, "docType": "manual" }'

返回里应该包含rewrittenQuery、documents、hasConflict字段。如果documents为空，检查workspace/knowledge目录下有没有文档，以及索引是否跑过。

5. 本篇常见错排查

5.1 模型返回 401 或 403

最常见的原因是 Key 没注入成功。检查echo $TAOTOKEN_API_KEY是否有值，Spring 配置里是否用了${TAOTOKEN_API_KEY}而不是写死的字符串。另一个原因是 Key 被禁用或配额耗尽，去控制台确认一下。

5.2 子 Agent 不委派，Supervisor 自己回答

检查子 Agent 的description是否写清楚了擅长什么。Supervisor 是根据描述判断委派的，描述太模糊它就不委派。另外检查maxIters是否设得太小，Supervisor 还没走完判断流程就被截断了。

5.3 RAG 检索结果为空

三个排查方向：知识库目录是否配置正确，索引是否执行过，topK是否设得太小。如果文档是 PDF 但解析出来是乱码，检查 PDF 是否加密或扫描件，扫描件需要 OCR 预处理。

5.4 工具调用超时

先看tool.execution.timeout_seconds是否设得太短，默认 5 秒对大多数只读查询够用，但如果工具内部有复杂计算可以调到 10 秒。如果频繁超时，检查工具实现里是否有阻塞操作，比如同步 HTTP 调用没设超时。

5.5 多 Agent 互相绕圈

这是 loop guard 要解决的问题。如果日志里看到同一个子 Agent 被反复委派，检查max_consecutive_duplicates是否生效，以及子 Agent 的输出是否真的在变化。有时候是工具返回了缓存数据导致指纹相同，这时候要检查幂等缓存的 TTL 设置。

5.6 配置改了不生效

Spring AI 工程里settings.json和config.toml的加载顺序要注意。如果两个文件里有同名配置，后加载的会覆盖先加载的。建议把模型通道配置放settings.json，工具和 RAG 参数放config.toml，避免冲突。

6. 下一步：把骨架跑成可维护的工程

配置骨架跑通只是第一步。接下来要做的三件事：把子 Agent 的工具权限再收紧一轮，确保每个 Agent 只能访问它真正需要的工具；把 RAG 评估集建起来，用 Recall@5 和 MRR 量化检索质量；把工具执行的可靠性逻辑从进程内缓存迁到 Redis，为多实例部署做准备。

如果你在接入过程中遇到模型通道或 Key 管理的问题，可以先去接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 查参数说明，或者在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 直接试一下模型是否可用。长期做 Agent 编码任务的，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 可以了解一下配额策略。Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，建议给不同环境建不同的 Key，方便排障时定位是哪个环境出的问题。

这套骨架的价值不在于配置本身，而在于它把多 Agent 协作、RAG、工具生态三条线的模型入口收敛到了一处。后面无论加多少个子 Agent、换多少个向量库、接多少个 MCP 工具，模型通道这一层都不用再动。