企业官网建设流程全解析

1. joyagent 多智能体框架本地落地：从 BaseTool 到 MCP 的完整接入路径

joyagent（JoyAgent-JDGenie）是一个通用多智能体框架，核心思路是把子智能体和工具挂载到主 Genie 上，让用户按场景自由拼装能力。它适合谁？适合想本地跑通多智能体任务、又需要二次开发自定义工具的后端和算法同学。我这次上手的目标很明确：用 TaoToken 统一 Key 和 API 通道，把 joyagent 的 BaseTool 自定义工具和 MCP 服务配置一次性打通，跑通第一个多智能体任务。

整个落地链路分四块：前端 ui、工具服务 genie-tool、后端 genie-backend、MCP 客户端 genie-client。最容易卡住的不是安装，而是配置分散——搜索工具的 Key、模型调用的 Key、MCP 的 SSE 地址散落在.env、application.yml、settings.json里。如果每个服务各配一套 Key，维护成本高还容易串。所以这篇的重点是：用 TaoToken 作为统一 API 通道，把模型调用收敛到一个 Key，再分别对接 BaseTool 和 MCP。

下面按「先统一 Key，再配工具，再配 MCP，最后验证」的顺序走，每一步都给可复制的配置和命令。

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

在动 joyagent 之前，先把模型调用的通道准备好。TaoToken 在这里扮演的角色是统一入口：你只需要一个 Key，就能通过兼容接口调用多种模型，省去在 joyagent 各个配置文件里塞不同厂商 Key 的麻烦。

第一步，注册并拿到 Key。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，在「API Keys」页面创建一个新 Key，复制保存。API Keys 直达页：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

第二步，确认 API 基地址。TaoToken 的 API 入口是 https://taotoken.net/api ，注意这个地址不带任何查询参数，配置时直接填这个即可。joyagent 里凡是需要填base_url或api_base的地方，都指向它。

第三步，先做一次最小连通性验证，别等 joyagent 全配完才发现 Key 有问题。用 curl 直接打一次对话接口：

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

返回里出现choices字段和内容，说明 Key 和通道都正常。这一步过了，后面 joyagent 的模型调用才有基础。如果你还想先在网页上试试模型效果，可以直接用模型对话页：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

注意：Key 只创建时完整显示一次，务必先存到本地环境变量或密码管理器，别直接硬编码进要提交的配置文件。

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

joyagent 的配置分散在几个文件里，这里给出统一用 TaoToken 的骨架。先约定：把 Key 放进环境变量TAOTOKEN_API_KEY，配置文件里用占位引用，避免明文泄露。

3.1 genie-tool 的 .env 配置

进入genie-tool目录，把.env_template复制为.env。搜索工具这里用 langsearch 的 Key（官方示例里 SERPER 收费，改用 langsearch 更省事），同时把模型通道指向 TaoToken：

# genie-tool/.env SERPER_SEARCH_API_KEY=你的LANGSEARCH_KEY OPENAI_API_KEY=${TAOTOKEN_API_KEY} OPENAI_BASE_URL=https://taotoken.net/api

首次启动工具服务前，需要初始化数据库，只需执行一次：

cd genie-tool python -m genie_tool.db.db_engine

之后每次启动用：

uv run python server.py

3.2 搜索组件适配 langsearch 数据结构

官方示例里search_engine.py的SerperSearch类是按 SERPER 的返回结构解析的，换成 langsearch 后要改解析逻辑。核心是search方法里对返回 JSON 的取值路径：

async def search(self, query: str, request_id: str = None, *args, **kwargs) -> List[Doc]: body = self.construct_body(query, request_id) async with aiohttp.ClientSession() as session: async with session.post(self._url, json=body, headers=self.headers, timeout=self._timeout) as response: result = json.loads(await response.text()) return [ Doc( doc_type="web_page", content=item.get("snippet", ""), title=item.get("name", ""), link=item.get("url", ""), data={"search_engine": self._engine}, ) for item in result.get("data", {}).get("webPages", {}).get("value", []) ]

关键差异在最后的取值路径result["data"]["webPages"]["value"]，这是 langsearch 的结构。如果你换别的搜索源，先打印一次result看真实结构，再改这段列表推导。

3.3 自定义 BaseTool 工具

joyagent 的自定义工具要实现BaseTool接口，声明名称、描述、参数和调用方法。接口定义在com.jd.genie.controller.tool.common下：

