第2章：用模板快速搭建第一个工具调用型 Agent（以 Email Assistant 为例）

本章目标（1-2 句） 用 LangSmith Agent Builder 的模板（Templates）在 10–20 分钟内搭建一个“能真实调用工具”的 Agent，并完成：密钥/授权配置 → 启动测试对话 → 通过审批（approval）安全执行动作。
核心概念与机制（要准确，必要时引用官方定义）
1. 模板（Templates）= 可运行的“预配置 Agent” 官方说明模板是为特定用例设计的预配置 agents，通常包含：预配置工具（pre-configured tools）、系统指令（system instructions）以及可选触发器（triggers）；你可以直接使用，或作为基线继续定制。 参考：https://docs.langchain.com/langsmith/agent-builder-templates
2. 工具（Tools）与集成方式：OAuth vs Workspace Secrets Agent Builder 内置多类工具（Gmail / Google Calendar / Slack / GitHub / Search 等）；官方明确：Google、Slack、Linear、GitHub、LinkedIn 通过 OAuth 授权；而 Exa、Tavily 等需要在 workspace secrets 里配置 API Key。 参考：https://docs.langchain.com/langsmith/agent-builder-tools
3. Workspace Secrets 与 AGENT_BUILDER_ 前缀的优先级 Agent Builder 运行时从 workspace secrets 读取模型/工具密钥；官方特别指出：以 AGENT_BUILDER_ 开头的 secrets 会优先于通用同名 secrets（例如同时存在 OPENAI_API_KEY 与 AGENT_BUILDER_OPENAI_API_KEY 时，后者优先）。 参考：https://docs.langchain.com/langsmith/agent-builder-setup
4. 审批（Approvals）与“可控执行” Quickstart 明确：在测试对话中，agent 会在需要你批准的步骤提供 “Continue” 选项，从而让你对敏感工具调用保持控制权。 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
5. 授权中断与自动恢复（Auth-aware tool responses） 对需要 OAuth 的工具，官方文档说明 Agent Builder 有中间件可检测“工具需要授权”的响应，暂停执行并提示完成授权；授权后会自动重试同一个 tool call。 参考：https://docs.langchain.com/langsmith/agent-builder-auth-format
操作步骤/流程（用项目符号或编号） 下面按官方 quickstart 的 Email Assistant 路线走一次“可落地最小闭环”：
1. 配置模型密钥（必做）
  - LangSmith → Settings → Secrets
  - 添加 OPENAI_API_KEY 或 ANTHROPIC_API_KEY -（可选）用 AGENT_BUILDER_OPENAI_API_KEY / AGENT_BUILDER_ANTHROPIC_API_KEY 做隔离与统计 参考：
  - https://docs.langchain.com/langsmith/agent-builder-setup
  - https://docs.langchain.com/langsmith/agent-builder-quickstart
2. 进入 Agent Builder → 选择模板
  - 在 LangSmith 左侧导航顶部点击 “Switch to Agent Builder”
  - 左侧进入 Templates，选择 Email Assistant，点击 “Use this template” 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
3. 授权 Google 账号（Gmail / Calendar 等）
  - Agent 提示连接 Google：Connect → OAuth → Allow
  - 完成后回到 LangSmith，agent 创建完成 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
4. 检查工具清单与权限策略
  - 确认 Gmail 工具已启用（读邮件、打标签、草稿/发送等）
  - 对“写操作”（发送邮件、创建日历事件）建议默认开启 approvals 参考：https://docs.langchain.com/langsmith/agent-builder-tools
5. Test Chat 验证工具调用 + 审批流程
  - 右侧 Test Chat 输入类似指令： “给需要我复核的邮件打上 ‘Review’ 标签”
  - 观察是否出现“Continue”审批点并逐步批准 参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
6. 保存与迭代（Iterate）
  - 收紧 instructions（过滤条件、时间窗、输出格式）
  - 新增工具时遵循“读优先自动、写默认审批”的策略 参考：https://docs.langchain.com/langsmith/agent-builder-templates

