学习笔记 · Obsidian
Tools：外部能力与副作用治理
核心模型
LangChain tool 是“输入由模型生成、输出再交给模型”的可调用能力，toolkit 是一组协同工具。统一包装只统一了调用形状，不会统一权限、事务、幂等、超时、费用或数据保留语义。搜索是只读候选能力；发邮件、建日历、执行 SQL、运行代码、付款和链上交易则是不同风险等级的真实副作用。
/tools 与 /tools/index 当前是同正文别名。索引按搜索、代码解释器、生产力、浏览器、数据库、金融等类别列出大量官方与社区生态项；下载量和出现在索引中都不是安全认证或生产支持承诺。
路由覆盖与能力地图
平台工具、浏览器与代码执行
| 路由 | 安装/入口 | 能力与边界 |
|---|---|---|
tools、tools/index | 生态索引 | 解释 tool/toolkit，按类别发现集成；不提供跨 provider 的可靠性保证。 |
azure_ai | langchain-azure-ai，AzureAIProjectToolbox | Foundry 项目内的图像、转写、代码解释器、Web/File Search、MCP；builtin 工具只对 Foundry 项目中部署的 OpenAI 模型生效。 |
azure_ai_services | langchain-azure-ai | Content Understanding、Document Intelligence、图像分析、医疗文本、STT/TTS；使用 Azure 托管服务。 |
azure_dynamic_sessions | langchain-azure-dynamic-sessions | Hyper-V 隔离 Python REPL、文件上传和图像结果；文件进入 session 的 /mnt/data/，页面示例为同步工具调用。 |
azure_logic_apps | langchain-azure-ai[tools] | 调用预配置 Logic App 工作流，可触发通知、同步和多步骤业务流程。 |
bedrock_agentcore_browser | langchain-aws，另需 Playwright/BeautifulSoup | 托管 Chrome 导航、点击、表单、抽取、截图；proxy、S3 extension、持久 profile 会扩大网络和身份边界。 |
bedrock_agentcore_code_interpreter | langchain-aws | 托管 Python/JavaScript/TypeScript 沙箱，文件、安装包和异步 task；状态按 thread_id 隔离。 |
databricks | databricks-langchain、SDK、LangGraph、MLflow | 把 Unity Catalog SQL/Python function 暴露为工具；函数和参数注释是模型调用契约，默认执行等待为 120 秒。 |
AgentCore browser/toolkit 创建是同步的，调用可 ainvoke，cleanup() 必须 await。同一 thread_id 并发访问会抛 RuntimeError，不同 thread 才能并发；结束后必须 cleanup。Code Interpreter 同样需要 thread 隔离和清理。隔离环境降低主机风险，但不自动阻止数据外传、恶意依赖、过量算力、SSRF 或凭证滥用。
外部账户与高风险动作
| 路由 | 包/认证 | 可见副作用 |
|---|---|---|
cdp_agentkit | coinbase-agentkit、coinbase-agentkit-langchain；CDP key ID/private key | 转账、交易、合约交互、token/NFT 部署等链上操作，具体动作取决于 action providers。 |
composio | composio、composio-langchain；COMPOSIO_API_KEY + 用户 OAuth | 1,000+ toolkit 的发现、认证、执行、trigger/webhook；稳定 user_id 隔离每个用户连接。 |
discord | langchain-discord-shikenso；bot token | 读取频道消息和发送消息。 |
google_calendar | langchain-google-community[calendar]；OAuth | 搜索、创建、更新、移动和删除日历事件；可明确使用 readonly scope。 |
google_drive | langchain-googledrive；credentials.json/token.json | 搜索 Drive/Docs；首次认证会在配置目录生成 token 文件。 |
google_gmail | langchain-google-community[gmail]；OAuth | 读邮件/线程、建草稿、发送等；示例的 mail.google.com scope 很宽，生产应缩到所需 scope。 |
privy | langchain-privy；server-side app secret | 自动创建/复用钱包、查余额、签名并发送交易。 |
stripe | stripe-agent-toolkit；Stripe secret key | 创建产品、价格、payment link 等真实支付对象。 |
tableau | langchain-tableau；connected-app JWT | 查询已发布 datasource；需要 VizqlDataApiAccess 权限。 |
这些工具必须在服务端把用户身份映射到独立凭证或连接，模型不可提供 tenant、scope、wallet、account 等授权事实。读取和写入工具应拆开注册；付款、发信、删除、交易和外部发布至少要求策略校验与 HITL，执行请求使用业务幂等键并记录审批前后参数。
搜索、抽取与长期任务
| 路由 | 包 | 返回/执行模式 |
|---|---|---|
exa_search | langchain-exa | 搜索、相似页面和 Retriever；TextContentsOptions.max_length 已弃用，改用 max_characters。 |
google_search | langchain-google-community | Programmable Search 的文本或带 metadata 结果。 |
parallel_search | langchain-parallel | 一次返回结构化网页 excerpts；旧名 ParallelWebSearchTool 只是别名。 |
parallel_extract | langchain-parallel | URL 内容/聚焦 excerpts；逐 URL 返回错误，call-level full-content 配置覆盖 tool default。 |
parallel_findall | langchain-parallel | 按目标和全部布尔条件发现实体，可排除已见候选、取消任务。 |
parallel_monitor | langchain-parallel | 1 小时到 30 天周期监控，支持 polling 或 webhook，CRUD/event 有 a* 异步版本。 |
parallel_task | langchain-parallel | research-grade 长任务、deep research、group、enrichment、BYO MCP；run/arun，高阶 tier 可能数分钟以上。 |
perplexity_search | langchain-perplexity | 排序且带来源的 Search API 结果。 |
tavily_search | langchain-tavily | 搜索结果、内容、图片和可选 answer。 |
tavily_map | langchain-tavily | 只发现站点 URL，不抽正文。 |
tavily_crawl | langchain-tavily | 从起始 URL 结构化遍历并抽取。 |
tavily_extract | langchain-tavily | 对一个或多个 URL 抽取内容。 |
unstructured_transform | langchain-unstructured-transform | 通过托管 MCP 请求上传 URL、转换、轮询、取结果；每文件 ≤50 MB、每请求 ≤10 文件、最多 5 个并发请求。 |
upstage_groundedness_check | langchain-upstage | 对 response/context 做 groundedness 检查；是质量信号，不是事实证明。 |
Parallel Search/Extract/FindAll 提供 ainvoke；Monitor 的异步方法以 a 前缀；Task Group 有 arun。长任务应用 webhook 时必须验证 PARALLEL_WEBHOOK_SECRET，事件去重并能恢复漏投。Parallel 文档明确建议分钟级 research 使用 webhook，而不是阻塞 invoke。Unstructured 的 MCP tool 装载本身是异步的，使用 aget_tools()/aget_transform_tools()；它返回完成后的 job 结果，不是 token 级流式解析。
Web 搜索和网页内容都属于不可信输入：必须保留 URL/发布日期等 provenance，过滤 prompt injection，不允许页面文字扩大工具权限，也不能把 provider 摘要直接当已核验事实。
数据、媒体与企业服务
| 路由 | 包 | 主要能力 |
|---|---|---|
google_cloud_texttospeech | langchain-google-community | TextToSpeechTool 生成音频；旧 GoogleCloudTextToSpeechTool 位于不再维护的 langchain-community。 |
google_imagen | langchain-google-vertexai | 图像生成、编辑、caption、VQA；VQA 当前仅单轮。 |
ibm_watsonx | langchain-ibm | 按 watsonx Cloud/Software 环境发现并执行 toolkit；可用工具集合会变化。 |
ibm_watsonx_sql | langchain-ibm[sql-toolkit] | 通过 Flight 服务执行模型生成 SQL；官方明确要求最小数据库权限。 |
mcp_toolbox | toolbox-langchain | 从 MCP Toolbox 装载数据库工具并交给 agent；索引标注可执行任意 SQL。 |
oracleai | langchain-oracledb | 用 OracleSummary 在 Oracle AI Database 侧生成文档摘要。 |
SQL 工具默认使用只读账号、限定 schema/view、语句类型和行数，设置 statement timeout，并在执行层解析/拒绝 DDL、DML、跨库访问与注释绕过。示例中的 allow 或自然语言提示不是安全控制。生成摘要、语音和图像时还要处理原始内容出境、区域、保留周期、版权与内容政策。
认证边界
- Azure 页面优先
DefaultAzureCredential，生产用 Managed Identity 或显式最小权限 credential；不要让本地 CLI 身份意外进入服务环境。 - AWS 使用标准 credential chain 和 IAM；Browser proxy 凭证放 Secrets Manager，S3 extension/profile 资源分别授权。
- Google Workspace 使用 OAuth scope；GCP 服务使用 ADC/项目 IAM。
credentials.json和自动生成的token.json都是敏感资产。 - API key 只通过 secret manager/环境注入，日志、trace、tool result 和错误中不得回显。
- Composio 的
user_id、Google/Discord channel、Stripe account、钱包 ID 都必须由服务端绑定，不接受模型自由指定跨租户目标。
生产执行协议
建议在工具适配层统一实现：
- 注册前分级：read、reversible-write、irreversible/external；按用户、租户和会话动态给模型最小工具集。
- 调用前验证：结构化 schema、长度/枚举/URL/SQL 检查、服务端注入身份、费用与速率预算。
- 副作用门禁：高风险动作先生成可审阅计划，HITL 后再执行；重复提交使用 provider 或业务幂等键。
- 执行控制：connect/read/total timeout、有限重试、指数退避、circuit breaker、并发 semaphore；非幂等动作不盲重试。
- 结果收敛：大响应保存为受控 artifact，只把摘要和引用交给模型；区分 success、partial、rejected、unknown。
- 审计与恢复：记录 tool 名、授权主体、目标、审批、provider request ID、状态和耗时，但不记录秘密或不必要正文；异步 job/webhook 可对账与补偿。
验证边界
已逐页核对这 38 个路由的官方 Markdown、包名、示例接口和页面警告。未使用真实 Azure/AWS/Google/Stripe/区块链/搜索 provider 凭证运行，因此配额、区域、费用、side-effect 幂等和供应商当前 SLA 仍需在目标环境单独验证。