学习笔记 · Obsidian
外部 SaaS 搜索、通信与自动化工具
结论
- 这些集成的共同价值是把外部系统包装成 LangChain Tool；它们不替代应用层的 OAuth、租户隔离、发送审批、内容可信度判断或 webhook 验签。
- 搜索类产品在“发现 URL、提取正文、返回检索片段、完成深度研究”上的语义不同。应把结果结构、引用、时效和成本作为显式契约，不能只按工具名切换。
- 通信、仓库、工单等有副作用的工具默认应关闭；只有在目标对象、操作者和动作均通过业务授权后才开放。
集成能力地图
| 集成 | 核心能力 | 关键边界 |
|---|---|---|
| ClickSend | SMS、Email、Voice，经 MCP 接入 | 发送属于外部副作用；号码/地址、模板、费用与退订合规需应用控制 |
| Composio | 500+ toolkit、OAuth、多用户、trigger、custom tool | 必须用用户级 entity 隔离连接，生产 trigger 走验签 webhook |
| Decodo | 通用抓取、Google/Amazon 搜索、地域与 JS 渲染 | 代理访问和抓取需遵守站点政策；输出不可信 |
| Exa | 语义 Web 搜索与清洗内容 | Tool 返回搜索结果；Retriever 是另一种 Document[] 抽象 |
| JigsawStack | 抓取、搜索、语音转写、视觉 OCR、Text-to-SQL | Text-to-SQL 只生成语句，执行仍需只读账户和查询检查 |
| Nia | 索引/读取代码与文档、Web 搜索、上下文共享 | source sync 和 context save 会改变远端状态，应按租户授权 |
| Perplexity | 实时 grounded search | Tool 返回 JSON 字符串；Retriever 版本返回 Document[] |
| Tavily | Search、Map、Crawl、Extract | 四个端点的遍历和正文语义不同，响应规模配置不能全交给 agent |
| You.com | Search、Research、Contents | Research effort 会显著改变成本/延迟；Contents 要限制 URL |
Composio：连接层而非权限层
@composio/langchain 通过 Composio 与 LangchainProvider 获取 toolkit 或指定 action。生产设计要点：
defaultentity 仅适合单用户试验；多租户必须用稳定、不可猜测的用户/组织 subject 映射连接。- 获取整套 toolkit 会扩大模型动作空间，优先按 action allowlist 获取最少工具，并使用 fine-grained permissions。
- OAuth connection 创建只负责连接流程，业务仍需校验“此连接是否属于当前主体、是否允许当前动作”。
- 本地可直接订阅 trigger；生产应由 webhook 接收事件，完成签名、时间戳、防重放和幂等校验后再唤起 agent。
- standalone custom tool 不需要认证；toolkit-based custom tool 可使用已有连接凭据。自定义执行器不可把凭据暴露给模型或返回值。
Tavily 四种工作负载
| 工具 | 输入/输出 | 适用场景 |
|---|---|---|
| Search | query → 标题、URL、片段，可选原文/答案/图片 | 一次性事实检索 |
| Map | 起始 URL → 发现的 URL 列表，不抽正文 | 站点结构发现与覆盖清单 |
| Crawl | 起始 URL → 多页 URL、正文、图片等 | 有边界的站点遍历 |
| Extract | 一个或多个 URL → 清洗正文，可选图片 | 已知页面的内容抽取 |
Map/Crawl 的 maxDepth、maxBreadth、limit 与域名/路径过滤决定成本和攻击面；默认值也不等于安全值。Search 的 includeAnswer 与 includeRawContent 会影响上下文体积，因此文档明确不允许 agent 在 invocation 时动态改这两项。构造期配置应由服务端控制，agent 只调整允许的 query/filter 参数。
Exa、Perplexity、Nia 与 You.com 的选择
- Exa 强调 neural search 与清洗 HTML；
ExaSearchResults.invoke()可直接调用，也可接收ToolCall并返回ToolMessage。如需要统一检索链，优先相应 Retriever，而不是解析 Tool JSON。 - Perplexity Search Tool 返回 JSON 编码数组，字段含 title、url、snippet、date、last_updated；country、domain、recency 与日期范围应进行白名单/格式验证。
- NiaToolkit 暴露约 20 个工具，覆盖索引、读取、grep、repo tree、deep research 与 dependency subscribe。一次性把全部工具交给模型会增加上下文和权限，应按场景选择
includeSearch或单独实例化工具。 - You.com 的
youSearch做筛选搜索，youResearch生成带引用研究结果并有多档 effort，youContents抽取 URL 正文。对 Research 设置预算与截止时间，对 Contents 做 SSRF 防护。
通信与抓取安全
- ClickSend 之类发送工具采用“生成草稿 → 业务校验 → 人工确认 → 幂等发送”，不要让模型直接决定收件人和发送时机。
- 抓取 URL 仅允许
https，拒绝回环、链路本地、私网、云 metadata 地址及 DNS rebinding；重定向后重新校验。 - 搜索/网页返回中可能包含 prompt injection。把正文标记为证据数据，不赋予其修改工具规则的能力。
- 记录引用 URL、抓取时间和 provider request id；结论使用多个独立来源或权威主源复核。
- 外部 SaaS 统一配置熔断、429/5xx 有界退避、并发与月度预算；非幂等发送不得自动盲重试。
文档边界
- ClickSend 页面表格中的 “Python support” 链接实际回到 JavaScript 路由，不能据此认定 Python 已支持。
- 多数页面演示在代码中直接赋 API key；生产实现应由服务端 secret manager 或工作负载身份注入，且绝不进入前端 bundle、日志或笔记。
- 搜索结果“grounded”表示带检索依据，不表示内容正确、安全或适合自动执行。