学习笔记 · Obsidian
生产化、测试、可观测性与迁移
/test是 unit、integration、evals 三条测试路径的聚合入口；与/test/index内容同源但属于独立可点击路由。
生产闭环
一个“能回答问题”的 agent 还不是生产系统。完整闭环至少包括：
本地可视化调试 → 单元/集成/轨迹评估 → 部署与持久运行 → trace/指标/告警 → 线上样本回流评估 → 受控升级与回滚
模型不确定性不会降低传统工程要求，反而要求把结构断言、执行轨迹、权限、副作用和恢复能力分层验证。
本地开发与 Studio
LangSmith Studio 是连接本地 Agent Server 的可视化调试界面，可查看 prompt、tool args/results、state、异常、token 和 latency，并从历史步骤重跑。
当前 Python setup 边界：
langgraph-cli[inmem]的本地 Studio 流程要求 Python 3.11+；这比langchain核心包的 Python 3.10+ 更严格。create_agent返回 compiled LangGraph graph，可直接在langgraph.json的graphs中指向module:agent。langgraph dev默认在127.0.0.1:2024启动；Safari 对 Studio 访问 localhost 有限制，文档建议--tunnel。- Studio 需要 LangSmith 凭证建立连接；若不希望本地数据被 trace，显式设
LANGSMITH_TRACING=false。.env不能进版本控制。
热重载和从中间步骤重跑适合开发诊断，但不能替代持久数据库、真实网络、并发和部署环境验证。
可观测性
LangChain agent 原生支持 LangSmith tracing。开启后，一条 trace 覆盖用户输入、每次模型调用、工具、决策点和最终输出。可通过环境配置全局开启，也可用 tracing_context 只 trace 指定操作，并用 project、tags、metadata 划分版本和环境。
生产 trace 设计建议：
- 用稳定的 app/model/prompt/tool 版本标签支持回归对比；
- 记录延迟、token、重试、工具错误、interrupt 等可操作指标；
- user/session 标识应使用受控、可脱敏标识，不记录凭证、完整 PII、原始敏感工具结果；
- trace 采样、保留期和访问权限按数据等级设置；
- 观测数据用于定位失败模式，不能只看平均响应时间。
测试金字塔
1. 单元测试
用 GenericFakeChatModel 依次返回预设文本、tool call 或错误，验证确定性逻辑；用 InMemorySaver 验证 thread 内 state/checkpoint 行为。适合：
- tool schema、输入校验和错误转换；
- middleware hook、顺序、jump、retry/fallback；
- state reducer、结构化输出解析和权限分支；
- 固定 tool-call/result 关联。
它不验证 provider schema 兼容性、真实模型选择工具的能力、网络与延迟。
2. 集成测试
真实模型/API 测试应与 unit tests 分开，以 pytest marker 显式运行；凭证从环境/CI secrets 注入，缺少时 skip。由于输出非确定性，断言 message/tool 类型、tool name、参数结构、状态和约束，不断言完整自然语言字符串。
控制成本和波动：选小模型、限制 max tokens、每个测试只覆盖一个行为、只在 CI/预发布运行。用 VCR/pytest-recording 重放 HTTP 时必须过滤 Authorization、API key 和 query secret；prompt/tool/预期轨迹变化会使 cassette 过期，应重新录制并审查内容。
3. Agent eval
AgentEvals 评估的是完整 trajectory，而不只是最终文本：
| 匹配模式 | 含义 | 适用 |
|---|---|---|
| strict | 消息结构和工具顺序严格一致 | 必须先查政策再授权等顺序约束 |
| unordered | 所需工具相同但顺序不限 | 可并行、顺序无关的检索 |
| subset | 实际工具不能超出 reference | 限制 agent 行为范围 |
| superset | 至少执行 reference 要求工具 | 验证最低必需动作，允许额外步骤 |
LLM-as-judge 可按 rubric 判断定性轨迹，不一定需要 reference，但自身也有模型偏差、费用和漂移；高风险规则优先确定性 evaluator，开放质量再叠加 judge。异步 evaluator 有对应 async factory。LangSmith 可在 pytest 或 experiment 中记录数据集、输出、reference 和评分，长期比较 prompt/model/tool 版本。
部署
官方快速路径是把 LangGraph-compatible agent 放在 GitHub 仓库，部署到 LangSmith Cloud，再从 Studio 测试并通过 deployment API/SDK 访问。Cloud 提供 stateful、long-running agent 的托管基础设施；另有 hybrid、standalone server 和 self-hosted control plane，选择取决于数据驻留、网络、合规、团队运维能力和成本。
部署前最少确认：
- 生产 checkpointer/store、备份、迁移与恢复；
- 工具出网、文件系统、sandbox、数据库账号的最小权限；
- request/run/node/tool timeout，有限重试、幂等和 graceful shutdown；
- queue/concurrency、模型/工具 rate limit、费用上限与租户隔离；
- HITL 恢复、webhook/外部副作用幂等、审计；
- readiness、health、metrics、trace sampling、告警与回滚版本。
部署教程展示的是接入路径，不是完整生产验收清单；约 15 分钟等时间描述也只是页面当时的经验值。
Agent Chat UI
开源 Agent Chat UI 是可快速连接本地或 deployed agent 的 Next.js 客户端，内建实时 chat、tool visualization、interrupt thread、time travel/state fork。Hosted UI 适合验证协议；自托管/定制时通过 graph ID、deployment URL 连接。它能减少基础 UI 开发，但鉴权、数据暴露、品牌、accessibility 与业务审批仍由应用负责。
Voice agent 架构
两条生产路线：
| 架构 | 优点 | 代价 |
|---|---|---|
| STT → text agent → TTS（sandwich） | 组件可替换、最新文本模型能力、边界可观察可控制 | 多服务编排、音频转文字会损失语气信息 |
| Native speech-to-speech | 链路短、简单交互通常延迟低、保留语音细节 | provider/model 选择少、锁定强、可解释和定制较弱 |
官方教程选择 sandwich，以浏览器与 Python server 间 WebSocket、async generators 串起音频输入、STT transcript、LangChain token stream 与 TTS audio chunks。页面提到特定 provider 可做到 sub-700ms，这是特定实现的目标/示例，不是普遍 SLA。生产还需处理 VAD、打断/barge-in、背压、会话取消、音频隐私、重连、语言与无障碍文本回退。
版本与迁移观察
changelog-py.md 当前重定向到 canonical /oss/python/releases/changelog.md。当前页面覆盖 v1.0 以来的重要变化：
- LangChain v1.0：高层 chains/agents 收敛为 LangGraph 上的 agent；旧能力迁至
langchain-classic；迁移需查专用 guide。 - v1.1：model profiles、profile-aware summarization、ProviderStrategy 推断、SystemMessage prompt、ModelRetryMiddleware。
- v1.2：tool
extras承载 provider-specific tool 配置，structured output strict schema。 - v1.3：agent 支持
stream_events/astream_events的version="v3"typed projections。 - 同期 LangGraph 1.1 引入 opt-in v2 typed invoke/stream；1.2 加入 node timeout/error handler/graceful shutdown、DeltaChannel 和 v3 event stream。不要把 LangChain、LangGraph、Deep Agents 的版本号当成同一序列。
升级策略：锁定 direct dependencies → 阅读目标版本 release/migration guide → 先跑 unit/integration/evals → 对 streaming、state/checkpoint、tool schema、structured output 和 middleware 顺序做契约回归 → 灰度 → 保留回滚。订阅 changelog RSS 比偶尔浏览更适合持续维护。
求助与权威来源
排查顺序建议：当前版本 API Reference/官方 docs → changelog/migration guide → GitHub issue → Community Forum/Slack；企业关键问题使用 support portal，并通过 LangSmith status 区分平台故障。提问时提供最小复现、包版本、trace/错误类型和已脱敏配置，不公开凭证或业务数据。
逐页覆盖索引
| 页面 | 学习结论 |
|---|---|
| Deployment | LangSmith Cloud GitHub 部署、Studio 验证、deployment URL 与 SDK 访问；其他托管模式另选。 |
| Observability | 自动 tracing、selective context、project、tags 和 metadata。 |
| Studio | CLI、本地 Agent Server、langgraph.json、hot reload、state/tool/trace 调试。 |
| Test overview | unit、integration、trajectory eval 的职责与 agent 更依赖集成测试的原因。 |
| Unit testing | GenericFakeChatModel 与 InMemorySaver 的确定性测试。 |
| Integration testing | pytest marker、凭证管理、结构断言、成本控制、VCR 脱敏与 cassette 更新。 |
| Agent evals | strict/unordered/subset/superset trajectory match、LLM judge、async 与 LangSmith experiment。 |
| Agent Chat UI | hosted/local Next.js UI、graph/deployment 连接、tool/interrupt/time-travel 支持。 |
| Voice agent | sandwich 与 S2S 架构，WebSocket + async streaming 的 STT-agent-TTS 实现。 |
| Get help | Chat LangChain/API reference、Forum/Slack、support/status、贡献和更新渠道。 |
| Changelog | alias 重定向后的 v1.0–v1.3、LangGraph/Deep Agents 同期变化、RSS 与迁移边界。 |
上线前验收
- ○ 单元、真实 provider 集成、关键 trajectory eval 均有基线。
- ○ 数据库/工具/文件系统/网络权限最小化，所有副作用具备幂等与审批策略。
- ○ checkpointer/store 在真实后端完成迁移、恢复、并发与容量验证。
- ○ tracing/日志已脱敏，并具备费用、错误率、延迟、重试和异常轨迹告警。
- ○ streaming/HITL/rejoin/checkpoint 在断网、重启、超时和取消下可恢复。
- ○ 版本锁、迁移说明、灰度与回滚路径明确。