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 AppBYOABring 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 AppauthConfig 必须与该 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_iduser_123, auth_configs{ jira: auth_config_id, # 固定 BYOA 配置而不是默认 Jira 配置 }, )// TypeScript const session await composio.create(user_123, { authConfigs: { jira: auth_config_id, }, });为什么必须固定如果会话没有指定 Jira 的 authConfigTool 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_keyyour-api-key) connection composio.connected_accounts.initiate( user_iduser_123, auth_config_idac_your_auth_config, configauth_scheme.api_key({ api_key: your-atlassian-api-token, email: userexample.com, subdomain: yourcompany, # 即 https://yourcompany.atlassian.net 的子域 }), )示例参照 importing-existing-connections.mdx 中initiateconfigauth_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 URIauthConfig 与 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 缺少audienceapi.atlassian.comAtlassian OAuth 2.0 要求在授权 URL 中包含audienceapi.atlassian.com参数。缺少该参数时Atlassian 可能不认可offline_access结果是不返回 refresh tokenaccess token 到期后无法刷新连接随即失效。排查清单当 Jira 凭据立即过期时逐项核对connected account 是否缺少offline_access授权Jira OAuth 配置authConfig是否包含必需的audience参数授权 URL 是否以https://auth.atlassian.com/authorize?audienceapi.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默认完整保存请求参数与响应数据Dont 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），仅供参考 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 AppBYOABring 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 AppauthConfig 必须与该 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_iduser_123, auth_configs{ jira: auth_config_id, # 固定 BYOA 配置而不是默认 Jira 配置 }, )// TypeScript const session await composio.create(user_123, { authConfigs: { jira: auth_config_id, }, });为什么必须固定如果会话没有指定 Jira 的 authConfigTool 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_keyyour-api-key) connection composio.connected_accounts.initiate( user_iduser_123, auth_config_idac_your_auth_config, configauth_scheme.api_key({ api_key: your-atlassian-api-token, email: userexample.com, subdomain: yourcompany, # 即 https://yourcompany.atlassian.net 的子域 }), )示例参照 importing-existing-connections.mdx 中initiateconfigauth_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 URIauthConfig 与 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 缺少audienceapi.atlassian.comAtlassian OAuth 2.0 要求在授权 URL 中包含audienceapi.atlassian.com参数。缺少该参数时Atlassian 可能不认可offline_access结果是不返回 refresh tokenaccess token 到期后无法刷新连接随即失效。排查清单当 Jira 凭据立即过期时逐项核对connected account 是否缺少offline_access授权Jira OAuth 配置authConfig是否包含必需的audience参数授权 URL 是否以https://auth.atlassian.com/authorize?audienceapi.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默认完整保存请求参数与响应数据Dont 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），仅供参考