---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - typescript
  - testing
  - observability
  - deployment
  - migration
topic: LangChain TypeScript 生产化、测试、可观测性、部署与迁移
sources:
  - https://docs.langchain.com/oss/javascript/langchain/changelog-js.md
  - https://docs.langchain.com/oss/javascript/langchain/deploy.md
  - https://docs.langchain.com/oss/javascript/langchain/get-help.md
  - https://docs.langchain.com/oss/javascript/langchain/observability.md
  - https://docs.langchain.com/oss/javascript/langchain/studio.md
  - https://docs.langchain.com/oss/javascript/langchain/test
  - https://docs.langchain.com/oss/javascript/langchain/test/evals.md
  - https://docs.langchain.com/oss/javascript/langchain/test/index.md
  - https://docs.langchain.com/oss/javascript/langchain/test/integration-testing.md
  - https://docs.langchain.com/oss/javascript/langchain/test/unit-testing.md
  - https://docs.langchain.com/oss/javascript/langchain/ui.md
  - https://docs.langchain.com/oss/javascript/langchain/voice-agent.md
last_verified: 2026-08-11
---
# 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` 提供：

| 模式 | 判断 | 适用 |
|---|---|---|
| `strict` | 消息结构、工具与顺序一致，文本可不同 | 必须遵循的合规流程 |
| `unordered` | 工具集合一致，顺序不限 | 并行/顺序无关检索 |
| `subset` | 实际不调用 reference 之外的工具 | 限制行为范围 |
| `superset` | 至少调用 reference 要求的工具 | 验证最低动作，允许额外步骤 |

还可用 `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

两种架构：

| 架构 | 优点 | 代价 |
|---|---|---|
| STT → text agent → TTS（sandwich） | 组件可替换、文本模型能力新、步骤可观测 | 多服务、丢失语气、编排复杂 |
| Native speech-to-speech | 链路短、保留音频细节、简单场景延迟低 | provider 锁定、模型少、控制与透明度弱 |

官方 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，但不重复创造知识点。

## 逐页覆盖

| 页面 | 学习结论 |
|---|---|
| Deployment | Cloud/GitHub/Studio/API/SDK 路径，JS framework/hosting 与多种托管模式。 |
| Observability | 自动/选择性 tracing、project、tags、metadata 和数据治理。 |
| Studio | CLI、Agent Server、langgraph.json、hot reload、replay 和 Safari tunnel。 |
| Test overview（两路） | unit、integration、eval 的职责；canonical/index 同文。 |
| Unit testing | fakeModel builder、tool/error/factory/structured response、calls 与 bindTools。 |
| Integration testing | Vitest 分组、secret、结构断言、自定义 matcher 与成本。 |
| Agent evals | 四种 trajectory match、LLM judge、LangSmith Vitest/Jest/evaluate。 |
| Agent Chat UI | hosted/local Next.js、agent 连接、tool/interrupt/time travel。 |
| Voice agent | sandwich/S2S、Node WebSocket 与 async STT-agent-TTS pipeline。 |
| Get help | 学习、社区、企业 support/status、贡献；JS 页误链 Python reference。 |
| Changelog | v1.0–v1.2、LangGraph 1.1、Deep Agents alpha 与独立版本/迁移边界。 |

## 延伸

- [[08-TypeScript-Errors-and-Troubleshooting]]
- [[06-TypeScript-Frontend-and-Generative-UI]]
- [Python 对照](../Python/07-Production-Testing-and-Migration.md)