实验 07 — 总结

目标: 将你构建的内容整理归类，整理好你的机器，并选择一个合理的下一步。

时间: ~10分钟

你涵盖了什么

实验	能力
01	安装了依赖项，运行了 FastAPI 应用程序，并对 SDK 示例进行了冒烟测试
02	追踪了一个流式传输的聊天回合，并在运行时发现了模型
03	将静态上下文替换为 Python @define_tool 工具
04	观察会话事件生命周期和完成信号
05	在进程重启后持久化并恢复 SDK 会话
06	连接 MCP 服务器以扩展代理以包含外部工具

可选的 extra-* 实验现在位于主 SDK 路径之外。当您需要 CLI 自定义智能体、治理钩子，或 FastAPI/SQLModel 扩展实践时使用它们，但它们不是 SDK 序列所必需的。

值得保留的想法

1. 嵌入比聊天更胜一筹。 SDK 将智能体转变为应用程序的一部分，受你的认证、日志和部署管道所支配。在 Python 中，这始于 CopilotClient()，通常以 async with CopilotClient() as client: 的形式；如果你手动构建它，需要在创建会话之前调用 await client.start()。

2. 发现能力；不要硬编码它们。 模型来自await client.list_models()，所以读者不需要所有人都能访问相同的预览模型。

3. 会话创建是基于关键字的。 你反复看到的调用结构是await client.create_session(model=..., streaming=..., system_message=..., tools=..., mcp_servers=..., on_permission_request=...)。那些关键字参数是聊天、工具、MCP 和权限的配置表面。

4. 工具胜过填充上下文。 @define_tool 让模型获取所需的内容，而不是在每次回合都预加载猜测，这些猜测无论是否有用都会消耗令牌。Python 自定义工具 需要 on_permission_request 才能使用，否则请求被拒绝；.NET 示例则不需要这样的处理器。

5. 事件是只推送的。 session.on(handler) 注册一个回调并返回一个取消订阅的可调用。没有异步迭代器，所以示例共享。 IdleWaiter 在等待空闲或错误时。 sdk_labs/_common.py 在等待空闲或错误时。

6. Python 只有一个事件数据类。 .NET 在事件子类上进行模式匹配；Python 给你一个 SessionEvent，你根据 evt.type 分支，一个 SessionEventType 枚举。这就是为什么示例检查 evt.type is SessionEventType.SESSION_IDLE 的原因。

7. 发送和完成是两个独立的选择。 使用 await session.send(prompt) 当您希望自行观看事件时。使用 await session.send_and_wait(prompt, timeout=...) 当您只需要 SDK 等待完成即可。

8. 会话使智能体具有便携性。 resume_session 加上 get_session_metadata 能够在进程重启后继续有效。演示应用的浏览器本地存储历史记录很方便，但无法在不同设备之间迁移。

9. MCP扩展了覆盖范围。 Python通过普通的字典配置MCP服务器——例如， 不需要将每种集成都烘焙到你的应用程序中。与.NET不同，Python不需要抑制权限API。 mcp_servers={"microsoft.docs.mcp": {"type": "http", ...}} 不需要 GHCP001 抑制

清理

停止服务 (Ctrl+C 在终端中)，或者如果它已分离：

lsof -ti:5070        # prints a PID if still listening
kill <PID>

移除本地 artefacts：

rm -f src/AgentOrchestrator-python/retail.db*   # SQLite DB + WAL files
rm -f logs/*                                    # if you ran the shared CLI extras

retail.db 在第一次运行时在 Python 工作目录中创建，并被 git 忽略。⚠️ 如果在 macOS 上文件仍然打开，删除命令可能会看起来成功，而服务会重新创建它。首先停止服务，然后删除该 artefact。

git status --short

预期结果：没有输出，或者只有你有意编辑的实验文件。如果你希望丢弃本地实验工作并返回到一个干净的检出：

git status
git checkout -- .        # discards uncommitted changes — irreversible

检查你的理解

1. 为什么 Python 技术路线使用 async with CopilotClient()？
2. 为什么样品需要IdleWaiter而不是async for evt in session？
3. 如果注册一个未包含on_permission_request的自定义Python工具会发生什么？
4. 在 Python 中你检查哪个事件字段，以及哪些 SDK 调用证明一个会话可以在重启后恢复？

答案

1. 它可靠地启动和停止客户端。如果你不使用上下文管理器，自己调用 `await client.start()` 和稍后调用 `await client.stop()`。 2. SDK事件是推送回调。`session.on(handler)`订阅一个处理程序，因此一个小的基于未来的辅助程序等待 `SESSION_IDLE` 或在 `SESSION_ERROR` 时抛出。 3. 工具调用被拒绝。Python需要一个权限处理程序来处理自定义工具；.NET不需要为等效的样本提供一个。 4. 每个事件都是 `SessionEvent`；根据 `evt.type` 分支，一个 `SessionEventType` 枚举。`await client.resume_session(session_id, ...)` 重新启动对话，`await client.get_session_metadata(session_id)` 获取存储的元数据。

下一步该去哪里

方向	开始这里
重新运行一个聚焦的 SDK 示例	sdk_labs
深入理解演示代码	演示
参考故障排查和架构	突破
构建你自己的智能体应用	GitHub Copilot SDK 仓库
扩展Copilot的外部工具	模型上下文协议

进一步的想法

• 推广一个示例到应用中。 将一个 sdk_labs 命令移动到一个真实的 API 端点，并添加面向用户的进度指示。
• 在服务器端持久化会话。 替换浏览器的 localStorage 为基于 SQLite 的会话元数据，使历史记录在不同设备间持久。
• 添加第二个MCP服务器。 将凭证保持在源之外，记录所需的环境变量，并证明工具在运行时出现。
• 增强可观测性。记录您今天忽略的事件类型，以便生产调试时有足够的上下文，而无需存储完整的提示。

✅ 最终检查点

• [x] 七个 SDK 实验全部完成
• [x] 服务已停止，本地 artefacts 已清理
• [x] git status --short 是干净的，或者只有意图中的实验编辑仍然存在
• [x] 你可以回答上面的四个问题

相关

• 实验室首页
• Python 应用 README
• 排除故障
• AGENTS.md