Agent Skill 入门实战：从零构建你的第一个智能代理

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

概念解析：Agent Skill 到底是什么？

第一次听到 Agent Skill 这个概念时，我想到了微服务和函数式编程的结合体。简单来说，它就像一个能够独立完成特定任务的智能模块，可以被其他系统按需调用。和传统编程最大的不同在于，Agent Skill 更强调上下文感知和自主决策能力。

举个生活中的例子：传统编程像是去餐厅点餐，你告诉服务员要什么菜，他就原封不动地把指令传给厨房；而 Agent Skill 更像是一个懂你的私人厨师，他会根据你过去的饮食习惯、当前的身体状况，甚至天气情况来调整菜单。

环境准备：搭建开发环境

在开始编码前，我们需要准备以下工具（以 macOS/Linux 为例）：

1. Python 3.8+（推荐使用 pyenv 管理版本）
2. Rasa SDK（安装命令：pip install rasa-sdk）
3. 代码编辑器（VS Code 或 PyCharm）
4. Postman（用于 API 测试）

# 验证 Python 版本
python3 --version

# 创建虚拟环境（Windows 用户用 `python -m venv .venv`）python3 -m venv .venv
source .venv/bin/activate

核心实现：构建你的第一个技能

1. 技能注册（YAML 配置）

在 skills/weather_skill.yml 中定义技能元数据：

name: weather_query
version: 1.0.0
description: 提供实时天气查询功能
endpoint: http://localhost:5055/webhook
supported_intents:
  - ask_weather
parameters:
  - name: location
    type: string
    required: true

2. 技能实现（Python 代码）

创建 weather_skill.py，注意看代码中的详细注释：

from typing import Dict, Text, Any
from rasa_sdk import Action, Tracker
from rasa_sdk.executor import CollectingDispatcher
import requests

class WeatherQueryAction(Action):
    def name(self) -> Text:
        # 必须与 YAML 中定义的 name 一致
        return "weather_query"

    async def run(
        self, 
        dispatcher: CollectingDispatcher,
        tracker: Tracker,
        domain: Dict[Text, Any]
    ) -> Dict[Text, Any]:
        """
        核心业务逻辑：1. 从用户消息中提取位置参数
        2. 调用天气 API
        3. 格式化返回结果
        """
        try:
            # 获取对话中的位置实体
            location = tracker.get_slot("location")
            if not location:
                raise ValueError("未提供位置信息")

            # 调用第三方 API（示例使用 mock 数据）response = requests.get(f"https://api.weather.mock/{location}",
                timeout=5
            )
            response.raise_for_status()

            # 格式化自然语言响应
            weather_data = response.json()
            message = f"{location}当前天气：{weather_data['condition']}，温度{weather_data['temp']}℃"

            dispatcher.utter_message(message)
            return {}

        except requests.exceptions.RequestException as e:
            dispatcher.utter_message("天气服务暂时不可用")
            return {}
        except ValueError as e:
            dispatcher.utter_message(str(e))
            return {}

调试技巧：快速验证功能

使用 Postman 测试流程

1. 启动技能服务：rasa run actions
2. 在 Postman 中创建 POST 请求：
3. URL: http://localhost:5055/webhook
4. Headers: Content-Type: application/json
5. Body 示例：

   {
     "tracker": {
       "sender_id": "test_user",
       "slots": {"location": "北京"}
     },
     "domain": {}}

日志追踪技巧

建议在代码中添加结构化日志：

import logging
logger = logging.getLogger(__name__)

# 在关键位置添加日志
logger.info(f"开始处理天气查询，位置: {location}", 
            extra={"trace_id": tracker.sender_id})

生产环境建议

版本兼容方案

• 在技能 URL 中包含版本号：/v1/weather
• 使用语义化版本控制（SemVer）
• 为新版本维护单独的部署实例

冷启动优化

1. 预加载常用资源
2. 实现心跳检测机制
3. 对于 Python 技能，考虑使用 uvloop 提升异步性能：

   import asyncio
   import uvloop
   asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())

延伸思考

1. 技能编排：当多个技能需要协同工作时，如何设计优先级和冲突解决机制？比如当天气查询和行程规划技能都需要位置信息时。

2. 上下文继承：如何让技能记住用户偏好？比如用户说过 ” 不喜欢雨天 ”，之后的天气播报是否应该自动过滤雨天活动建议？

3. 限流策略：对于高频调用的技能（如时间查询），应该如何设计缓存和限流机制来保证系统稳定性？

写在最后

通过这次实践，我发现 Agent Skill 最有趣的地方在于它让代码变得更有『预见性』。与传统编程相比，开发者需要考虑更多上下文场景，但也因此能创造出更智能的交互体验。建议初学者从一个具体的小技能开始，比如时间查询或简单计算器，逐步体会这种开发范式的不同。

遇到问题时，不妨多在技能日志中记录完整的对话上下文，这往往能帮我们更快定位到问题根源。