LangChain TypeScript：生产化、测试与迁移

生产闭环

Agent 上线不是“本地能回答”到“部署 URL”两步，而是：

Studio 可视化调试 → deterministic unit tests → real-provider integration tests → trajectory evals → 部署与持久运行 → traces/指标/告警 → 线上样本回流 → 受控升级与回滚

模型的不确定性不会减免传统工程要求；相反，工具副作用、状态恢复、流式协议和模型漂移要求更强的分层验证。

Studio 本地开发

LangSmith Studio 连接 LangGraph CLI 启动的本地 Agent Server，可查看 prompt、tool args/results、state、异常、token/latency，并热重载和从历史步骤重跑。

TypeScript setup：

1. npx @langchain/langgraph-cli / ... dev；
2. createAgent 返回的 compiled graph 导出到 agent.ts；
3. langgraph.json 的 graphs 指向 ./src/agent.ts:agent；
4. .env 注入 LangSmith/provider secrets；
5. 默认 API 在 http://127.0.0.1:2024，Studio 以该 baseUrl 连接。

Safari 会阻止 Studio 直接访问 localhost，页面建议使用 --tunnel。Tunnel 会改变暴露面，使用时仍需确认鉴权和敏感数据。若不希望 trace 离开本地，显式设 LANGSMITH_TRACING=false。.env 永远不提交。

Studio 的重跑和 hot reload 是开发工具，不验证真实数据库、持久 checkpointer、并发、网络分区和部署权限。

Observability

createAgent 自动支持 LangSmith tracing。设置 LANGSMITH_TRACING=true 与 API key 后，一条 trace 覆盖模型、工具、决策点和最终输出。也可给某次 invoke 传 LangChainTracer，通过 project、tags 和 metadata 区分环境/版本。

生产观测至少包括：

• run/node/model/tool 延迟、token、费用、重试、错误、interrupt、cancel；
• model/prompt/tool/schema/middleware/app 版本；
• 受控 user/session/tenant 标识；
• tool 副作用的业务 request/idempotency ID；
• trace sampling、保留期、脱敏和 RBAC。

不要把凭证、完整 PII、数据库结果或音频原文无条件写入 trace。LangSmith trace 能解释执行路径，但不能证明回答正确，仍需 eval 与业务监控。

TypeScript 测试金字塔

1. Unit：fakeModel

fakeModel() 是 builder-style BaseChatModel 替身，可顺序脚本化行为：

• .respond(AIMessage | Error | factory)：文本、tool call、特定 turn 错误或动态响应；
• .respondWithTools([...])：快速生成 tool calls，ID 可自动生成；
• .alwaysThrow(error)：每次失败；
• .structuredResponse(value)：为 .withStructuredOutput() 提供固定结果；
• model.calls / callCount：断言实际收到的 messages/options；
• bindTools()：与原模型共享 queue 和 calls，可直接用于 agent/framework。

queue 用完会抛明确错误；factory 每注册一次只消费一次。.structuredResponse 会忽略传入 schema，它只用于测试应用逻辑，不能证明真实 provider 可生成该 schema。

单元测试适合 tool schema/handler、middleware 顺序、retry/fallback、state reducer、HITL 分支和错误转换。它不验证 provider tool schema、真实模型选工具、网络和延迟。

2. Integration：真实网络、结构断言

用 Vitest 把 *.int.test.ts 与默认 unit 分开，vitest --mode int 显式运行，设更长 test timeout；API key 从 .env/CI secret 注入，缺少时 test.skipIf。不要在测试输出打印 secret。

LLM 文本非确定，断言结构而非完整句子。@langchain/core/testing 提供 Vitest matchers：

• toBeHumanMessage / toBeAIMessage / toBeSystemMessage / toBeToolMessage；
• toHaveToolCalls / toHaveToolCallCount / toContainToolCall；
• toHaveToolMessages；
• toHaveBeenInterrupted；
• toHaveStructuredResponse。

控制费用：用能力足够的小模型、maxTokens、单行为用例、CI/预发布按需运行。真实 provider 仍可能波动，失败重跑需区分产品回归与上游暂时错误，不能无限 retry 掩盖问题。

3. AgentEvals：轨迹质量

agentevals 提供：

还可用 toolArgsMatchMode/override 定制参数匹配。createTrajectoryLLMAsJudge 按 rubric 评估整体轨迹，可带或不带 reference；它有费用、延迟、偏差和版本漂移，高风险硬规则优先 deterministic evaluator。

