Composio Zendesk 集成实战OAuth 子域名配置、工具版本查询与工单操作指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本篇技术指南以 Composio 开源仓库的知识库文档 docs/kb/source/toolkits/zendesk/public.md 为核心系统讲解在 Composio 中接入 Zendesk 账号的完整流程OAuth 与 API-key/Basic 两种认证方案的连接发起方式、subdomain与 base64 凭据的传递规则、通过toolkit_versions查询最新工具集的方法以及ZENDESK_SEARCH_ZENDESK、ZENDESK_UPDATE_ZENDESK_TICKET、按 ID 获取工单等核心工具与触发器能力。读完本文你将能够正确发起 Zendesk 连接、避开工具列表不完整等常见坑并直接调用工单相关动作构建自己的 AI 客服或工单处理 Agent。Zendesk 连接的两个关键前提在发起任何 Zendesk 连接之前需要先理解两个贯穿始终的前提条件它们决定了后续所有连接参数的正确写法。OAuth 流程自动注入访问令牌无需手动填写对于 Zendesk OAuthaccess token 会在 OAuth 流程完成后由 Composio 自动注入客户不需要手动输入访问令牌。这意味着在连接过程中你只需要完成浏览器侧的 OAuth 授权即可无需在代码或配置里准备 token 字段。Redirect URI重定向地址是否必填取决于 auth-config 的具体设置可以省略但如果 Zendesk 侧要求配置重定向地址则需要把 Composio 的 auth 重定向 URL 配置到 Zendesk OAuth 应用中。这一规则也同步记录在面向终端用户的知识库文章 docs/kb/articles/toolkits-zendesk.md 中。连接必须携带账号子域名subdomain而非完整 URLZendesk 在连接发起阶段要求提供账号子域名。需要注意传入的是 Zendesk 站点前缀site prefix不是完整 URL。Composio 会使用该字段来拼接 Zendesk API 请求地址。例如如果 Zendesk 站点完整地址是https://mycompany.zendesk.com那么subdomain字段应填写mycompany而不是https://mycompany.zendesk.com。传错这个字段会导致后续所有 Zendesk 工具调用无法正确解析目标站点。发起 Zendesk OAuth 连接subdomain的两种传参写法当你通过 SDK 发起 Zendesk OAuth 连接的 connected account 时必须把subdomain放进连接配置config values中。官方文档给出了当前 SDK 形态的推荐写法config{auth_scheme: OAUTH2, val: {subdomain: site-name}}其中site-name即上节提到的 Zendesk 站点前缀。而在早期版本中示例使用的是connected_account_params{subdomain: site-name}这种较旧的参数形状。如果你在旧文档或旧代码中看到connected_account_params应将其迁移到当前的config{auth_scheme:OAUTH2,val:{...}}写法。在 TypeScript SDK 侧同样的能力由connectedAccounts.initiate()方法承载仓库中的 Connected Accounts API 文档 ts/docs/api/connected-accounts.md 专门以 Zendesk 为例演示了需要额外参数的 OAuth 配置这一场景// For OAuth configs requiring additional parameters (e.g., Zendesk, PostHog) const zendeskConnection await composio.connectedAccounts.initiate(user_123, zendesk_auth_config, { config: AuthScheme.OAuth2({ subdomain: yout_subdomain_here }) }); // The redirectUrl is where the user should be redirected to authenticate (for OAuth flows) console.log(zendeskConnection.redirectUrl); // wait for the user to connect the account const connectedAccount await zendeskConnection.waitForConnection();可以看到TypeScript 侧通过AuthScheme.OAuth2({ subdomain: ... })这个类型安全的 helper 构造连接配置这与 Python 侧config{auth_scheme:OAUTH2,val:{subdomain:...}}的底层结构是对应的。initiate()返回的连接请求对象带有redirectUrl将用户重定向到该地址完成授权后再调用waitForConnection()等待连接进入活跃状态OAuth2 方案下连接状态会先置为INITIALIZING完成后转为ACTIVE。发起 Zendesk API-key/Basic 连接subdomain base64 凭据如果使用的是 API-key 或 Basic auth 认证方案连接发起时除了subdomain还需要传递一个basic_encoded凭据值subdomain与 OAuth 一致传入 Zendesk 站点前缀basic_encoded由 Zendesk 邮箱/令牌形式的凭据email/token credential form按 auth config 的要求做base64 编码后得到的字符串。也就是说basic_encoded不是原始邮箱或令牌而是邮箱:令牌等凭据组合形式经 base64 编码后的结果。具体编码哪种凭据组合取决于 auth config 所声明的凭据形式Zendesk 常见的 Basic 认证是email/token其中 token 为 API token。请按照对应 auth config 的要求拼装原始字符串后再编码避免直接传入明文邮箱导致鉴权失败。这类手动传参发起连接的通用 API 入口在 Python SDK 中由initiate_connection系列方法承担TypeScript 侧对应connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.Basic({...}) })见 ts/docs/api/connected-accounts.md 中的 Basic Auth 示例。Basic 方案发起后连接会直接进入ACTIVE状态无需等待 OAuth 回调。列出 Zendesk 工具必须带上toolkit_versions查询参数通过 API 列出 Zendesk 工具时必须包含 toolkit version 查询参数官方推荐的示例为toolkit_versionslatesttoolkit_slugzendesklimit1000如果不带 toolkit version 查询参数API 响应可能不会返回你预期的工具集。这一点在仓库中有多处印证Python SDK 的Toolset/工具集合对象在 python/composio/core/models/tools.py 中定义了toolkit_versions参数其文档注释明确写着The versions of the toolkits to use. Defaults to latest if not provided.即默认按latest解析SDK 入口 python/composio/sdk.py 中toolkit_versions被描述为 A dictionary mapping toolkit names to specific versions并通过get_toolkit_versions工具函数统一规范化同一知识库下的 docs/kb/articles/toolkits-google-analytics.md 也记录了类似现象旧版固定/默认版本暴露的工具数量可能远少于最新版本。因此在集成 Zendesk 时建议始终显式携带toolkit_versionslatest并在排查工具缺失问题时首先检查是否遗漏了该参数。Zendesk 的 toolkit slug 本身已在 CLI 生成的 ts/packages/cli/src/generated/toolkit-slugs.ts 中注册为zendesk可直接用于查询。核心工具动作搜索、更新工单与按 ID 获取工单Zendesk 工具集中有几个面向工单场景的关键动作可直接按名称引用ZENDESK_SEARCH_ZENDESKZendesk 搜索针对 Zendesk 搜索场景使用ZENDESK_SEARCH_ZENDESK。它适用于在不知道具体工单 ID、需要按关键词、状态、优先级等条件检索 Zendesk 数据工单、用户、组织等的场合是搜索型用例的专用动作。ZENDESK_UPDATE_ZENDESK_TICKET更新工单针对工单更新使用ZENDESK_UPDATE_ZENDESK_TICKET。从端点层面看它对应的是 Zendesk ticketing API 中的Update Ticket端点。适合在 Agent 需要修改工单字段如状态、指派人、优先级、评论时调用。按 ID 获取工单get-ticket-by-idZendesk 的 get-ticket-by-id 动作单次工具调用即可返回工单详情。适用场景是客户已经持有 Zendesk 工单 ID需要直接获取该工单的元数据/详情而不必先走搜索流程。它比先搜索再取详情更直接高效能节省一次工具调用。提示ZENDESK_SEARCH_ZENDESK与ZENDESK_UPDATE_ZENDESK_TICKET这类动作名同样需要配合toolkit_versionslatest使用——如果工具列表来自旧的固定版本可能取不到这些新动作这也是知识库文档反复强调版本参数的原因。触发器Triggers支持Zendesk 在 Composio 中支持触发器trigger能力可用于监听 Zendesk 侧的事件如新工单创建、工单状态变更并主动触发 Agent 流程。需要说明的是仓库文档明确建议在引用具体触发器数量之前先核对当前的触发器目录trigger catalog不要凭记忆写死某个数量。在实现层面Python SDK 的 Triggers 集合同样接受toolkit_versions参数见 python/composio/core/models/triggers.py这意味着拉取 Zendesk 触发器时也应考虑传入toolkit_versionslatest以确保拿到最新、完整的触发器集合。实操核查清单按本文内容落地 Zendesk 集成时可逐项自查子域名所有连接发起无论 OAuth 还是 API-key/Basic都传站点前缀如mycompany而非完整 URLOAuth 连接使用config{auth_scheme:OAUTH2,val:{subdomain:site-name}}或 TS 侧AuthScheme.OAuth2({ subdomain })token 由流程自动注入无需手动填写API-key/Basic 连接同时传subdomain与basic_encoded后者为 email/token 凭据形式的 base64 编码工具列表始终携带toolkit_versionslatesttoolkit_slugzendesklimit1000避免拿到旧版本工具集动作选择搜索用ZENDESK_SEARCH_ZENDESK更新工单用ZENDESK_UPDATE_ZENDESK_TICKET已知 ID 取详情直接用 get-ticket-by-id触发器确认 Zendesk 触发器可用但在引用具体数量前先核对当前触发器目录。以上内容以知识库源文档 docs/kb/source/toolkits/zendesk/public.md 为骨架并结合仓库中的 SDK 实现python/composio/core/models/tools.py、python/composio/sdk.py、Connected Accounts API 文档ts/docs/api/connected-accounts.md与知识库文章docs/kb/articles/toolkits-zendesk.md交叉印证可作为你在 Composio 中构建 Zendesk 驱动型 Agent 的直接参考。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考