第1章：Agent Builder 是什么，以及为什么它是“最新推出”的（GA 里程碑）

本章目标（1-2 句） 让你对 LangSmith Agent Builder 的定位、能力边界与“最新推出”的证据形成一致认知，并完成“可开始动手”的最小准备（账号、密钥、入口与调用方式）。
核心概念与机制（要准确，必要时引用官方定义）
1. 产品定位：no-code agents LangSmith Agent Builder 的官方定义是：“Create helpful AI agents without code（无需写代码创建 AI Agent）”；你可以从模板出发或用自然语言描述目标，让系统生成可运行的 Agent 配置，并在关键动作上通过“审批”保持人类控制权。 参考：https://docs.langchain.com/langsmith/agent-builder
2. “最新推出”的含义：从 Beta → GA 的发布阶段跃迁 官方在 2026-01-13 发布 GA 公告，明确 Agent Builder “now generally available”，并描述其从“描述目标 → 引导方案 → 生成详细指令、工具选择、必要时使用 subagents → 部署”的端到端路径。对企业/团队而言，GA 通常意味着可用性、支持与商业化策略进入更稳定阶段，因此在“最新推出”语境下，GA 是最关键、最可验证的最新发布节点。 参考：https://www.blog.langchain.com/langsmith-agent-builder-generally-available/
3. 底层实现主线：Deep Agents（deepagents）与 LangGraph 官方在 2025-10-29 的介绍文章里说明：当时的 LangSmith Agent Builder built on top of deepagents，并强调 Deep Agents 提供 planning、persistent memory、sub-task decomposition 等能力，使得用户无需手工绘制每个分支流程。 参考：https://www.blog.langchain.com/langsmith-agent-builder/ 同时，Deep Agents 官方文档将其定义为一个 “agent harness”，并强调它是建立在 LangGraph 之上的独立库，包含规划、文件系统式上下文管理、子代理等能力。 参考：https://docs.langchain.com/oss/python/deepagents/overview
4. 与开发者生态的衔接：Agent Server + LangGraph SDK Agent Builder 生成的 agent 运行在 Agent Server 上，并可通过 LangGraph SDK 从 Python/TypeScript 侧调用。这意味着：
  - 业务同学可以 no-code 搭建；
  - 工程团队可以把 agent 作为服务集成到应用、触发器或工作流中（例如后续章节会讲到：Webhook/定时任务/Slack 触发等）。 参考：https://docs.langchain.com/langsmith/agent-builder-code
操作步骤/流程（用项目符号或编号） 下面给出你在第 1 天最应该完成的最小闭环（MVP）路径：
1. 准备 LangSmith 账号与模型密钥
  - 打开 LangSmith（smith.langchain.com），进入 Settings → Secrets
  - 添加你使用的模型提供方密钥，例如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY（按官方 quickstart） 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
2. 进入 Agent Builder 入口
  - 在 LangSmith 左侧导航中，点击 “Switch to Agent Builder”（官方 quickstart 明确该入口）
  - 选择一种创建方式：
    - Template（模板）起步：适合快速落地
    - Chat（自然语言）起步：适合从“需求描述”生成配置
    - Manual（手工配置）起步：适合对工具/权限/审批粒度有严格要求 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
3. 完成一次最小测试对话（强烈建议）
  - 在右侧 Test Chat 里输入一条简单任务指令
  - 观察 agent 是否会在关键动作前请求审批（approval），并确认工具连接是否正常（例如 Gmail/Calendar 等需要 OAuth） 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
4. （可选，但推荐）生成调用代码片段，确保可“工程化集成”
  - 打开 agent 设置 → View code snippets
  - 记录 agent_id 与 api_url，后续章节会用它们做部署、A/B 测试、以及与 LangSmith Tracing/Evals 的结合 参考：https://docs.langchain.com/langsmith/agent-builder-code

