1. 为什么我要把 Jira 操作交给 Langchain v1.0 智能体如果你每天在 Jira 里重复做三件事建任务、改状态、补评论那这篇文章就是写给你的。我用 Langchain v1.0 搭了一个 Jira 智能体目标很直接——把「自然语言一句话」变成「Jira 里真实存在的任务和状态流转」。它适合三类人一是想入门 AI 智能体但不知道拿什么场景练手的开发者二是团队里被 Jira 流程拖慢节奏、想用自动化任务管理提效的工程同学三是已经在用 Langchain但还没跑通「工具调用 外部系统」闭环的人。Langchain v1.0 相比早期版本最大的变化是把状态管理和工具调用收敛得更清晰配合 LangGraph 的图结构你可以把「检索上下文 → 决策 → 调 Jira → 回执」拆成可观测的节点。Jira 智能体的本质就是让大模型不再只聊天而是能真正调用 Jira API 去创建 issue、转换状态、追加评论。这篇不堆概念直接给你可复制的 config.toml、settings.json 骨架以及一条统一的 Key/API 通道配置示例最后用本地运行验证任务创建和流转是否真的成功。我试过把 Jira 的 REST 调用直接塞进 prompt 让模型拼 URL结果参数一多就崩所以更稳的做法是模型只负责「决定做什么」真正的 Jira 操作交给工具函数或 MCP 风格的标准化接口。下面从环境准备开始一步步跑通。2. 前置准备TaoToken 统一 Key 与 API 通道在写 Jira 工具之前先把模型调用这条链路固定下来。我用的方式是 TaoToken 作为统一入口好处是 Key 和 API 地址集中管理后面换模型或加工具不用到处改代码。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 这个不加 UTM。你需要先拿到一个可用的 Key然后把它写进环境变量而不是硬编码在代码里。我习惯用.env加settings.json双层管理.env放敏感值settings.json放非敏感的结构化配置。这样本地跑和后面部署都不会因为改一个地址而翻遍代码。注意Jira 的 API Token 和模型 Key 是两套东西别混在一个变量里。Jira 那边用的是 Atlassian 的邮箱 API Token模型这边用的是 TaoToken 的 Key。如果你还没建 Key可以到 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成后复制保存页面只显示一次。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数不确定时对着看。3. 可复制配置config.toml 与 settings.json 骨架先建项目目录我习惯这样分mkdir jira-agent cd jira-agent python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install langchain langchain-openai langgraph requests python-dotenv tomli然后是config.toml这个文件放模型和 Jira 的连接参数注意不要把真实 Token 写进去用占位符配合环境变量读取[model] provider openai-compatible base_url https://taotoken.net/api model_name gpt-4o-mini temperature 0.2 max_tokens 1024 [jira] base_url https://your-domain.atlassian.net project_key PROJ default_issue_type Task [agent] max_iterations 6 verbose true接着是settings.json这个文件描述工具能力和字段映射方便后面扩展{ tools: [ { name: create_jira_issue, description: 在 Jira 中创建一个新任务, parameters: { summary: string, description: string, issue_type: string, assignee: string } }, { name: transition_jira_issue, description: 转换 Jira 任务状态, parameters: { issue_key: string, transition_name: string } } ], field_mapping: { summary: summary, description: description, issue_type: issuetype.name, assignee: assignee.name } }.env文件这样写TAOTOKEN_API_KEY你的_TaoToken_Key JIRA_BASE_URLhttps://your-domain.atlassian.net JIRA_USER_EMAILyouexample.com JIRA_API_TOKEN你的_Jira_API_Token读取配置的代码import os, json, tomli from dotenv import load_dotenv load_dotenv() with open(config.toml, rb) as f: config tomli.load(f) with open(settings.json, r, encodingutf-8) as f: settings json.load(f) config[model][api_key] os.getenv(TAOTOKEN_API_KEY) config[jira][user_email] os.getenv(JIRA_USER_EMAIL) config[jira][api_token] os.getenv(JIRA_API_TOKEN)这样配置和代码分离后面换模型或换 Jira 实例只改配置文件。4. 核心实现把 Jira 操作封装成 Langchain 工具Langchain v1.0 里工具定义推荐用tool装饰器配合类型注解模型能自动推断参数。先写 Jira 的底层调用import requests from requests.auth import HTTPBasicAuth from langchain_core.tools import tool JIRA_BASE config[jira][base_url] AUTH HTTPBasicAuth(config[jira][user_email], config[jira][api_token]) HEADERS {Accept: application/json, Content-Type: application/json} tool def create_jira_issue(summary: str, description: str, issue_type: str Task, assignee: str ) - str: 在 Jira 中创建一个新任务返回任务 Key。 payload { fields: { project: {key: config[jira][project_key]}, summary: summary, description: description, issuetype: {name: issue_type}, } } if assignee: payload[fields][assignee] {name: assignee} resp requests.post(f{JIRA_BASE}/rest/api/2/issue, jsonpayload, authAUTH, headersHEADERS) if resp.status_code 201: return f创建成功任务 Key: {resp.json()[key]} return f创建失败: {resp.status_code} {resp.text} tool def transition_jira_issue(issue_key: str, transition_name: str) - str: 转换 Jira 任务状态例如从 To Do 到 In Progress。 url f{JIRA_BASE}/rest/api/2/issue/{issue_key}/transitions resp requests.get(url, authAUTH, headersHEADERS) transitions resp.json().get(transitions, []) target next((t for t in transitions if t[name].lower() transition_name.lower()), None) if not target: return f未找到状态转换: {transition_name} requests.post(url, json{transition: {id: target[id]}}, authAUTH, headersHEADERS) return f{issue_key} 已转换为 {transition_name}然后绑定模型和工具from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate llm ChatOpenAI( modelconfig[model][model_name], base_urlconfig[model][base_url], api_keyconfig[model][api_key], temperatureconfig[model][temperature], ) tools [create_jira_issue, transition_jira_issue] prompt ChatPromptTemplate.from_messages([ (system, 你是 Jira 助手根据用户指令调用工具完成任务。), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools, verboseTrue, max_iterations6)这里的关键点是模型只输出「调用哪个工具、传什么参数」真正的 HTTP 请求在工具函数里完成。这样即使模型幻觉也不会直接拼出错误的 URL。5. 验证请求本地跑通任务创建与状态流转先验证模型通道是否通单独跑一句resp llm.invoke(用一句话说明你能做什么) print(resp.content)如果这里报 401说明 TaoToken Key 没读到检查.env是否被load_dotenv()正确加载。通道通了之后跑智能体result executor.invoke({ input: 创建一个任务标题是优化登录页加载速度描述是目标 FCP 小于 1.5 秒类型 Task }) print(result[output])成功的话终端会打印类似创建成功任务 Key: PROJ-123。你可以打开 Jira 确认任务真的存在。接着验证状态流转result executor.invoke({ input: 把 PROJ-123 的状态改成 In Progress }) print(result[output])如果返回PROJ-123 已转换为 In Progress说明工具调用闭环跑通了。这一步是整个自动化任务管理的核心验证点——模型决策、工具执行、Jira 真实变更三者一致。提示如果 Jira 项目的工作流里没有In Progress这个转换名会返回「未找到状态转换」。先去 Jira 项目设置里看实际的状态名再传对应字符串。6. 本篇常见错排查报错一401 Unauthorized模型侧多数是TAOTOKEN_API_KEY没生效。检查.env文件是否在项目根目录load_dotenv()是否在读取配置之前调用。另外确认base_url写的是https://taotoken.net/api不要多加斜杠或路径。报错二Jira 返回 400 Bad Request常见原因是project_key写错或者issue_type名称和 Jira 里的不一致。Jira 默认项目里类型叫Task、Bug、Story但有些团队改过名字。先用GET /rest/api/2/project/{key}确认。报错三工具没被调用模型直接回答说明 prompt 里没有明确要求调用工具或者模型不支持 tool calling。换支持 function calling 的模型并在 system prompt 里强调「必须调用工具完成操作不要凭空回答」。报错四状态转换找不到Jira 的 transition 名称依赖工作流配置不是固定的。用GET /rest/api/2/issue/{key}/transitions列出所有可用转换把返回的name字段抄进你的指令里。报错五中文描述乱码Jira REST API v2 对中文支持没问题但如果你用了 v3 的 ADF 格式description 需要结构化。简单起见先用 v2 接口description 传纯字符串。7. 继续往下走从单次调用到长期编码助手跑通上面这套之后你已经有了一个能创建和流转 Jira 任务的智能体。但如果想让它长期挂在开发流程里比如监听 Git 提交、自动更新任务状态单次脚本就不够了。这时候可以考虑 Coding Plan 这类长期编码/Agent 场景的方案把模型调用和工具编排做成可持续运行的服务https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。如果你更想先在对话里验证模型对 Jira 指令的理解能力可以到模型对话页面直接试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。把「创建一个高优先级 bug 并分配给张三」这类指令丢进去看模型是否能稳定输出结构化参数再决定要不要接真实 Jira。我自己的经验是先把工具函数的错误处理写扎实再让模型去调。模型再聪明也救不了一个返回 500 的接口。把create_jira_issue和transition_jira_issue的返回信息设计得足够清晰模型下一轮决策的准确率会明显提升。