【大模型 agent-skills】DeepAgents-skills 技能调用全攻略

既然你已经趟过了 Windows 和 Ubuntu 的所有坑位，这份教程将以实战避坑 为核心，带你从零到一掌握 deepagents 的技能调用（Skills）机制。

DeepAgents 技能调用全攻略

DeepAgents 的核心魅力在于其"插件化"思想。一个 Skill（技能） 本质上是一个包含描述文件（SKILL.md）和逻辑脚本（可选）的独立文件夹。

一、技能目录的标准结构

Agent 能不能认出你的技能，全看目录长得准不准。

text 复制代码

my_project/
├── main.py                # 主程序
└── skills/                # 技能根目录
    ├── reimbursement/     # 技能A：报销 (文件夹名必须与name一致)
    │   └── SKILL.md       # 技能定义（核心）
    └── weekly-report/     # 技能B：周报
        └── SKILL.md

二、编写核心 `SKILL.md`

这是 Agent 的"说明书"，决定了模型何时以及如何调用该技能。

markdown 复制代码

---
name: reimbursement
description: 当用户需要整理消费记录、打车费、餐饮费为报销清单时调用。
inputs:
  content:
    type: string
    description: 原始报销文字
---

# 技能指令
1. 提取日期、项目、金额。
2. 汇总总金额。
3. 输出 Markdown 表格。

避坑指南 ：文件开头必须是 ---，严禁有空行。Windows 用户建议用 VS Code 确保编码为 UTF-8（无 BOM）。

三、主程序 `main.py` 的跨平台写法

为了同时适配 Windows 和 Ubuntu，路径处理必须使用 Path.as_posix()。

python 复制代码

from pathlib import Path
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from deepagents.backends import FilesystemBackend

# 1. 路径标准化处理
current_root = Path(__file__).parent.resolve()
skills_dir = (current_root / "skills").as_posix() # 统一为正斜杠 /

# 2. 初始化 Backend
backend = FilesystemBackend(root_dir=str(current_root), virtual_mode=True)

# 3. 创建 Agent
agent = create_deep_agent(
    model=ChatOpenAI(
        model='deepseek-ai/DeepSeek-V3', # V3 在工具调用上比 R1 更稳
        base_url='https://api.siliconflow.cn/v1',
        api_key='YOUR_API_KEY'
    ),
    backend=backend,
    skills=[skills_dir], # 注入技能路径
    system_prompt="你是一个办公助手。必须根据用户需求调用对应的工具完成任务。"
)

四、精简版流式输出（生产级监控）

在实际使用中，我们不需要看冗长的参数，只需要看 Agent 正在干什么。

python 复制代码

if __name__ == "__main__":
    inputs = {"messages": [{"role": "user", "content": "张三打车30元，整理下"}]}
    
    for chunk in agent.stream(inputs, config={"configurable": {"thread_id": "job_01"}}):
        # 监控：是否加载成功
        if 'SkillsMiddleware.before_agent' in chunk:
            count = len(chunk['SkillsMiddleware.before_agent'].get('skills_metadata', []))
            print(f"📊 状态: 已加载 {count} 个技能")

        # 监控：正在做什么
        if 'model' in chunk:
            msg = chunk['model']['messages'][0]
            if msg.tool_calls:
                # 只打印动作名称，不打印那一长串内容
                print(f"🤔 动作: 正在调用 [{msg.tool_calls[0]['name']}]...")

        # 结果：最终回答
        if 'agent' in chunk:
            print(f"\n🎯 结果:\n{chunk['agent']['messages'][-1].content}")

五、避坑总结（Checklist）

检查项	关键点
文件夹命名	文件夹名必须与 `SKILL.md` 里的 `name` 完全一致。
路径斜杠	Windows 下也请确保传给 `skills` 的是正斜杠 `/`。
编码格式	严禁使用带有 BOM 头的 UTF-8 编码，会导致加载数为 0。
模型选择	DeepSeek-V3 适合执行任务，DeepSeek-R1 适合复杂逻辑思考。
权限问题	Ubuntu 下确保对 `skills` 目录有 `755` 权限。

六、进阶：如何让技能更强大？

如果 SKILL.md 解决不了复杂逻辑，你可以在技能文件夹里放入 index.py，并利用 FilesystemBackend 读写文件。Agent 会自动识别并根据需求执行更复杂的 Python 逻辑。

需要我帮你针对具体的"周报自动生成"技能写一个更复杂的 SKILL.md 模板吗？

【大模型 agent-skills】DeepAgents-skills 技能调用全攻略

DeepAgents 技能调用全攻略

一、 技能目录的标准结构

二、 编写核心 SKILL.md

三、 主程序 main.py 的跨平台写法

四、 精简版流式输出（生产级监控）

五、 避坑总结（Checklist）