MAF 上下文工程长会话最容易被卡住的地方往往不在 ContextAwareAgent 的提示词而在_deepseek.py里那两行配置DEEPSEEK_API_KEY和模型地址。把模型后端接到 TaoToken 兼容通道后这套示例才能稳定跑起来。先去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 Key再回到_deepseek.py把base_url填成https://taotoken.net/api末尾不要带/v1多轮日本旅行对话和search_hotels巴黎酒店查询才有机会一次过。这一篇对应微软 AI Agents for Beginners 的第 11、12 章第 11 章讲 MCP、A2A、NLWeb 三类智能代理协议第 12 章讲上下文工程。课程示例用 Microsoft Agent FrameworkMAF跑后端原本是 DeepSeek 的 OpenAI 兼容接口。示例一靠ContextAwareAgent和summarize_preferences演示长会话怎么记住偏好、怎么压缩上下文示例二把search_hotels封装成工具演示第 11 章“外部能力接入”的思想。两者共用_deepseek.py里的make_client()所以模型地址和 Key 只要错一处两个示例都起不来。1. MAF 上下文工程长会话卡在 _deepseek.py先认清两道门1.1 DEEPSEEK_API_KEY 与 base_url 为什么让示例一、示例二都停住原文第 1 篇的环境配置步骤里第一步是创建.env把DEEPSEEK_API_KEY填成开发者自己的密钥第二步是写_deepseek.py作为所有示例共享的客户端工厂。第 12 章的ContextAwareAgent、summarize_preferences以及第 11 章协议思想落地的search_hotels都不直接 new 客户端而是from _deepseek import make_client。这意味着只要make_client()里的api_key或base_url不对报错会先在第一个示例的第一轮对话里爆出来而不是在工具调用那一步。很多人的直觉是“先跑通示例一再回来补示例二”但 MAF 的客户端是共享的。你在示例一里把 Key 写死在脚本里示例二又会去读_deepseek.py结果两套配置打架。更稳的做法是把 Key 和模型地址都收到.env和_deepseek.py两个地方脚本只负责业务逻辑。TaoToken 在这套流程里只做一件事提供兼容 OpenAI 协议的 API Key 和 Base URL不替你做上下文压缩也不改summarize_preferences的返回值。1.2 Session、summarize_preferences、search_hotels 都走同一个客户端会话线程Session是 MAF 里的短期记忆容器agent.create_session()之后每次agent.run(..., sessionsession)都往同一条线程里追加消息代理才能引用前面轮次说过的预算、日期和偏好。总结工具summarize_preferences则是压缩杠杆它把散落在多轮里的偏好压成一条摘要即使后面的历史被裁剪摘要也能留下来。search_hotels是外部工具模型通过工具描述决定是否调用它调用结果再被注入当前上下文。三者看起来是不同机制但底层都要先把请求发到模型后端。所以配置顺序应该是先确认.env里能读到 Key再确认_deepseek.py里的base_url指向https://taotoken.net/api最后跑示例一验证多轮上下文跑示例二验证工具调用。不要一上来就改instructions也不要先怀疑 MAF 的 Session 有 bug。大部分“多轮失忆”其实是session没传或者每一轮都新建了客户端。2. 去 TaoToken 拿 Key改 _deepseek.py 的 base_url2.1 注册、创建 Key、复制模型 ID打开 TaoToken 注册账号进控制台创建 API Key。Key 复制出来后不要写死在示例脚本里先用占位符YOUR_API_KEY表示等会放进.env。接着去模型广场看当前可用的模型 ID不同时间列表可能不同所以不要凭记忆写一个带日期后缀的名字。模型 ID 以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场当时列表为准复制哪一个就填哪一个。这一步对应原文第 1 篇里“申请密钥”的位置。原文让你去开发者后台拿DEEPSEEK_API_KEY现在改成从 TaoToken 控制台拿 Key然后回到 MAF 项目里改共享客户端。注意官网地址带?utm_sourcetaotoken_aicg_blog_end而填进_deepseek.py的 Base URL 是https://taotoken.net/api两者不要混。Base URL 末尾不要加/v1也不要加任何查询参数。2.2 .env 与 _deepseek.py 最小改动在 MAF 项目根目录建.env把 Key、Base URL 和模型 ID 分开写。模型 ID 先留占位去模型广场复制后再替换。.env不要提交到公开仓库调试阶段也尽量只放在本地。TAOTOKEN_API_KEYYOUR_API_KEY TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL模型广场里复制的模型 ID_deepseek.py保留你原来的客户端类只改构造参数。下面这段的重点是base_url和api_key的来源YourChatClient替换成课程里实际用的 MAF 客户端类名。如果你原文件用的是 OpenAI SDK 的AsyncOpenAI也可以按同样两个参数传进去再把as_agent那层换成 MAF 的 ChatAgent 封装。import os from dotenv import load_dotenv load_dotenv() TAOTOKEN_BASE_URL https://taotoken.net/api # 末尾不要 /v1 def make_client(): return YourChatClient( # 替换成你原来的 MAF 客户端类 modelos.getenv(TAOTOKEN_MODEL, 模型广场里复制的模型 ID), api_keyos.getenv(TAOTOKEN_API_KEY, YOUR_API_KEY), base_urlTAOTOKEN_BASE_URL, )2.3 依赖安装与目录结构原文第 1 篇的安装命令继续用不需要换成别的框架。Python 环境里执行下面这行保证agent-framework、python-dotenv和 OpenAI 兼容依赖都在。pip install agent-framework python-dotenv openai目录可以保持原样.env放在项目根目录_deepseek.py与示例脚本同级。这样from _deepseek import make_client不会因为路径问题失败。运行前先单独验证环境变量是否读到了 Key可以写一个三行的小脚本打印bool(os.getenv(TAOTOKEN_API_KEY))不要在日志里打印完整 Key。确认能读到之后再去跑示例一的多轮对话。3. ContextAwareAgent 六轮日本旅行对话上下文怎么被记住3.1 六轮对话的观察点示例一的核心不是让代理写一份完美行程而是观察它在六轮里能不能记住前面说过的信息。第一轮用户说喜欢寿司、寺庙和摄影第二轮补预算 3000 美元、单人、4 月、10 天第三轮问“结合前面说的最不能错过什么”第四轮提到想住传统日式旅馆第五轮改到 10 月第六轮要求总结完整计划。每一轮都复用同一个session代理的回复里应该能引用早先的偏好而不是重复问“你喜欢什么”。这里能直观看到上下文窗口的代价轮次越多历史越长Token 消耗越高。原文用summarize_preferences做压缩把长对话里的偏好压成一条紧凑摘要。压缩之后即使旧消息被裁剪代理仍能基于摘要回答“基于你记录的偏好推荐哪几个目的地”。TaoToken 通道只保证请求能到达模型压缩逻辑仍然由你写的工具和 MAF 的会话机制负责。3.2 summarize_preferences 只做压缩不替代业务逻辑summarize_preferences不是数据库也不是记忆服务它只是一个被代理调用的工具函数。示例里它把conversation_notes包一层[SUMMARY]前缀返回告诉模型“这条是已记录的偏好”。真正决定要不要调用它的是代理的instructions收集到几条偏好后调用总结工具用户要求回忆时引用摘要回答保持简洁。这套设计对应上下文工程里的“便签 压缩”策略目标是降低长会话的 Token 成本同时避免上下文分心。有一点容易被误读配了 TaoToken 并不等于自动拥有上下文压缩。Base URL 和 Key 只解决“请求发得出去、模型回得来”summarize_preferences的压缩质量、摘要里保留哪些字段、什么时候触发总结仍然取决于你的代码和提示词。如果摘要写得太粗代理可能会丢掉“10 月”“3000 美元”这类关键约束如果每轮都总结又会多出额外调用。调参时先让示例跑通再改摘要格式。3.3 可运行代码会话线程 总结工具下面代码把模型后端接到_deepseek.py保留 Session 和总结工具。六轮输入用列表循环每一轮都传同一个session。运行前确认.env里的 Key 和模型 ID 已经替换_deepseek.py里的base_url是https://taotoken.net/api。import asyncio from agent_framework import tool from _deepseek import make_client tool(approval_modenever_require) def summarize_preferences(conversation_notes: str) - str: 把用户偏好压缩成一条可复用的摘要。 return f[SUMMARY] 已记录偏好{conversation_notes} async def main(): client make_client() agent client.as_agent( nameContextAwareAgent, instructions你是旅行规划助手。 对话变长时用要点总结前文跟踪用户偏好引用已有决策不要重复全部历史。, ) session agent.create_session() turns [ 我打算去日本喜欢寿司、寺庙和摄影。, 预算 3000 美元一个人4 月去 10 天。, 结合我前面说的最不能错过的是什么, 我想住传统日式旅馆。, 改到 10 月出发。, 帮我总结一下完整计划。, ] for q in turns: reply await agent.run(q, sessionsession) print(q) print(reply) print(- * 40) if __name__ __main__: asyncio.run(main())如果第六轮回复里还能看到“寿司、寺庙、摄影”“3000 美元”“10 月”这些信息说明 Session 生效了。如果它只回答最后一轮先检查session是否被重复创建再检查make_client()是否每轮都新建了客户端。工具调用是否发生可以在回复里看[SUMMARY]是否出现或者打开 TaoToken 控制台看这次会话的调用次数和 Token 消耗。4. search_hotels 巴黎酒店查询示例二的工具调用与验证4.1 MCP 思想落地为本地工具第 11 章讲 MCP 时重点是“动态发现工具、标准化调用、跨模型复用”。课程示例二没有真的启动 MCP 服务器而是用tool把search_hotels定义成 MAF 能识别的工具模拟“通过标准接口连接外部数据源”。search_hotels内部只有一份示例酒店列表按location或tags做字符串匹配返回 JSON。它不连接任何生产库也不执行真实预订读者可以放心在本地跑。这正好呼应第 11 章的协议分层MCP 负责“模型 ↔ 外部能力”A2A 负责“代理 ↔ 代理”NLWeb 负责“代理 ↔ 网站”。示例二只落地第一层的最小版本——工具发现与调用。你不必为了跑通上下文工程示例去搭 MCP 服务器先把工具定义、工具描述、参数 Schema 写清楚让模型能选中search_hotels就够验证兼容通道了。4.2 可运行代码MAF 代理调用 search_hotels下面代码同样从_deepseek import make_client把tools[search_hotels]传给代理。用户问“帮我找一家巴黎的浪漫酒店”模型应该调用工具工具返回 Le Meurice Paris代理再把结果整理成自然语言。注意base_url仍然来自_deepseek.py不要在这个脚本里另写一套地址。import asyncio import json from typing import Annotated from agent_framework import tool from _deepseek import make_client tool(approval_modenever_require) def search_hotels(query: Annotated[str, 位置、设施或标签]) - str: 在示例酒店表里查找匹配项。 hotels [ {name: Le Meurice Paris, location: Paris, price: 850, tags: [luxury, romantic]}, {name: Four Seasons Maui, location: Maui, price: 695, tags: [beach, family]}, {name: Hotel Sacher Vienna, location: Vienna, price: 420, tags: [historic, accessible]}, ] q query.lower() hits [h for h in hotels if q in h[location].lower() or any(q in t for t in h[tags])] return json.dumps(hits or hotels[:2], ensure_asciiFalse, indent2) async def main(): agent make_client().as_agent( nameHotelAgent, instructions你通过 search_hotels 工具查酒店回答时给出匹配结果。, tools[search_hotels], ) print(await agent.run(帮我找一家巴黎的浪漫酒店)) if __name__ __main__: asyncio.run(main())如果代理没有调用工具先看工具描述是否太模糊。query: Annotated[str, 位置、设施或标签]把参数含义写清楚能提高命中率。再看tools是否真的传给了as_agent。如果返回的是两家默认酒店而不是巴黎匹配项通常是查询词没有匹配上location或tags可以把q打印出来确认。4.3 验证模型对话 控制台用量两个示例都跑完后去 TaoToken 模型对话 用同一把 Key 发一条测试消息确认模型 ID 和 Base URL 没有填错。模型对话里能正常回复说明 Key 有效、通道可用如果这里就报 401先不用改 MAF 代码回到.env检查 Key 是否复制完整。接着打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 看用量记录确认示例一和示例二的调用都被记上账。验证时不需要让代理去连生产系统。示例二只查本地列表示例一只跑多轮对话。你要看的是三件事多轮上下文有没有保持、search_hotels有没有被调用、控制台里有没有出现对应的 Token 消耗。三件事都正常说明 MAF 到 TaoToken 的兼容通道已经配通。至于summarize_preferences的摘要质量可以在第二轮调试里单独改进。5. 401、404、模型 ID 与多轮丢失MAF 接入排障与下一步5.1 401 与 404 对照排障先看报错码别急着改instructions。401 大多是 Key 没读到常见原因是.env没有load_dotenv()或者load_dotenv()写在make_client()之后也可能是 Key 复制时带了空格。404 通常是 Base URL 写错比如写成https://taotoken.net/api/v1或者末尾多了/v1。正确填法是https://taotoken.net/apiOpenAI 兼容路径由 SDK 自己拼。不要把?utm_source...加到 Base URL 上也不要加到环境变量里。现象优先检查正确写法401.env是否在make_client()前加载TAOTOKEN_API_KEYYOUR_API_KEY404Base URL 是否多写/v1https://taotoken.net/api模型不存在模型 ID 是否从模型广场复制以模型广场当时列表为准多轮丢失每轮是否传了同一个sessionagent.run(q, sessionsession)工具没触发tools是否传入as_agenttools[search_hotels]5.2 模型 ID 与工具未触发模型 ID 是最容易想当然的地方。课程原文可能写了一个 DeepSeek 模型名但你现在走 TaoToken 通道应该用模型广场里当前可选的 ID。不同账号看到的列表可能不同所以不要编造带日期后缀的名字也不要照搬截图里的旧名称。把模型 ID 放进.env的TAOTOKEN_MODEL_deepseek.py只负责读取。换模型时只改这一处示例一和示例二同时生效。工具未触发一般不是通道问题。MAF 会把你注册的工具描述发给模型模型根据描述决定是否调用。search_hotels的描述写“查询酒店数据库中的匹配房产”参数说明写“位置/设施/标签”命中率会高很多。如果你把描述写成“处理酒店相关事务”模型可能只回复一段文字而不调用工具。工具调用成功时返回的 JSON 会进入上下文代理再基于它生成回答。这个链路里没有任何环节需要连接生产库。5.3 下一步控制台对账与 CTA跑通之后下一步不是立刻加更多工具而是先把这次调用对清楚。先在 TaoToken 模型对话 用同一把 Key 发一条消息确认调用记上账如果打算长期跑 MAF 示例或本地调试可以看 Coding Plan 的套餐是否匹配你的调用频率Key 则在 控制台 API Keys 创建和管理。控制台里能看到调用记录和用量这比在终端里猜“到底有没有发出去”更直接。最后留一个检查清单.env里有TAOTOKEN_API_KEY、TAOTOKEN_BASE_URL、TAOTOKEN_MODEL_deepseek.py里base_url是https://taotoken.net/api示例一每轮都传同一个session示例二把tools[search_hotels]传给了代理。四项都对再去 TaoToken 模型对话 发一条消息然后回控制台看这次调用有没有记上账。剩下的就是按第 12 章的思路继续调你的摘要格式和上下文预算。