Composio Jira 工具包实战指南：OAuth 认证配置、Tool Router 会话与分页排障-二趣网

Composio Jira 工具包实战指南：OAuth 认证配置、Tool Router 会话与分页排障

【免费下载链接】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 官方知识库中的 Jira 支持文档（toolkits-jira.md）整理而成，聚焦于在 Composio 平台中使用 Jira 工具包时最容易踩坑的十个问题：从 Atlassian OAuth 作用域限制、redirect URI 匹配、refresh token 丢失，到 Tool Router 会话中固定自定义 authConfig、分页 token 的正确使用，再到日志存储策略与工具选型。读完本文，你将掌握 Jira 工具包在认证配置、会话创建、分页与数据合规方面的完整排障方法，能够直接对照检查自己的接入代码。

Jira 工具包在 Composio 中的定位

Composio 将 Jira 封装为一组可直接供 AI Agent 调用的工具（toolkit），覆盖问题（Issue）的搜索、创建、附件下载、服务器信息查询等场景。与多数 SaaS 工具包一样，Jira 工具包面临两类核心挑战：

认证链路复杂：Atlassian OAuth 2.0 的授权 URL 参数、回调地址、作用域数量都有严格的平台约束；
多账号解析：当客户使用自己的 OAuth App（BYOA，Bring Your Own App）时，Tool Router 需要精确匹配到正确的 authConfig 与 connected account，否则会回退到默认配置导致执行失败。

本文的每一节都对应知识库中一个独立的已知问题与官方处置建议，可与 Composio 官方 Jira 支持文档（即本知识库文章的渲染版本，frontmatter 中toolkitSlugs: ["jira"]，主题覆盖auth-config、authentication、errors-and-troubleshooting、sessions-and-execution、toolkits-and-providers）相互对照。

一、OAuth 作用域：保持在 Atlassian 支持的范围内

Jira/Atlassian 将单个 OAuth App 的作用域数量限制为50 个，且不支持的、与 Atlassian App 审批范围不匹配的作用域会导致用户授权（consent）失败。

核心规则：对于客户自有的 OAuth App，authConfig 必须与该 Atlassian App 上实际审批通过的作用域保持一致，二者一一对齐。

排查建议：当托管认证（managed-auth）出现失败时，不要沿用历史上"已解决"的作用域问题结论去套用，而应直接检查当前的 consent 报错信息与当前 authConfig 的 scope 配置。这一原则与 Composio 官方文档中"作用域变更只影响新连接"的语义一致：在 controlling-scopes.mdx 中明确说明，修改 scope 后，已有 connected account 会保留其已授予的作用域，直到用户重新认证。

实现佐证：docs/kb/source/toolkits/jira/public.md是本文知识库内容的原始来源文件，其中强调"不要用旧的托管 App 作用域事件诊断当前故障，请检查客户当前的 consent 报错与 authConfig"。

二、Tool Router 会话：固定自定义 Jira authConfig

当客户使用自定义 Jira OAuth App并通过 Tool Router 执行工具时，必须在创建会话（session）时显式传入自定义 authConfig：

# Python session = composio.create( user_id="user_123", auth_configs={ "jira": "<auth_config_id>", # 固定 BYOA 配置，而不是默认 Jira 配置 }, )

// TypeScript const session = await composio.create("user_123", { authConfigs: { jira: "<auth_config_id>", }, });

为什么必须固定：如果会话没有指定 Jira 的 authConfig，Tool Router 可能回退到自动生成/默认的 Jira 配置，从而看不到客户已经激活的自定义认证连接，导致工具调用无法解析到正确的 connected account。

这一行为在仓库其他认证文档中得到印证：

custom-app-vs-managed-app.mdx 明确写道："创建 authConfig 本身不够，只有把其 ID 以authConfigs（按 toolkit 为键）传入会话，会话才会使用该配置；未列出的 toolkit 继续使用 Composio 托管认证。"
custom-mcp.mdx 说明：会话默认按user_id自动匹配 connected account（前提是 authConfig 创建时设置了is_enabled_for_tool_router: true），否则需要显式通过connected_accounts/connectedAccounts固定账号 ID。

三、自定义 token 执行：必须提供 Atlassian 租户子域

Jira 期望的租户 URL 形式为https://<subdomain>.atlassian.net。在**发起连接（initiate connected account）**时，无论使用OAuth2、API-key 还是 S2S OAuth2认证方案，都必须提供subdomain参数：

