llm-application-dev 插件实战：基于 LangGraph 与 LangChain 1.x 构建生产级 Agent

llm-application-dev 插件实战基于 LangGraph 与 LangChain 1.x 构建生产级 Agent【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents导读本文以plugins/llm-application-dev插件中的/llm-application-dev:langchain-agent命令langchain-agent.md为核心骨架系统讲解如何在 Claude Code、Codex、Cursor、OpenCode 等多 harness 环境中基于 LangGraph 与 LangChain 1.x 从零构建可投入生产环境的 AI Agent。读完本文你将掌握 LangGraph 状态图StateGraph的设计方法、ReAct / Plan-and-Execute / 多 Agent 编排三种主流 Agent 架构、面向 Claude 的 Voyage AI 嵌入与混合检索 RAG 管线、内存系统选型、FastAPI 流式部署以及基于 LangSmith 的测试与评估方案。该插件定位为 LLM 应用开发套件插件清单包含ai-engineer、prompt-engineer、vector-database-engineer三个 Agent、八个 Skill 与三个命令。其中langchain-agent命令把「构建 LangGraph Agent」这一任务沉淀为一套可复用的专家指令调用方只需把需求描述作为$ARGUMENTS传入命令即按生产级标准输出完整实现。一、命令定位与运行前提1.1 命令元信息该命令的 Frontmatter 定义了两个关键元信息--- description: Create LangGraph-based agent with modern patterns argument-hint: agent-type [options] ---description说明该命令的职责是「使用现代模式创建基于 LangGraph 的 Agent」argument-hint提示调用格式为agent-type [options]即第一个位置参数是 Agent 类型如react、plan-execute、multi-agent后续可跟配置选项。调用时传入的文本会作为$ARGUMENTS被注入命令的 Context 段且命令明确声明该文本「作为数据而非指令」处理防止提示词注入。1.2 环境与版本前提根据 README.md 中的 Requirements 与 Changelog使用本插件前需确认LangChain 1.2.0插件 2.x 已从 0.x 迁移至 1.xLangGraph 0.3.0Python 3.11。值得注意的是插件 v2.0.0 是一次破坏性升级废弃了 LangChain 0.x 时代的initialize_agent()全面转向 LangGraph StateGraph 工作流模型引用更新为 Claude 4.6 / GPT-5.4 系列新增 Voyage AI 作为 Claude 应用的官方推荐嵌入方案并加入 Pydantic 结构化输出、带 Checkpointer 的异步模式。当前插件版本为 2.0.6见 plugin.json因此本文所有示例均遵循 LangGraph 风格 API。命令运行后Agent 需严格遵循以下核心要求产出代码使用最新的 LangChain 0.1 与 LangGraph API全程实现异步模式包含完整的错误处理与回退fallback机制集成 LangSmith 可观测性面向规模化与生产部署设计落实安全最佳实践针对成本效率进行优化。二、核心架构LangGraph 状态管理LangGraph 的核心价值在于「显式的状态管理」。命令给出的最小状态定义如下from langgraph.graph import StateGraph, MessagesState, START, END from langgraph.prebuilt import create_react_agent from langchain_anthropic import ChatAnthropic class AgentState(TypedDict): messages: Annotated[list, conversation history] context: Annotated[dict, retrieved context]Annotated的作用是给状态字段附加 reducer 语义——当多个节点返回同一字段时LangGraph 会按既定规则合并而非覆盖。在 langchain-architecture 的 Skill 文档中对该模式做了进一步扩展展示了两种更完整的状态形态from typing import Annotated, TypedDict from langgraph.graph import MessagesState # 继承 MessagesState 并追加业务字段 class AgentState(MessagesState): Extends MessagesState with custom fields. context: Annotated[list, retrieved documents] # 完全自定义状态 class CustomState(TypedDict): messages: Annotated[list, conversation history] context: Annotated[dict, retrieved context] current_step: str results: list除状态管理外LangGraph 还提供四类关键能力Durable ExecutionAgent 可跨失败持久化、Human-in-the-Loop任意节点可暂停并人工审查/修改状态、跨会话短/长期记忆、以及Checkpointing保存与恢复 Agent 运行状态。2.1 模型与嵌入选型命令文档明确给出了与 Claude 搭配的推荐技术栈主模型Claude Sonnet 5模型 IDclaude-sonnet-5通过ChatAnthropic接入嵌入模型Voyage AI 的voyage-3-largeAnthropic 官方推荐用于 Claude 应用专业领域模型voyage-code-3代码、voyage-finance-2金融、voyage-law-2法律。embedding-strategiesSkillSKILL.md提供了更完整的嵌入模型对比可作为选型依据模型维度最大 Token适用场景voyage-3-large102432000Claude 应用Anthropic 推荐voyage-3102432000Claude 应用成本更低voyage-code-3102432000代码搜索voyage-finance-2102432000金融文档voyage-law-2102432000法律文档text-embedding-3-large30728191OpenAI 应用高精度text-embedding-3-small15368191OpenAI 应用性价比bge-large-en-v1.51024512开源、本地部署multilingual-e5-large1024512多语言选型要点不要混用不同嵌入模型向量空间不兼容、注意 token 上限避免截断丢失信息、为余弦相似度检索做向量归一化、静态内容务必缓存嵌入结果。三、三种 Agent 类型与适用场景命令文档定义了三种主流 Agent 架构并给出各自定位3.1 ReAct Agent通用任务from langgraph.prebuilt import create_react_agent agent create_react_agent(llm, tools, state_modifier)ReActReasoning Acting通过「推理 → 调用工具 → 观察结果 → 再推理」的循环解决多步任务。state_modifier参数用于定制注入给模型的系统消息与状态视图。该 Skill 的 Quick Start 给出了带 Checkpointer 的完整示例见 langchain-architecture/SKILL.mdfrom langgraph.prebuilt import create_react_agent from langgraph.checkpoint.memory import MemorySaver from langchain_anthropic import ChatAnthropic from langchain_core.tools import tool llm ChatAnthropic(modelclaude-sonnet-5) checkpointer MemorySaver() agent create_react_agent(llm, tools, checkpointercheckpointer) # 用 thread_id 维持会话记忆 config {configurable: {thread_id: user-123}} result await agent.ainvoke( {messages: [(user, Search for Python tutorials and calculate 25 * 4)]}, configconfig )值得注意的安全细节该 Skill 中的calculate工具使用 Pythonast模块做安全数学表达式求值仅允许 - * / ** %与一元负号等算子杜绝了eval()的任意代码执行风险——这正是插件 v2.0.0 Changelog 中「修复安全漏洞以 AST 安全数学求值替换不安全的代码执行」的实现落点。3.2 Plan-and-Execute复杂任务适用于需要「先规划、后执行」的复杂任务将规划节点与执行节点分离通过状态跟踪进度。典型形态是「生成多步计划 → 逐节点执行 → 依据中间结果动态调整」。3.3 多 Agent 编排监督者路由from langgraph.types import Command from typing import Literal # 用 Command 指定下一个 Agent # Command[Literal[agent1, agent2, END]]监督者Supervisor根据上下文决定下一个由哪个专业 Agent 接手。references/details.mdlangchain-architecture/references/details.md给出了完整的「研究 → 写作 → 评审」三 Agent 编排实现监督者节点用 LLM 判断下一步交给researcher、writer、reviewer还是FINISH各专业 Agent 执行完毕后都回到监督者节点形成循环路由class MultiAgentState(TypedDict): messages: list next_agent: str builder StateGraph(MultiAgentState) builder.add_node(supervisor, supervisor) builder.add_node(researcher, researcher) builder.add_node(writer, writer) builder.add_node(reviewer, reviewer) builder.add_edge(START, supervisor) builder.add_conditional_edges(supervisor, route_to_agent, { researcher: researcher, writer: writer, reviewer: reviewer, end: END }) # 每个 Agent 执行完都回到监督者 for agent in [researcher, writer, reviewer]: builder.add_edge(agent, supervisor)四、内存系统从短时记忆到生产级 Checkpointer命令文档列出的内存选型包括短时记忆ConversationTokenBufferMemory基于 token 的滑动窗口摘要压缩ConversationSummaryMemory压缩长对话历史实体跟踪ConversationEntityMemory跟踪人物、地点、事实向量记忆VectorStoreRetrieverMemory基于语义检索的长期记忆混合方案组合多种内存类型获得完整上下文。在现代 LangGraph 体系中references/details.md给出了更贴合 1.x 的落地方式——Checkpointer成为持久化记忆的主流载体# 开发环境内存 Checkpointer from langgraph.checkpoint.memory import MemorySaver checkpointer MemorySaver() agent create_react_agent(llm, tools, checkpointercheckpointer) # 同一 thread_id 下消息跨调用保留 config {configurable: {thread_id: session-abc123}} result1 await agent.ainvoke({messages: [(user, My name is Alice)]}, config) result2 await agent.ainvoke({messages: [(user, Whats my name?)]}, config) # Agent 记得Your name is Alice # 生产环境PostgreSQL Checkpointer from langgraph.checkpoint.postgres import PostgresSaver checkpointer PostgresSaver.from_conn_string( postgresql://user:passlocalhost/langgraph ) agent create_react_agent(llm, tools, checkpointercheckpointer)对于跨会话的长期语义记忆可借助向量库保存对话快照from langchain_community.vectorstores import Chroma from langchain_voyageai import VoyageAIEmbeddings embeddings VoyageAIEmbeddings(modelvoyage-3-large) memory_store Chroma( collection_nameconversation_memory, embedding_functionembeddings, persist_directory./memory_db ) async def store_memory(content: str, metadata: dict {}): 将对话存入长期记忆。 await memory_store.aadd_texts([content], metadatas[metadata]) async def retrieve_relevant_memory(query: str, k: int 5) - list: 按语义相似度检索历史对话。 docs await memory_store.asimilarity_search(query, kk) return [doc.page_content for doc in docs]对应 Skill 的测试策略也验证了记忆持久化这一关键行为langchain-architecture/SKILL.md先让 Agent 记住12345再次调用询问「What was the code?」断言最终回复包含12345。五、RAG 管线混合检索 重排命令文档给出的 RAG 核心代码使用 Voyage AI 嵌入与 Pinecone 混合检索from langchain_voyageai import VoyageAIEmbeddings from langchain_pinecone import PineconeVectorStore # 为 Claude 应用推荐 voyage-3-large embeddings VoyageAIEmbeddings(modelvoyage-3-large) # 混合检索向量库 vectorstore PineconeVectorStore( indexindex, embeddingembeddings ) # 混合检索 重排 base_retriever vectorstore.as_retriever( search_typehybrid, search_kwargs{k: 20, alpha: 0.5} )参数说明k20表示召回候选数alpha0.5表示向量与关键词BM25两种检索得分的融合权重01 之间取值0.5 意味着两者等权。5.1 高级 RAG 模式命令文档推荐了三种进阶模式HyDE让 LLM 先生成假设性文档HyDEHypothetical Document Embeddings再检索弥合查询与文档之间的语义鸿沟RAG Fusion从多个查询视角生成候选集合并融合提升召回覆盖Reranking用 Cohere Rerank 对召回结果做相关性重排。rag-implementationSkillSKILL.md)补充了完整的检索策略谱系稠密检索语义相似度、稀疏检索BM25/TF-IDF 关键词匹配、混合检索加权融合、多查询扩展生成多个查询变体与 HyDE。5.2 用 LangGraph 搭建 RAG 全流程references/details.md与rag-implementationSkill 都提供了「检索 → 生成」双节点图的标准实现可直接嵌入 Agent 的检索增强环节from langgraph.graph import StateGraph, START, END from langchain_anthropic import ChatAnthropic from langchain_voyageai import VoyageAIEmbeddings from langchain_pinecone import PineconeVectorStore from langchain_core.prompts import ChatPromptTemplate from typing import TypedDict, Annotated class RAGState(TypedDict): question: str context: Annotated[list, retrieved documents] answer: str llm ChatAnthropic(modelclaude-sonnet-5) embeddings VoyageAIEmbeddings(modelvoyage-3-large) vectorstore PineconeVectorStore(index_namedocs, embeddingembeddings) retriever vectorstore.as_retriever(search_kwargs{k: 4}) rag_prompt ChatPromptTemplate.from_template( Answer based on the context below. If you cannot answer, say so. Context: {context} Question: {question} Answer: ) async def retrieve(state: RAGState) - RAGState: docs await retriever.ainvoke(state[question]) return {context: docs} async def generate(state: RAGState) - RAGState: context_text \n\n.join(doc.page_content for doc in state[context]) response await llm.ainvoke( rag_prompt.format(contextcontext_text, questionstate[question]) ) return {answer: response.content} builder StateGraph(RAGState) builder.add_node(retrieve, retrieve) builder.add_node(generate, generate) builder.add_edge(START, retrieve) builder.add_edge(retrieve, generate) builder.add_edge(generate, END) rag_chain builder.compile() result await rag_chain.ainvoke({question: What is the main topic?})5.3 混合检索融合方法速查hybrid-search-implementationSkillSKILL.md总结了四种融合策略可在实现 Agent 工具时按需选择方法描述适用场景RRF倒数排名融合通用场景无需调参Linear得分加权求和需要可调平衡Cross-encoder神经网络重排最高质量Cascade先过滤再重排追求效率实践经验权重要靠数据实测调优、优先用 RRF 起步、务必叠加重排、同时记录两种检索得分便于排查、用 A/B 测试衡量真实收益同时不要过度取回平衡召回与延迟、不要忽略空结果和单字查询等边界情况。六、工具集成Pydantic Schema 驱动的 StructuredTool命令文档给出了标准工具定义方式——用 Pydantic 描述输入参数用StructuredTool.from_function注册异步实现from langchain_core.tools import StructuredTool from pydantic import BaseModel, Field class ToolInput(BaseModel): query: str Field(descriptionQuery to process) async def tool_function(query: str) - str: # 实现时务必带错误处理 try: result await external_call(query) return result except Exception as e: return fError: {str(e)} tool StructuredTool.from_function( functool_function, nametool_name, descriptionWhat this tool does, args_schemaToolInput, coroutinetool_function )references/details.md展示了更完整的多工具注册范例为search_database含可选 filters 参数与send_email收件人/主题/正文三参数分别定义SearchInput、EmailInput两个 Pydantic 模型再统一打包传入create_react_agent(llm, tools)即完成带结构化参数校验的工具型 Agent 构建。LangGraph 会依据args_schema让模型生成符合 schema 的 JSON 参数并自动校验这是保证工具调用可靠性的关键一环。七、生产部署FastAPI 流式服务与可观测性7.1 FastAPI 流式响应命令文档给出的服务端模式根据请求中的stream标志决定返回 SSE 流式响应还是普通结果from fastapi import FastAPI from fastapi.responses import StreamingResponse app.post(/agent/invoke) async def invoke_agent(request: AgentRequest): if request.stream: return StreamingResponse( stream_response(request), media_typetext/event-stream ) return await agent.ainvoke({messages: [...]})底层流式能力由 LangChain/LangGraph 的异步事件流提供references/details.md# 逐 token 流式输出 async for chunk in llm.astream(Tell me a story): print(chunk.content, end, flushTrue) # 流式 Agent 事件v2 事件协议 async for event in agent.astream_events( {messages: [(user, Search and summarize)]}, versionv2 ): if event[event] on_chat_model_stream: print(event[data][chunk].content, end) elif event[event] on_tool_start: print(f\n[Using tool: {event[name]}])7.2 监控与可观测性命令文档要求的四层观测体系LangSmith追踪所有 Agent 执行轨迹。启用方式是在环境变量中配置LANGCHAIN_TRACING_V2true、LANGCHAIN_API_KEY、LANGCHAIN_PROJECT此后所有 LangChain/LangGraph 操作自动被追踪见 references/details.mdPrometheus采集请求数、延迟、错误率等指标结构化日志使用structlog保证日志格式一致健康检查逐一验证 LLM、工具、内存与外部服务的可用性。此外references/details.md还提供了自定义回调处理器BaseCallbackHandler的写法可在on_llm_start、on_llm_end、on_tool_start、on_tool_end等钩子中注入自有观测逻辑并通过config{callbacks: [CustomCallbackHandler()]}挂载。7.3 性能与成本优化策略命令文档给出的优化清单缓存Redis 响应缓存 TTL对应 Skill 给出RedisCacheset_llm_cache的完整用法见 langchain-architecture/SKILL.md连接池复用向量库连接如复用 Pinecone 客户端实例避免重复初始化负载均衡多 Agent worker round-robin 路由超时控制所有异步操作设置超时重试指数退避 最大重试次数。批量场景推荐用asyncio.gather并行处理文档分块与向量化同 Skill 的 Async Batch Processing 示例以显著提升吞吐。八、测试与评估LangSmith 评估套件命令文档要求为 Agent 建立系统化评估。核心代码from langsmith.evaluation import evaluate # 运行评估套件 eval_config RunEvalConfig( evaluators[qa, context_qa, cot_qa], eval_llmChatAnthropic(modelclaude-sonnet-5) ) results await evaluate( agent_function, datadataset_name, evaluatorseval_config )其中evaluators可选用三种评估器qa纯问答质量、context_qa基于上下文的事实性回答、cot_qa思维链问答并以 Claude Sonnet 5 作为评判模型LLM-as-Judge。llm-evaluationSkillSKILL.md进一步给出评估指标体系可在配置 Agent 评估时对照选用文本生成BLEUn-gram 重叠、ROUGE面向摘要的召回、METEOR语义相似度、BERTScore嵌入相似度、困惑度分类Accuracy、Precision/Recall/F1、混淆矩阵、AUC-ROC检索RAGMRR平均倒数排名、NDCG归一化折损累计增益、PrecisionK、RecallK人工评估维度准确性、连贯性、相关性、流畅度、安全性、有帮助程度LLM-as-Judge 范式逐点评分pointwise、两两对比pairwise、基于参考答案、无参考答案。九、关键模式速查9.1 状态图模式命令文档给出了 StateGraph 的标准骨架——节点、边、条件边与 Checkpointer 一应俱全builder StateGraph(MessagesState) builder.add_node(node1, node1_func) builder.add_node(node2, node2_func) builder.add_edge(START, node1) builder.add_conditional_edges(node1, router, {a: node2, b: END}) builder.add_edge(node2, END) agent builder.compile(checkpointercheckpointer)references/details.md还提供了「实体提取 → 分析 → 摘要」三阶段工作流的完整路由实现每个节点返回current_step路由函数据此返回Literal[analyze, summarize, end]配合add_conditional_edges的映射表实现动态流转。9.2 异步调用模式async def process_request(message: str, session_id: str): result await agent.ainvoke( {messages: [HumanMessage(contentmessage)]}, config{configurable: {thread_id: session_id}} ) return result[messages][-1].content9.3 错误处理模式from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) async def call_with_retry(): try: return await llm.ainvoke(prompt) except Exception as e: logger.error(fLLM error: {e}) raise该模式采用 tenacity 的指数退避策略最多重试 3 次退避区间 410 秒。十、实施清单与最佳实践10.1 从零到生产的一站式清单命令文档要求按以下清单逐项完成初始化 Claude Sonnet 5 模型配置 Voyage AI 嵌入voyage-3-large创建带异步支持与错误处理的工具实现内存系统按用例选型用 LangGraph 构建状态图加入 LangSmith 追踪实现流式响应配置健康检查与监控加入缓存层Redis配置重试逻辑与超时编写评估测试编写 API 端点文档与使用说明10.2 八条最佳实践始终异步ainvoke、astream、aget_relevant_documents优雅处理错误try/except fallback监控一切追踪、日志、指标覆盖所有操作优化成本缓存响应、使用 token 上限、压缩记忆保护密钥一律走环境变量禁止硬编码充分测试单元测试、集成测试、评估套件详尽文档API 文档、架构图、runbook状态版本化使用 Checkpointer 保证结果可复现。结语/llm-application-dev:langchain-agent命令把「生产级 LangGraph Agent」的完整技术栈浓缩为一份可直接执行的专家指令从 LangGraph 状态管理与 Checkpointer 记忆到 ReAct / Plan-and-Execute / 多 Agent 三种架构从 Voyage AI 嵌入与 Pinecone 混合检索的 RAG 管线到 Pydantic 结构化工具、FastAPI 流式部署、LangSmith 评估。配合插件内的 langchain-architecture、rag-implementation、embedding-strategies、hybrid-search-implementation、llm-evaluation 等 Skill你可以在自己的 Claude Code / Codex / Cursor / OpenCode 会话中直接复用这套模式快速交付可观测、可扩展、成本可控的 AI Agent 系统。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考