从零开始搭建Agent Skill：新手避坑指南与最佳实践

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

新手常见三大痛点

刚接触 Agent Skill 开发时，开发者往往会遇到以下几个典型问题：

1. 状态管理混乱：在多轮对话中，忘记保存或错误覆盖对话状态，导致用户需要重复提供信息。

2. 意图识别不准：NLU 模型训练数据不足或标注不准确，导致系统无法正确理解用户意图。

3. 对话流维护困难：随着业务逻辑复杂化，对话流程变得难以理解和修改，添加新功能时容易引入 bug。

技术方案与架构设计

分层架构

一个标准的 Agent Skill 系统通常分为三个核心组件：

1. NLU（自然语言理解）层：负责解析用户输入，识别意图和提取实体。
2. DM（对话管理）层：维护对话状态，决定系统响应策略。
3. NLG（自然语言生成）层：将系统响应转化为自然语言输出。

对话状态机实现

状态机是管理对话流程的有效工具。以下是一个简单的天气查询状态机设计：

stateDiagram
    [*] --> Greeting
    Greeting --> AskCity: 用户打招呼
    AskCity --> ProvideWeather: 提供城市名称
    ProvideWeather --> AskCity: 用户请求其他城市
    ProvideWeather --> [*]: 用户结束对话

技能插件标准化接口

为了实现技能的可插拔，建议采用以下接口设计：

class SkillPlugin:
    def __init__(self):
        self.skill_name = ""def can_handle(self, intent):""" 判断是否能处理该意图 """
        pass

    def handle(self, context):
        """处理请求并返回响应"""
        pass

代码示例：天气查询技能

# weather_skill.py
class WeatherSkill(SkillPlugin):
    def __init__(self):
        self.skill_name = "weather"
        self.required_slots = ["city"]

    def can_handle(self, intent):
        return intent == "query_weather"

    def handle(self, context):
        # 检查是否已获取所有必要信息
        if not all(slot in context for slot in self.required_slots):
            missing = [s for s in self.required_slots if s not in context]
            return {"response": f"请告诉我您想查询哪个城市的天气？", 
                    "missing_slots": missing}

        # 模拟天气 API 调用
        city = context["city"]
        weather = self._get_weather(city)

        return {"response": f"{city}的天气是{weather}", "complete": True}

    def _get_weather(self, city):
        # 实际项目中这里会调用天气 API
        return "晴天"

# 对话管理器示例
class DialogManager:
    def __init__(self):
        self.skills = [WeatherSkill()]
        self.context = {}

    def process(self, user_input):
        # 在实际项目中，这里会调用 NLU 服务
        intent = "query_weather"  # 简化示例

        # 找到能处理该意图的技能
        for skill in self.skills:
            if skill.can_handle(intent):
                # 更新上下文（示例中简化了实体提取）if "city" in user_input:
                    self.context["city"] = user_input["city"]

                response = skill.handle(self.context)
                return response

        return {"response": "抱歉，我不明白您的意思"}

避坑指南

对话超时处理

长时间不活跃的对话应该自动清理：

1. 为每个对话会话设置最后活跃时间戳
2. 定期检查超时会话
3. 清理前可发送提醒或保存重要信息

上下文清理策略

1. 按技能划分上下文命名空间
2. 敏感信息（如支付金额）应在使用后立即清理
3. 提供 reset_context 方法供显式调用

技能命名空间隔离

# 在上下文中为每个技能创建独立命名空间
context = {"weather": {"city": "北京"},
    "shopping": {"items": [...]}
}

进阶建议

技能热加载

1. 使用 Python 的 importlib 动态加载模块
2. 为每个技能定义版本号
3. 实现技能注册表，支持运行时添加 / 移除

性能监控

建议埋点以下指标：

1. 意图识别准确率
2. 平均响应时间
3. 对话完成率
4. 用户满意度

思考题

1. 如何处理用户在同一句话中提供多个信息的情况？（如 ” 我想订明天北京到上海的机票 ”）
2. 在多技能协作场景下，如何优雅地处理技能间的依赖关系？