这次我们来看一个关于 AI Agent 与 Skills 开发的系统性教程。这个教程的核心价值在于它并非空谈概念而是提供了一套从环境搭建、基础概念理解到实际代码开发的完整路径。对于想要进入 AI Agent 开发领域尤其是希望构建具备特定“技能”Skills的智能体的开发者来说这是一个非常实用的切入点。本文将带你梳理 AI Agent 开发的核心脉络重点关注如何定义、开发并集成 Skills。我们会从最基础的环境准备开始一步步搭建开发框架然后通过代码实例手把手演示如何为一个 Agent 赋予搜索、文件读写、数据计算等具体能力。整个过程将围绕“可运行、可验证”展开确保你读完就能动手实践。无论你是刚接触 AI 应用开发的新手还是希望将大语言模型LLM能力工程化的进阶开发者这篇文章都将提供清晰的指引。我们将重点关注开发流程、代码结构、工具链选择以及如何避免常见的“坑”。1. 核心能力速览在深入代码之前我们先快速了解通过本教程你将掌握的核心能力以及对应的技术栈和工具。能力项说明与目标核心概念理解 Agent智能体、Skills技能、Tools工具、Orchestrator编排器等关键概念及其关系。开发环境基于 Python 的现代 AI 开发环境搭建包括 PyCharm/VSCode、Git、虚拟环境管理conda/venv。框架选择主流的 Agent 开发框架概览与选择如 LangChain、LangGraph、AutoGen、Semantic Kernel 等并确定一个进行实战。Skill 开发学会将一项具体能力如网络搜索、文件操作、API调用封装成可被 Agent 调用的标准化 Skill。Agent 集成将多个 Skills 集成到一个 Agent 中并实现基于自然语言指令的任务规划和自动调用。运行与调试启动 Agent 服务通过对话或 API 进行功能测试观察其推理和调用链条并进行问题排查。项目结构建立一个清晰、可扩展的 Agent 项目目录结构便于后续维护和添加新 Skill。适用场景自动化工作流助手、智能客服机器人、数据分析代理、个人知识管理助手等。2. 适用场景与使用边界AI Agent 与 Skills 的开发模式为解决特定领域的复杂任务提供了一种灵活、可扩展的架构。它非常适合以下场景自动化流程将重复性的、多步骤的办公或开发流程自动化例如自动收集数据、生成报告、代码审查。智能问答与决策支持构建能理解领域知识、调用专业工具进行推理和回答的助手如技术客服、法律咨询初筛。个性化助手开发理解个人习惯和需求的私人助手管理日程、过滤信息、推荐内容。系统集成桥梁作为中间层连接不同的软件系统、数据库和 API用自然语言统一操作界面。需要注意的使用边界非万能解决方案Agent 依赖于底层 LLM 的理解和规划能力以及 Skills 的可靠执行。对于需要极高精确度、实时性或复杂逻辑判断的任务需谨慎评估。成本与性能频繁调用 LLM 和外部 API 会产生成本。本地部署大模型则对硬件有要求。需要权衡响应速度、效果和开销。安全与权限Agent 能够执行文件操作、网络请求等必须严格控制其权限边界避免执行危险指令或访问敏感数据。稳定性与错误处理Skills 执行可能失败LLM 可能生成错误规划。必须构建完善的错误处理、重试和人工审核机制。合规与授权如果 Skill 涉及访问第三方数据、生成内容或处理用户信息务必确保符合相关法律法规和数据使用协议。3. 环境准备与前置条件开始代码实战前需要准备好开发环境。以下是基于 Python 技术栈的通用准备清单。1. 操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04)。推荐使用 Linux 或 WSL2 (Windows) 以获得最佳开发体验。2. 基础工具Python 3.9 - 3.11这是大多数 AI 框架稳定支持的版本。避免使用 Python 3.12 可能存在的兼容性问题。Git用于版本控制和克隆示例项目。代码编辑器/IDEPyCharm Professional (推荐对 AI 项目支持好) 或 Visual Studio Code 配合 Python 插件。终端Windows 可用 PowerShell 或 Windows TerminalmacOS/Linux 用系统自带终端。3. 环境管理工具Conda或venv强烈建议使用虚拟环境隔离项目依赖。Conda 安装: 从 Miniconda 官网下载安装。venv 是 Python 内置模块。4. 关键依赖概览我们将主要围绕一个主流框架展开例如LangChain。它生态丰富社区活跃是学习 Agent 开发的优秀起点。核心langchain,langchain-community,langchain-coreLLM 接入openai(如需使用 OpenAI API) 或ollama(本地模型)工具类requests(网络请求),python-dotenv(管理环境变量)可选langgraph(用于更复杂的多 Agent 工作流),fastapi(构建 API 服务)4. 安装部署与启动方式我们以一个简单的“查询天气并保存结果”的 Agent 项目为例演示从零开始的流程。步骤 1创建项目并初始化环境打开终端执行以下命令# 1. 创建项目目录 mkdir ai-agent-tutorial cd ai-agent-tutorial # 2. 创建虚拟环境 (以 conda 为例) conda create -n agent-env python3.10 -y conda activate agent-env # 3. 使用 venv 的替代命令 # python -m venv venv # source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 4. 创建关键文件 touch main.py # 主程序入口 touch skills.py # 存放自定义 Skills touch requirements.txt # 依赖列表 touch .env.example # 环境变量模板步骤 2安装核心依赖编辑requirements.txt文件加入以下内容langchain0.1.0 langchain-community0.0.10 openai1.0.0 # 如果你使用 OpenAI API requests2.31.0 python-dotenv1.0.0然后在终端中安装pip install -r requirements.txt步骤 3配置环境变量复制.env.example为.env并填入你的密钥如果使用 OpenAI# .env 文件内容示例 # OPENAI_API_KEYsk-your-openai-api-key-here # 如果你使用其他模型服务如 Azure OpenAI 或本地 Ollama在此配置 # AZURE_OPENAI_ENDPOINThttps://your-resource.openai.azure.com/ # OLLAMA_BASE_URLhttp://localhost:11434步骤 4编写第一个 Skill 和 Agent现在我们开始编写代码。首先在skills.py中定义一个模拟的天气查询 Skill# skills.py import json from typing import Type, Optional from pydantic import BaseModel, Field from langchain.tools import BaseTool class WeatherQueryInput(BaseModel): 查询天气的输入参数。 location: str Field(description城市名称例如北京、Shanghai) class WeatherQueryTool(BaseTool): name get_current_weather description 获取指定城市的当前天气情况。 args_schema: Type[BaseModel] WeatherQueryInput def _run(self, location: str) - str: 模拟天气查询实际项目中应调用真实天气API。 # 这里模拟一个固定的返回真实情况应调用如 OpenWeatherMap 的 API weather_data { location: location, temperature: 22°C, condition: 晴朗, humidity: 65%, wind: 10 km/h } return json.dumps(weather_data, ensure_asciiFalse) async def _arun(self, location: str): 异步版本可选。 raise NotImplementedError(此工具不支持异步调用。)接着在main.py中创建 Agent 并集成这个 Skill# main.py import os from dotenv import load_dotenv from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_openai import ChatOpenAI from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from skills import WeatherQueryTool # 1. 加载环境变量 load_dotenv() # 2. 初始化 LLM (这里以 OpenAI GPT-4 为例可替换为其他模型) llm ChatOpenAI( modelgpt-4-turbo-preview, temperature0, api_keyos.getenv(OPENAI_API_KEY) # 确保 .env 中已配置 ) # 3. 定义工具列表 tools [WeatherQueryTool()] # 4. 构建 Agent 提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个有用的助手可以查询天气。请根据用户的请求和可用工具来回答问题。), MessagesPlaceholder(variable_namechat_history, optionalTrue), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) # 5. 创建 Agent agent create_openai_tools_agent(llm, tools, prompt) # 6. 创建 Agent 执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 7. 运行测试 if __name__ __main__: while True: try: user_input input(\n用户: ) if user_input.lower() in [quit, exit, q]: break response agent_executor.invoke({input: user_input}) print(f助手: {response[output]}) except Exception as e: print(f执行出错: {e})步骤 5启动与测试在终端中确保虚拟环境已激活并运行主程序python main.py程序启动后在提示符下输入“北京天气怎么样”你将看到类似以下的输出展示了 Agent 的思考过程和工具调用用户: 北京天气怎么样 进入新的 AgentExecutor 链... 思考用户想知道北京的天气。我有一个工具叫 get_current_weather 可以查询天气。我应该使用这个工具。 行动get_current_weather 行动输入{location: 北京} 观察{location: 北京, temperature: 22°C, condition: 晴朗, humidity: 65%, wind: 10 km/h} 思考我已经通过工具获取了北京的天气信息现在可以回答用户了。 最终答案北京当前天气晴朗气温22°C湿度65%风速10 km/h。 助手: 北京当前天气晴朗气温22°C湿度65%风速10 km/h。至此一个最简单的、具备单一 Skill 的 Agent 已经成功运行。5. 功能测试与效果验证一个健壮的 Agent 需要经过多方面测试。我们将从基础功能开始逐步增加复杂度。5.1 基础工具调用测试测试目的验证 Agent 能否正确理解用户意图并调用对应的 Skill。输入示例“查询一下上海的天气。”“使用天气工具看看伦敦的天气。”预期结果Agent 应识别出需要调用get_current_weather工具并传入正确的城市参数。控制台应显示完整的“思考-行动-观察”链条。判断成功Agent 返回了结构化的天气信息且调用过程在verboseTrue模式下清晰可见。5.2 多技能集成与选择测试测试目的验证 Agent 在拥有多个 Skills 时能否根据任务选择正确的工具。操作步骤在skills.py中增加一个“文件写入” Skill。# skills.py (追加) class FileWriteInput(BaseModel): 写入文件的输入参数。 filepath: str Field(description要写入的文件路径) content: str Field(description要写入文件的内容) class FileWriteTool(BaseTool): name write_to_file description 将内容写入到指定的文本文件中。 args_schema: Type[BaseModel] FileWriteInput def _run(self, filepath: str, content: str) - str: try: with open(filepath, w, encodingutf-8) as f: f.write(content) return f成功将内容写入文件{filepath} except Exception as e: return f写入文件失败{str(e)}在main.py的tools列表中加入这个新工具tools [WeatherQueryTool(), FileWriteTool()]重启main.py进行测试。输入示例“把‘Hello, Agent!’这句话保存到greeting.txt文件里。”“先查一下东京的天气然后把查询结果保存到weather_report.txt。”预期结果对于第一个请求Agent 应调用write_to_file。对于第二个复杂请求Agent 应能规划顺序先调用get_current_weather再将返回的结果作为content参数调用write_to_file。判断成功Agent 能顺序执行两个工具并生成最终答案。文件被成功创建并写入内容。5.3 错误处理与边界测试测试目的验证 Agent 在工具调用失败或收到模糊指令时的行为。输入示例“查询一个不存在的城市的天气。”如“中土世界”“向一个没有权限的路径写文件。”如“C:\system\test.txt” on Windows“帮我做一杯咖啡。”没有对应工具预期结果模拟的天气工具可能返回默认数据或错误。观察 Agent 如何处理不理想的工具输出。文件工具应返回明确的错误信息Agent 应能捕获并告知用户。Agent 应承认自己能力的边界回复无法完成该任务。判断成功Agent 没有崩溃能够处理工具抛出的异常并以友好的方式向用户反馈问题。6. 接口 API 与批量任务将 Agent 封装成 API 服务是将其集成到其他应用系统的标准方式。同时处理批量任务能极大提升效率。6.1 使用 FastAPI 构建 Web API首先安装 FastAPIpip install fastapi uvicorn。 然后创建api.py# api.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List, Optional import asyncio from main import agent_executor # 导入我们之前创建的执行器 app FastAPI(titleAI Agent API Service) class AgentRequest(BaseModel): query: str session_id: Optional[str] None # 用于支持多轮对话会话 class BatchAgentRequest(BaseModel): tasks: List[AgentRequest] app.post(/v1/chat) async def chat_with_agent(request: AgentRequest): 单次对话接口 try: # 注意原 agent_executor.invoke 是同步方法在异步上下文中需使用 run_in_executor loop asyncio.get_event_loop() result await loop.run_in_executor(None, agent_executor.invoke, {input: request.query}) return {success: True, session_id: request.session_id, response: result[output]} except Exception as e: raise HTTPException(status_code500, detailfAgent execution failed: {str(e)}) app.post(/v1/batch_chat) async def batch_chat_with_agent(batch_request: BatchAgentRequest): 批量任务处理接口 results [] for task in batch_request.tasks: try: loop asyncio.get_event_loop() result await loop.run_in_executor(None, agent_executor.invoke, {input: task.query}) results.append({ query: task.query, success: True, response: result[output], session_id: task.session_id }) except Exception as e: results.append({ query: task.query, success: False, error: str(e), session_id: task.session_id }) return {results: results} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)启动 API 服务python api.py。服务将在http://127.0.0.1:8000运行。6.2 调用 API 示例使用curl或 Pythonrequests库进行测试。单次调用curl -X POST http://127.0.0.1:8000/v1/chat \ -H Content-Type: application/json \ -d {query: 北京天气如何, session_id: user_123}批量调用# batch_test.py import requests import json url http://127.0.0.1:8000/v1/batch_chat payload { tasks: [ {query: 查询伦敦天气, session_id: task_1}, {query: 将‘测试内容’写入 test_batch.txt, session_id: task_2}, {query: 今天星期几, session_id: task_3} # 无对应工具测试边界 ] } response requests.post(url, jsonpayload, timeout60) print(json.dumps(response.json(), indent2, ensure_asciiFalse))6.3 批量任务最佳实践队列与限流对于大量任务应使用消息队列如 Redis, RabbitMQ而非简单 HTTP 批量接口并限制并发数避免压垮服务或触发 LLM API 的速率限制。结果持久化将每个任务的结果包括输入、输出、状态、错误信息存入数据库便于追踪和重试。异步处理使用asyncio或Celery等异步任务框架避免阻塞主线程。幂等性设计确保任务可安全重试不会因重复执行导致副作用如重复写入文件。7. 资源占用与性能观察Agent 系统的性能主要取决于 LLM 的调用和工具的执行效率。1. LLM 调用开销延迟调用云端 API如 OpenAI的延迟在几百毫秒到数秒不等受网络和模型影响。本地模型如通过 Ollama 部署的首次加载慢但后续推理延迟相对稳定。成本API 调用按 Token 计费。复杂的思考和规划会消耗更多 Token。在verboseTrue模式下可以观察 Agent 产生的“思考”文本量估算成本。观察方法在代码中记录每个请求的发起和结束时间或使用 LangChain 的 Callback 机制。2. 工具执行效率工具本身的执行时间如网络请求 I/O、文件读写是主要瓶颈。确保工具代码高效并对可能耗时的操作设置超时。使用异步工具实现_arun方法并在异步框架中调用可以提升并发性能。3. 内存与显存占用如果使用本地大模型显存占用是核心指标。使用nvidia-smi(GPU) 或htop(CPU 内存) 监控。Agent 框架本身LangChain内存占用不大但会缓存对话历史。长时间运行的 Agent 服务需注意内存泄漏可定期清理或限制历史长度。4. 优化建议缓存对频繁且结果不变的查询如某些天气、百科信息进行缓存。精简提示词优化 System Prompt 和工具描述减少不必要的 Token 消耗。选择合适模型简单任务使用小模型如 GPT-3.5-turbo复杂规划再使用大模型。超时与重试为所有外部调用LLM API、工具 API设置合理的超时和重试策略。8. 常见问题与排查方法在开发过程中你可能会遇到以下典型问题。问题现象可能原因排查方式解决方案导入 LangChain 模块失败版本不兼容或未安装。pip listgrep langchain 检查版本。查看错误信息。Agent 不调用工具直接回答1. 工具描述不清晰。2. LLM 温度 (temperature) 过高导致随机性大。3. 提示词未引导使用工具。1. 检查工具name和description是否准确。2. 将temperature设为 0。3. 在 System Prompt 中强调“你必须使用工具”。优化工具描述使其功能一目了然。使用更明确的提示词。工具调用参数错误LLM 未能正确解析用户输入为工具所需的参数格式。查看verboseTrue输出的“行动输入”是否为合法 JSON。1. 使用AgentExecutor(handle_parsing_errorsTrue)。2. 在工具参数Field的description中提供更详细的示例。API 密钥错误环境变量未正确加载或密钥无效。在代码中打印os.getenv(‘OPENAI_API_KEY’)的前几位检查。确认.env文件在项目根目录且变量名正确。重启 IDE 或终端。批量任务卡住或失败某个任务超时或出错影响整体。为每个任务添加独立超时和异常捕获。查看服务日志。实现任务的隔离执行和健全的错误处理机制避免单个任务失败导致整个批次崩溃。Agent 陷入循环Agent 反复调用相同工具或无法得出最终答案。观察agent_scratchpad中的思考链条是否重复。1. 设置max_iterations参数限制最大步数。2. 在提示词中要求“在得到足够信息后给出最终答案”。9. 最佳实践与使用建议基于实战经验以下建议能帮助你构建更稳健、可维护的 Agent 系统。1. 项目结构规范化ai-agent-project/ ├── agents/ # 存放不同职责的 Agent 定义 │ ├── __init__.py │ ├── weather_agent.py │ └── data_agent.py ├── skills/ # 技能包按领域分类 │ ├── __init__.py │ ├── web_skills.py # 网络相关 │ ├── file_skills.py # 文件操作 │ └── calc_skills.py # 计算 ├── config/ # 配置文件 │ └── settings.py ├── schemas/ # Pydantic 数据模型 │ └── models.py ├── utils/ # 工具函数 │ └── logger.py ├── tests/ # 单元测试 ├── main.py # 主入口 ├── api.py # FastAPI 入口 └── requirements.txt2. Skill 设计原则单一职责一个 Skill 只做一件事并做好。描述清晰name和description要足够精确让 LLM 能准确判断何时调用。强健性做好输入验证、异常处理和超时控制返回结构化的成功/失败信息。无状态性尽量设计无状态的 Skill便于并发和扩展。3. 提示词工程系统提示词 (System Prompt)明确 Agent 的角色、能力和约束。例如“你是一个数据分析助手可以调用工具来查询数据库和生成图表。如果你不知道或没有合适工具请直接说明。”工具描述优化在工具描述中加入使用示例能显著提升 LLM 调用的准确性。4. 安全与合规权限最小化文件操作 Skill 限制在特定工作目录网络请求 Skill 过滤危险 URL。输入过滤对用户输入和工具参数进行基本的清洗和校验防止注入攻击。审计日志记录所有用户交互、工具调用和结果便于追溯和审计。人工审核对于关键操作如删除文件、发送邮件设计“确认”环节或加入人工审核流程。5. 测试与监控单元测试为每个 Skill 编写测试用例模拟各种输入和边界条件。集成测试模拟真实用户对话测试 Agent 的端到端流程。监控指标记录请求量、响应时间、工具调用成功率、Token 消耗等关键指标。从运行一个简单的天气查询 Agent到构建一个具备多种 Skills、可通过 API 调用的服务你已经走完了 AI Agent 开发的核心闭环。这个过程中最重要的不是记住某个框架的 API而是理解“思考-行动-观察”这个核心循环以及如何将现实世界的能力封装成 LLM 可理解和调用的标准化工具。建议你接下来以这个项目为基础尝试添加更实用的 Skill例如网络搜索集成 SerperAPI 或 Tavily 搜索。数据库查询连接 MySQL 或 PostgreSQL 执行 SQL。代码解释/生成集成 Code Interpreter 或调用 GitHub API。知识库问答结合 RAG (检索增强生成) 技术让 Agent 基于私有文档回答。同时可以探索更高级的框架如LangGraph来编排包含条件分支和循环的复杂工作流。记住清晰的架构设计、可靠的 Skills 和持续的测试迭代是构建高质量 AI Agent 应用的关键。建议收藏本文在实践每个新功能时回来查阅相关章节祝你开发顺利