Agent Skills 实战教程：从概念到批量调用与 API 接入

最近 Agent Skills 这个概念热度一直没降但很多朋友卡在“知道名字、不知道能干嘛”的状态。这轮我们不再泛泛聊概念直接把它拆开Agent Skills 到底是什么、它和普通 Agent 有什么区别、怎么从零上手做一个能用的技能以及如何批量调用、接入自己的服务。这篇教程不需要你已经很懂 Agent只要你写过一点 Python、能跑命令行就足够跟上。整篇文章按“先理解、再搭建、后验证”的顺序推进尽量不做无用的概念化铺垫。Agent Skills 的核心思路可以理解为一套给 Agent 预装“能力模块”的方法。和传统的对话型 Agent 相比Skills 更多强调的是可复用、可组合、可共享。你可以把技能理解成一个带有明确功能说明、调用示例和实现代码的工具包Agent 在接到任务时会根据用户的问题动态选择合适的技能再调用技能去完成具体操作。比如网页搜索技能、代码执行技能、文件解析技能、计算机控制技能都属于这个范畴。它的价值在于把“怎么用”直接交给模型而不是让模型每次都在推理中摸索工具接口。这篇教程我会带你完成下面几件事第一说清楚 Agent Skills 的定义、分类和运行机制第二准备好本地开发环境跑通最小可用的技能第三做一个真实的技能示例把它接入 Agent 流程第四验证技能调用的效果、显存或资源占用如果本地运行、API 接入方式第五总结一套适合批量任务和工程化部署的调用模板最后挂一份常见问题排查清单。如果你正打算给自己的工作流引入 Agent或者你想从普通 Chatbot 用户进阶成 Agent 开发者这篇文章建议直接收藏。1. Agent Skills 核心能力速览能力项说明项目类型Agent 能力模块 / 工具库不是独立的聊天应用核心来源OpenAI 提出的 Agent 构建范式最新实现以官方 Agents SDK 为主主要功能代码执行、网页搜索、文件搜索、计算机控制、自定义工具组合运行方式云端 API / 本地 SDK / 集成到 Agent 流程开发语言Python 为主官方 SDK 支持是否需要 GPU不需要本质是 API 工具调度不是本地推理模型推理模型要求建议使用支持 tool calling 的模型例如 GPT 系列或兼容接口的开源模型是否支持批量任务支持可以通过脚本循环调用 API 批量执行是否支持接口 API支持基于 Responses API / Chat Completions API 扩展是否支持一键启动无图形一键包需要通过 Python 脚本或 CLI 启动适合场景论文写作辅助、数据处理、代码生成、搜索问答、Agent 工作流自动化这里要特别说清楚Agent Skills 不是一个需要下载到本地的大模型而是一套“技能规范 调度机制”。你不需要一台很强的显卡也不需要跑模型权重。真正的计算量发生在提供推理能力的模型 API 侧。所以如果你只是学习和开发 Agent Skills普通办公电脑就够用。2. 适用场景与使用边界Agent Skills 最直接的场景是把重复性、工具依赖型的工作封装成可复用的技能。比如你经常需要搜索网页、总结内容、再写入文档这个完整流程可以做成一个“搜索写作技能”如果你每天要处理固定格式的报表、让模型按模板改写文本、抽取结构化字段也可以做成独立的“文本处理技能”。在学术界和写作领域Agent Skills 已经出现了一些很实际的用法。比如“Agent Skills 赋能人文社科混合研究方法论文写作”本质就是通过技能把文献检索、文本分析、结构化写作等环节拆开让模型按步骤调用工具而不是一次性生成一大段不严谨的内容。这种思路适合需要严格流程、可追溯、可修改的研究型写作。它的使用边界同样要明确。第一Agent Skills 不适合当作完全离线、隐私绝对安全的方案因为大多数能力依赖云端推理接口敏感数据传到外部服务前必须做脱敏和安全评估。第二它生成的结果存在幻觉风险不能直接当作事实来源尤其是论文和正式报告必须有真人复核。第三涉及人脸、声音、版权素材、未公开数据时要确认授权范围不能用技能批量抓取、生成或传播未经授权的资源。合规使用是硬边界。把 Agent Skills 接入自己业务时以下几点必须遵守只调用你有权限访问的 API 和数据源。不绕过任何网站的反爬机制不批量抓取受版权保护的页面。涉及个人信息时遵守数据保护法规获取用户授权。涉及生成内容时标注 AI 参与避免误导。商用前确认所用模型和终端的产品条款。3. Agent Skills 环境准备与前置条件Agent Skills 开发的前置条件比较轻不像本地大模型那样需要庞大的依赖。准备以下环境和工具即可。3.1 开发环境清单项目要求操作系统Windows 10 / 11、macOS、Linux 均可Python建议 Python 3.10 或以上版本包管理工具pip / pipx / uv核心依赖openai-agents、openai、python-dotenv、rich模型 API支持 tool calling / function calling 的模型网络能访问模型 API 服务磁盘空间5GB 以内足够GPU不需要3.2 验证 Python 环境先用命令行确认 Python 版本避免后续依赖安装版本冲突。python --version pip --version如果 Python 版本低于 3.10建议先升级到较新版本。Windows 用户可以直接从 Python 官网下载安装包macOS 用户可以用 HomebrewLinux 用户看发行版对应的包管理器。3.3 安装 Agents SDK官方推荐的 Agent 开发库是openai-agents。安装命令如下pip install openai-agents openai python-dotenv如果网络环境对默认 PyPI 源访问较慢可以切换国内镜像例如阿里云镜像pip install openai-agents openai python-dotenv -i https://mirrors.aliyun.com/pypi/simple/安装完成后确认关键包能正常导入import agents import openai print(agents version:, getattr(agents, __version__, unknown)) print(openai version:, openai.__version__)能打印出版本号说明环境基础可用。3.4 准备 API Key 和环境变量在项目目录下新建一个.env文件写入你的 API Key。注意这只是一个本地模板实际密钥字段需要根据你使用的模型服务调整。OPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxx # 如果你的服务使用自定义接口地址可以追加这一行 # OPENAI_BASE_URLhttps://your-endpoint.example.com/v1.env必须加入.gitignore避免泄露。程序中通过load_dotenv()加载环境变量。到这里环境部分就准备好了。接下来进入实际开发流程。4. Agent Skills 部署与启动方式Agent Skills 并不像 Web 应用那样有一个固定的“双击启动”入口它的标准运行方式是编写技能定义、把技能挂载到 Agent、启动 Agent 接收任务。下面给出一套通用模板你可以按自己的项目替换路径和参数。4.1 创建项目目录mkdir agent-skills-demo cd agent-skills-demo mkdir skills mkdir outputs touch main.py目录结构如下agent-skills-demo/ ├── .env ├── main.py ├── skills/ │ └── example_skill.py └── outputs/4.2 实现一个最简单的技能技能的核心是提供一段清晰的说明 可执行函数。下面这个示例技能功能很简单对输入文本做去空格和字数统计但它能完整展示 Agent Skills 的调用机制。# skills/example_skill.py from typing import Any async def text_process_skill(text: str, mode: str word_count) - dict[str, Any]: text_process_skill 技能对文本做基础处理。 参数: text: 输入文本 mode: word_count字数统计/ strip去除首尾空格 / dedupe合并连续空格 返回: 处理结果字典 if mode word_count: return {word_count: len(text), char_count: len(text.replace( , ))} if mode strip: return {result: text.strip()} if mode dedupe: import re return {result: re.sub(r\s, , text.strip())} return {error: unsupported mode}这个函数没有启动任何服务但它已经是“技能”的最小形态有说明、有参数、有返回值。Agent 通过读取函数 docstring 来理解技能用途和调用方式所以 docstring 要写得清楚、准确。4.3 把技能挂载到 Agent下面写主程序将技能注册到 Agent 中。# main.py import os import asyncio from dotenv import load_dotenv from agents import Agent, Runner from skills.example_skill import text_process_skill load_dotenv() agent Agent( nameTinyAgent, instructions你是一个能处理文本任务的助手用户需要时请调用 text_process_skill。, tools[text_process_skill], ) async def main(): user_input 将这段文字 中的 连续空格去掉然后统计字数。 result await Runner.run(agent, user_input) print(最终回答:, result.final_output) if __name__ __main__: asyncio.run(main())启动python main.py这里用的是openai-agents的通用写法。如果你的模型服务兼容 OpenAI 接口也可以把模型配置改成你实际使用的模型名称。工具函数的注册方式因 SDK 版本而异以官方文档为准。4.4 验证是否启动成功启动后可以观察两点终端没有报错Agent 能响应输入。输入包含技能触发条件时Agent 会调用对应函数并返回结构化结果。如果模型没有调用技能可以检查 instructions 是否写清楚“什么时候用什么技能”这一点在 Agent Skills 中非常关键。5. 功能测试与效果验证技能开发完成后不能只看“能跑通”要按功能维度做系统验证。下面是一套通用测试流程可以复用到大多数 Agent 技能上。5.1 测试一技能函数单独调用先不经过 Agent直接调用函数确认逻辑正确。# test_skill_direct.py import asyncio from skills.example_skill import text_process_skill async def main(): print(await text_process_skill( hello world , modeword_count)) print(await text_process_skill( hello world , modededupe)) asyncio.run(main())预期结果第一个返回正确字数第二个返回hello world。如果这里就错了后面接入 Agent 也没有意义。5.2 测试二Agent 自动选择技能输入一段自然语言要求 Agent 自动判断是否需要调用技能。这里的关键是模型必须先理解用户意图再决定触发哪个工具。如果模型没有触发工具大概率是技能描述不够清晰。user_input 请把这句话的连续空格合并Agent Skills 让工具调用更稳定。预期流程Agent 读取到“合并连续空格”这个需求。Agent 从技能列表中找到text_process_skill参数 mode 设为dedupe。技能返回处理后的文本。Agent 根据技能结果生成最终回答。5.3 测试三多参数和错误参数向技能传入缺失参数、错误参数观察 Agent 是否给出合理反馈而不是直接崩溃。从工程角度技能应尽量处理异常输入比如async def text_process_skill(text: str, mode: str word_count): if not text: return {error: text is empty} # ... 其余逻辑5.4 测试四与搜索类或外部工具类技能的联动真实场景中技能往往不是单一函数而是多个工具配合。比如设计一个“搜索总结技能”用户给出主题Agent 调用搜索工具获取资料再用文本处理技能清洗内容最后汇总。由于具体搜索工具需要 API Key 和搜索服务权限这里只给出抽象调用流程用户输入主题 - Agent 调用 search_web() - 得到搜索结果列表 - Agent 调用 text_process_skill 清洗摘要 - 输出结构化报告这类链路测试关注两个点一个是步骤顺序是否正确另一个是中间结果是否会丢给用户看。默认情况下 Agent 在工具链中传递的是结构化字典最终输出由模型重新组织所以要做好日志记录。5.5 判断成功标准功能层技能返回结果正确错误处理有效。调度层Agent 能根据意图自动触发技能没有把工具调用写死在提示词里。质量层最终输出语言自然没有把工具返回的原始 JSON 直接抛给用户。6. 接口 API 与批量任务Agent Skills 与 API 相结合是把它落到工程里的关键一步。无论技能运行在本地还是云端最终都可以通过 API 接口的方式被其他系统调用。6.1 基于 OpenAI Responses API 的通用调用示例下面的代码演示如何通过openai客户端调用支持工具调用的模型并把技能函数作为工具传给模型。注意这是一个通用模板实际接口路径和参数需要对照你使用的 SDK 文档调整。# api_call_example.py import os import json from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) def search_documents(query: str): 模拟文档检索技能。 参数: query: 检索关键词 返回: 匹配文档列表 # 实际项目中这里应该接入向量数据库或检索服务 return [{title: demo, content: f包含 {query} 的示例内容}] tools [ { type: function, function: { name: search_documents, description: 根据关键词检索文档, parameters: { type: object, properties: { query: {type: string} }, required: [query] } } } ] response client.chat.completions.create( modelos.getenv(MODEL_NAME, gpt-4o-mini), messages[ {role: user, content: 帮我查一下 Agent Skills 相关文档} ], toolstools, tool_choiceauto ) print(response.choices[0].message.tool_calls)运行这个脚本后你会看到一个tool_calls列表里面包含模型决定调用的函数名和参数。拿到这个结果后你的程序再执行对应函数把执行结果作为消息回传给模型形成一次完整的工具调用闭环。6.2 做成一键执行的 API 服务如果你希望技能以 HTTP 服务发布可以使用 FastAPI。下面是一个最小示例外部系统通过 POST 请求调用技能服务返回处理结果。# api_server.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from skills.example_skill import text_process_skill app FastAPI(titleAgent Skills Demo API) class SkillRequest(BaseModel): text: str mode: str word_count app.post(/api/text_process) async def run_skill(req: SkillRequest): result await text_process_skill(req.text, req.mode) if error in result: raise HTTPException(status_code400, detailresult) return result启动服务pip install fastapi uvicorn uvicorn api_server:app --host 127.0.0.1 --port 8000调用测试curl -X POST http://127.0.0.1:8000/api/text_process \ -H Content-Type: application/json \ -d {text: Agent Skills 让批量任务更高效, mode: dedupe}6.3 批量任务调度模板批量任务是 Agent 技能工程化最常见的需求之一。通常的做法是读取一批输入文件循环调用技能把结果写入输出目录并记录每条任务的执行状态和失败原因。# batch_process.py import asyncio import json from pathlib import Path from skills.example_skill import text_process_skill INPUT_DIR Path(./inputs) OUTPUT_DIR Path(./outputs) OUTPUT_DIR.mkdir(exist_okTrue) async def process_file(filepath: Path): text filepath.read_text(encodingutf-8) result await text_process_skill(text, modededupe) return {file: filepath.name, status: ok, result: result} async def main(): tasks [] for filepath in INPUT_DIR.glob(*.txt): tasks.append(process_file(filepath)) results await asyncio.gather(*tasks, return_exceptionsTrue) for filepath, res in zip(INPUT_DIR.glob(*.txt), results): output_file OUTPUT_DIR / f{filepath.stem}.json if isinstance(res, Exception): output_file.write_text( json.dumps({status: failed, error: str(res)}, ensure_asciiFalse, indent2), encodingutf-8 ) else: output_file.write_text( json.dumps(res, ensure_asciiFalse, indent2), encodingutf-8 ) print(f完成: {filepath.name}) asyncio.run(main())批量任务设计时要注意三个点输入输出分离原始文件不要和结果混在一起。每条任务要有独立日志至少记录成功/失败状态。对网络请求类技能建议加入重试机制和并发限制防止触发频率限制。import asyncio from random import uniform async def call_with_retry(func, args, retries3): for attempt in range(retries): try: return await func(*args) except Exception as e: if attempt retries - 1: raise await asyncio.sleep(uniform(1, 3))6.4 接口接入常见注意点tool_choiceauto让模型自主决定是否调用工具如果希望强制调用某个技能可以改为{type: function, function: {name: search_documents}}。工具返回给模型的内容大小要控制避免一次性传入过长的文档。调用 API 时要设置超时时间避免任务卡住。批量调用时要注意并发数和频率限制不同 API 服务有不同限额。7. 资源占用与性能观察Agent Skills 的性能瓶颈主要是 API 调用延迟和工具本身的执行耗时而不是 GPU 计算。基础技能的 CPU 和内存占用都很低通常几十兆内存足够。真正影响整体耗时的是模型推理时间也就是模型“决定调什么工具”和“总结工具结果”的时间。如果你是本地运行推理模型比如通过 Ollama、vLLM 或 LM Studio 提供本地模型接口这时才需要观察 GPU 显存占用。但无论本地还是云端启动前都应该确认以下几点模型名是否正确。是否配置了自定义接口地址。是否使用了兼容 OpenAI 的工具调用格式。输入文本长度是否超出模型上下文窗口。观察资源占用最简单的方法是使用系统监控工具。Windows 打开任务管理器macOS 打开活动监视器Linux 使用htop。Python 脚本里也可以打印函数耗时import time start time.perf_counter() result await text_process_skill( hello , modededupe) elapsed time.perf_counter() - start print(f技能耗时: {elapsed:.4f}s)对于 API 类任务耗时主要分布在网络请求阶段。一次工具调用的常见流程是发送请求到模型 API、等待模型返回 tool_calls、执行本地技能函数、再把技能结果回传给模型、模型生成最终回答。这个链路需要两次模型交互所以耗时通常会比单轮 Chat Completion 长。如果出现批量任务卡住优先看是不是某个技能函数抛出了异常或者网络请求没有设置超时。一个经验做法是所有外部请求都设置超时所有技能函数都捕获异常并返回错误信息而不是直接抛出导致进程中断。8. 常见问题与排查方法问题现象可能原因排查方式解决方案模型没有调用技能指令不够明确或技能描述不清晰打印模型返回的完整消息查看是否有 tool_calls优化技能 description明说“当用户需要 X 时必须调用 Y”技能函数报错参数类型不匹配、函数抛异常检查输入参数和函数内部逻辑给函数增加类型校验和 try/exceptAPI 返回 401API Key 无效或过期确认环境变量是否加载成功更新 API Key检查 .env 文件API 返回 404模型名或接口地址错误查看模型服务文档换成正确的模型名和 base_url批量任务卡死网络请求未设置超时、函数循环等待加日志观察卡在哪一步给所有请求设置 timeout加重试机制输出包含原始 JSONAgent 没有把工具结果组织成自然语言检查 Agent 的 instructions 是否要求总结后回答增加“请用自然语言向用户解释结果”的指令上下文过长工具返回大量文本查看请求的 token 使用量截断工具返回内容或改用更精确的检索依赖安装失败Python 版本不兼容、网络问题查看 pip 错误信息升级 Python切换镜像源或使用虚拟环境虚拟环境是规避依赖冲突最直接的办法。建议在项目开头就创建python -m venv .venv source .venv/bin/activate # Windows 下用 .venv\Scripts\activate所有依赖统一装在虚拟环境内避免污染全局 Python。9. 最佳实践与使用建议9.1 技能设计原则一个技能只做一件事保持函数短小。每个函数必须写清楚 docstring说明用途、参数含义、返回值。技能文件名和函数名要可读避免出现main_2024_final_v3.py这类命名。输入参数越少越好默认值给足降低模型误调用的概率。技能内部尽量不依赖全局变量所有上下文通过参数传入。9.2 项目结构建议agent-project/ ├── .env ├── .gitignore ├── requirements.txt ├── main.py # Agent 入口 ├── skills/ # 技能目录 │ ├── __init__.py │ ├── text_skill.py │ ├── search_skill.py │ └── file_skill.py ├── tools/ # 非 Agent 直接调用的基础工具 ├── config/ # 配置加载 ├── inputs/ # 输入数据 ├── outputs/ # 输出结果 ├── logs/ # 运行日志 └── tests/ # 单元测试9.3 测试与发布建议先用最少参数跑通再逐步增加功能。保留一套最小可运行配置方便快速回归。为每个技能写独立测试脚本函数逻辑不依赖 Agent 也能验证。批量任务要有断点续跑能力至少记录每条任务的完成状态。技能发布到团队共享时附上使用示例和已知限制。9.4 合规与安全建议技能不要设计成“绕过任何安全限制”的形态。不要上传未经脱敏的个人信息到 API。不要把内部文档全文发送给外部模型除非确认服务条款允许。涉及人脸、声音、版权内容时必须确认授权后再处理。商用技能前复核输入输出是否符合模型服务商的可接受使用政策。10. 总结与下一步Agent Skills 最值得尝试的点是它把“工具调用”从隐式的模型行为变成了显式、可复用的工程资产。你不需要重新训练模型只需要把已有的工具整理成结构化的技能Agent 就能在合适的时候自动选择和使用它们。对普通开发者来说这意味着可以用很低的成本把自己的本地能力接入 Agent 流程。建议你最先验证的是“技能选择准确性”用三个差异明显的小技能比如文本处理、日期计算、文件搜索看模型是否能根据用户输入准确选择正确工具。这个实验能帮你理解模型对工具描述的理解方式也是后续所有 Agent 开发的基础。最容易踩的坑是技能描述写得含糊。模型看不到你的代码实现它只通过函数名和 docstring 判断该不该调用所以描述里一定要写明触发条件和参数含义。后续可以继续扩展的方向包括把搜索技能接入真实的搜索服务、把文件技能扩展为向量数据库检索、把多个技能组合成一个完整的业务 Agent 工作流或者把技能封装成 FastAPI 服务接入团队内部系统。从“会用一个技能”到“造一套技能”中间隔着的就是清晰的定义和工程化的调试习惯。建议先按这篇文章跑通一个最小 Demo再逐步加功能。