LangSmith 支持 Vitest/Jest integration 或 evaluate() + dataset，记录 inputs、outputs、reference 和 evaluator score，持续比较 model/prompt/tool 版本。

部署

官方快速路径：把 LangGraph-compatible agent 放进 GitHub → LangSmith Cloud 创建 deployment → Studio 验证 → 使用 API URL、@langchain/langgraph-sdk 或 REST stream 调用。Cloud 面向 stateful、long-running agent，并提供托管基础设施；也可选 hybrid、standalone server、自托管 control plane，或通过 Agent Streaming Protocol 部署在 Next.js、SvelteKit、Nuxt、Cloudflare Workers、Deno 等平台。

框架能运行协议不等于所有 runtime 等价。部署前确认：

• Node/runtime、原生依赖、持久 checkpoint/store、migration/backup/restore；
• worker concurrency、queue、run/node/tool timeout、graceful shutdown；
• 有限 retry、circuit breaker、幂等与外部 rate limit；
• MCP/tool 网络、filesystem/sandbox、数据库最小权限；
• tenant 隔离、HITL 恢复、webhook/副作用审计；
• health/readiness、metrics、trace sampling、alert 和 rollback。

教程中“部署约 15 分钟”只是当时示例，不是 SLA。

Agent Chat UI

Agent Chat UI 是开源 Next.js 客户端，可连接本地或已部署 agent，自动展示实时消息、tool calls、interrupt，并支持 time travel/state fork。Hosted 版本适合协议验证；自托管可用 create-agent-chat-app 或 clone 定制，通过 graph ID、deployment URL 和可选 LangSmith key 连接。

它不是完整业务前端：用户认证、thread 权限、API key 代理、PII、品牌、accessibility、移动端和自定义审批仍由应用实现。浏览器不应直接持有高权限 LangSmith key。

Voice agent

两种架构：

官方 TypeScript 教程选择 sandwich：浏览器捕获 16kHz PCM，通过 WebSocket 发给 Node server；producer/consumer async iterators 并发 STT；最终 transcript 进入带 MemorySaver/thread 的 agent；streamEvents({ version: "v3" }) 的 text token 立即送 TTS；audio chunks 再回浏览器。AssemblyAI/Cartesia 只是示例 provider。

页面声称特定组合可达到 sub-700ms，这是参考实现目标，不是普遍 SLA。生产还需 VAD、barge-in、中断/取消、背压、重连、音频授权/保留、内容审核、噪声/语言和无障碍文本回退。

Changelog 与迁移边界

changelog-js.md 当前 307 到 canonical /oss/javascript/releases/changelog。页面截至本次验证展示的关键节点：

• 2025-10 LangChain v1.0：高层 API 收敛到 LangGraph-backed agent，旧 chains/agents 进入 @langchain/classic；
• 2025-11 v1.1：model profiles、retry/content moderation、profile-aware summarization/provider strategy；
• 2025-12 v1.2：strict provider strategy；LangGraph/集成/MCP 同期继续演进；
• 2026-01 LangGraph v1.1：StateSchema、Standard Schema、ReducedValue/UntrackedValue/MessagesValue 等；
• 2026-03 页面出现 Deep Agents JS v1.9.0-alpha.0，async subagents、backend v2、工具重命名和 v1 deprecated adapter。

langchain、@langchain/langgraph、deepagents、frontend SDK 和 provider 不共享版本号。Alpha 不能按 stable 对待；异步 subagents 页面还要求 LangSmith Deployment 等外部运行能力。

升级流程：锁 direct dependencies → 查目标 changelog/migration/API reference → TypeScript compile → unit/integration/eval → 对 state/checkpoint、stream events、tool schema、middleware 顺序和 structured output 做契约回归 → shadow/canary → 保留 lockfile/部署回滚。旧 v0.3 文档已归档，不要混用当前 v1 snippet。

求助与文档质量边界

排查顺序：当前 JavaScript API Reference与官方 docs → changelog/migration → GitHub issue → Forum/Slack → 企业 support/status。提供最小复现、精确包版本、脱敏 trace 和错误类型。

get-help 页面当前把 API Reference 链到 Python，而本栏是 JavaScript；这是文档缺陷，不代表 JS 无 reference。类似语言混入应通过 JS reference 和 TypeScript compiler 纠正。

路由闭包

/test（sitemap）与 /test/index（llms）当前均 HTTP 200 且正文相同；两条可点击入口都列入 sources，但不重复创造知识点。

逐页覆盖

延伸

• 08-TypeScript-Errors-and-Troubleshooting
• 06-TypeScript-Frontend-and-Generative-UI
• Python 对照