Agent Skills 智能体技能格式规范概述

Agent Skills 智能体技能格式规范旨在标准化智能体技能的描述、调用和交互方式，确保不同智能体之间的兼容性和可扩展性。规范通常包含技能定义、输入输出格式、调用协议和错误处理机制。

技能定义与元数据

技能定义是规范的核心部分，通常以 JSON 或 YAML 格式描述。元数据包括技能名称、描述、版本、作者等信息。

{
  "name": "weather_lookup",
  "description": "查询指定城市的天气信息",
  "version": "1.0.0",
  "author": "OpenAI",
  "inputs": {
    "city": {
      "type": "string",
      "description": "城市名称"
    }
  },
  "outputs": {
    "temperature": {
      "type": "float",
      "description": "当前温度（摄氏度）"
    },
    "conditions": {
      "type": "string",
      "description": "天气状况"
    }
  }
}

输入输出格式

输入输出格式定义了技能的参数和返回值结构。通常采用 JSON Schema 进行约束。

{
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "minLength": 1
      }
    },
    "required": ["city"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number"
      },
      "conditions": {
        "type": "string"
      }
    },
    "required": ["temperature", "conditions"]
  }
}

调用协议

技能调用通常通过 HTTP API 或 RPC 实现。以下是一个 HTTP POST 请求的示例：

import requests

skill_url = "https://api.agent.example.com/skills/weather_lookup"
payload = {"city": "北京"}

response = requests.post(skill_url, json=payload)
if response.status_code == 200:
    weather_data = response.json()
    print(f"温度: {weather_data['temperature']}°C, 天气: {weather_data['conditions']}")
else:
    print("技能调用失败:", response.text)

错误处理

规范应定义统一的错误码和错误信息格式。

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "城市名称不能为空",
    "details": {
      "field": "city",
      "constraint": "minLength"
    }
  }
}

技能组合与编排

多个技能可以通过编排实现复杂功能。以下是一个 Python 示例，展示如何组合天气查询和邮件发送技能：

def get_weather_and_notify(city, email):
    weather = requests.post(weather_skill_url, json={"city": city}).json()
    message = {
        "to": email,
        "subject": f"{city}天气报告",
        "body": f"当前温度: {weather['temperature']}°C, 天气状况: {weather['conditions']}"
    }
    return requests.post(email_skill_url, json=message).status_code

版本控制与兼容性

技能应支持版本控制，确保向后兼容。版本号遵循语义化版本规范（SemVer）。

name: stock_price
version: 2.1.0
compatibility:
  min_agent_version: "1.4.0"
deprecated:
  fields:
    - legacy_ticker_format

测试与验证

规范的实现需要测试验证。以下是一个使用 Pytest 的测试用例：

def test_weather_skill():
    response = requests.post(weather_skill_url, json={"city": "上海"})
    assert response.status_code == 200
    data = response.json()
    assert isinstance(data["temperature"], float)
    assert isinstance(data["conditions"], str)

性能监控与日志

技能应提供性能指标和日志接口。

import time
import logging

def timed_skill_execution(skill_func, *args):
    start = time.time()
    result = skill_func(*args)
    latency = time.time() - start
    logging.info(f"Skill executed in {latency:.2f}s")
    return result

通过以上规范，智能体技能可以实现标准化描述、调用和组合，为复杂智能体系统的开发奠定基础。