人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载本指南以 Hive 仓库内 Zoho CRM Tool 官方文档 为核心系统讲解如何通过 MCPModel Context Protocol工具让 AI Agent 直接操作 Zoho CRM搜索记录、按 ID 读取、新建与更新 Leads / Contacts / Accounts / Deals 记录并为任意记录添加备注。读完本文你将掌握该工具的全部 5 个 Phase 1 工具的参数用法、基于 OAuth2 refresh token 的免维护认证配置、区域Data Center路由规则以及响应格式与测试方法。一、工具概述Agent 直接操作 Zoho CRMZoho CRM Tool 是 Hive 项目中 Aden Tools 工具集的一员代码位于 tools/src/aden_tools/tools/zoho_crm_tool/zoho_crm_tool.py通过 Zoho CRM API 为 Hive Agent 提供以下能力按关键词word或条件表达式criteria搜索记录获取、创建、更新 Leads、Contacts、Accounts、Deals 模块中的记录为任意受支持记录添加 Notes 备注。该工具以 MCP 工具的形式注册到 FastMCP 服务器上因此 Agent 可以像调用本地函数一样调用 Zoho CRM 的 REST API无需关心 HTTP 细节。工具通过 tools/mcp_server.py 中的register_all_tools()统一装载并在 tools/src/aden_tools/tools/init.py 中以register_zoho_crm(mcp, credentialscredentials)的方式注册当前位于 unverified/社区集成分组中可通过include_unverifiedTrue开启。二、可用工具清单Phase 1按官方文档定义Phase 1 提供五个 MCP 工具工具名功能必填参数zoho_crm_search在模块中搜索记录criteria或word二选一modulezoho_crm_get_record按 ID 获取单条记录module,idzoho_crm_create_record创建新记录module,datazoho_crm_update_record更新已有记录module,id,datazoho_crm_add_note为记录添加备注Leads、Contacts、Accounts、Dealsmodule,id,note_title,note_content实现说明从当前源码结构看zoho_crm_tool.py 实际注册的工具集合为zoho_crm_list_records、zoho_crm_get_record、zoho_crm_create_record、zoho_crm_search_records、zoho_crm_list_modules、zoho_crm_add_note六个其中zoho_crm_update_record已在凭据规范 zoho.py 的工具清单中列出但尚未在当前版本的工具模块中注册。文档约定的工具语义与源码注册集合大体一致实际可用工具名以你本地拉取版本的register_tools实现为准。三、认证与配置OAuth2 授权流程详解Zoho CRM 使用 OAuth2 认证。官方文档明确了一个核心设计原则正常使用场景下用户不需要把 access token 交给工具只需一次性提供应用级凭据工具内部负责换取并自动刷新 access token。3.1 用户需要一次性提供的内容refresh 流程以下四个环境变量或其中一组等价配置需要在首次使用时从 Zoho API Console 获取并设置环境变量是否必填说明ZOHO_CLIENT_ID必填refresh 流程来自 Zoho API Console → 你的客户端应用ZOHO_CLIENT_SECRET必填refresh 流程来自 Zoho API Console → 你的客户端应用ZOHO_REFRESH_TOKEN必填refresh 流程通过一次性 OAuth 授权或 Self Client 流程生成ZOHO_ACCOUNTS_DOMAIN或ZOHO_REGION必填refresh 流程指定区域ZOHO_ACCOUNTS_DOMAIN填完整 URL或ZOHO_REGION填区域代码其中ZOHO_REGION只接受精确代码in、us、eu、au、jp、uk、sg大小写敏感必须完全一致。凭据规范 zoho.py 中同样强调这些代码 exact codes only并提供了相同的能力映射。3.2 仅使用 access token快速测试场景如果只想快速验证连通性也可以直接提供 access token有效期约 1 小时过期后需要重新生成环境变量何时设置ZOHO_API_DOMAIN强烈建议设置为你所在区域的 API 域名例如https://www.zohoapis.in若省略代码默认回退到https://www.zohoapis.com美国区从源码看当前工具实现对应地支持ZOHO_CRM_ACCESS_TOKEN与ZOHO_CRM_DOMAIN两个环境变量见 zoho_crm.py 与_base_url()的实现domain os.getenv(ZOHO_CRM_DOMAIN, www.zohoapis.com)默认即美国区 API 域名。凭据提供方可以是环境变量也可以是注入的CredentialStoreAdapter_get_token()优先从凭据存储读取zoho_crm条目否则回退到环境变量。3.3 系统自动完成的部分使用 refresh 流程时工具或凭据存储会替你完成三件事换取 access token首次调用时用 refresh token 自动换取 access token用户永远不需要手动粘贴自动续期access token 约 1 小时过期工具在需要时随时用 refresh token 换取新 token用户无需“重新生成”区域路由token 交换完成后Zoho 会返回api_domain例如https://www.zohoapis.in后续所有 CRM API 调用都基于该域名路由自动匹配用户所在数据中心。3.4 快速开始bash 配置示例方式一refresh 流程推荐长期使用export ZOHO_CLIENT_IDyour_client_id export ZOHO_CLIENT_SECRETyour_client_secret export ZOHO_REFRESH_TOKENyour_refresh_token # 以下二选一 export ZOHO_ACCOUNTS_DOMAINhttps://accounts.zoho.in # 或 .com / .eu 等 export ZOHO_REGIONin # 合法值in, us, eu, au, jp, uk, sg方式二仅 access token快速测试export ZOHO_ACCESS_TOKEN1000.xxxx... export ZOHO_API_DOMAINhttps://www.zohoapis.in # 你的区域配置完成后按常规方式使用工具即可。首次调用会完成 refresh token 交换后续 CRM 调用均使用 Zoho 返回的api_domain你无需自己设置或刷新 access token。3.5 Credential Store可选生产环境推荐如需自动刷新与生产化部署可将 OAuth2 凭据写入凭据存储并注册 Zoho 提供方from framework.credentials import CredentialStore from framework.credentials.oauth2 import ZohoOAuth2Provider zoho_provider ZohoOAuth2Provider( client_idos.getenv(ZOHO_CLIENT_ID, ), client_secretos.getenv(ZOHO_CLIENT_SECRET, ), accounts_domainos.getenv(ZOHO_ACCOUNTS_DOMAIN, https://accounts.zoho.com), ) store CredentialStore.with_encrypted_storage(providers[zoho_provider])ZohoOAuth2Provider的实现位于 core/framework/credentials/oauth2/zoho_provider.py它针对 Zoho 做了三件定制预置区域化端点根据accounts_domain自动拼接{base}/oauth/v2/token与{base}/oauth/v2/auth默认 CRM 作用域ZOHO_DEFAULT_SCOPES覆盖 Phase 1 全部能力——ZohoCRM.modules.leads.ALL、ZohoCRM.modules.contacts.ALL、ZohoCRM.modules.accounts.ALL、ZohoCRM.modules.deals.ALL、ZohoCRM.modules.notes.CREATEZoho 专属鉴权头format_for_request()返回Authorization: Zoho-oauthtoken {access_token}不是 Bearer 前缀并带上Content-Type: application/json与Accept: application/json。其refresh()方法还会把 token 响应中的api_domain、accounts-server、location持久化到凭据对象中实现数据中心元数据的自动维护validate()则通过GET /crm/v2/users?typeCurrentUser做轻量校验该端点不要求模块访问权限且 429 被视为“有效但被限流”。四、源码级实现原理4.1 工具注册链路Zoho CRM 工具的装载链路为mcp_server.py→register_all_tools(mcp, credentials, include_unverified)→register_zoho_crm→zoho_crm_tool.register_tools(mcp, credentials)。register_tools内部使用mcp.tool()装饰器逐个注册工具函数工具函数签名即 MCP 工具的 JSON Schema 参数Agent 可以直接按参数名调用。4.2 HTTP 层与错误处理工具内部封装了_get/_post两个 HTTP 助手基于 httpx超时 30 秒并做了统一的错误规范化401→ 返回{error: Unauthorized. Check your ZOHO_CRM_ACCESS_TOKEN (may need refresh).}204→ 返回空数据{data: []}适用于无记录场景非 200/201→ 返回{error: fZoho CRM API error {status_code}: {resp.text[:500]}}截断响应体前 500 字符超时 / 网络异常→ 返回对应的{error: ...}结构保证 Agent 侧始终拿到可解析的字典而非抛异常。请求 URL 由_base_url()拼接https://{ZOHO_CRM_DOMAIN}/crm/v7默认www.zohoapis.com。需要说明的是官方文档描述的是 Zoho CRM API v8而当前仓库工具实现中的端点版本为/crm/v7见模块顶部注释两者在模块资源路径上保持一致实际以 Zoho 官方 API 版本演进为准。4.3 分页与搜索语义搜索工具zoho_crm_search_records强制要求criteria、email、phone、word至少提供一个对应 README 中 “The API requires at least one of: word, criteria, email, or phone” 的约束分页参数per_page通过max(1, min(per_page, 200))收敛到合法区间 1–200。列表与搜索响应都会携带page/per_page分页信息并在返回结构中透出more_records等翻页标记。五、工具使用详解以下五个小节完整继承官方文档的参数定义与示例可直接复制到你的 Agent 提示词或脚本中。5.1 zoho_crm_search —— 搜索模块记录按条件或关键词搜索指定模块中的记录。API 要求word、criteria、email、phone至少提供一个。参数参数类型必填默认值说明modulestr是—取值Leads、Contacts、Accounts、Dealscriteriastr否Zoho 条件表达式如(Email:equals:userexample.com)pageint否1页码per_pageint否200每页记录数1–200fieldslist[str]否—需要返回的字段 API 名称列表wordstr否可选的全文本搜索关键词示例# 按条件搜索 zoho_crm_search(moduleContacts, criteria(Email:equals:johnexample.com)) # 按关键词搜索 zoho_crm_search(moduleLeads, wordZoho, page1, per_page10)5.2 zoho_crm_get_record —— 按 ID 获取单条记录参数参数类型必填说明modulestr是Leads、Contacts、Accounts 或 Dealsidstr是记录 ID示例zoho_crm_get_record(moduleLeads, id1192161000000585006)5.3 zoho_crm_create_record —— 创建新记录使用字段 API 名称如First_Name、Last_Name、Company传值。实现中请求体会包装为 Zoho 要求的{data: [{...}]}结构返回结果会解析出id、status、message字段。参数参数类型必填说明modulestr是Leads、Contacts、Accounts 或 Dealsdatadict是字段 API 名称 → 值示例zoho_crm_create_record( moduleLeads, data{First_Name: Jane, Last_Name: Doe, Company: Acme Inc, Email: janeacme.com} )源码 docstring 还补充了各模块常见字段的速查Leads 常用Last_Name、Company、Email、PhoneContacts 常用Last_Name、Email、Phone、Account_NameDeals 常用Deal_Name、Stage、Amount、Closing_Date。5.4 zoho_crm_update_record —— 更新已有记录只发送需要修改的字段未提供的字段保持不变。参数参数类型必填说明modulestr是Leads、Contacts、Accounts 或 Dealsidstr是记录 IDdatadict是字段 API 名称 → 值示例zoho_crm_update_record(moduleLeads, id1192161000000585006, data{Description: Follow up next week})5.5 zoho_crm_add_note —— 为记录添加备注备注会显示在 Zoho CRM 中该记录的 Notes 区域。实现上通过POST {module}/{record_id}/Notes写入请求体为{data: [{Note_Title: ..., Note_Content: ...}]}。参数参数类型必填说明modulestr是父模块Leads、Contacts、Accounts、Dealsidstr是父记录 IDnote_titlestr是备注标题note_contentstr是备注正文示例zoho_crm_add_note( moduleLeads, id1192161000000585006, note_titleCall back, note_contentCustomer asked for pricing by Friday. )六、响应格式约定官方文档约定了统一的响应契约便于 Agent 侧做分支判断成功{success: true, id: ...|null, module: ..., data: ..., raw: {...}, ...}其中id在创建/更新类操作中返回记录 ID无 ID 场景为null失败{error: Description, retriable: true}retriable用于标识可重试错误如限流搜索分页响应中带more_records与next_page字段next_page在没有下一页时为null。从实现看当前工具返回结构与文档约定基本对齐列表/搜索类工具返回{module: ..., records/results: ..., count: ..., more_records: ..., page: ...}创建类工具返回{id: ..., status: ..., message: ...}错误统一为{error: ...}字典。无论哪种结构Agent 都应优先检查error键是否存在再做后续处理。七、测试验证官方文档提供了基于 mock HTTP 的单元测试命令注意文档中的测试路径指向工具包内 tests 目录而当前仓库实际将测试文件放在 tools/tests/tools/test_zoho_crm_tool.py运行时可使用实际存在的路径uv run pytest tools/tests/tools/test_zoho_crm_tool.py -v测试覆盖了以下关键场景可作为集成验证的参考清单缺少 token / 缺少 module验证参数校验与认证错误分支error键存在成功列表mock 200 响应断言module与records结构按 ID 获取mock 单条记录断言记录内容透传创建记录mock 201 响应status: success、details.id断言返回id与status搜索参数校验无任何搜索参数时返回错误提供word后成功返回结果模块列表透传api_name、module_name、plural_label、editable添加备注content 为空时报错正常请求返回status。所有测试均通过unittest.mock.patch替换 httpx 调用不依赖真实 Zoho 账号可在 CI 中稳定运行。八、小结Zoho CRM Tool 为 Hive Agent 提供了一个结构清晰、配置友好的 CRM 集成入口refresh token 流程让长期运行的生产 Agent 无需人工维护 access token区域路由通过ZOHO_REGION/ZOHO_ACCOUNTS_DOMAIN精确适配全球数据中心五个 Phase 1 工具覆盖了销售场景中最常用的搜索、读取、创建、更新与备注记录操作。配合 Credential Store 的加密存储与自动刷新这套集成可以直接嵌入 Sales 外呼、线索清洗、客户跟进等自动化工作流中。完整的 API 细节可进一步查阅官方文档的 README.md 及 ZohoOAuth2Provider 实现。赞分享人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载相关推荐在 PostHog 中通过 MCP 工具管理 Streamlit 应用完整生命周期实战指南在 PostHog 中通过 MCP 工具管理 Streamlit 应用完整生命周期实战指南 Streamlit 应用是运行在 PostHog 隔离沙箱中的 P数据分析后端前端数据可视化大数据OpenViking 可选 MCP 工具实战指南tree、write/edit 与 watch 生命周期管理OpenViking 可选 MCP 工具实战指南tree、write/edit 与 watch 生命周期管理 导读 OpenViking 通过 viking:人工智能AI AgentAgent 记忆RAG后端数据库openai-agents-python MCP 集成完全指南四类传输、托管工具与服务器生命周期管理openai agents python MCP 集成完全指南四类传输、托管工具与服务器生命周期管理 本篇指南基于 openai agents python人工智能AI AgentAgent 框架多智能体工具调用MCP Clients上一篇TinyDB类型注解详解提升代码可读性与健壮性的技巧下一篇微信读书助手wereader5分钟打造个人知识管理系统的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考