跳到主要内容

快速开始指南

本指南将帮助你快速上手 agent_skills 协议，从环境配置到创建和注册你的第一个技能。无论你是希望提供技能还是使用技能，这里都提供了必要的步骤和示例代码。

准备工作​

在开始使用 agent_skills 协议之前，你需要准备以下环境：

安装 agent_skills SDK​

agent_skills SDK 提供了各种编程语言的实现，选择你最熟悉的语言：

Python​

pip install agent-skills

JavaScript/Node.js​

npm install @agent-skills/sdk

Java​

<dependency>
  <groupId>org.agent-skills</groupId>
  <artifactId>agent-skills-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

注册 agent_skills 开发者账号​

  1. 访问 agent_skills 开发者门户
  2. 创建一个新的开发者账号
  3. 生成 API 密钥和访问令牌

创建你的第一个技能​

基础技能模板​

以下是创建一个简单技能的基本代码模板（Python 版本）：

from agent_skills import SkillProvider, SkillRegistry

# 创建技能提供者
provider = SkillProvider(
    agent_id="my-first-agent",
    agent_name="我的第一个代理",
    registry_url="https://registry.agent-skills.org"
)

# 定义一个技能处理函数
def greet_user(name: str) -> dict:
    """向用户问好"""
    return {
        "greeting": f"Hello, {name}!",
        "timestamp": "2024-01-01T00:00:00Z"
    }

# 注册技能
provider.register_skill({
    "skill_id": "greet-user",
    "name": "用户问候",
    "description": "向用户发送问候消息",
    "version": "1.0.0",
    "handler": greet_user,
    "input_schema": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "用户名称"
            }
        },
        "required": ["name"]
    },
    "output_schema": {
        "type": "object",
        "properties": {
            "greeting": {"type": "string"},
            "timestamp": {"type": "string"}
        }
    },
    "metadata": {
        "category": "communication",
        "tags": ["greeting", "basic"]
    }
})

# 连接到注册中心并发布技能
registry = SkillRegistry("https://registry.agent-skills.org")
provider.publish_to_registry(registry, api_key="your-api-key-here")

# 启动技能服务
provider.serve(host="0.0.0.0", port=8000)

JavaScript/Node.js 版本​

const { SkillProvider, SkillRegistry } = require('@agent-skills/sdk');

// 创建技能提供者
const provider = new SkillProvider({
  agentId: 'my-first-agent',
  agentName: '我的第一个代理',
  registryUrl: 'https://registry.agent-skills.org'
});

// 定义技能处理函数
const greetUser = (params) => {
  return {
    greeting: `Hello, ${params.name}!`,
    timestamp: new Date().toISOString()
  };
};

// 注册技能
provider.registerSkill({
  skillId: 'greet-user',
  name: '用户问候',
  description: '向用户发送问候消息',
  version: '1.0.0',
  handler: greetUser,
  inputSchema: {
    type: 'object',
    properties: {
      name: {
        type: 'string',
        description: '用户名称'
      }
    },
    required: ['name']
  },
  outputSchema: {
    type: 'object',
    properties: {
      greeting: { type: 'string' },
      timestamp: { type: 'string' }
    }
  },
  metadata: {
    category: 'communication',
    tags: ['greeting', 'basic']
  }
});

// 连接到注册中心
const registry = new SkillRegistry('https://registry.agent-skills.org');
provider.publishToRegistry(registry, { apiKey: 'your-api-key-here' });

// 启动服务
provider.serve({ host: '0.0.0.0', port: 8000 });

使用已注册的技能​

发现技能​

你可以通过注册中心查找和发现已注册的技能：

from agent_skills import SkillClient, SkillRegistry

# 创建技能客户端
client = SkillClient(
    registry_url="https://registry.agent-skills.org",
    api_key="your-api-key"
)

# 通过分类查找技能
communication_skills = client.discover_skills(category="communication")

# 通过标签搜索技能
greeting_skills = client.discover_skills(tags=["greeting"])

# 通过技能ID查找特定技能
specific_skill = client.get_skill("greet-user")

调用技能​

# 同步调用技能
result = client.call_skill(
    skill_id="greet-user",
    provider_agent_id="my-first-agent",
    parameters={
        "name": "Alice"
    }
)