from composio import Composio from composio.types import auth_scheme composio = Composio(api_key="your-api-key") connection = composio.connected_accounts.initiate( user_id="user_123", auth_config_id="ac_your_auth_config", config=auth_scheme.api_key({ "api_key": "your-atlassian-api-token", "email": "user@example.com", "subdomain": "yourcompany", # 即 https://yourcompany.atlassian.net 的子域 }), )

（示例参照 importing-existing-connections.mdx 中initiate+config=auth_scheme.api_key(...)的调用形态；该文档同时说明subdomain、base_url等附加参数对支持的工具包同样生效。）

验证手段：可使用JIRA_GET_SERVER_INFO工具查询当前连接解析到的服务器信息，从而确认 base URL 是否正确。

不要使用旧的变通方案：禁止再通过customConnectionData注入裸 access token 的老 SDK 变通做法，应通过正规的 authConfig + connected account 机制传递凭据。

四、分页 token：保留搜索上下文，跨工具复用会失效

当前版本的 Jira 搜索工具会将provider 的分页 token 与原始搜索上下文一起包装返回。正确用法：

将同一个 Composio action返回的next_page_token直接传给该 action 的下一次调用；
如果调用方自行提供 Jira 原始nextPageToken，则必须同时提供原始 JQL，否则上下文缺失会导致分页失效。

官方推荐的处置规则：

不要把某个 Jira action 返回的 token 传给另一个不同的 action；
立即用该 token 请求下一页，不要隔太久；
不要持久化旧 token，也不要重试被拒绝的 token；如果 Jira 在相同上下文下仍返回invalid or expired，直接丢弃该 token，从第 1 页重新开始分页。

从知识库语义索引（semantic-index.json）可以确认，next_page_token是 Jira 搜索工具返回参数中被记录的关键字段，说明该包装行为是当前 Jira 工具的标准契约。

五、OAuth redirect URI：authConfig 与 Atlassian App 必须完全一致

Jira/Atlassian OAuth 要求Composio authConfig 中的回调地址与Atlassian OAuth App 中注册的 redirect URI完全一致。

直接从当前 auth-config 流程或文档展示的 callback 中复制，逐字符匹配；
不要复用旧示例中的 v1、v3 遗留回调路径（如老的https://backend.composio.dev/api/v1/auth-apps/add这类旧路径）。

仓库中的认证文档也印证了回调地址的机制：programmatic-auth-configs.mdx 说明，oauth_redirect_uri字段缺省时使用 Composio 默认回调，只有当你需要把回调路由到自有域名时才显式设置。

六、refresh token 丢失：授权 URL 缺少`audience=api.atlassian.com`

Atlassian OAuth 2.0 要求在授权 URL 中包含audience=api.atlassian.com参数。缺少该参数时，Atlassian 可能不认可offline_access，结果是：

不返回 refresh token；
access token 到期后无法刷新，连接随即失效。

排查清单（当 Jira 凭据"立即过期"时逐项核对）：

connected account 是否缺少offline_access授权；
Jira OAuth 配置（authConfig）是否包含必需的audience参数；
授权 URL 是否以https://auth.atlassian.com/authorize?audience=api.atlassian.com&...的形式正确构造。

紧急替代方案：当 OAuth 刷新链路一时无法修复时，可使用API key 认证（Atlassian 邮箱 + API token），这类凭据不依赖 refresh token，可获得稳定、不过期的连接（参见第三节的initiate示例，配合subdomain参数使用）。

七、工具选型：优先使用新的 create-metadata 与附件下载工具

1. 用`JIRA_GET_CREATE_METADATA_ISSUE_TYPE_FIELDS`替代旧行为

Jira 已弃用旧的 create-metadata API 行为，因此JIRA_GET_ISSUE_CREATE_METADATA对应流程已不再是最优选择。官方推荐使用JIRA_GET_CREATE_METADATA_ISSUE_TYPE_FIELDS作为最接近的替代，它是在 Jira 弃用旧 API 后新增的替代工具，用于获取指定 issue type 可用的字段元数据。

从知识库语义索引中可以确认这两个工具 slug 均被记录在案（JIRA_GET_CREATE_METADATA_ISSUE_TYPE_FIELDS、JIRA_GET_ISSUE_CREATE_METADATA），说明二者在工具目录中是并存且具有明确的"新旧替代"关系。

2. 用`JIRA_GET_ATTACHMENT`下载附件二进制内容

下载 Jira issue 附件应使用JIRA_GET_ATTACHMENT：按attachment ID传入参数，返回该附件的二进制内容，专门用于下载 issue 上挂载的特定文件。

使用建议：附件下载通常与搜索/列举附件的工具配合使用——先通过搜索或 issue 详情拿到 attachment ID，再调用JIRA_GET_ATTACHMENT取回文件内容。

八、日志保留：tool-call 负载跟随项目的 Log storage 设置

Composio 负责管理 Jira OAuth token，并将 Jira API 的响应返回给客户应用。请求/响应负载是否被保留在 Composio 工具日志中，取决于项目的 Log storage（日志存储）设置：

Store all logs（默认）：完整保存请求参数与响应数据；
Don't store data：新日志行省略负载内容，但保留审计元数据（哪个工具、何时运行、是否成功、相关 ID、耗时等）。

这一机制在 contenteditable="false">【免费下载链接】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），仅供参考

企业官网建设流程全解析