在实际 AI 应用开发中我们经常面临一个困境大语言模型LLM虽然知识渊博但它在执行复杂、多步骤任务时往往表现得像一个健谈但缺乏执行力的“顾问”。它知道“做什么”却难以独立、可靠地“完成”整个任务。这正是 Agent智能体技术要解决的核心问题。Agent 不是简单的聊天机器人它是一个能够感知环境、自主规划、调用工具并执行动作最终达成目标的智能系统。从自动化客服、代码生成助手到复杂的业务流程编排Agent 正在成为连接 LLM 认知能力与现实世界操作的关键桥梁。然而构建一个稳定、高效的 Agent 并非易事。开发者需要理解其核心架构如 ReAct、CoT 等模式学会集成外部工具Skills并有效管理其状态和记忆。更进一步为了让 Agent 具备更深层次的推理和关联能力知识图谱Knowledge Graph的引入变得至关重要。它能为 Agent 提供结构化的领域知识使其决策不再仅仅依赖于 LLM 的“常识”而是建立在精准、可追溯的事实关系之上。同时像 Vibe Coding 这类强调开发者直觉与 AI 协作的新型编程范式也在改变我们构建 Agent 的方式。本文旨在为有一定 AI 或编程基础的开发者提供一份从零构建一个具备知识增强能力的 Agent 的实战指南。我们将不仅涵盖 Agent 的核心概念与框架选择还会深入如何集成 Neo4j 知识图谱如何开发与管理自定义 Skills工具并探讨 Vibe Coding 思想在 Agent 开发流程中的应用。最终你将获得一个可运行的原型理解其中每一环的设计原理并掌握排查常见问题的方法。1. 理解 Agentic AI从概念到架构在深入代码之前我们必须厘清几个核心概念并理解一个典型 Agent 系统的运行架构。这有助于我们在后续实现中明确每一部分代码的职责。1.1 Agent、Skills 与 Agentic AIAgent智能体是一个能够自主行动的软件实体。在 LLM 驱动的上下文中它通常指一个系统该系统以 LLM 作为“大脑”接收用户目标Goal或任务Task然后通过“思考”决定下一步行动Action执行行动后观察结果Observation并循环此过程直至任务完成或无法继续。Skills技能是 Agent 赖以执行具体操作的工具。一个 Skill 可以是一个函数、一个 API 接口、一个数据库查询甚至是另一个软件模块。例如“查询天气”是一个 Skill“发送邮件”是另一个 Skill。Agent 的核心能力之一就是根据当前上下文从可用的 Skills 中选择最合适的一个来调用。Agentic AI智能体式 AI是一种强调 AI 系统应具备自主性、目标导向性和持续交互能力的范式。它不仅仅是让模型生成一段文本而是设计一套机制让 AI 能够像“智能体”一样在复杂环境中通过多轮决策和行动来解决问题。构建 Agent 就是在实践 Agentic AI。1.2 知识图谱在 Agent 中的作用LLM 拥有强大的语义理解和生成能力但其知识是隐式、静态且可能存在幻觉的。知识图谱通过“实体-关系-实体”的三元组形式显式地存储结构化知识。将其与 Agent 结合可以带来以下关键提升事实准确性增强当 Agent 需要回答涉及具体事实如产品参数、公司关系、历史事件时间线的问题时可以直接从知识图谱中查询确凿证据减少 LLM 的“编造”。可解释性与溯源Agent 的决策可以基于从知识图谱中检索到的路径进行解释例如“推荐产品 A 是因为它满足条件 X而条件 X 来源于知识图谱中的关系 Y”。复杂关系推理知识图谱擅长处理多跳关系查询。例如Agent 可以回答“我们公司有哪些供应商同时又是竞争对手的客户”这类需要连接多个关系的问题。长期记忆与状态管理知识图谱可以作为 Agent 的“长期记忆”存储关于用户、会话历史、任务上下文的结构化信息供后续决策使用。1.3 典型 Agent 系统架构ReAct 模式一个广泛采用的 Agent 架构是ReAct (Reason Act)模式。在这个模式中Agent 与环境的交互是一个循环思考ReasonLLM 根据当前任务描述、历史观察和可用工具列表分析现状决定下一步是给出最终答案还是调用某个工具。行动Act如果决定调用工具则生成格式化的工具调用请求包括工具名和参数。观察Observe执行工具获取工具返回的结果可能是成功的数据也可能是错误信息。循环将工具执行结果作为新的“观察”输入给 LLM进入下一轮思考。这个循环会持续进行直到 LLM 认为任务已经完成并输出最终答案。整个流程中一个关键的“编排器”Orchestrator负责维护这个循环管理对话历史并调用 LLM 和工具。1.4 Vibe Coding一种开发范式Vibe Coding并非一个具体的技术栈而是一种强调快速原型、交互式反馈和以“感觉”或“直觉”引导开发过程的编程思想。在 Agent 开发中Vibe Coding 体现为快速迭代不追求一开始就设计完美的架构而是先构建一个最小可行产品MVP通过与 Agent 交互来发现设计缺陷。交互式测试在开发过程中频繁地与正在构建的 Agent 对话测试其反应并根据反馈调整提示词Prompt、工具定义或流程逻辑。提示词即代码将精心设计的提示词视为核心“代码”其质量直接决定 Agent 的行为。Vibe Coding 鼓励不断微调提示词以达到最佳效果。理解了这些概念我们就可以开始着手搭建我们的开发环境了。2. 环境准备与核心工具选型构建一个 Agent 系统涉及多个组件。为了高效开发和后续集成我们需要选择合适的框架、数据库和 LLM 服务。以下配置是一个兼顾学习成本和生产可行性的方案。2.1 核心框架与库我们选择LangChain作为主要的 Agent 开发框架。它是一个强大的开源框架抽象了与 LLM 交互、工具调用、记忆管理、链式编排等复杂逻辑提供了大量开箱即用的组件极大降低了开发门槛。同时为了更灵活地定义和管理工具Skills我们会结合使用LangChain Tools和Microsoft’s Guidance或OpenAI’s Function Calling来确保工具调用的格式稳定。环境与依赖清单Python 3.9确保你的 Python 版本在 3.9 及以上。LangChain LangChain Community核心框架。OpenAI SDK或其他 LLM SDK用于调用大语言模型。本文以 OpenAI GPT 系列为例。Neo4j图数据库用于构建和存储知识图谱。我们将使用其 Python 驱动neo4j。FastAPI可选用于将 Skills 封装成 HTTP API 服务方便 Agent 远程调用。Docker推荐用于快速部署 Neo4j 数据库避免本地安装的复杂性。2.2 知识图谱数据库Neo4jNeo4j 是领先的图数据库其 Cypher 查询语言非常直观适合表示和查询知识图谱。我们将使用 Docker 运行它。使用 Docker 启动 Neo4j# 拉取 Neo4j 官方镜像 docker pull neo4j:latest # 运行 Neo4j 容器 # -p 7474:7474 浏览器访问端口 # -p 7687:7687 Bolt 协议端口Python驱动连接用 # -v 挂载数据卷持久化数据 # NEO4J_AUTHneo4j/your_password 设置默认用户和密码 docker run -d \ --name my-neo4j \ -p 7474:7474 \ -p 7687:7687 \ -v /path/to/your/neo4j/data:/data \ -v /path/to/your/neo4j/logs:/logs \ -v /path/to/your/neo4j/import:/var/lib/neo4j/import \ --env NEO4J_AUTHneo4j/your_strong_password \ neo4j:latest启动后可以通过浏览器访问http://localhost:7474使用用户名neo4j和你设置的密码登录 Neo4j Browser进行可视化操作。2.3 LLM 服务配置你需要一个 LLM 服务的 API Key。这里以 OpenAI 为例。访问 OpenAI 平台创建账户并获取 API Key。在项目中通常通过环境变量来管理密钥避免硬编码。# 在终端中设置环境变量Linux/macOS export OPENAI_API_KEYyour-api-key-here # 或者在项目根目录创建 .env 文件 # OPENAI_API_KEYyour-api-key-here2.4 项目初始化与依赖安装创建一个新的项目目录并初始化虚拟环境。# 创建项目目录 mkdir agentic-ai-project cd agentic-ai-project # 创建虚拟环境Python 3.9 python -m venv venv # 激活虚拟环境 # Windows venv\Scripts\activate # Linux/macOS source venv/bin/activate # 安装核心依赖 pip install langchain langchain-community langchain-openai pip install neo4j python-dotenv fastapi uvicorn requests创建项目基础结构agentic-ai-project/ ├── .env # 环境变量文件 ├── requirements.txt # 依赖列表 ├── main.py # Agent 主程序入口 ├── knowledge_graph/ # 知识图谱相关模块 │ ├── __init__.py │ ├── connector.py # Neo4j 连接器 │ └── builder.py # 知识图谱构建脚本 ├── skills/ # 工具Skills模块 │ ├── __init__.py │ ├── base_tool.py # 工具基类 │ ├── weather_tool.py # 示例天气查询工具 │ └── kg_query_tool.py # 知识图谱查询工具 └── prompts/ # 提示词模板目录 └── agent_prompt.txt现在基础环境已经就绪。接下来我们将首先构建知识图谱为 Agent 提供“事实大脑”。3. 构建与集成知识图谱知识图谱是 Agent 的“长期记忆”和“事实库”。我们先从 Neo4j 连接开始然后创建一些示例数据最后将其封装成一个可供 Agent 调用的 Skill。3.1 连接 Neo4j 并初始化数据在knowledge_graph/connector.py中我们创建数据库连接类。# knowledge_graph/connector.py from neo4j import GraphDatabase import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 class Neo4jConnector: def __init__(self): # 从环境变量读取连接信息 self.uri os.getenv(NEO4J_URI, bolt://localhost:7687) self.user os.getenv(NEO4J_USER, neo4j) self.password os.getenv(NEO4J_PASSWORD, your_strong_password) self.driver None def connect(self): 建立数据库连接 try: self.driver GraphDatabase.driver(self.uri, auth(self.user, self.password)) # 测试连接 with self.driver.session() as session: result session.run(RETURN 1 AS x) print(Neo4j 连接成功) return True except Exception as e: print(f连接 Neo4j 失败: {e}) return False def close(self): 关闭数据库连接 if self.driver: self.driver.close() def run_query(self, query, parametersNone): 执行一个 Cypher 查询返回结果列表 if not self.driver: self.connect() with self.driver.session() as session: result session.run(query, parameters or {}) # 将结果转换为字典列表便于处理 return [record.data() for record in result]在knowledge_graph/builder.py中我们编写一个脚本来创建示例图谱。假设我们构建一个关于“科技公司”的微型知识图谱。# knowledge_graph/builder.py from connector import Neo4jConnector def build_sample_kg(): kg Neo4jConnector() if not kg.connect(): return # 清空现有数据仅用于示例生产环境慎用 kg.run_query(MATCH (n) DETACH DELETE n) # 创建节点和关系 queries [ # 创建公司节点 CREATE (a:Company {name:OpenAI, founded:2015, domain:AI Research}), CREATE (b:Company {name:Microsoft, founded:1975, domain:Software}), CREATE (c:Company {name:NVIDIA, founded:1993, domain:Hardware}), # 创建人物节点 CREATE (p1:Person {name:Sam Altman, role:CEO}), CREATE (p2:Person {name:Satya Nadella, role:CEO}), # 创建关系 MATCH (a:Company {name:OpenAI}), (p1:Person {name:Sam Altman}) CREATE (p1)-[:LEADS]-(a), MATCH (b:Company {name:Microsoft}), (p2:Person {name:Satya Nadella}) CREATE (p2)-[:LEADS]-(b), MATCH (a:Company {name:OpenAI}), (b:Company {name:Microsoft}) CREATE (a)-[:PARTNER_WITH {since:2023}]-(b), MATCH (c:Company {name:NVIDIA}), (a:Company {name:OpenAI}) CREATE (a)-[:USES_CHIPS_FROM]-(c), ] for query in queries: kg.run_query(query) print(f执行查询: {query[:50]}...) print(示例知识图谱构建完成) kg.close() if __name__ __main__: build_sample_kg()运行此脚本 (python knowledge_graph/builder.py)数据便存入 Neo4j。你可以在 Neo4j Browser (localhost:7474) 中执行MATCH (n) RETURN n查看可视化图谱。3.2 将知识图谱查询封装为 Agent 的 SkillAgent 需要通过一个标准的接口来访问知识图谱。我们使用 LangChain 的BaseTool类来封装这个功能。在skills/kg_query_tool.py中# skills/kg_query_tool.py from langchain.tools import BaseTool from typing import Optional, Type from pydantic import BaseModel, Field import sys import os sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from knowledge_graph.connector import Neo4jConnector class KnowledgeGraphQueryInput(BaseModel): 知识图谱查询工具的输入模型。 query: str Field(description一个用自然语言描述的问题例如OpenAI的CEO是谁 或 微软和哪些公司有合作关系) class KnowledgeGraphQueryTool(BaseTool): name query_knowledge_graph description 当问题涉及公司、人物、产品及其关系等结构化事实时使用此工具从知识图谱中查询准确信息。输入应为自然语言问题。 args_schema: Type[BaseModel] KnowledgeGraphQueryInput def _run(self, query: str) - str: 执行工具的主要逻辑将自然语言问题转换为 Cypher 查询并执行。 # 注意这里简化了实际应用中你需要一个更复杂的模块或调用另一个LLM # 来将自然语言问题 query 转换为 Cypher 查询。 # 此处为了演示我们使用一个简单的规则映射。 cypher_query self._natural_language_to_cypher(query) if not cypher_query: return 抱歉我无法理解这个问题请尝试换一种方式提问关于公司或人物的关系。 kg Neo4jConnector() try: results kg.run_query(cypher_query) kg.close() if not results: return 在知识图谱中没有找到相关信息。 # 将结果格式化为易读的文本 return self._format_results(results) except Exception as e: return f查询知识图谱时出错: {e} def _natural_language_to_cypher(self, nl_query: str) - Optional[str]: 一个极其简化的 NLQ 到 Cypher 的转换。生产环境应使用更复杂的方法。 nl_query_lower nl_query.lower() if ceo in nl_query_lower and openai in nl_query_lower: return MATCH (p:Person)-[:LEADS]-(c:Company {name:OpenAI}) RETURN p.name AS name, p.role AS role elif partner in nl_query_lower and microsoft in nl_query_lower: return MATCH (c1:Company {name:Microsoft})-[:PARTNER_WITH]-(c2:Company) RETURN c2.name AS partner, c2.domain AS domain elif founded in nl_query_lower and nvidia in nl_query_lower: return MATCH (c:Company {name:NVIDIA}) RETURN c.name AS name, c.founded AS founded_year else: # 更通用的查询查找包含关键词的节点 # 这是一个非常基础的示例实际应用需要更精细的解析。 words nl_query_lower.split() for word in words: if len(word) 3: # 忽略短词 return fMATCH (n) WHERE toLower(n.name) CONTAINS {word} OR toLower(n.domain) CONTAINS {word} RETURN n.name AS name, labels(n) AS type, n.domain AS domain LIMIT 5 return None def _format_results(self, results: list) - str: 将查询结果格式化为字符串。 formatted [] for i, record in enumerate(results, 1): formatted.append(f{i}. {record}) return \n.join(formatted) if formatted else 无结果 async def _arun(self, query: str) - str: 异步版本如果需要。 raise NotImplementedError(此工具不支持异步调用。)这个KnowledgeGraphQueryTool类定义了一个标准的 LangChain Tool。当 Agent 决定使用它时会传入一个自然语言问题工具内部在_run方法中尝试将其转换为 Cypher 查询执行并返回结果。注意_natural_language_to_cypher函数是最大的简化。在实际项目中这通常是一个复杂的模块可能涉及另一个专门的 LLM 调用Text-to-Cypher或使用预定义的查询模板。这里仅用于演示流程。现在我们已经有了一个结构化的知识源和一个访问它的标准工具。接下来我们创建另一个更简单的 Skill并最终将它们组装到 Agent 中。4. 开发与组装 Agent 核心我们将创建一个具备多种 Skills 的 Agent并使用 LangChain 的 Agent 执行器来运行 ReAct 循环。4.1 创建更多示例 Skills为了让 Agent 更实用我们再添加一个简单的“天气查询”工具模拟和一个“计算器”工具。在skills/weather_tool.py中# skills/weather_tool.py from langchain.tools import BaseTool from typing import Optional, Type from pydantic import BaseModel, Field import requests class WeatherQueryInput(BaseModel): location: str Field(description城市名称例如北京、Shanghai) class WeatherQueryTool(BaseTool): name get_weather description 获取指定城市的当前天气信息。 args_schema: Type[BaseModel] WeatherQueryInput def _run(self, location: str) - str: # 这是一个模拟工具实际应调用如 OpenWeatherMap 的 API # 这里返回模拟数据 mock_data { 北京: {temp: 22°C, condition: 晴朗, humidity: 40%}, 上海: {temp: 25°C, condition: 多云, humidity: 65%}, 深圳: {temp: 28°C, condition: 阵雨, humidity: 80%}, } weather mock_data.get(location, None) if weather: return f{location}的天气温度{weather[temp]}{weather[condition]}湿度{weather[humidity]}。 else: return f未找到{city}的天气信息目前支持北京、上海、深圳。 async def _arun(self, location: str) - str: raise NotImplementedError(此工具不支持异步调用。)在skills/calculator_tool.py中# skills/calculator_tool.py from langchain.tools import BaseTool from typing import Optional, Type from pydantic import BaseModel, Field import math class CalculatorInput(BaseModel): expression: str Field(description一个数学表达式例如3 5 * 2 或 sqrt(16)) class CalculatorTool(BaseTool): name calculator description 执行数学计算。支持加减乘除和常见函数如 sqrt, sin, cos。请提供清晰的表达式。 args_schema: Type[BaseModel] CalculatorInput def _run(self, expression: str) - str: try: # 警告使用 eval 有安全风险仅用于演示。生产环境必须使用安全的表达式求值库如 ast.literal_eval 或 numexpr。 # 这里进行了极简的安全过滤切勿在生产中直接使用。 if any(keyword in expression.lower() for keyword in [import, os, sys, exec, eval, __]): return 表达式包含不安全字符拒绝计算。 # 替换常见的数学函数 expression expression.replace(sqrt, math.sqrt).replace(sin, math.sin).replace(cos, math.cos) result eval(expression, {__builtins__: {}}, {math: math}) return f计算结果: {result} except Exception as e: return f计算表达式 {expression} 时出错: {e} async def _arun(self, expression: str) - str: raise NotImplementedError(此工具不支持异步调用。)4.2 初始化 LLM 并创建 Agent 执行器现在在main.py中我们将所有组件组装起来。# main.py import os from dotenv import load_dotenv from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain.prompts import PromptTemplate from skills.kg_query_tool import KnowledgeGraphQueryTool from skills.weather_tool import WeatherQueryTool from skills.calculator_tool import CalculatorTool # 加载环境变量 load_dotenv() def main(): # 1. 初始化 LLM # 确保 OPENAI_API_KEY 已在 .env 文件中设置 llm ChatOpenAI( modelgpt-3.5-turbo, # 或 gpt-4 temperature0, # 降低随机性使 Agent 行为更确定 api_keyos.getenv(OPENAI_API_KEY) ) # 2. 准备工具列表 tools [ KnowledgeGraphQueryTool(), WeatherQueryTool(), CalculatorTool(), ] # 3. 定义 ReAct 风格的提示词模板 # 这个模板告诉 LLM 如何思考、使用工具和格式化输出。 prompt_template 你是一个有帮助的 AI 助手可以访问以下工具 {tools} 请严格按照以下格式使用工具 思考你需要先思考当前情况决定是否需要使用工具。 行动你选择的工具名称必须是以下之一[{tool_names}] 行动输入工具的输入参数 观察工具返回的结果 ... (这个 思考/行动/行动输入/观察 循环可以重复多次) 当你有了最终答案时必须使用以下格式 最终答案你的最终回答 开始 之前的对话历史 {chat_history} 用户输入{input} {agent_scratchpad} prompt PromptTemplate.from_template(prompt_template) # 4. 创建 Agent # 使用 LangChain 的 create_react_agent 辅助函数 agent create_react_agent(llm, tools, prompt) # 5. 创建 Agent 执行器它负责管理循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设置为 True 可以看到 Agent 的思考过程调试时非常有用 handle_parsing_errorsTrue, # 处理解析错误 max_iterations5, # 限制最大循环次数防止无限循环 early_stopping_methodgenerate, # 当 Agent 认为任务完成时停止 ) print(Agent 已启动输入 quit 或 exit 退出。) print(- * 50) # 6. 交互循环 while True: try: user_input input(\n你的问题: ) if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input.strip(): continue # 执行 Agent response agent_executor.invoke({input: user_input, chat_history: }) print(f\n助手: {response[output]}) except KeyboardInterrupt: print(\n程序被中断。) break except Exception as e: print(f\n运行过程中出现错误: {e}) if __name__ __main__: main()4.3 运行与验证在运行前请确保Neo4j 容器正在运行并且示例知识图谱已构建。.env文件中正确设置了OPENAI_API_KEY。所有依赖已安装。在项目根目录下执行python main.py你将看到类似以下的交互过程verboseTrue会打印详细思考过程Agent 已启动输入 quit 或 exit 退出。 -------------------------------------------------- 你的问题: OpenAI 的 CEO 是谁 思考用户问的是关于 OpenAI 公司 CEO 的事实信息。我应该使用知识图谱查询工具来获取准确信息。 行动query_knowledge_graph 行动输入OpenAI的CEO是谁 观察1. {name: Sam Altman, role: CEO} 思考我已经从知识图谱中得到了答案。可以给出最终答案了。 最终答案OpenAI 的 CEO 是 Sam Altman。 助手: OpenAI 的 CEO 是 Sam Altman。你的问题: 北京天气怎么样 思考用户询问天气信息。我应该使用天气查询工具。 行动get_weather 行动输入北京 观察北京的天气温度22°C晴朗湿度40%。 思考我已经得到了天气信息可以给出最终答案。 最终答案北京当前天气晴朗温度22°C湿度40%。 助手: 北京当前天气晴朗温度22°C湿度40%。你的问题: 微软和哪些公司有合作 思考用户询问微软的合作关系这属于公司间的关系查询应该使用知识图谱工具。 行动query_knowledge_graph 行动输入微软和哪些公司有合作 观察1. {partner: OpenAI, domain: AI Research} 思考从知识图谱中查到微软与 OpenAI 有合作关系。可以回答用户了。 最终答案根据知识图谱微软与 OpenAI 公司领域AI Research存在合作关系。 助手: 根据知识图谱微软与 OpenAI 公司领域AI Research存在合作关系。你的问题: 计算一下 3 的平方加上 4 的平方等于多少 思考这是一个数学计算问题。我应该使用计算器工具。 行动calculator 行动输入3**2 4**2 观察计算结果: 25 思考计算完成得到结果。 最终答案3 的平方 (9) 加上 4 的平方 (16) 等于 25。 助手: 3 的平方 (9) 加上 4 的平方 (16) 等于 25。通过以上交互你可以看到 Agent 成功地在不同任务间进行判断并选择了正确的工具。当问题涉及知识图谱中的结构化事实时它使用了query_knowledge_graph当需要计算或查询天气时它又切换到了其他工具。这就是一个具备多技能Skills和知识增强Knowledge Graph的 Agent 的基本形态。5. 关键配置、参数与原理详解仅仅让程序跑起来还不够理解其背后的配置和原理才能应对更复杂的需求和问题。5.1 LLM 模型与参数选择在ChatOpenAI初始化时有几个关键参数model选择gpt-3.5-turbo成本较低、速度较快适合开发和测试。gpt-4在复杂推理和遵循指令方面更强但成本更高、速度更慢。根据任务复杂度选择。temperature控制输出的随机性。范围 0 到 2。对于 Agent 这种需要稳定、可靠执行动作的场景通常设置为0或接近 0 的值如 0.1以减少不可预测的行为。max_tokens限制单次响应的最大长度。对于 Agent 的“思考”步骤通常不需要太长的响应可以适当限制以节省成本。5.2 Agent 执行器参数AgentExecutor是控制 Agent 生命周期的核心verboseTrue调试必备。它会打印出 Agent 内部的“思考”、“行动”、“观察”的完整链条是理解 Agent 为何做出某个决策的最重要手段。handle_parsing_errorsTrue当 LLM 的输出不符合工具调用的预期格式时这个参数允许执行器尝试修复或给出友好错误而不是直接崩溃。max_iterations安全阀。防止 Agent 陷入死循环。如果一个简单问题需要超过 5 轮工具调用可能意味着提示词设计有问题或工具选择不当。early_stopping_methodgenerate当 Agent 的输出以“最终答案”开头时执行器会停止循环。这依赖于提示词模板中的严格格式要求。5.3 提示词工程Agent 的“行为准则”prompt_template是 Agent 的“大脑软件”。它定义了 Agent 的思考框架。一个有效的 ReAct 提示词通常包含角色定义告诉 LLM 它是什么“有帮助的 AI 助手”。工具描述{tools}和{tool_names}会被自动替换为可用工具列表LLM 需要知道它能用什么。格式指令强制 LLM 按照“思考/行动/观察”的固定格式输出。这是实现结构化交互的关键。历史上下文{chat_history}允许 Agent 记住之前的对话实现多轮交互本例中初始为空。用户输入{input}是当前问题。暂存器{agent_scratchpad}是一个特殊变量LangChain 会自动将之前的“行动”和“观察”记录填充进去供 LLM 在下一轮思考时参考。为什么格式如此重要因为 LangChain 的 Agent 执行器会解析 LLM 的输出寻找特定的关键词如“行动”来触发工具调用。如果格式混乱解析就会失败。5.4 工具Skill设计要点清晰的名称和描述name和description是 LLM 选择工具的主要依据。描述应准确说明工具的用途和适用场景。例如“查询知识图谱”比“查询数据库”更明确。强类型的输入模式使用 Pydantic 的BaseModel定义args_schema可以给 LLM 提供清晰的参数结构和描述显著提高它生成正确参数的能力。健壮的错误处理在工具的_run方法中必须用try-except包裹核心逻辑并返回友好的错误信息。一个崩溃的工具会导致整个 Agent 运行失败。结果格式化工具返回的字符串应该简洁、信息丰富便于 LLM 理解并整合到后续的思考中。6. 常见问题排查与优化实践在开发和使用 Agent 过程中你会遇到各种问题。下面是一些典型场景的排查路径和优化建议。6.1 Agent 行为异常排查表问题现象可能原因检查与解决步骤Agent 不调用任何工具直接给出答案可能是错误的1. 提示词未强调使用工具。2. 工具描述不够清晰LLM 不知道何时用。3. LLMtemperature过高行为不稳定。1. 检查提示词模板确保有明确的格式指令和工具列表。2. 优化工具的描述 (description)使其更匹配用户问题。3. 将temperature设为 0 再测试。Agent 陷入循环反复调用同一个工具1. 工具返回的结果未能让 LLM 认为任务完成。2.max_iterations设置过高。3. 工具结果格式混乱LLM 无法理解。1. 开启verboseTrue观察“观察”内容是否有效。2. 检查工具返回的字符串是否清晰。尝试简化结果。3. 在提示词中加强“当得到 X 信息后你应该给出最终答案”的指令。解析错误Parsing LLM output errorLLM 的输出不符合“行动工具名”的预期格式。1. 开启verboseTrue查看 LLM 的原始输出确认其是否遵循格式。2. 简化提示词使用更明确的格式要求。3. 使用handle_parsing_errorsTrue让执行器尝试恢复。4. 考虑换用支持“函数调用”Function Calling的模型和 Agent 类型格式更稳定。工具执行出错1. 工具代码本身有 Bug。2. LLM 生成的输入参数不符合工具args_schema的要求。3. 外部服务如 Neo4j、天气 API不可用。1. 单独测试工具函数确保其能正确处理各种输入。2. 检查verbose日志中“行动输入”的内容是否正确。3. 检查网络连接、数据库状态和 API 密钥。知识图谱查询返回空或错误结果1. 自然语言到 Cypher 的转换 (_natural_language_to_cypher) 逻辑不匹配用户问题。2. 知识图谱中不存在相关数据。3. Cypher 查询语法错误。1. 打印出转换后的 Cypher 查询语句进行验证。2. 在 Neo4j Browser 中手动执行该查询确认数据和语法。3. 考虑引入一个更强大的 Text2Cypher 微调模型或使用图查询生成服务。6.2 性能与稳定性优化实践优化提示词这是提升 Agent 表现性价比最高的方法。通过反复测试Vibe Coding 思想微调提示词中的角色设定、格式要求和工具描述。可以使用 LangChain 的PromptTemplate进行模块化管理。使用更稳定的工具调用方式OpenAI 的 GPT 系列模型原生支持Function Calling。LangChain 提供了create_openai_tools_agent它能利用此特性让模型以 JSON 格式输出工具调用请求格式更稳定解析成功率远高于文本解析。实现对话历史管理当前的chat_history是空的。要实现多轮对话需要维护一个历史列表并在每次调用时将其格式化后传入agent_executor.invoke()。注意历史长度过长可能导致 token 超限。为知识图谱查询添加缓存对于频繁查询的相同或类似问题可以在工具层或 Agent 外层添加缓存机制如functools.lru_cache避免重复查询图数据库提升响应速度。结构化工具输出让工具返回结构化的数据如 Pydantic 对象而不仅仅是字符串。这有助于后续的 Agent 或其它系统组件进行更精确的处理。实施超时和重试机制对于调用外部 API 的工具如天气查询应设置网络超时并考虑在失败时进行有限次数的重试。日志与监控在生产环境中记录 Agent 的每一次“思考-行动-观察”循环、工具调用耗时和最终结果。这对于分析性能瓶颈、理解用户意图和调试异常至关重要。6.3 知识图谱集成的深入方向我们当前的 Text2Cypher 转换极其简陋。生产级应用需要考虑专用 Text2Cypher 模型训练或微调一个模型专门用于将自然语言问题转换为高质量的 Cypher 查询。这需要大量的问题Cypher配对数据。检索增强生成RAG与图谱结合结合向量数据库进行混合检索。先用向量搜索找到相关文本片段再用知识图谱查询其中的实体和关系最后综合两者信息生成答案。图上下文注入在提问前先从知识图谱中检索出与问题相关的子图实体和关系将其作为上下文和问题一起送给 LLM让 LLM 在丰富的图谱上下文中进行推理和回答无需每次都生成 Cypher。7. 扩展方向与生产环境考量当你掌握了基础 Agent 的构建后可以考虑以下方向进行深化和扩展。7.1 技能Skills生态扩展集成真实 API将天气工具替换为真实的 OpenWeatherMap API添加股票查询、新闻摘要、邮件发送、日历管理等实用技能。代码执行 Skill创建一个安全的沙盒环境让 Agent 能够编写并执行 Python 代码片段来解决复杂问题需极其注意安全隔离。文件操作 Skill让 Agent 能够读取、分析、总结本地文档如 PDF、Word的内容。Skill 的动态注册与发现设计一个中心化的 Skill 注册表支持热插拔无需重启 Agent 即可添加新功能。7.2 多 Agent 协作系统单个 Agent 能力有限。可以设计一个多 Agent 系统规划 Agent负责分解复杂任务为子任务。执行 Agent专精于某类技能如数据分析 Agent、代码生成 Agent。评审 Agent检查其他 Agent 的工作结果。协调者管理这些 Agent 之间的通信和任务分配。这可以通过 LangChain 的AgentExecutor与LLMChain组合或使用更高级的框架如 AutoGen、CrewAI来实现。7.3 生产环境部署清单将学习原型转化为生产服务需要额外关注配置管理将所有配置API Keys、数据库连接串、模型参数外置到环境变量或配置中心如 Apollo、Nacos。可观测性集成日志如 Structlog、指标如 Prometheus和分布式追踪如 OpenTelemetry全面监控 Agent 的健康状况、性能指标和错误。限流与熔断对 LLM API 和外部工具调用实施限流防止因意外流量或错误导致费用激增或服务雪崩。安全性输入净化对用户输入进行严格的检查和过滤防止提示词注入攻击。工具权限控制为不同用户或场景的 Agent 分配不同的工具访问权限例如普通用户不能调用“删除数据库”工具。输出审查对 Agent 的最终输出进行内容安全过滤。版本化与回滚对 Agent 的提示词、工具集进行版本管理确保可以快速回滚到稳定版本。构建一个成熟的 Agentic AI 系统是一个持续迭代的过程。从本文的最小可行原型出发结合 Vibe Coding 的快速反馈理念不断测试、调整、扩展你就能逐步搭建起真正解决实际业务问题的智能体。核心在于理解每个组件的职责LLM 负责推理Tools 负责执行Orchestrator 负责调度KG 负责记忆并让它们通过清晰、稳定的协议协同工作。 在实际 AI 应用开发中我们经常面临一个困境大语言模型LLM虽然知识渊博但它在执行复杂、多步骤任务时往往表现得像一个健谈但缺乏执行力的“顾问”。它知道“做什么”却难以独立、可靠地“完成”整个任务。这正是 Agent智能体技术要解决的核心问题。Agent 不是简单的聊天机器人它是一个能够感知环境、自主规划、调用工具并执行动作最终达成目标的智能系统。从自动化客服、代码生成助手到复杂的业务流程编排Agent 正在成为连接 LLM 认知能力与现实世界操作的关键桥梁。然而构建一个稳定、高效的 Agent 并非易事。开发者需要理解其核心架构如 ReAct、CoT 等模式学会集成外部工具Skills并有效管理其状态和记忆。更进一步为了让 Agent 具备更深层次的推理和关联能力知识图谱Knowledge Graph的引入变得至关重要。它能为 Agent 提供结构化的领域知识使其决策不再仅仅依赖于 LLM 的“常识”而是建立在精准、可追溯的事实关系之上。同时像 Vibe Coding 这类强调开发者直觉与 AI 协作的新型编程范式也在改变我们构建 Agent 的方式。本文旨在为有一定 AI 或编程基础的开发者提供一份从零构建一个具备知识增强能力的 Agent 的实战指南。我们将不仅涵盖 Agent 的核心概念与框架选择还会深入如何集成 Neo4j 知识图谱如何开发与管理自定义 Skills工具并探讨 Vibe Coding 思想在 Agent 开发流程中的应用。最终你将获得一个可运行的原型理解其中每一环的设计原理并掌握排查常见问题的方法。1. 理解 Agentic AI从概念到架构在深入代码之前我们必须厘清几个核心概念并理解一个典型 Agent 系统的运行架构。这有助于我们在后续实现中明确每一部分代码的职责。1.1 Agent、Skills 与 Agentic AIAgent智能体是一个能够自主行动的软件实体。在 LLM 驱动的上下文中它通常指一个系统该系统以 LLM 作为“大脑”接收用户目标Goal或任务Task然后通过“思考”决定下一步行动Action执行行动后观察结果Observation并循环此过程直至任务完成或无法继续。Skills技能是 Agent 赖以执行具体操作的工具。一个 Skill 可以是一个函数、一个 API 接口、一个数据库查询甚至是另一个软件模块。例如“查询天气”是一个 Skill“发送邮件”是另一个 Skill。Agent 的核心能力之一就是根据当前上下文从可用的 Skills 中选择最合适的一个来调用。Agentic AI智能体式 AI是一种强调 AI 系统应具备自主性、目标导向性和持续交互能力的范式。它不仅仅是让模型生成一段文本而是设计一套机制让 AI 能够像“智能体”一样在复杂环境中通过多轮决策和行动来解决问题。构建 Agent 就是在实践 Agentic AI。1.2 知识图谱在 Agent 中的作用LLM 拥有强大的语义理解和生成能力但其知识是隐式、静态且可能存在幻觉的。知识图谱通过“实体-关系-实体”的三元组形式显式地存储结构化知识。将其与 Agent 结合可以带来以下关键提升事实准确性增强当 Agent 需要回答涉及具体事实如产品参数、公司关系、历史事件时间线的问题时可以直接从知识图谱中查询确凿证据减少 LLM 的“编造”。可解释性与溯源Agent 的决策可以基于从知识图谱中检索到的路径进行解释例如“推荐产品 A 是因为它满足条件 X而条件 X 来源于知识图谱中的关系 Y”。复杂关系推理知识图谱擅长处理多跳关系查询。例如Agent 可以回答“我们公司有哪些供应商同时又是竞争对手的客户”这类需要连接多个关系的问题。长期记忆与状态管理知识图谱可以作为 Agent 的“长期记忆”存储关于用户、会话历史、任务上下文的结构化信息供后续决策使用。1.3 典型 Agent 系统架构ReAct 模式一个广泛采用的 Agent 架构是ReAct (Reason Act)模式。在这个模式中Agent 与环境的交互是一个循环思考ReasonLLM 根据当前任务描述、历史观察和可用工具列表分析现状决定下一步是给出最终答案还是调用某个工具。行动Act如果决定调用工具则生成格式化的工具调用请求包括工具名和参数。观察Observe执行工具获取工具返回的结果可能是成功的数据也可能是错误信息。循环将工具执行结果作为新的“观察”输入给 LLM进入下一轮思考。这个循环会持续进行直到 LLM 认为任务已经完成并输出最终答案。整个流程中一个关键的“编排器”Orchestrator负责维护这个循环管理对话历史并调用 LLM 和工具。1.4 Vibe Coding一种开发范式Vibe Coding并非一个具体的技术栈而是一种强调快速原型、交互式反馈和以“感觉”或“直觉”引导开发过程的编程思想。在 Agent 开发中Vibe Coding 体现为快速迭代不追求一开始就设计完美的架构而是先构建一个最小可行产品MVP通过与 Agent 交互来发现设计缺陷。交互式测试在开发过程中频繁地与正在构建的 Agent 对话测试其反应并根据反馈调整提示词Prompt、工具定义或流程逻辑。提示词即代码将精心设计的提示词视为核心“代码”其质量直接决定 Agent 的行为。Vibe Coding 鼓励不断微调提示词以达到最佳效果。理解了这些概念我们就可以开始着手搭建我们的开发环境了。2. 环境准备与核心工具选型构建一个 Agent 系统涉及多个组件。为了高效开发和后续集成我们需要选择合适的框架、数据库和 LLM 服务。以下配置是一个兼顾学习成本和生产可行性的方案。2.1 核心框架与库我们选择LangChain作为主要的 Agent 开发框架。它是一个强大的开源框架抽象了与 LLM 交互、工具调用、记忆管理、链式编排等复杂逻辑提供了大量开箱即用的组件极大降低了开发门槛。同时为了更灵活地定义和管理工具Skills我们会结合使用LangChain Tools和Microsoft’s Guidance或OpenAI’s Function Calling来确保工具调用的格式稳定。环境与依赖清单Python 3.9确保你的 Python 版本在 3.9 及以上。LangChain LangChain Community核心框架。OpenAI SDK或其他 LLM SDK用于调用大语言模型。本文以 OpenAI GPT 系列为例。Neo4j图数据库用于构建和存储知识图谱。我们将使用其 Python 驱动neo4j。FastAPI可选用于将 Skills 封装成 HTTP API 服务方便 Agent 远程调用。Docker推荐用于快速部署 Neo4j 数据库避免本地安装的复杂性。2.2 知识图谱数据库Neo4jNeo4j 是领先的图数据库其 Cypher 查询语言非常直观适合表示和查询知识图谱。我们将使用 Docker 运行它。使用 Docker 启动 Neo4j# 拉取 Neo4j 官方镜像 docker pull neo4j:latest # 运行 Neo4j 容器 # -p 7474:7474 浏览器访问端口 # -p 7687:7687 Bolt 协议端口Python驱动连接用 # -v 挂载数据卷持久化数据 # NEO4J_AUTHneo4j/your_password 设置默认用户和密码 docker run -d \ --name my-neo4j \ -p 7474:7474 \ -p 7687:7687 \ -v /path/to/your/neo4j/data:/data \ -v /path/to/your/neo4j/logs:/logs \ -v /path/to/your/neo4j/import:/var/lib/neo4j/import \ --env NEO4J_AUTHneo4j/your_strong_password \ neo4j:latest启动后可以通过浏览器访问http://localhost:7474使用用户名neo4j和你设置的密码登录 Neo4j Browser进行可视化操作。2.3 LLM 服务配置你需要一个 LLM 服务的 API Key。这里以 OpenAI 为例。访问 OpenAI 平台创建账户并获取 API Key。在项目中通常通过环境变量来管理密钥避免硬编码。# 在终端中设置环境变量Linux/macOS export OPENAI_API_KEYyour-api-key-here # 或者在项目根目录创建 .env 文件 # OPENAI_API_KEYyour-api-key-here2.4 项目初始化与依赖安装创建一个新的项目目录并初始化虚拟环境。# 创建项目目录 mkdir agentic-ai-project cd agentic-ai-project # 创建虚拟环境Python 3.9 python -m venv venv # 激活虚拟环境 # Windows venv\Scripts\activate # Linux/macOS source venv/bin/activate # 安装核心依赖 pip install langchain langchain-community langchain-openai pip install neo4j python-dotenv fastapi uvicorn requests创建项目基础结构agentic-ai-project/ ├── .env # 环境变量文件 ├── requirements.txt # 依赖列表 ├── main.py # Agent 主程序入口 ├── knowledge_graph/ # 知识图谱相关模块 │ ├── __init__.py │ ├── connector.py # Neo4j 连接器 │ └── builder.py # 知识图谱构建脚本 ├── skills/ # 工具Skills模块 │ ├── __init__.py │ ├── base_tool.py # 工具基类 │ ├── weather_tool.py # 示例天气查询工具 │ └── kg_query_tool.py # 知识图谱查询工具 └── prompts/ # 提示词模板目录 └── agent_prompt.txt现在基础环境已经就绪。接下来我们将首先构建知识图谱为 Agent 提供“事实大脑”。3. 构建与集成知识图谱知识图谱是 Agent 的“长期记忆”和“事实库”。我们先从 Neo4j 连接开始然后创建一些示例数据最后将其封装成一个可供 Agent 调用的 Skill。3.1 连接 Neo4j 并初始化数据在knowledge_graph/connector.py中我们创建数据库连接类。# knowledge_graph/connector.py from neo4j import GraphDatabase import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 class Neo4jConnector: def __init__(self): # 从环境变量读取连接信息 self.uri os.getenv(NEO4J_URI, bolt://localhost:7687) self.user os.getenv(NEO4J_USER, neo4j) self.password os.getenv(NEO4J_PASSWORD, your_strong_password) self.driver None def connect(self): 建立数据库连接 try: self.driver GraphDatabase.driver(self.uri, auth(self.user, self.password)) # 测试连接 with self.driver.session() as session: result session.run(RETURN 1 AS x) print(Neo4j 连接成功) return True except Exception as e: print(f连接 Neo4j 失败: {e}) return False def close(self): 关闭数据库连接 if self.driver: self.driver.close() def run_query(self, query, parametersNone): 执行一个 Cypher 查询返回结果列表 if not self.driver: self.connect() with self.driver.session() as session: result session.run(query, parameters or {}) # 将结果转换为字典列表便于处理 return [record.data() for record in result]在knowledge_graph/builder.py中我们编写一个脚本来创建示例图谱。假设我们构建一个关于“科技公司”的微型知识图谱。# knowledge_graph/builder.py from connector import Neo4jConnector def build_sample_kg(): kg Neo4jConnector() if not kg.connect(): return # 清空现有数据仅用于示例生产环境慎用 kg.run_query(MATCH (n) DETACH DELETE n) # 创建节点和关系 queries [ # 创建公司节点 CREATE (a:Company {name:OpenAI, founded:2015, domain:AI Research}), CREATE (b:Company {name:Microsoft, founded:1975, domain:Software}), CREATE (c:Company {name:NVIDIA, founded:1993, domain:Hardware}), # 创建人物节点 CREATE (p1:Person {name:Sam Altman, role:CEO}), CREATE (p2:Person {name:Satya Nadella, role:CEO}), # 创建关系 MATCH (a:Company {name:OpenAI}), (p1:Person {name:Sam Altman}) CREATE (p1)-[:LEADS]-(a), MATCH (b:Company {name:Microsoft}), (p2:Person {name:Satya Nadella}) CREATE (p2)-[:LEADS]-(b), MATCH (a:Company {name:OpenAI}), (b:Company {name:Microsoft}) CREATE (a)-[:PARTNER_WITH {since:2023}]-(b), MATCH (c:Company {name:NVIDIA}), (a:Company {name:OpenAI}) CREATE (a)-[:USES_CHIPS_FROM]-(c), ] for query in queries: kg.run_query(query) print(f执行查询: {query[:50]}...) print(示例知识图谱构建完成) kg.close() if __name__ __main__: build_sample_kg()运行此脚本 (python knowledge_graph/builder.py)数据便存入 Neo4j。你可以在 Neo4j Browser (localhost:7474) 中执行MATCH (n) RETURN n查看可视化图谱。3.2 将知识图谱查询封装为 Agent 的 SkillAgent 需要通过一个标准的接口来访问知识图谱。我们使用 LangChain 的BaseTool类来封装这个功能。在skills/kg_query_tool.py中# skills/kg_query_tool.py from langchain.tools import BaseTool from typing import Optional, Type from pydantic import BaseModel, Field import sys import os sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from knowledge_graph.connector import Neo4jConnector class KnowledgeGraphQueryInput(BaseModel): 知识图谱查询工具的输入模型。 query: str Field(description一个用自然语言描述的问题例如OpenAI的CEO是谁 或 微软和哪些公司有合作关系) class KnowledgeGraphQueryTool(BaseTool): name query_knowledge_graph description 当问题涉及公司、人物、产品及其关系等结构化事实时使用此工具从知识图谱中查询准确信息。输入应为自然语言问题。 args_schema: Type[BaseModel] KnowledgeGraphQueryInput def _run(self, query: str) - str: 执行工具的主要逻辑将自然语言问题转换为 Cypher 查询并执行。 # 注意这里简化了实际应用中你需要一个更复杂的模块或调用另一个LLM # 来将自然语言问题 query 转换为 Cypher 查询。 # 此处为了演示我们使用一个简单的规则映射。 cypher_query self._natural_language_to_cypher(query) if not cypher_query: return 抱歉我无法理解这个问题请尝试换一种方式提问关于公司或人物的关系。 kg Neo4jConnector() try: results kg.run_query(cypher_query) kg.close() if not results: return 在知识图谱中没有找到相关信息。 # 将结果格式化为易读的文本 return self._format_results(results) except Exception as e: return f查询知识图谱时出错: {e} def _natural_language_to_cypher(self, nl_query: str) - Optional[str]: 一个极其简化的 NLQ 到 Cypher 的转换。生产环境应使用更复杂的方法。 nl_query_lower nl_query.lower() if ceo in nl_query_lower and openai in nl_query_lower: return MATCH (p:Person)-[:LEADS]-(c:Company {name:OpenAI}) RETURN p.name AS name, p.role AS role elif partner in nl_query_lower and microsoft in nl_query_lower: return MATCH (c1:Company {name:Microsoft})-[:PARTNER_WITH]-(c2:Company) RETURN c2.name AS partner, c2.domain AS domain elif founded in nl_query_lower and nvidia in nl_query_lower: return MATCH (c:Company {name:NVIDIA}) RETURN c.name AS name, c.founded AS founded_year else: # 更通用的查询查找包含关键词的节点 # 这是一个非常基础的示例实际应用需要更精细的解析。 words nl_query_lower.split() for word in words: if len(word) 3: # 忽略短词 return fMATCH (n) WHERE toLower(n.name) CONTAINS {word} OR toLower(n.domain) CONTAINS {word} RETURN n.name AS name, labels(n) AS type, n.domain AS domain LIMIT 5 return None def _format_results(self, results: list) - str: 将查询结果格式化为字符串。 formatted [] for i, record in enumerate(results, 1): formatted.append(f{i}. {record}) return \n.join(formatted) if formatted else 无结果 async def _arun(self, query: str) - str: 异步版本如果需要。 raise NotImplementedError(此工具不支持异步调用。)这个KnowledgeGraphQueryTool类定义了一个标准的 LangChain Tool。当 Agent 决定使用它时会传入一个自然语言问题工具内部在_run方法中尝试将其转换为 Cypher 查询执行并返回结果。注意_natural_language_to_cypher函数是最大的简化。在实际项目中这通常是一个复杂的模块可能涉及另一个专门的 LLM 调用Text-to-Cypher或使用预定义的查询模板。这里仅用于演示流程。现在我们已经有了一个结构化的知识源和一个访问它的标准工具。接下来我们创建另一个更简单的 Skill并最终将它们组装到 Agent 中。4. 开发与组装 Agent 核心我们将创建一个具备多种 Skills 的 Agent并使用 LangChain 的 Agent 执行器来运行 ReAct 循环。4.1 创建更多示例 Skills为了让 Agent 更实用我们再添加一个简单的“天气查询”工具模拟和一个“计算器”工具。在skills/weather_tool.py中# skills/weather_tool.py from langchain.tools import BaseTool from typing import Optional, Type from pydantic import BaseModel, Field import requests class WeatherQueryInput(BaseModel): location: str Field(description城市名称例如北京、Shanghai) class WeatherQueryTool(BaseTool): name get_weather description 获取指定城市的当前天气信息。 args_schema: Type[BaseModel] WeatherQueryInput def _run(self, location: str) - str: # 这是一个模拟工具实际应调用如 OpenWeatherMap 的 API # 这里返回模拟数据 mock_data { 北京: {temp: 22°C, condition: 晴朗, humidity: 40%}, 上海: {temp: 25°C, condition: 多云, humidity: 65%}, 深圳: {temp: 28°C, condition: 阵雨, humidity: 80%}, } weather mock_data.get(location, None) if weather: return f{location}的天气温度{weather[temp]}{weather[condition]}湿度{weather[humidity]}。 else: return f未找到{city}的天气信息目前支持北京、上海、深圳。 async def _arun(self, location: str) - str: raise NotImplementedError(此工具不支持异步调用。)在skills/calculator_tool.py中# skills/calculator_tool.py from langchain.tools import BaseTool from typing import Optional, Type from pydantic import BaseModel, Field import math class CalculatorInput(BaseModel): expression: str Field(description一个数学表达式例如3 5 * 2 或 sqrt(16)) class CalculatorTool(BaseTool): name calculator description 执行数学计算。支持加减乘除和常见函数如 sqrt, sin, cos。请提供清晰的表达式。 args_schema: Type[BaseModel] CalculatorInput def _run(self, expression: str) - str: try: # 警告使用 eval 有安全风险仅用于演示。生产环境必须使用安全的表达式求值库如 ast.literal_eval 或 numexpr。 # 这里进行了极简的安全过滤切勿在生产中直接使用。 if any(keyword in expression.lower() for keyword in [import, os, sys, exec, eval, __]): return 表达式包含不安全字符拒绝计算。 # 替换常见的数学函数 expression expression.replace(sqrt, math.sqrt).replace(sin, math.sin).replace(cos, math.cos) result eval(expression, {__builtins__: {}}, {math: math}) return f计算结果: {result} except Exception as e: return f计算表达式 {expression} 时出错: {e} async def _arun(self, expression: str) - str: raise NotImplementedError(此工具不支持异步调用。)4.2 初始化 LLM 并创建 Agent 执行器现在在main.py中我们将所有组件组装起来。# main.py import os from dotenv import load_dotenv from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain.prompts import PromptTemplate from skills.kg_query_tool import KnowledgeGraphQueryTool from skills.weather_tool import WeatherQueryTool from skills.calculator_tool import CalculatorTool # 加载环境变量 load_dotenv() def main(): # 1. 初始化 LLM # 确保 OPENAI_API_KEY 已在 .env 文件中设置 llm ChatOpenAI( modelgpt-3.5-turbo, # 或 gpt-4 temperature0, # 降低随机性使 Agent 行为更确定 api_keyos.getenv(OPENAI_API_KEY) ) # 2. 准备工具列表 tools [ KnowledgeGraphQueryTool(), WeatherQueryTool(), CalculatorTool(), ] # 3. 定义 ReAct 风格的提示词模板 # 这个模板告诉 LLM 如何思考、使用工具和格式化输出。 prompt_template 你是一个有帮助的 AI 助手可以访问以下工具 {tools} 请严格按照以下格式使用工具 思考你需要先思考当前情况决定是否需要使用工具。 行动你选择的工具名称必须是以下之一[{tool_names}] 行动输入工具的输入参数 观察工具返回的结果 ... (这个 思考/行动/行动输入/观察 循环可以重复多次) 当你有了最终答案时必须使用以下格式 最终答案你的最终回答 开始 之前的对话历史 {chat_history} 用户输入{input} {agent_scratchpad} prompt PromptTemplate.from_template(prompt_template) # 4. 创建 Agent # 使用 LangChain 的 create_react_agent 辅助函数 agent create_react_agent(llm, tools, prompt) # 5. 创建 Agent 执行器它负责管理循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设置为 True 可以看到 Agent 的思考过程调试时非常有用 handle_parsing_errorsTrue, # 处理解析错误 max_iterations5, # 限制最大循环次数防止无限循环 early_stopping_methodgenerate, # 当 Agent 认为任务完成时停止 ) print(Agent 已启动输入 quit 或 exit 退出。) print(- * 50) # 6. 交互循环 while True: try: user_input input(\n你的问题: ) if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input.strip(): continue # 执行 Agent response agent_executor.invoke({input: user_input, chat_history: }) print(f\n助手: {response[output]}) except KeyboardInterrupt: print(\n程序被中断。) break except Exception as e: print(f\n运行过程中出现错误: {e}) if __name__ __main__: main()4.3 运行与验证在运行前请确保Neo4j 容器正在运行并且示例知识图谱已构建。.env文件中正确设置了OPENAI_API_KEY。所有依赖已安装。在项目根目录下执行python main.py你将看到类似以下的交互过程verboseTrue会打印详细思考过程Agent 已启动输入 quit 或 exit 退出。 -------------------------------------------------- 你的问题: OpenAI 的 CEO 是谁 思考用户问的是关于 OpenAI 公司 CEO 的事实信息。我应该使用知识图谱查询工具来获取准确信息。 行动query_knowledge_graph 行动输入OpenAI的CEO是谁 观察1. {name: Sam Altman, role: CEO} 思考我已经从知识图谱中得到了答案。可以给出最终答案了。 最终答案OpenAI 的 CEO 是 Sam Altman。 助手: OpenAI 的 CEO 是 Sam Altman。你的问题: 北京天气怎么样 思考用户询问天气信息。我应该使用天气查询工具。 行动get_weather 行动输入北京 观察北京的天气温度22°C晴朗湿度40%。 思考我已经得到了天气信息可以给出最终答案。 最终答案北京当前天气晴朗温度22°C湿度40%。 助手: 北京当前天气晴朗温度22°C湿度40%。你的问题: 微软和哪些公司有合作 思考用户询问微软的合作关系这属于公司间的关系查询应该使用知识图谱工具。 行动query_knowledge_graph 行动输入微软和哪些公司有合作 观察1. {partner: OpenAI, domain: AI Research} 思考从知识图谱中查到微软与 OpenAI 有合作关系。可以回答用户了。 最终答案根据知识图谱微软与 OpenAI 公司领域AI Research存在合作关系。 助手: 根据知识图谱微软与 OpenAI 公司领域AI Research存在合作关系。你的问题: 计算一下 3 的平方加上 4 的平方等于多少 思考这是一个数学计算问题。我应该使用计算器工具。 行动calculator 行动输入3**2 4**2 观察计算结果: 25 思考计算完成得到结果。 最终答案3 的平方 (9) 加上 4 的平方 (16) 等于 25。 助手: 3 的平方 (9) 加上 4 的平方 (16) 等于 25。通过以上交互你可以看到 Agent 成功地在不同任务间进行判断并选择了正确的工具。当问题涉及知识图谱中的结构化事实时它使用了query_knowledge_graph当需要计算或查询天气时它又切换到了其他工具。这就是一个具备多技能Skills和知识增强Knowledge Graph的 Agent 的基本形态。5. 关键配置、参数与原理详解仅仅让程序跑起来还不够理解其背后的配置和原理才能应对更复杂的需求和问题。5.1 LLM 模型与参数选择在ChatOpenAI初始化时有几个关键参数model选择gpt-3.5-turbo成本较低、速度较快适合开发和测试。gpt-4在复杂推理和遵循指令方面更强但成本更高、速度更慢。根据任务复杂度选择。temperature控制输出的随机性。范围 0 到 2。对于 Agent 这种需要稳定、可靠执行动作的场景通常设置为0或接近 0 的值如 0.1以减少不可预测的行为。max_tokens限制单次响应的最大长度。对于 Agent 的“思考”步骤通常不需要太长的响应可以适当限制以节省成本。5.2 Agent 执行器参数AgentExecutor是控制 Agent 生命周期的核心verboseTrue调试必备。它会打印出 Agent 内部的“思考”、“行动”、“观察”的完整链条是理解 Agent 为何做出某个决策的最重要手段。handle_parsing_errorsTrue当 LLM 的输出不符合工具调用的预期格式时这个参数允许执行器尝试修复或给出友好错误而不是直接崩溃。max_iterations安全阀。防止 Agent 陷入死循环。如果一个简单问题需要超过 5 轮工具调用可能意味着提示词设计有问题或工具选择不当。early_stopping_methodgenerate当 Agent 的输出以“最终答案”开头时执行器会停止循环。这依赖于提示词模板中的严格格式要求。5.3 提示词工程Agent 的“行为准则”prompt_template是 Agent 的“大脑软件”。它定义了 Agent 的思考框架。一个有效的 ReAct 提示词通常包含角色定义告诉 LLM 它是什么“有帮助的 AI 助手”。工具描述{tools}和{tool_names}会被自动替换为可用工具列表LLM 需要知道它能用什么。格式指令强制 LLM 按照“思考/行动/观察”的固定格式输出。这是实现结构化交互的关键。历史上下文{chat_history}允许 Agent 记住之前的对话实现多轮交互本例中初始为空。用户输入{input}是当前问题。暂存器{agent_scratchpad}是一个特殊变量LangChain 会自动将之前的“行动”和“观察”记录填充进去供 LLM 在下一轮思考时参考。为什么格式如此重要因为 LangChain 的 Agent 执行器会解析 LLM 的输出寻找特定的关键词如“行动”来触发工具调用。如果格式混乱解析就会失败。5.4 工具Skill设计要点清晰的名称和描述name和description是 LLM 选择工具的主要依据。描述应准确说明工具的用途和适用场景。例如“查询知识图谱”比“查询数据库”更明确。强类型的输入模式使用 Pydantic 的BaseModel定义args_schema可以给 LLM 提供清晰的参数结构和描述显著提高它生成正确参数的能力。健壮的错误处理在工具的_run方法中必须用try-except包裹核心逻辑并返回友好的错误信息。一个崩溃的工具会导致整个 Agent 运行失败。结果格式化工具返回的字符串应该简洁、信息丰富便于 LLM 理解并整合到后续的思考中。6. 常见问题排查与优化实践在开发和使用 Agent 过程中你会遇到各种问题。下面是一些典型场景的排查路径和优化建议。6.1 Agent 行为异常排查表问题现象可能原因检查与解决步骤Agent 不调用任何工具直接给出答案可能是错误的1. 提示词未强调使用工具。2. 工具描述不够清晰LLM 不知道何时用。3. LLMtemperature过高行为不稳定。1. 检查提示词模板确保有明确的格式指令和工具列表。2. 优化工具的描述 (description)使其更匹配用户问题。3. 将temperature设为 0 再测试。Agent 陷入循环反复调用同一个工具1. 工具返回的结果未能让 LLM 认为任务完成。2.max_iterations设置过高。3. 工具结果格式混乱LLM 无法理解。1. 开启verboseTrue观察“观察”内容是否有效。2. 检查工具返回的字符串是否清晰。尝试简化结果。3. 在提示词中加强“当得到 X 信息后你应该给出最终答案”的指令。解析错误Parsing LLM output errorLLM 的输出不符合“行动工具名”的预期格式。1. 开启verboseTrue查看 LLM 的原始输出确认其是否遵循格式。2. 简化提示词使用更明确的格式要求。3. 使用handle_parsing_errorsTrue让执行器尝试恢复。4. 考虑换用支持“函数调用”Function Calling的模型和 Agent 类型格式更稳定。工具执行出错1. 工具代码本身有 Bug。2. LLM 生成的输入参数不符合工具args_schema的要求。3. 外部服务如 Neo4j、天气 API不可用。1. 单独测试工具函数确保其能正确处理各种输入。2. 检查verbose日志中“行动输入”的内容是否正确。3. 检查网络连接、数据库状态和 API 密钥。知识图谱查询返回空或错误结果1. 自然语言到 Cypher 的转换 (_natural_language_to_cypher) 逻辑不匹配用户问题。2. 知识图谱中不存在相关数据。3. Cypher 查询语法错误。1. 打印出转换后的 Cypher 查询语句进行验证。2. 在 Neo4j Browser 中手动执行该查询确认数据和语法。3. 考虑引入一个更强大的 Text2Cypher 微调模型或使用图查询生成服务。6.2 性能与稳定性优化实践优化提示词这是提升 Agent 表现性价比最高的方法。通过反复测试Vibe Coding 思想微调提示词中的角色设定、格式要求和工具描述。可以使用 LangChain 的PromptTemplate进行模块化管理。使用更稳定的工具调用方式OpenAI 的 GPT 系列模型原生支持Function Calling。LangChain 提供了create_openai_tools_agent它能利用此特性让模型以 JSON 格式输出工具调用请求格式更稳定解析成功率远高于文本解析。实现对话历史管理当前的chat_history是空的。要实现多轮对话需要维护一个历史列表并在每次调用时将其格式化后传入agent_executor.invoke()。注意历史长度过长可能导致 token 超限。为知识图谱查询添加缓存对于频繁查询的相同或类似问题可以在工具层或 Agent 外层添加缓存机制如functools.lru_cache避免重复查询图数据库提升响应速度。结构化工具输出让工具返回结构化的数据如 Pydantic 对象而不仅仅是字符串。这有助于后续的 Agent 或其它系统组件进行更精确的处理。实施超时和重试机制对于调用外部 API 的工具如天气查询应设置网络超时并考虑在失败时进行有限次数的重试。日志与监控在生产环境中记录 Agent 的每一次“思考-行动-观察”循环、工具调用耗时和最终结果。这对于分析性能瓶颈、理解用户意图和调试异常至关重要。6.3 知识图谱集成的深入方向我们当前的 Text2Cypher 转换极其简陋。生产级应用需要考虑专用 Text2Cypher 模型训练或微调一个模型专门用于将自然语言问题转换为高质量的 Cypher 查询。这需要大量的问题Cypher配对数据。检索增强生成RAG与图谱结合结合向量数据库进行混合检索。先用向量搜索找到相关文本片段再用知识图谱查询其中的实体和关系最后综合两者信息生成答案。图上下文注入在提问前先从知识图谱中检索出与问题相关的子图实体和关系将其作为上下文和问题一起送给 LLM让 LLM 在丰富的图谱上下文中进行推理和回答无需每次都生成 Cypher。7. 扩展方向与生产环境考量当你掌握了基础 Agent 的构建后可以考虑以下方向进行深化和扩展。7.1 技能Skills生态扩展集成真实 API将天气工具替换为真实的 OpenWeatherMap API添加股票查询、新闻摘要、邮件发送、日历管理等实用技能。代码执行 Skill创建一个安全的沙盒环境让 Agent 能够编写并执行 Python 代码片段来解决复杂问题需极其注意安全隔离。文件操作 Skill让 Agent 能够读取、分析、总结本地文档如 PDF、Word的内容。Skill 的动态注册与发现设计一个中心化的 Skill 注册表支持热插拔无需重启 Agent 即可添加新功能。7.2 多 Agent 协作系统单个 Agent 能力有限。可以设计一个多 Agent 系统规划 Agent负责分解复杂任务为子任务。执行 Agent专精于某类技能如数据分析 Agent、代码生成 Agent。评审 Agent检查其他 Agent 的工作结果。协调者管理这些 Agent 之间的通信和任务分配。这可以通过 LangChain 的AgentExecutor与LLMChain组合或使用更高级的框架如 AutoGen、CrewAI来实现。7.3 生产环境部署清单将学习原型转化为生产服务需要额外关注配置管理将所有配置API Keys、数据库连接串、模型参数外置到环境变量或配置中心如 Apollo、Nacos。可观测性集成日志如 Structlog、指标如 Prometheus和分布式追踪如 OpenTelemetry全面监控 Agent 的健康状况、性能指标和错误。限流与熔断对 LLM API 和外部工具调用实施限流防止因意外流量或错误导致费用激增或服务雪崩。安全性输入净化对用户输入进行严格的检查和过滤防止提示词注入攻击。工具权限控制为不同用户或场景的 Agent 分配不同的工具访问权限例如普通用户不能调用“删除数据库”工具。输出审查对 Agent 的最终输出进行内容安全过滤。版本化与回滚对 Agent 的提示词、工具集进行版本管理确保可以快速回滚到稳定版本。构建一个成熟的 Agentic AI 系统是一个持续迭代的过程。从本文的最小可行原型出发结合 Vibe Coding 的快速反馈理念不断测试、调整、扩展你就能逐步搭建起真正解决实际业务问题的智能体。核心在于理解每个组件的职责LLM 负责推理Tools 负责执行Orchestrator 负责调度KG 负责记忆并让它们通过清晰、稳定的协议协同工作。 