print(f"问候结果: {result['greeting']}")

# 异步调用技能
import asyncio

async def call_skill_async():
    result = await client.call_skill_async(
        skill_id="greet-user",
        provider_agent_id="my-first-agent",
        parameters={"name": "Bob"}
    )
    return result

# 执行异步调用
result = asyncio.run(call_skill_async())
print(result)

创建技能组合工作流​

简单工作流示例​

from agent_skills import SkillWorkflow

# 创建工作流
workflow = SkillWorkflow("文本处理工作流")

# 添加技能步骤
workflow.add_step(
    skill_id="text-preprocessing",
    provider_agent_id="text-processor-agent",
    parameters={"text": "${input.text}"}
)

workflow.add_step(
    skill_id="text-sentiment-analysis",
    provider_agent_id="nlp-expert-agent",
    parameters={
        "text": "${steps.0.output.processed_text}"
    }
)

workflow.add_step(
    skill_id="generate-summary",
    provider_agent_id="summary-agent",
    parameters={
        "text": "${steps.0.output.processed_text}",
        "sentiment": "${steps.1.output.sentiment}"
    }
)

# 执行工作流
result = workflow.execute({
    "text": "这是一段需要处理的文本内容..."
})

print(f"工作流执行结果: {result}")

部署你的技能服务​

Docker 容器部署​

创建一个 Dockerfile：

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["python", "skill_provider.py"]

构建和运行容器：

docker build -t my-skill-provider .
docker run -p 8000:8000 -e AGENT_SKILLS_API_KEY=your-api-key my-skill-provider

云服务部署​

大多数云平台都支持部署技能服务，例如：

  • AWS Lambda + API Gateway
  • Google Cloud Functions
  • Azure Functions
  • Heroku

监控和管理​

部署后，使用 agent_skills 管理控制台监控你的技能：

  1. 访问 agent_skills 管理控制台
  2. 登录你的开发者账号
  3. 在"我的技能"部分查看技能状态
  4. 监控调用次数、性能指标和错误率
  5. 设置警报和通知

调试技巧​

本地测试​

使用 agent_skills 模拟器进行本地测试：

from agent_skills import SkillSimulator

# 创建模拟环境
sim = SkillSimulator()

# 添加你的技能
sim.add_skill(provider, "greet-user")

# 添加模拟技能
sim.add_mock_skill(
    skill_id="mock-translation",
    handler=lambda params: {"translated": f"[翻译] {params['text']}"}
)

# 运行模拟测试
result = sim.test_skill(
    skill_id="greet-user",
    parameters={"name": "Test User"}
)

print(f"测试结果: {result}")

日志和追踪​

启用详细日志以便调试：

import logging
from agent_skills import set_log_level

# 设置日志级别
set_log_level(logging.DEBUG)

# 启用追踪
provider.enable_tracing(output_dir="./traces")

最佳实践​

  1. 明确定义技能：为每个技能提供清晰的描述、输入输出说明
  2. 提供健壮的错误处理：处理各种可能的输入错误和边缘情况
  3. 优化性能：对于频繁调用的技能，优化响应时间
  4. 遵循安全最佳实践：验证所有输入，限制访问敏感技能
  5. 版本控制：明确标记你的技能版本，支持向后兼容
  6. 提供良好文档：为你的技能提供详细的使用文档

常见问题解答​

Q: agent_skills 协议是否支持自托管注册中心？
A: 是的，你可以部署自己的私有 agent_skills 注册中心，适用于企业内部或敏感环境。

Q: 我可以同时使用多个技能提供者吗？
A: 是的，agent_skills 协议的设计确保不同提供者的技能可以无缝协作。

Q: agent_skills 协议如何处理大型数据传输？
A: 对于大型数据，建议使用引用传递（如 URL 或标识符）而不是直接在参数中包含数据。

Q: 如何确保我的技能安全？
A: 实施适当的访问控制、验证所有输入、使用加密通信，并定期更新依赖项。

Q: 技能调用的延迟如何？
A: 延迟取决于部署架构，但 agent_skills 协议本身经过优化，引入的额外延迟最小。