--- type: study status: verified created: 2026-08-11 updated: 2026-08-11 sensitivity: standard tags: - study - langchain - python - integrations - tools - security topic: LangChain Python 工具集成与外部副作用治理 sources: - https://docs.langchain.com/oss/python/integrations/tools - https://docs.langchain.com/oss/python/integrations/tools/azure_ai - https://docs.langchain.com/oss/python/integrations/tools/azure_ai_services - https://docs.langchain.com/oss/python/integrations/tools/azure_dynamic_sessions - https://docs.langchain.com/oss/python/integrations/tools/azure_logic_apps - https://docs.langchain.com/oss/python/integrations/tools/bedrock_agentcore_browser - https://docs.langchain.com/oss/python/integrations/tools/bedrock_agentcore_code_interpreter - https://docs.langchain.com/oss/python/integrations/tools/cdp_agentkit - https://docs.langchain.com/oss/python/integrations/tools/composio - https://docs.langchain.com/oss/python/integrations/tools/databricks - https://docs.langchain.com/oss/python/integrations/tools/discord - https://docs.langchain.com/oss/python/integrations/tools/exa_search - https://docs.langchain.com/oss/python/integrations/tools/google_calendar - https://docs.langchain.com/oss/python/integrations/tools/google_cloud_texttospeech - https://docs.langchain.com/oss/python/integrations/tools/google_drive - https://docs.langchain.com/oss/python/integrations/tools/google_gmail - https://docs.langchain.com/oss/python/integrations/tools/google_imagen - https://docs.langchain.com/oss/python/integrations/tools/google_search - https://docs.langchain.com/oss/python/integrations/tools/ibm_watsonx - https://docs.langchain.com/oss/python/integrations/tools/ibm_watsonx_sql - https://docs.langchain.com/oss/python/integrations/tools/index - https://docs.langchain.com/oss/python/integrations/tools/mcp_toolbox - https://docs.langchain.com/oss/python/integrations/tools/oracleai - https://docs.langchain.com/oss/python/integrations/tools/parallel_extract - https://docs.langchain.com/oss/python/integrations/tools/parallel_findall - https://docs.langchain.com/oss/python/integrations/tools/parallel_monitor - https://docs.langchain.com/oss/python/integrations/tools/parallel_search - https://docs.langchain.com/oss/python/integrations/tools/parallel_task - https://docs.langchain.com/oss/python/integrations/tools/perplexity_search - https://docs.langchain.com/oss/python/integrations/tools/privy - https://docs.langchain.com/oss/python/integrations/tools/stripe - https://docs.langchain.com/oss/python/integrations/tools/tableau - https://docs.langchain.com/oss/python/integrations/tools/tavily_crawl - https://docs.langchain.com/oss/python/integrations/tools/tavily_extract - https://docs.langchain.com/oss/python/integrations/tools/tavily_map - https://docs.langchain.com/oss/python/integrations/tools/tavily_search - https://docs.langchain.com/oss/python/integrations/tools/unstructured_transform - https://docs.langchain.com/oss/python/integrations/tools/upstage_groundedness_check last_verified: 2026-08-11 --- # 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 都必须由服务端绑定，不接受模型自由指定跨租户目标。 ## 生产执行协议 建议在工具适配层统一实现： 1. **注册前分级**：read、reversible-write、irreversible/external；按用户、租户和会话动态给模型最小工具集。 2. **调用前验证**：结构化 schema、长度/枚举/URL/SQL 检查、服务端注入身份、费用与速率预算。 3. **副作用门禁**：高风险动作先生成可审阅计划，HITL 后再执行；重复提交使用 provider 或业务幂等键。 4. **执行控制**：connect/read/total timeout、有限重试、指数退避、circuit breaker、并发 semaphore；非幂等动作不盲重试。 5. **结果收敛**：大响应保存为受控 artifact，只把摘要和引用交给模型；区分 success、partial、rejected、unknown。 6. **审计与恢复**：记录 tool 名、授权主体、目标、审批、provider request ID、状态和耗时，但不记录秘密或不必要正文；异步 job/webhook 可对账与补偿。 ## 验证边界 已逐页核对这 38 个路由的官方 Markdown、包名、示例接口和页面警告。未使用真实 Azure/AWS/Google/Stripe/区块链/搜索 provider 凭证运行，因此配额、区域、费用、side-effect 幂等和供应商当前 SLA 仍需在目标环境单独验证。