Composio Zendesk 集成实战：OAuth 子域名配置、工具版本查询与工单操作指南-编程实验室

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 OAuth，access token 会在 OAuth 流程完成后由 Composio 自动注入，客户不需要手动输入访问令牌。这意味着在连接过程中，你只需要完成浏览器侧的 OAuth 授权即可，无需在代码或配置里准备 token 字段。

Redirect URI（重定向地址）是否必填取决于 auth-config 的具体设置，可以省略；但如果 Zendesk 侧要求配置重定向地址，则需要把 Composio 的 auth 重定向 URL 配置到 Zendesk OAuth 应用中。这一规则也同步记录在面向终端用户的知识库文章 docs/kb/articles/toolkits-zendesk.md 中。

连接必须携带账号子域名（subdomain），而非完整 URL

Zendesk 在连接发起阶段要求提供账号子域名。需要注意：传入的是 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_versions=latest&toolkit_slug=zendesk&limit=1000

如果不带 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_versions=latest，并在排查"工具缺失"问题时首先检查是否遗漏了该参数。Zendesk 的 toolkit slug 本身已在 CLI 生成的 ts/packages/cli/src/generated/toolkit-slugs.ts 中注册为'zendesk'，可直接用于查询。

核心工具动作：搜索、更新工单与按 ID 获取工单

Zendesk 工具集中有几个面向工单场景的关键动作，可直接按名称引用：

`ZENDESK_SEARCH_ZENDESK`：Zendesk 搜索

针对 Zendesk 搜索场景，使用ZENDESK_SEARCH_ZENDESK。它适用于在不知道具体工单 ID、需要按关键词、状态、优先级等条件检索 Zendesk 数据（工单、用户、组织等）的场合，是搜索型用例的专用动作。

`ZENDESK_UPDATE_ZENDESK_TICKET`：更新工单

针对工单更新，使用ZENDESK_UPDATE_ZENDESK_TICKET。从端点层面看，它对应的是 Zendesk ticketing API 中的Update Ticket端点。适合在 Agent 需要修改工单字段（如状态、指派人、优先级、评论）时调用。

按 ID 获取工单（get-ticket-by-id）

Zendesk 的 get-ticket-by-id 动作单次工具调用即可返回工单详情。适用场景是：客户已经持有 Zendesk 工单 ID，需要直接获取该工单的元数据/详情，而不必先走搜索流程。它比"先搜索再取详情"更直接高效，能节省一次工具调用。

提示：ZENDESK_SEARCH_ZENDESK与ZENDESK_UPDATE_ZENDESK_TICKET这类动作名同样需要配合toolkit_versions=latest使用——如果工具列表来自旧的固定版本，可能取不到这些新动作，这也是知识库文档反复强调版本参数的原因。

触发器（Triggers）支持

Zendesk 在 Composio 中支持触发器（trigger）能力，可用于监听 Zendesk 侧的事件（如新工单创建、工单状态变更）并主动触发 Agent 流程。需要说明的是，仓库文档明确建议在引用具体触发器数量之前，先核对当前的触发器目录（trigger catalog），不要凭记忆写死某个数量。

在实现层面，Python SDK 的 Triggers 集合同样接受toolkit_versions参数（见 python/composio/core/models/triggers.py），这意味着拉取 Zendesk 触发器时也应考虑传入toolkit_versions=latest，以确保拿到最新、完整的触发器集合。

实操核查清单

按本文内容落地 Zendesk 集成时，可逐项自查：

子域名：所有连接发起（无论 OAuth 还是 API-key/Basic）都传站点前缀（如mycompany），而非完整 URL；
OAuth 连接：使用config={"auth_scheme":"OAUTH2","val":{"subdomain":"<site-name>"}}（或 TS 侧AuthScheme.OAuth2({ subdomain })），token 由流程自动注入，无需手动填写；
API-key/Basic 连接：同时传subdomain与basic_encoded，后者为 email/token 凭据形式的 base64 编码；
工具列表：始终携带toolkit_versions=latest&toolkit_slug=zendesk&limit=1000，避免拿到旧版本工具集；
动作选择：搜索用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 的直接参考。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Composio Zendesk 集成实战：OAuth 子域名配置、工具版本查询与工单操作指南