Agent Skill 编写入门指南：从零开始构建你的第一个智能体技能

共计 2427 个字符，预计需要花费 7 分钟才能阅读完成。

智能体技能基础概念

Agent Skill 是赋予智能体（如聊天机器人、语音助手）特定能力的模块。就像手机里的 App 一样，每个 Skill 负责处理特定类型的任务，比如天气查询、日程提醒或智能家居控制。

• 典型应用场景：
• 客服系统中的自动问答
• 智能家居的语音控制
• 企业内部的流程自动化助手

开发环境准备

1. 安装 Python 3.8+（推荐使用 Miniconda 管理环境）
2. 获取开发工具包：

   pip install rasa-sdk
   pip install flask

3. 推荐 IDE：VS Code（安装 Python 插件）或 PyCharm

核心开发流程

1. 技能注册

每个 Skill 需要注册到智能体平台，通常需要提供：
– 技能名称（如 ”weather_checker”）
– 支持的交互方式（文本 / 语音）
– 版本号

2. 意图定义

在 domain.yml 中声明技能理解的用户意图：

intents:
  - ask_weather:
      examples: |
        - 今天天气怎么样
        - 北京会下雨吗

3. 对话处理

创建 Python 处理类（以天气查询为例）：

from rasa_sdk import Action
from rasa_sdk.events import SlotSet

class ActionCheckWeather(Action):
    def name(self):
        return "action_check_weather"

    async def run(self, dispatcher, tracker, domain):
        location = tracker.get_slot("location")
        # 调用天气 API 获取数据
        weather = get_weather(location)
        dispatcher.utter_message(f"{location}天气是{weather}")
        return [SlotSet("location", location)]

完整代码示例

# weather_skill.py
import requests
from typing import Dict, Text, Any, List

API_KEY = "your_weather_api_key"

def get_weather(city: str) -> str:
    try:
        url = f"https://api.weatherapi.com/v1/current.json?key={API_KEY}&q={city}"
        response = requests.get(url)
        data = response.json()
        return data["current"]["condition"]["text"]
    except Exception as e:
        print(f"API 调用失败: {e}")
        return "未知"

class ActionCheckWeather(Action):
    """处理天气查询的 Action 类"""

    def name(self) -> Text:
        return "action_check_weather"

    async def run(self,
                 dispatcher: CollectingDispatcher,
                 tracker: Tracker,
                 domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:

        location = tracker.get_slot("location") or "北京"  # 默认城市
        weather = get_weather(location)

        dispatcher.utter_message(
            response="utter_weather_report",
            location=location,
            weather=weather
        )

        return [SlotSet("last_queried_city", location)]

测试与调试技巧

1. 交互式测试：

   rasa shell

   输入测试语句查看响应

2. 日志检查：

3. 添加调试日志：logger.debug(f"收到位置参数: {location}")

4. 使用 --debug 参数启动服务

5. 单元测试 示例：

   def test_weather_action():
       from rasa_sdk.interfaces import Tracker
       from rasa.shared.core.trackers import DialogueStateTracker
   
       tracker = Tracker(
           "default",
           slots={"location": "上海"},
           latest_message={},
           events=[])
   
       action = ActionCheckWeather()
       result = action.run(None, tracker, None)
       assert "上海" in str(result)

生产环境部署

1. 性能优化：
2. 添加 API 调用缓存（如 redis）
3. 限制并发请求数

4. 使用异步 IO 处理耗时操作

5. 安全建议：

6. 不要硬编码 API 密钥
7. 验证用户输入防止注入攻击

8. 使用 HTTPS 传输敏感数据

9. 部署方式：

   # 使用 gunicorn 部署
   gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

常见问题解决方案

• 问题 1 ：意图识别不准确
• 检查训练数据是否充足
• 添加更多示例语句

• 使用同义词扩展（nlu.yml中的synonyms）

• 问题 2 ：上下文丢失

• 检查 SlotSet 事件是否正确触发
• 确认对话策略中的 memorization 设置

• 使用 Tracker 的get_slot()方法验证状态

• 问题 3 ：API 响应慢

• 添加超时处理（建议 3 秒超时）
• 实现本地缓存
• 考虑使用 CDN 加速

经验总结

开发第一个 Agent Skill 时，建议从小功能入手，比如实现单轮问答的天气查询。重点掌握三个核心机制：意图识别→动作执行→响应生成。测试阶段要特别注意边界情况，比如用户没说具体城市时如何处理。部署后持续监控日志，根据用户实际反馈优化对话流。

当熟悉基础模式后，可以尝试更复杂的多轮对话和上下文保持功能。记住好的 Skill 应该像自然的对话，而不是机械的问答。