技能与扩展

技能的核心概念

技能是 DeepAgents 生态中的知识模块，提供了一种系统化的方式来扩展代理的能力。每个技能包含特定领域的指导和必要的工具，代理可以在需要时加载和使用。

技能 vs 工具

维度	技能	工具
作用域	宽泛，涵盖多个步骤	具体，单一功能
加载方式	延迟加载（按需）	立即可用
内容	指导 + 工具 + 资源	仅是函数
重用性	跨项目共享	通常是本地的

技能的结构

每个技能是一个目录，包含以下内容：

skills/
├── research-toolkit/
│   ├── SKILL.md              # 技能定义和指导
│   ├── arxiv_search.py        # 辅助脚本
│   └── references/
│       └── top-papers.md      # 参考资料
│
├── data-analysis/
│   ├── SKILL.md
│   ├── analysis_utils.py
│   └── templates/
│       └── report_template.md
│
└── web-automation/
    ├── SKILL.md
    ├── selenium_helpers.py
    └── docs/
        └── selector-guide.md

SKILL.md 文件格式

技能的核心是 SKILL.md 文件，遵循标准格式：

---
name: research                        # 技能名称
description: 进行学术和行业研究      # 简短描述
license: MIT                         # 许可证
compatibility: 需要网络访问           # 依赖说明
metadata:
  author: langchain
  version: "1.0"
  category: information-gathering
allowed-tools: web_search, fetch_url  # 允许使用的工具
---

# 研究技能 (Research)

## 概述

本技能提供了一套系统化的研究流程，包括：
- 多源信息搜索
- 信息验证和交叉引用
- 结构化报告生成

## 使用场景

当需要进行以下任务时使用本技能：
- 市场调研
- 竞争分析
- 技术趋势分析
- 政策研究

## 详细指导

### 1. 收集信息

使用 web_search 工具搜索关键信息源...

### 2. 验证信息

交叉引用多个来源以确保准确性...

### 3. 生成报告

组织信息并生成结构化报告...

## 工具使用

此技能使用以下工具：
- `web_search`: 搜索网络信息
- `fetch_url`: 获取完整页面内容

使用技能

基本用法

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-3-5-sonnet-20241022",
    tools=[web_search, fetch_url],
    skills=["/path/to/skills/research/"],  # 指定技能目录
    system_prompt="你是一个研究助手。使用提供的技能来进行深度研究。"
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "研究 GPU 市场的最新发展"}]
})

多个技能

agent = create_deep_agent(
    model="anthropic:claude-3-5-sonnet-20241022",
    skills=[
        "/path/to/skills/research/",
        "/path/to/skills/data-analysis/",
        "/path/to/skills/report-writing/",
    ],
    system_prompt="""你是一个专业分析师。

可用的技能：
1. 研究技能：收集和验证信息
2. 数据分析技能：处理和可视化数据
3. 报告写作技能：生成专业报告

根据任务需要使用这些技能。"""
)

创建自定义技能

步骤 1：创建目录结构

mkdir -p skills/custom-analysis
cd skills/custom-analysis

步骤 2：创建 SKILL.md

---
name: sentiment-analysis
description: 进行文本情感分析和情绪趋势追踪
version: "1.0"
author: your-org
compatibility: 需要 TextBlob 和 VADER
metadata:
  domain: NLP
  difficulty: intermediate
allowed-tools: analyze_text, save_results
---

# 情感分析技能

## 功能

本技能提供以下能力：
- 单个文本的情感分析
- 多文本情感聚合
- 情感趋势时间序列分析

## 使用指导

### 单文本分析

对单个文本进行情感分析，返回：
- 情感极性（正面/负面/中立）
- 置信度分数
- 关键词识别

使用示例：
分析这条推文："我特别喜欢这个新产品！"

### 批量分析

对文本集合进行分析，返回：
- 整体情感分布
- 情感强度统计

### 趋势分析

追踪特定话题的情感变化...

## 工具参考

- `analyze_text(text, method)`: 分析文本情感
- `save_results(data, format)`: 保存分析结果

步骤 3：创建辅助脚本（可选）

# analysis_utils.py

def calculate_sentiment_distribution(texts: list[str]) -> dict:
    """计算文本集合的情感分布"""
    from textblob import TextBlob
    
    sentiments = []
    for text in texts:
        blob = TextBlob(text)
        sentiments.append(blob.sentiment.polarity)
    
    return {
        "mean": sum(sentiments) / len(sentiments),
        "positive": len([s for s in sentiments if s > 0.1]),
        "negative": len([s for s in sentiments if s < -0.1]),
        "neutral": len([s for s in sentiments if -0.1 <= s <= 0.1]),
    }

def format_report(data: dict) -> str:
    """将分析结果格式化为报告"""
    return f"""
情感分析报告
============
正面评论: {data['positive']} ({data['positive']/len(data)*100:.1f}%)
负面评论: {data['negative']} ({data['negative']/len(data)*100:.1f}%)
中立评论: {data['neutral']} ({data['neutral']/len(data)*100:.1f}%)
平均极性: {data['mean']:.2f}
"""

