Agent Skill参数占位符的设计与实现：解决动态技能调用的核心痛点

9次阅读

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

在构建智能 Agent 系统时，技能（Skill）的动态组合是核心需求。但实际操作中会遇到几类典型问题：

类型安全问题：技能 A 输出字符串类型，而技能 B 期望输入数字类型时，缺乏编译期检查
参数传递缺失：技能链中后续节点无法自动获取前置节点的输出参数
人工映射成本高：开发人员需要手动编写大量胶水代码处理参数传递逻辑

以电商客服场景为例：当用户询问 ” 我的订单 1234 物流状态 ” 时，需要先后调用 订单查询 和物流查询 两个技能，前者输出的 orderId 必须准确传递给后者。传统硬编码方式会让系统变得僵化。

采用三层设计解决参数传递问题：

模板注册中心
存储技能参数元数据（类型、约束条件等）
提供版本化管理能力
参数解析器
支持 ${skillName.outputParam}格式的占位符
实现嵌套参数解析（如 ${A.${B.x}}）
校验引擎
编译期验证模板语法
运行时检查实际参数类型

flowchart TD
    A[接收原始请求] --> B[解析技能依赖图]
    B --> C{是否有占位符}
    C -->| 是 | D[查询参数模板库]
    C -->| 否 | E[直接执行]
    D --> F[构建参数依赖树]
    F --> G[执行参数替换]
    G --> H[类型校验]
    H --> I[执行目标技能]

class SkillTemplate:
    def __init__(self, name: str):
        self.name = name
        self.params = {}  # 参数名 -> (类型, 是否必填)

    def add_param(self, name: str, type_cls: type, required=True):
        """示例：注册参数模板"""
        self.params[name] = (type_cls, required)

# 注册订单查询技能模板
order_template = SkillTemplate('OrderQuery')
order_template.add_param('orderId', str)
order_template.add_param('userId', int, required=False)

import re
from typing import Any, Dict

class PlaceholderEngine:
    PATTERN = r'\${([^}]+)}'  # 匹配 ${xxx}格式

    @classmethod
    def resolve(cls, template: str, context: Dict[str, Any]) -> Any:
        """递归解析嵌套占位符"""
        def replacer(match):
            key = match.group(1)
            # 处理嵌套场景如 ${A.${B.x}}
            if cls.PATTERN.search(key):
                key = cls.resolve(key, context)
            return str(context.get(key, ''))

        while cls.PATTERN.search(template):
            template = re.sub(cls.PATTERN, replacer, template)
        return template

def validate_input(skill: SkillTemplate, inputs: dict):
    missing = [p for p, (_, req) in skill.params.items() 
               if req and p not in inputs]
    if missing:
        raise ValueError(f"Missing required params: {missing}")

    for param, value in inputs.items():
        expected_type, _ = skill.params.get(param, (object, False))
        if not isinstance(value, expected_type):
            raise TypeError(f"Param'{param}'expects {expected_type}, got {type(value)}")