public interface BaseTool { String getName(); // 工具名称 String getDescription(); // 工具描述 Map<String, Object> toParams(); // 工具参数 Object execute(Object input); // 调用工具 }

写一个天气工具示例：

public class WeatherTool implements BaseTool { @Override public String getName() { return "agent_weather"; } @Override public String getDescription() { return "这是一个可以查询天气的智能体"; } @Override public Map<String, Object> toParams() { return "{\"type\":\"object\",\"properties\":{\"location\":{\"description\":\"地点\",\"type\":\"string\"}},\"required\":[\"location\"]}"; } @Override public Object execute(Object input) { return "今日天气晴朗"; } }

然后在com.jd.genie.controller.GenieController#buildToolCollection里注册：

WeatherTool weatherTool = new WeatherTool(); toolCollection.addTool(weatherTool);

toParams()返回的是 JSON Schema 字符串，描述工具入参，模型据此决定怎么调用。描述写得越清楚，模型选工具的准确率越高。

3.4 genie-backend 的 application.yml

后端配置在genie-backend/src/main/resources/application.yml。模型通道同样指向 TaoToken，MCP 服务地址也在这里加：

# genie-backend/src/main/resources/application.yml model: api_key: ${TAOTOKEN_API_KEY} base_url: https://taotoken.net/api mcp_server_url: "http://127.0.0.1:8001/sse,http://127.0.0.1:8002/sse"

多个 MCP server 用逗号分隔。改完配置后重新构建并启动：

cd genie-backend sh build.sh sh start.sh tail -f genie-backend_startup.log

用tail -f盯日志，是排查后端启动问题最直接的方式。

3.5 MCP 客户端 settings.json 骨架

MCP 客户端在genie-client目录，配置走settings.json。一个最小骨架如下：

{ "mcpServers": { "local-tools": { "url": "http://127.0.0.1:8001/sse", "transport": "sse" }, "remote-tools": { "url": "http://127.0.0.1:8002/sse", "transport": "sse" } } }

启动客户端：

cd genie-client sh start.sh

如果所有配置都正常，回到主目录执行总启动脚本：

sh start_genie.sh

4. 验证请求与成功结果

配置完别急着跑复杂任务，先做分层验证，一层层确认。

第一层，工具服务是否起来。访问genie-tool的端口，或者直接看uv run python server.py的启动日志，出现监听地址即正常。

第二层，后端是否连上模型。看genie-backend_startup.log，搜索有没有模型调用相关的报错。如果日志里出现 401，基本是 Key 或 base_url 问题；出现 404，多半是路径拼错。

第三层，MCP 客户端是否连上 server。genie-client启动后，日志里会打印每个 server 的连接状态，connected才算通。

第四层，端到端跑一个最小任务。在前端界面输入一个简单请求，比如「查询北京天气」，观察是否触发agent_weather工具。成功时你会看到工具被调用、返回「今日天气晴朗」，并在对话里给出结果。

用 curl 再验证一次模型通道，确认 joyagent 用的就是同一个 Key：

curl 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":"你好"}]}'

返回正常内容，说明从 Key 到模型这条链路是通的，joyagent 里如果报错，问题就在 joyagent 自身的配置，而不是通道。

5. 本篇常见错排查

报错一：401 Unauthorized。出现在后端日志或 curl 里。检查三处：环境变量TAOTOKEN_API_KEY是否真的导出到当前 shell；application.yml里是否用了${TAOTOKEN_API_KEY}而不是写死的旧 Key；base_url 是否误写成带/v1的地址。TaoToken 的基地址是https://taotoken.net/api，路径拼接由 SDK 处理。

报错二：MCP 连接超时。genie-client日志里显示某个 servertimeout。先确认对应 server 的端口在监听，再确认mcp_server_url里的 IP 和端口和实际一致。本地调试统一用127.0.0.1，别混用localhost和容器内网 IP。

报错三：自定义工具不被调用。模型始终不选agent_weather。多半是getDescription()写得太模糊，或者toParams()的 JSON Schema 不合法。把描述改成明确的动作句，Schema 用在线工具校验一遍。

报错四：搜索工具返回空。search方法返回空列表。先print(result)看 langsearch 的真实返回结构，确认取值路径data.webPages.value是否匹配。不同搜索源结构差异大，别照抄路径。

报错五：后端改了配置不生效。只改了application.yml没重新 build。joyagent 后端每次改配置都要sh build.sh再sh start.sh，直接重启不重新构建可能读到旧产物。

报错六：数据库未初始化。genie-tool启动报数据库相关错误。首次必须执行python -m genie_tool.db.db_engine，之后才不用重复执行。

排查顺序建议固定：先 curl 验通道，再看各服务启动日志，最后看端到端任务。这样能把问题范围快速缩小到某一层。

6. 长期编码与 Agent 场景的通道选择

如果你只是偶尔跑跑 joyagent 验证想法，按上面的配置用按量 Key 就够了。但如果你打算长期做多智能体开发、频繁跑 Agent 任务、或者把 joyagent 接进日常编码流程，建议了解一下 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。它更适合高频、长期的编码和 Agent 调用场景，能省去反复管理额度的麻烦。

接入文档在这里，遇到接口细节问题可以对照查：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果你用的是 Claude Code 这类工具，Anthropic 兼容接入的说明在：https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

回到 joyagent 本身，跑通第一个任务后，最值得花时间的是把自定义 BaseTool 的描述和参数打磨好——多智能体框架的上限，往往取决于工具描述的质量，而不是模型本身。