示例（代码或伪代码，尽量短但能运行；若涉及配置也写出） 这个示例的目标不是“构建 agent”（那在 UI 完成），而是验证：你已经可以在代码里通过 LangGraph SDK 读到 Agent Builder agent 的元信息，为后续“应用集成/触发执行”打基础。
1）安装依赖

1	pip install langgraph-sdk python-dotenv

2）写入 .env（使用 LangSmith Personal Access Token）

1	LANGGRAPH_API_KEY=your-personal-access-token

3）Python：读取 agent 元信息（官方示例改写为最小可运行版）

   import os
   import asyncio
   from dotenv import load_dotenv
   from langgraph_sdk.client import get_client
   
   load_dotenv()
   
   AGENT_ID = "your-agent-id"  # 从 Agent Builder -> settings -> View code snippets 获取
   API_URL = "your-api-url"    # 同上
   
   async def main():
     api_key = os.getenv("LANGGRAPH_API_KEY")
     if not api_key:
       raise RuntimeError("Missing LANGGRAPH_API_KEY in environment")
   
     client = get_client(
       url=API_URL,
       api_key=api_key,
       headers={"X-Auth-Scheme": "langsmith-api-key"},
     )
   
     agent = await client.assistants.get(AGENT_ID)
     print("Agent name:", agent.get("name"))
     print("Agent id:", agent.get("id"))
   
   if __name__ == "__main__":
     asyncio.run(main())

关键点：X-Auth-Scheme: langsmith-api-key 与 PAT 绑定关系是 Agent Builder 调用成功的前提（详见官方文档）。参考：https://docs.langchain.com/langsmith/agent-builder-code

常见坑与排查（至少 2 条）
1. “创建后无法运行/模型不响应”：多数是没在 LangSmith workspace 里配置模型密钥（Secrets）。
  - 排查：Settings → Secrets 是否存在 OPENAI_API_KEY / ANTHROPIC_API_KEY 等，并且 key 名与官方要求一致。 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
2. “从代码调用返回 404 Not Found”：官方明确指出，如果 PAT 不是 agent 所有者账户 的 token，请求可能被拒绝并出现 404。
  - 排查：确认 PAT 归属；确认你调用的是你有权限访问的 agent；确认加了 X-Auth-Scheme: langsmith-api-key。 参考：https://docs.langchain.com/langsmith/agent-builder-code
3. “把 Vertex AI Agent Builder 当作 LangChain Agent Builder”：产品名相似但体系不同，会导致你跟着错误文档走。
  - 排查：确认你在 smith.langchain.com 的 Agent Builder 界面；文档域名是否为 docs.langchain.com / blog.langchain.com。 参考：https://docs.cloud.google.com/agent-builder/agent-engine/develop/langgraph
适用场景/最佳实践（至少 2 条）
1. 最佳场景：跨多应用的“标签页跳转型”日常工作自动化 官方 GA 公告点名了 daily briefings、research、project tracking 等跨工具任务；这类任务通常具备“输入是自然语言目标、输出是多步动作与工件”的特征，适合 Agent Builder 以“规划 + 工具调用 + 审批”的方式落地。参考：https://www.blog.langchain.com/langsmith-agent-builder-generally-available/
2. 先用模板收敛需求，再用“对话式修改”迭代 Agent Builder 官方文档强调从模板或自然语言开始，并可在运行中迭代配置。建议第一天先选模板把工具链跑通，再逐步收紧权限与审批策略，避免上来就做“大而全 agent”。 参考：https://docs.langchain.com/langsmith/agent-builder-templates 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
本章小结（1-2 句） 你现在应当明确：本文所说的 “Agent Builder” 指 LangSmith Agent Builder，并且其“最新推出”的关键证据是 2026-01-13 的 GA 公告。完成本章后，你已经具备在 UI 创建 agent、并在代码侧通过 LangGraph SDK 访问 agent 的最小能力。
参考链接/引用