LangChain 官方技能

LangChain 提供了预构建的技能库可以直接使用：

1. LangChain 文档访问技能

agent = create_deep_agent(
    skills=[
        "/path/to/langchain-skills/docs-access/",
    ],
    system_prompt="你可以访问 LangChain 文档进行技术查询"
)

2. 代码审查技能

agent = create_deep_agent(
    skills=[
        "/path/to/langchain-skills/code-review/",
    ],
)

3. 性能优化技能

agent = create_deep_agent(
    skills=[
        "/path/to/langchain-skills/performance-optimization/",
    ],
)

技能的加载和执行

延迟加载机制

DeepAgents 使用"渐进式披露"（Progressive Disclosure）来加载技能：

1. 启动时：只加载技能的元数据（名称、描述）
2. 匹配时：当用户查询与技能相关时，加载完整技能
3. 执行时：按需加载工具和资源

# 这只会在代理判断需要时加载详细内容
agent = create_deep_agent(
    skills=[
        "/path/to/large-skill-library/",  # 可以包含很多技能
    ]
)

# 代理会自动选择相关的技能
result = agent.invoke({
    "messages": [{"role": "user", "content": "分析这个数据集"}]
})

性能考虑

# ✅ 好的做法：按分类组织，按需加载
agent = create_deep_agent(
    skills=[
        "/skills/data-analysis/",    # 仅在需要时加载
        "/skills/visualization/",
    ]
)

# ❌ 避免：加载不必要的技能
agent = create_deep_agent(
    skills=[
        "/skills/all/",              # 一次性加载所有技能
    ]
)

在子代理中使用不同的技能

from deepagents import create_deep_agent

# 主代理使用通用技能
main_agent = create_deep_agent(
    skills=["/skills/general/"],
    subagents=[
        {
            "name": "data_scientist",
            "description": "数据分析和建模",
            "system_prompt": "你是数据科学家",
            "tools": [analyze, visualize],
            "skills": [
                "/skills/data-science/",  # 专门的技能
                "/skills/ml-models/",
            ]
        },
        {
            "name": "frontend_dev",
            "description": "前端开发",
            "system_prompt": "你是前端工程师",
            "tools": [build_ui, test_ui],
            "skills": [
                "/skills/web-development/",  # 不同的技能集
                "/skills/ui-frameworks/",
            ]
        }
    ]
)

技能市场和社区

使用来自社区的技能

DeepAgents 社区维护了一个技能库。可以从以下来源获取：

1. GitHub：官方 langchain-skills 仓库
2. 包注册：通过 pip 或其他包管理器
3. 自定义库：在组织内部共享

实现自己的技能市场

# 从远程库加载技能
class SkillManager:
    def __init__(self, skill_repo_url: str):
        self.repo_url = skill_repo_url
    
    def download_skill(self, skill_name: str) -> str:
        """从仓库下载技能到本地"""
        import requests
        response = requests.get(f"{self.repo_url}/skills/{skill_name}.zip")
        # 解压到本地
        local_path = f"/local/skills/{skill_name}/"
        return local_path
    
    def list_available_skills(self) -> list[dict]:
        """列出可用的技能"""
        pass

# 使用
manager = SkillManager("https://my-skill-repo.com")
skill_path = manager.download_skill("advanced-nlp")

agent = create_deep_agent(
    skills=[skill_path],
)

技能的最佳实践

1. 文档完整性

/* ❌ 不完整 */
---
name: tool
---

# Tool Skill

这是一个工具。

/* ✅ 完整 */
---
name: data-cleaning
description: 对数据进行清洗和验证
version: "1.0"
author: org
compatibility: Pandas >= 1.0
metadata:
  category: data-processing
  difficulty: intermediate
allowed-tools: validate_data, clean_data, save_data
---

# 数据清洗技能

## 功能概述
...
## 使用场景
...
## 详细指导
...

2. 合理的粒度

❌ 太粗粒度
- 一个"万能"技能包含所有功能

✅ 合适粒度
- 数据清洗技能
- 数据验证技能
- 数据转换技能

3. 清晰的接口

# ✅ 技能明确定义了它使用的工具和返回格式
"""
使用的工具：
- validate_schema(data, schema)
- clean_missing_values(data)
- save_clean_data(data, path)

输出格式：
始终返回表示成功/失败的字典和统计信息
"""

故障排查

技能未被加载

症状：代理不使用应该有的技能

解决：

1. 检查技能路径是否正确
2. 检查 SKILL.md 文件格式
3. 查看模型日志（启用 DEBUG 日志）

import logging
logging.basicConfig(level=logging.DEBUG)

agent = create_deep_agent(skills=[...])

技能工具不可用

症状：Tool not found: X

解决：

• 确认在 allowed-tools 中列出了工具
• 确认代理有访问这些工具的权限
• 检查工具是否正确实现

下一步

• 存储后端
• 长期记忆
• 生产部署