示例（代码或伪代码，尽量短但能运行；若涉及配置也写出） 本示例演示：把你在 UI 里创建好的 Email Assistant（Agent Builder agent）当作一个部署在 Agent Server 上的 assistant，从 Python 侧通过 LangGraph SDK 发起一次 run，并读取 thread state。

安装依赖

1	pip install langgraph-sdk python-dotenv

写入环境变量（.env）

1	LANGGRAPH_API_KEY=your_langsmith_personal_access_token

运行脚本（将 AGENT_ID 与 API_URL 替换为 Agent Builder 页面 “View code snippets” 中的值）

   import os
   import asyncio
   from dotenv import load_dotenv
   from langgraph_sdk.client import get_client
   
   load_dotenv()
   
   API_URL = "your-api-url"
   AGENT_ID = "your-agent-id"  # Agent Builder agent 的 UUID
   USER_MESSAGE = "把今天收到、需要我复核的邮件打上 Review 标签，并给我一个汇总。"
   
   async def main():
       api_key = os.getenv("LANGGRAPH_API_KEY")
       if not api_key:
           raise RuntimeError("Missing LANGGRAPH_API_KEY")
   
       client = get_client(
           url=API_URL,
           api_key=api_key,
           headers={"X-Auth-Scheme": "langsmith-api-key"},
       )
   
       # 1) 创建 thread（用于保留状态/对话历史）
       thread = await client.threads.create()
       thread_id = thread["thread_id"]
   
       # 2) 启动一次 run（把 AGENT_ID 作为 assistant_id 传入）
       run = await client.runs.create(
           thread_id,
           AGENT_ID,
           input={"messages": [{"role": "user", "content": USER_MESSAGE}]},
       )
   
       # 3) 等待 run 完成，然后读取 thread 的最新状态
       await client.runs.join(thread_id, run["run_id"])
       state = await client.threads.get_state(thread_id)
   
       messages = state.get("values", {}).get("messages", [])
       print("messages_len:", len(messages))
       if messages:
           print("last_message:", messages[-1])
   
   if __name__ == "__main__":
       asyncio.run(main())

常见坑与排查（至少 2 条）
1. 缺少搜索类工具密钥导致运行失败：启用 Exa/Tavily 后报“missing API key / secret not found”。
  - 排查：按 workspace setup 添加 EXA_API_KEY、TAVILY_API_KEY 等 workspace secrets；注意 key 名必须与文档一致。 参考：https://docs.langchain.com/langsmith/agent-builder-setup
2. OAuth 未完成/过期导致工具调用暂停：Gmail/Slack/GitHub 工具调用时提示需要授权。
  - 排查：按 quickstart 重新走 OAuth；Agent Builder 支持“检测授权→暂停→授权后自动重试”。 参考：
  - https://docs.langchain.com/langsmith/agent-builder-quickstart
  - https://docs.langchain.com/langsmith/agent-builder-auth-format
3. 写操作未加 approvals，造成误发送/误创建：对发送邮件/建会等写操作启用 approvals。参考：https://docs.langchain.com/langsmith/agent-builder-quickstart
适用场景/最佳实践（至少 2 条）
1. 从模板起步，先跑通“密钥-授权-审批”闭环再优化：模板自带 instructions + tools（可能还有 triggers），适合快速验证链路，再逐步删减工具、收紧权限。参考：https://docs.langchain.com/langsmith/agent-builder-templates
2. 工具最小化 + 权限分层：只启用必要工具；读操作尽量自动，写操作默认审批，降低误操作面。参考：https://docs.langchain.com/langsmith/agent-builder-tools
3. 把 Agent Builder 当作“可部署 assistant”来集成：UI 快速迭代，应用侧用 LangGraph SDK 触发 runs。参考：https://docs.langchain.com/langsmith/agent-builder-code
本章小结（1-2 句） 你已经跑通：模板创建 → secrets 与 OAuth 配置 → Test Chat 中通过 approvals 安全执行 →（可选）从代码侧触发一次 run 并读取结果。
参考链接/引用（至少 2 条，官方优先）