1. 为什么我要用 Langchain v1.0 重写 Jira 任务管理流程
Jira 任务管理自动化这件事，我最早是用 Python 脚本硬怼 REST API 做的。写一个create_issue要拼 JSON、处理字段校验、再手动加评论，脚本越堆越长，最后没人敢改。后来换成 Langchain v1.0 搭智能体，把「理解自然语言 → 决定动作 → 调 Jira」这条链路交给 Agent 编排，代码量反而降下来了。
Langchain v1.0 是什么？简单说，它把大模型调用、工具绑定、状态流转这几件事抽象成了可组合的组件。你能用它做什么？拿 Jira 场景举例：同事在群里说「把 PROJ-1024 挪到进行中，顺便 @ 一下张工」，智能体能自己解析出 issue key、目标状态、负责人，然后调 Jira API 完成流转。适合谁？适合每天要在 Jira 里点几十次状态、写重复评论的开发、测试和项目经理。
我这次的目标很明确：从零搭一个能创建任务、查询任务、流转状态的 Jira 智能体，跑通完整闭环。下面把环境准备、工具链选型、Agent 编排、验证动作全部拆开讲，代码可以直接复制。
先说清楚整体架构，避免你后面迷路。整个系统分三层：感知层用 RAG 把项目文档、历史任务记录做成向量库，让智能体有上下文；决策层用 Langchain v1.0 的 Agent 做推理，决定该调哪个工具；执行层通过 Jira 官方 Python SDK 真正落到 Jira 上。三层解耦的好处是，以后要接 Confluence 或 Git，只加执行层的工具就行，决策逻辑不用大改。
环境上，Python 3.10 以上、能访问 Jira 实例、有一个可用的模型 API 就够了。模型这块我后面会用 TaoToken 做统一接入，这样换模型不用改代码。
2. TaoToken 前置准备：统一模型接入与 API Key 获取
在写 Agent 之前，得先解决模型调用的问题。Langchain v1.0 支持多种 Chat Model，但如果你每个模型都单独配 key、单独改 base_url，代码会很乱。我的做法是用 TaoToken 做统一入口，它兼容 OpenAI 的接口格式，Langchain 里直接换base_url就能用。
TaoToken 是什么？它是一个大模型 API 聚合服务，能让你用一套 key 调用多个模型。能做什么？对 Jira 智能体来说，最直接的价值是：决策层需要推理能力强的模型，RAG 压缩可以用便宜的小模型，两者通过同一个入口切换，不用维护多套凭证。适合谁？适合需要频繁对比模型效果、或者想把模型调用集中管理的开发者。
第一步，去官网注册并拿到 API Key。地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建 key。控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。API Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，建议给这个项目单独建一个 key，方便后面按项目统计用量。
拿到 key 之后，先别急着写 Agent，用最简方式验证一下通路。TaoToken 的 API 端点是 https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接作为 base_url 用。你可以先用 curl 测一下：
curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "回复 OK 两个字母"}] }'如果返回里有choices字段，说明 key 和网络都正常。这一步很重要，因为后面 Langchain 报错时，你得能区分是模型接入问题还是 Agent 逻辑问题。
模型选型上，我的建议是：决策层用gpt-4o或claude-3-5-sonnet这类推理强的，RAG 文档压缩用gpt-4o-mini就够。TaoToken 的好处是这两个模型用同一个 key、同一个 base_url，Langchain 里只是model字段不同。如果你后面想试国产模型，也是改一个字符串的事。
顺便提一句，如果你打算长期跑编码类 Agent，可以了解下 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它针对高频调用场景做了额度优化。不过 Jira 智能体这种低频任务管理场景，按量付费就够了。
3. 可复制配置：依赖清单、环境变量与 Agent 编排代码
这一节是核心，我把依赖、配置、代码全部给全。你按顺序复制就能跑。
先建虚拟环境并装依赖。requirements.txt内容如下：
langchain==1.0.0 langchain-openai==1.0.0 langchain-community==0.3.0 langgraph==0.2.0 faiss-cpu==1.8.0 python-dotenv==1.0.1 jira==3.8.0 sentence-transformers==3.0.1 pydantic==2.9.0安装命令：
python -m venv jira_agent_env source jira_agent_env/bin/activate pip install -r requirements.txt然后是环境变量文件.env。这里把 TaoToken 的接入配置和 Jira 凭证都放进去：
# TaoToken 统一模型接入 TAOTOKEN_API_KEY=sk-你的key TAOTOKEN_BASE_URL=https://taotoken.net/api # Jira 配置 JIRA_BASE_URL=https://your-domain.atlassian.net JIRA_USER_EMAIL=your-email@example.com JIRA_API_TOKEN=your-jira-api-token # 向量库 VECTOR_DB_PATH=./vector_db EMBEDDING_MODEL=all-MiniLM-L6-v2Jira API Token 在 Atlassian 账户的 security 页面生成，不是你的登录密码，别搞混。JIRA_BASE_URL不要带结尾斜杠。
接下来是模型初始化。Langchain v1.0 里用ChatOpenAI指向 TaoToken 的 base_url：
import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() def get_llm(model: str = "gpt-4o", temperature: float = 0): return ChatOpenAI( model=model, temperature=temperature, api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL") + "/v1", )注意base_url后面要拼/v1，因为 Langchain 的 OpenAI 兼容层会自己加/chat/completions。这是最容易踩的坑，配错了会报 404。
然后是 Jira 工具定义。Langchain v1.0 用@tool装饰器把普通函数变成 Agent 可调用的工具：
from langchain_core.tools import tool from jira import JIRA import os jira_client = JIRA( server=os.getenv("JIRA_BASE_URL"), basic_auth=(os.getenv("JIRA_USER_EMAIL"), os.getenv("JIRA_API_TOKEN")), ) @tool def create_issue(project_key: str, summary: str, description: str, issue_type: str = "Task") -> str: """在 Jira 中创建一个新任务。project_key 是项目标识，summary 是标题，description 是描述，issue_type 默认 Task。""" issue = jira_client.create_issue( project={"key": project_key}, summary=summary, description=description, issuetype={"name": issue_type}, ) return f"已创建 {issue.key}，链接 {os.getenv('JIRA_BASE_URL')}/browse/{issue.key}" @tool def query_issue(issue_key: str) -> str: """根据 issue key 查询任务详情，返回标题、状态和负责人。""" issue = jira_client.issue(issue_key) return f"{issue.key} | {issue.fields.summary} | 状态:{issue.fields.status.name} | 负责人:{issue.fields.assignee}" @tool def transition_issue(issue_key: str, target_status: str) -> str: """把任务流转到目标状态，target_status 例如 'In Progress' 或 'Done'。""" issue = jira_client.issue(issue_key) transitions = jira_client.transitions(issue) for t in transitions: if t["name"].lower() == target_status.lower(): jira_client.transition_issue(issue, t["id"]) return f"{issue_key} 已流转到 {target_status}" return f"未找到状态 {target_status}，可用状态：{[t['name'] for t in transitions]}"工具函数的 docstring 很关键，Agent 靠它判断什么时候调哪个工具。写清楚参数含义，别偷懒。
最后是 Agent 编排。Langchain v1.0 推荐用 LangGraph 的create_react_agent：
from langgraph.prebuilt import create_react_agent tools = [create_issue, query_issue, transition_issue] llm = get_llm("gpt-4o") agent = create_react_agent(llm, tools) def run_agent(user_input: str): result = agent.invoke({"messages": [("user", user_input)]}) return result["messages"][-1].content到这里，一个最小可用的 Jira 智能体就搭好了。代码不多，但每一块都对应一个明确的职责：模型接入、工具定义、Agent 编排。
4. 验证请求：创建、查询、流转任务的完整闭环
配置写完了，得验证它真的能干活。我按「创建 → 查询 → 流转」三步走，每步都给你预期输出。
先测创建任务：
if __name__ == "__main__": print(run_agent("在 PROJ 项目创建一个任务，标题是'修复登录页超时'，描述是'用户反馈登录偶发超时，需要排查网络请求'"))预期输出类似：已创建 PROJ-1234，链接 https://your-domain.atlassian.net/browse/PROJ-1234。如果 Agent 没调工具而是直接回复，说明 docstring 不够清晰，或者模型没理解意图，可以换gpt-4o再试。
接着测查询：
print(run_agent("查一下 PROJ-1234 现在什么状态"))预期输出：PROJ-1234 | 修复登录页超时 | 状态:To Do | 负责人:None。这一步验证的是 Agent 能不能从自然语言里提取出 issue key。
最后测流转：
print(run_agent("把 PROJ-1234 流转到 In Progress"))预期输出：PROJ-1234 已流转到 In Progress。如果报「未找到状态」，说明你的 Jira 工作流里状态名不叫这个，工具会返回可用状态列表，照着改就行。
三步跑通，闭环就成了。你可以把这三句合成一句复杂指令测试 Agent 的多步推理能力：
print(run_agent("创建一个任务标题'优化搜索接口'，然后把它流转到 In Progress"))这时候 Agent 会先调create_issue，拿到 key 后再调transition_issue。LangGraph 的状态管理会自动把上一步的结果传给下一步，这就是用框架而不是裸写脚本的价值。
验证过程中，建议打开 Jira 网页对照，确认任务真的创建了、状态真的变了。别只看终端输出，有时候 Agent 回复成功但实际没落库，多半是工具函数里异常被吞了。
5. 本篇常见报错排查：401、local proxy failed、reading choices
这一节是我踩过的坑，按报错原文对照排查。
报错一：401 Unauthorized或invalid_api_key
这个基本是 TaoToken key 的问题。先确认.env里TAOTOKEN_API_KEY没有多余空格，然后确认base_url拼的是https://taotoken.net/api/v1。如果还报 401，去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认 key 没过期、没被禁用。Jira 侧的 401 则是JIRA_API_TOKEN或邮箱错了，注意 Jira 用的是 API Token 不是密码。
报错二：local proxy failed或连接超时
这个通常是网络层问题。先确认你的环境能正常访问https://taotoken.net/api，用第 2 节的 curl 命令测。如果 curl 通但 Langchain 不通，检查是不是系统里设了HTTP_PROXY环境变量，Langchain 会读这个变量。清掉再试：
unset HTTP_PROXY HTTPS_PROXY报错三：Error code: 400 - reading 'choices'
这个报错说明返回体里没有choices字段，通常是模型名写错了。TaoToken 的模型 ID 要和你账户里可用的模型一致，比如gpt-4o、claude-3-5-sonnet。写个不存在的模型名就会返回错误结构，Langchain 解析时找不到choices就抛这个。去模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 确认可用模型列表。
报错四：OAuth或authentication failed（Jira 侧）
Jira Cloud 现在强制用 API Token + 邮箱的 basic auth，如果你用的是 Server 版可能走 OAuth。确认JIRA_BASE_URL是https://xxx.atlassian.net格式，不要带/jira后缀。另外 API Token 生成后只显示一次，丢了就重新生成。
报错五：Agent 不调工具，直接编答案
这不是报错但很常见。原因是工具 docstring 太模糊，或者模型能力不够。解决办法：把 docstring 写具体，参数说明清楚；决策层换gpt-4o或claude-3-5-sonnet。如果还是不行，在 system prompt 里明确要求「必须调用工具获取真实数据，不要编造」。
排查顺序建议：先 curl 测模型通路，再单独测 Jira SDK 连通性，最后测 Agent。分层定位比一上来就 debug Agent 快得多。
6. 把 Jira 智能体接进你的日常工作流
跑通之后，我建议你别停在命令行。几个实用的延伸方向：
一是把 Agent 包成一个 FastAPI 接口，前端或飞书机器人调它，同事在群里 @ 机器人就能建任务。二是加一个 RAG 层，把项目的历史任务和文档灌进向量库，Agent 创建任务时能自动参考类似任务的描述格式。三是加审批环节，流转到 Done 之前先让 Agent 发个确认消息，避免误操作。
模型接入这块，如果你后面要换模型对比效果，TaoToken 的模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 可以直接试，不用改代码。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言的示例。
最后提醒一个细节：Jira 的字段在不同项目里配置不一样，create_issue里我只写了必填字段。如果你的项目要求填优先级、组件、Sprint，得在工具函数里补上，否则会报字段校验错误。这个坑我踩过，报错信息里会明确告诉你缺哪个字段，照着加就行。
