Manus 多 Agent 上下文工程实战：用 Schema 约束上下文传递与配置骨架

1. 多 Agent 协作里上下文为什么会越传越乱如果你正在用 Manus 这类支持多 Agent 协作的框架做任务编排大概率遇到过两个很典型的现象一是主 Agent 把任务拆给子 Agent 之后子 Agent 返回的内容格式飘忽不定有时是 JSON有时夹一段自然语言解释主 Agent 解析起来全靠正则硬扛二是任务链一长上下文窗口迅速膨胀历史消息越堆越多模型开始“忘事”前面确认过的约束到后面就不认了。这两个现象背后其实是同一个问题上下文在 Agent 之间传递时缺少一份稳定的“契约”。Manus 在多 Agent 协作上的一个核心思路就是用 Schema 来约束上下文传递——主 Agent 委派任务时先定义子 Agent 必须遵循的输出结构子 Agent 通过受约束的解码返回结果从而保证信息传递稳定、完整、可解析。这套思路落到工程上就是一份可复制的上下文配置骨架。这篇内容面向的是已经在本地跑通单 Agent、准备往多 Agent 协作推进的开发者。我会从 Schema 约束切入给出 settings.json 和 config.toml 两份配置骨架再接入 TaoToken 的统一 Key/API 通道最后附上上下文传递的验证动作和排查清单。你跟着做能在本地复现一套可校验的上下文工程流程。需要先明确一个概念上下文工程不是提示工程的放大版。提示工程优化的是单次交互的输入措辞上下文工程管理的是一个动态演变的信息环境——哪些历史该保留、哪些该压缩、哪些该以结构化形式在 Agent 之间流转。多 Agent 场景下这个环境被切分成多个隔离的上下文空间传递失真和膨胀就更容易发生。2. TaoToken 前置统一 Key 与 API 通道多 Agent 协作有个容易被忽略的成本问题不同子 Agent 可能调用不同模型如果每个模型都单独配一套 Key 和接入地址配置会迅速失控。我试过把模型接入统一到一个通道上配置复杂度会明显下降。TaoToken 在这里扮演的是统一接入层的角色。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力API 接入地址是 https://taotoken.net/api这个地址不加 UTM 参数直接用于代码里的 base_url。前置准备分三步走。第一步在控制台创建 API Key入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二步确认你要用的模型标识多 Agent 场景建议至少准备一个主力推理模型和一个轻量模型前者处理复杂规划后者处理简单子任务。第三步把 Key 写进环境变量不要硬编码进配置文件。这里有个实操细节多 Agent 框架通常会给每个子 Agent 独立的配置段如果每个段都写一遍 base_url 和 api_key维护起来很痛苦。更稳的做法是让所有子 Agent 共享同一个环境变量读取逻辑配置里只写模型名和参数差异。这样换 Key 或换通道时只改一处。如果你后续要做长期编码类或 Agent 类的持续任务可以了解 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合需要稳定配额的长任务场景。模型对话调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3. 可复制的 Agent 上下文配置骨架这一节是全文的技术核心。我给出两份配置settings.json 负责 Agent 运行时行为config.toml 负责模型通道与上下文策略。两份配置配合使用Schema 约束体现在 settings.json 的输出契约段。3.1 settings.jsonAgent 行为与 Schema 契约{ agent: { name: orchestrator, max_context_tokens: 128000, compaction_threshold: 0.75, compaction_keep_recent_ratio: 0.5, summarization_schema: { type: object, properties: { modified_files: { type: array, items: { type: string } }, user_goal: { type: string }, open_questions: { type: array, items: { type: string } }, next_action: { type: string } }, required: [modified_files, user_goal, next_action] } }, sub_agents: [ { name: researcher, mode: communicate_by_sharing_memory, output_schema: { type: object, properties: { findings: { type: array, items: { type: string } }, sources: { type: array, items: { type: string } }, confidence: { type: number, minimum: 0, maximum: 1 } }, required: [findings, confidence] } }, { name: coder, mode: share_memory_by_communicating, output_schema: { type: object, properties: { patch: { type: string }, tests_passed: { type: boolean }, notes: { type: string } }, required: [patch, tests_passed] } } ], action_space: { atomic_functions: [read_file, write_file, list_dir, run_shell], sandbox_tools: [pandoc, ffmpeg, jq], allow_script_execution: true } }这份配置里有几个关键点值得展开。compaction_threshold设为 0.75意思是上下文用到 75% 时触发紧凑化而不是等到 100% 才处理——留出缓冲空间避免临界点上的性能抖动。compaction_keep_recent_ratio设为 0.5只紧凑化最旧的 50% 历史保留最新部分作为完整格式的示例防止模型模仿紧凑格式导致后续输出异常。summarization_schema是总结阶段的结构化模板。注意它要求模型填充固定字段而不是自由发挥。这样每次总结产出的都是可解析的结构主 Agent 能稳定读取next_action字段决定下一步。两个子 Agent 的mode字段对应两种协作模式。researcher用共享内存模式因为它需要完整历史背景才能做研究coder用通信模式因为编码任务指令清晰、隔离上下文更高效。output_schema就是传递契约子 Agent 返回结果必须符合这个结构。3.2 config.toml模型通道与上下文策略[default] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout_seconds 120 max_retries 3 [models.primary] name claude-sonnet role orchestrator temperature 0.3 max_output_tokens 8192 [models.light] name gpt-4o-mini role sub_agent temperature 0.2 max_output_tokens 4096 [context] strategy compaction_first enable_schema_validation true log_compaction_events true offload_summary_to_file true summary_log_path ./logs/context_summary.jsonl [multi_agent] max_parallel_sub_agents 3 delegation_timeout_seconds 300 require_schema_on_delegation truebase_url指向 TaoToken 的 API 地址api_key_env指定从环境变量读取 Key这样配置文件可以安全地进版本库。strategy compaction_first对应 Manus 那套“优先紧凑化、必要时总结”的分层策略。require_schema_on_delegation true强制每次委派任务都必须带 Schema这是防止传递失真的硬约束。offload_summary_to_file和summary_log_path配合使用总结前把完整上下文卸载到日志文件后续需要细节时可以用 grep 检索。这是可逆性的兜底手段。3.3 环境变量与启动export TAOTOKEN_API_KEY你的Key export AGENT_CONFIG_PATH./settings.json export AGENT_CHANNEL_CONFIG./config.toml启动时让框架读取这两个配置路径即可。如果你的框架不支持双配置文件可以把 config.toml 的内容合并进 settings.json 的一个channel段逻辑不变。4. 验证请求与成功结果配置写完不等于生效必须做验证。我给出三个层次的验证动作从通道连通到上下文传递逐层校验。4.1 通道连通性验证curl -s -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: reply with ok}], max_tokens: 16 }预期返回里choices[0].message.content包含 ok。如果返回 401检查 Key 是否正确写入环境变量返回 404检查 base_url 是否多了或少了路径段。4.2 Schema 约束验证这一步验证子 Agent 是否真的按 Schema 返回。构造一个测试委派import json, os, requests schema { type: object, properties: { findings: {type: array, items: {type: string}}, confidence: {type: number} }, required: [findings, confidence] } payload { model: gpt-4o-mini, messages: [ {role: system, content: fReturn JSON matching this schema: {json.dumps(schema)}}, {role: user, content: Summarize: multi-agent context engineering uses schema contracts.} ], response_format: {type: json_object} } resp requests.post( https://taotoken.net/api/v1/chat/completions, headers{Authorization: fBearer {os.environ[TAOTOKEN_API_KEY]}}, jsonpayload, timeout60 ) result json.loads(resp.json()[choices][0][message][content]) assert findings in result and confidence in result print(schema ok:, result)跑通后你会看到类似schema ok: {findings: [...], confidence: 0.9}的输出。如果json.loads报错说明模型没按 JSON 返回需要检查response_format是否被通道支持或者把 Schema 描述写得更明确。4.3 上下文传递完整性验证这一步验证多 Agent 传递后信息有没有丢。做法是让主 Agent 委派一个带约束的任务检查子 Agent 返回是否保留了约束字段。delegation { task: list three risks of context bloat, constraints: {max_items: 3, format: json}, output_schema: schema } # 把 delegation 发给子 Agent检查返回条数是否等于 3成功结果是返回的findings数组长度恰好为 3且每项都是字符串。如果返回条数不对说明约束没传达到位检查委派消息里是否把constraints一起带上了。5. 本篇常见错排查清单下面这些是我在配置过程中踩过或见别人踩过的坑按出现频率排序。Schema 校验失败模型返回带 markdown 代码块。模型习惯把 JSON 包在 json 里。解决方式是在系统提示里明确“只返回裸 JSON不要代码块标记”或者在解析前先做一次代码块剥离。上下文紧凑化后模型行为突变。通常是紧凑化比例过高把最新示例也压掉了。检查compaction_keep_recent_ratio是否低于 0.3建议保持在 0.5 左右。子 Agent 拿不到完整历史。检查该子 Agent 的mode是否设成了share_memory_by_communicating。这个模式只传指令不传历史需要完整背景的任务应该用communicate_by_sharing_memory。委派超时。delegation_timeout_seconds默认 300 秒复杂研究任务可能不够。适当调大同时检查子 Agent 是否陷入了无效循环。总结日志文件不生成。检查summary_log_path的目录是否存在多数框架不会自动创建父目录。先mkdir -p ./logs再启动。通道返回 429。并发子 Agent 太多触发限流。把max_parallel_sub_agents降到 2 或 3或者了解 Coding Plan 获取更稳定的配额。Schema 里 required 字段没被填充。部分模型对 required 的遵循度不高。可以在系统提示里把必填字段单独强调一遍或者在解析后做一次字段补全兜底。换模型后架构性能下降。这其实是好事说明你的架构对模型能力敏感。按 Manus 的思路好架构在从弱模型切到强模型时应该有明显提升。如果换强模型反而变差检查是不是 Schema 约束过紧限制了强模型的发挥。6. 把上下文工程落到你的项目里回到最开始的问题多 Agent 上下文膨胀和传递失真本质上是缺少稳定的信息契约和分层的信息管理策略。Schema 约束解决的是“传得准”紧凑化与总结的分层策略解决的是“传得省”两者配合才能让多 Agent 协作在长任务里稳定运行。你可以先从最小闭环开始用上面那份 settings.json 跑通两个子 Agent 的委派确认 Schema 校验通过再逐步加上紧凑化和总结逻辑。不要一上来就把所有策略都打开那样出问题时很难定位是哪一层导致的。模型接入方面统一通道能省掉大量重复配置。需要调试模型行为时用模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期跑编码或 Agent 任务的话Coding Plan 入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后一个实操建议把每次委派的 Schema 和子 Agent 返回都记进日志跑一段时间后回看你会清楚看到哪些字段经常缺失、哪些任务模式容易触发上下文膨胀。这些真实数据比任何架构讨论都更能指导你调整配置。