1. 多语言 Agent 协作的真实痛点为什么单语言 Harness 一扩语种就崩AI Agent Harness Engineering 这两年从“能跑通一个 Agent”进化到“让一群 Agent 协作干活”但真正落地到多语言场景时问题会集中爆发。我见过太多团队一开始用英文 Prompt 写得好好的业务方说“加个日语客服”“让法国设计 Agent 和中文代码 Agent 对接”结果整个链路直接瘫掉。核心矛盾在于Agent 的 System Prompt、工具描述、Few-Shot 示例、协作消息全都是硬编码在单一语言里的。你换语言不是改一个配置项而是要改几十上百条 Prompt还要保证翻译后语义不漂移。更麻烦的是跨 Agent 协作——设计 Agent 输出日语需求稿代码 Agent 只认中文 Prompt中间产物传过去就变成“翻译碎片”协作效率归零。这篇要解决的就是这件事从一份config.toml骨架出发把翻译能力集成进 Harness让 Agent 之间能跨语言协作。目标很具体——你启动 Agent 后触发一条中英日任务链能看到翻译路由日志和协作日志一次跑通多语言 Agent 协作流程。适合谁看已经用 LangGraph、CrewAI 之类框架搭过单语言 Agent现在要扩多语言的工程师或者正在设计 Agent 平台、需要把“语言”抽象成配置项的架构同学。前置知识只需要 Python 基础、了解 Agent 的基本概念System Prompt、工具调用、消息传递不需要你精通翻译模型。下面所有配置和代码都可以直接复制我会给出完整的config.toml、settings.json片段以及验证动作。翻译能力这块我用 TaoToken 的模型对话接口来做翻译路由的实测因为它同时支持多模型切换方便对比不同翻译引擎的效果。2. TaoToken 前置把翻译能力做成可插拔的 Harness 组件在动手写配置之前先把“翻译能力”在架构里的位置定清楚。很多人的第一反应是“调个翻译 API 不就行了”但 Harness Engineering 的关键在于翻译不是一次性的函数调用而是一个可路由、可降级、可观测的组件。我把它拆成三层第一层是翻译引擎适配器。每个翻译后端通用翻译 API、专业领域模型、内部私有引擎都包一个统一接口输入是(text, source_lang, target_lang, domain)输出是翻译结果加元信息引擎名、耗时、是否命中缓存。第二层是翻译路由器。它根据source_lang → target_lang、任务领域、成本预算、响应速度从注册表里选一个最优引擎。比如中英日这种主流语言对走通用引擎就够如果是医疗术语的日英翻译路由到专业模型。第三层是语种感知的消息总线。Agent 之间传消息时总线先检测消息原始语言再查接收方的input_preference_language不一致就触发翻译路由翻译后再投递。结构化消息JSON、代码块只翻译值不翻译键和代码。TaoToken 在这里的角色是翻译引擎的模型来源之一。它的模型对话接口可以挂多个模型你可以把通用翻译、术语润色、语种检测分别路由到不同模型上。接入文档在https://taotoken.net/apiAPI Key 在控制台的api-keys页面生成。我实测下来用它的模型对话接口做中英日互译配合术语表专业词命中率比裸调通用翻译高不少。注意翻译路由的配置项要写进config.toml不要硬编码在代码里。这样换引擎、调优先级都不用改代码符合 Harness Engineering 的“配置驱动”原则。3. 可复制配置config.toml 骨架与 settings.json 片段先给完整的config.toml骨架。这份配置覆盖了 Agent 定义、翻译引擎注册、路由规则、消息总线四块。你可以直接存成config.toml放到项目根目录。# config.toml - 多语言 Agent Harness 配置骨架 [harness] name multilingual-agent-harness default_source_lang zh default_target_lang en log_level debug translation_cache_ttl 3600 # 翻译缓存秒数 # ---------- Agent 定义 ---------- [[agents]] id designer role UI Designer output_preference_language ja # 设计 Agent 输出日语 input_preference_language ja domain design system_prompt_prototype prompts/designer_en.txt # 英文原型运行时本地化 [[agents]] id developer role Frontend Developer output_preference_language zh # 代码 Agent 输出中文 input_preference_language zh domain it system_prompt_prototype prompts/developer_en.txt [[agents]] id tester role QA Tester output_preference_language en input_preference_language en domain it system_prompt_prototype prompts/tester_en.txt # ---------- 翻译引擎注册表 ---------- [[translation_engines]] name taotoken-general type llm_chat endpoint https://taotoken.net/api model gpt-4o-mini supported_pairs [[zh,en],[zh,ja],[en,ja],[ja,en],[en,zh],[ja,zh]] domain general cost_per_million_chars 0.5 avg_response_ms 800 priority 10 [[translation_engines]] name taotoken-domain-it type llm_chat endpoint https://taotoken.net/api model claude-3-5-sonnet supported_pairs [[zh,en],[en,zh],[ja,en],[en,ja]] domain it cost_per_million_chars 3.0 avg_response_ms 1500 priority 20 # 领域匹配时优先 # ---------- 翻译路由规则 ---------- [translation_routing] # 优先级从高到低领域匹配 语言对直译 priority 响应速度 成本 rules [ { domain it, prefer taotoken-domain-it }, { domain general, prefer taotoken-general } ] fallback_engine taotoken-general enable_cache true # ---------- 消息总线 ---------- [message_bus] type in_memory # 生产可换 redis detect_language true preserve_structured true # JSON/代码块只翻译值 log_translation_route true对应的settings.json片段主要给前端或运行时读取控制语种检测和日志开关{ harness: { language_detection: { engine: fasttext, model_path: models/lid.176.bin, min_confidence: 0.7 }, translation: { route_log: true, cache_backend: memory, structured_keys_whitelist: [task_id, component, type] }, collaboration: { max_chain_depth: 5, log_message_payload: true } } }关键配置项说明用表格对照一下配置项作用建议值output_preference_languageAgent 输出语言按业务方要求ISO 639-1input_preference_languageAgent 期望接收语言通常与输出一致domain领域标签影响翻译路由it/design/medical 等supported_pairs引擎支持的语言对只写实际用到的减少路由开销priority引擎优先级领域专用引擎给高值preserve_structured结构化消息保护必须 true否则代码会被翻坏提示system_prompt_prototype指向英文原型文件运行时由 Prompt L10N 引擎按 Agent 的output_preference_language本地化。这样你只维护一份英文原型加语种不用改 Prompt。4. 验证请求触发中英日任务链并检查翻译路由与协作日志配置写好后写一个最小可跑的验证脚本。它做三件事加载配置、注册 Agent、触发一条“设计→开发→测试”的中英日任务链然后打印翻译路由日志和协作日志。# verify_multilingual_chain.py import toml, json, time from harness.core import AgentHarness from harness.translation import TranslationRouter from harness.bus import LanguageAwareBus def load_config(pathconfig.toml): with open(path, r, encodingutf-8) as f: return toml.load(f) def main(): cfg load_config() router TranslationRouter(cfg[translation_engines], cfg[translation_routing]) bus LanguageAwareBus(cfg[message_bus], router) harness AgentHarness(cfg, bus) harness.register_agents_from_config() # 触发任务链设计(日) - 开发(中) - 测试(英) task { task_id: demo-001, task_name: E-commerce Homepage Development, requirements: [ {component: Header, description: Display logo, nav menu, search bar.}, {component: Hero, description: Show promotion banner and Shop Now button.} ] } print( 触发中英日任务链 ) result harness.run_chain( start_agentdesigner, chain[designer, developer, tester], payloadtask ) print(\n 翻译路由日志 ) for entry in bus.route_logs: print(json.dumps(entry, ensure_asciiFalse, indent2)) print(\n 协作日志 ) for msg in bus.collaboration_logs: print(f[{msg[source_agent_id]} - {msg[target_agent_id]}] f{msg[source_language]}-{msg[target_language]} fengine{msg.get(engine)} cached{msg.get(cached)}) print(\n 最终结果 ) print(json.dumps(result, ensure_asciiFalse, indent2)) if __name__ __main__: main()跑起来后你应该看到类似这样的输出我实测的日志结构 触发中英日任务链 [designer] output_langja, localizing prompt from en prototype... [bus] designer - developer: detect sourceja, targetzh, routetaotoken-general [bus] developer - tester: detect sourcezh, targeten, routetaotoken-domain-it 翻译路由日志 { from: ja, to: zh, domain: it, selected_engine: taotoken-general, reason: language_pair_direct, latency_ms: 812, cached: false } { from: zh, to: en, domain: it, selected_engine: taotoken-domain-it, reason: domain_match, latency_ms: 1480, cached: false } 协作日志 [designer - developer] ja-zh enginetaotoken-general cachedFalse [developer - tester] zh-en enginetaotoken-domain-it cachedFalse验证成功的标志有三个一是route_logs里能看到selected_engine和reason说明路由生效二是collaboration_logs里每条消息都标了source_language - target_language说明语种感知总线在工作三是最终结果里结构化字段task_id、component没被翻译只有description的值被翻译成了目标语言。如果你想单独验证翻译质量可以用模型对话接口直接测一条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: system, content: You are a professional IT translator. Translate the user text to Japanese, keep technical terms in English.}, {role: user, content: Display the company logo, navigation menu, search bar, and shopping cart icon.} ] }返回的日语翻译里logo、navigation menu这类术语应该保留英文或标准日文技术译法而不是被生硬意译。这一步能帮你确认翻译引擎的术语处理能力再决定要不要在路由里加术语表。5. 本篇常见错排查翻译路由不生效、结构化消息被翻坏、协作日志缺失跑多语言 Agent 协作最容易踩的坑集中在三个地方。我把排查路径整理成对照表你按现象定位。现象可能原因排查动作翻译路由日志为空log_translation_route没开或总线没接路由器检查config.toml的[message_bus]段确认log_translation_route true路由总是走 fallbacksupported_pairs没写全或语言对不匹配打印路由器的注册表确认source-target在某个引擎的supported_pairs里结构化消息被翻坏preserve_structured false或白名单没配检查settings.json的structured_keys_whitelist把 JSON 键加进去协作日志缺消息max_chain_depth太小链路被截断调大max_chain_depth或检查 Agent 的input_preference_language是否配错翻译缓存不命中translation_cache_ttl为 0或缓存后端没初始化确认enable_cache true且 TTL 大于 0语种检测误判min_confidence太低短文本被误判调高min_confidence到 0.8或对短消息跳过检测几个我实际踩过的坑展开说坑一语言对写成了[zh,en]但实际是zh-ja。路由器的匹配是精确匹配语言对zh-ja和zh-en是两条不同的规则。如果你只注册了zh-en那zh-ja就会走 fallback。解决办法是把所有实际用到的语言对都列进supported_pairs或者让路由器支持“经英语中转”的二级路由。坑二结构化消息的键被翻译了。比如task_id被翻成任务ID下游 Agent 按task_id取值就取不到。这是preserve_structured没生效或者白名单没覆盖。我的做法是默认所有 JSON 键都不翻译只翻译值如果某个值本身是枚举比如type: header也加进白名单不翻译。坑三协作日志里语言对是反的。这通常是source_language检测错了或者 Agent 的input_preference_language配成了输出语言。检查每个 Agent 的input_preference_language是否等于它期望接收的语言而不是它自己输出的语言。坑四翻译路由选了领域引擎但翻译质量反而差。领域引擎的priority高但如果它的supported_pairs不包含当前语言对路由器会跳过它。确认领域引擎的语言对覆盖范围别只写zh-en却期望它处理ja-en。注意排查时先把log_level调到debug路由器的每一步决策都会打日志。定位到具体环节后再调回info避免日志刷屏。6. 语义一致 CTA把翻译路由接进你的 Harness到这里多语言 Agent 协作的最小闭环已经跑通了config.toml定义 Agent 和翻译引擎settings.json控制语种检测和结构化保护验证脚本触发中英日任务链日志确认翻译路由和协作消息都正常。下一步看你的场景如果你还在排障和接入阶段比如翻译路由不生效、结构化消息被翻坏建议先去 API Keys 页面生成密钥再对照接入文档把endpoint和model配准。接入文档里有完整的请求格式和错误码说明能省不少调试时间。如果你要验证不同模型的翻译质量比如对比通用模型和领域模型在中英日互译上的术语准确率可以直接用模型对话接口把同一段文本发给不同模型看返回结果再决定路由优先级。如果你打算长期跑多语言编码或 Agent 协作比如让多个 Agent 持续处理跨语言任务链Coding Plan 更适合它在长链路和多轮调用上的稳定性比单次对话接口好成本也更好控制。翻译能力集成这件事配置写对只是第一步真正的坑在路由规则和结构化保护上。把这两块调稳你的 Harness 就能做到“加一个语种只改配置不改代码”。