Teneo SDK 技能

概述

Teneo SDK (@teneo-protocol/sdk) 用于连接 Teneo Protocol 平台上的 AI 智能体。它提供：

• 基于 WebSocket 的与 AI 智能体的实时通信
• 使用以太坊私钥的钱包认证
• 房间管理（私密/公开房间，邀请智能体）
• 用于付费智能体交互的 x402 微支付协议
• 多链支付支持（Base、Peaq、Avalanche）

安装

npm install @teneo-protocol/sdk
# 或
pnpm add @teneo-protocol/sdk

核心概念

房间

房间是用户与 AI 智能体交互的通信通道：
- 私密房间：认证后自动可用，无需订阅
- 公开房间：需要通过 subscribeToRoom() 显式订阅
- 房间所有权决定了邀请智能体的能力

智能体

AI 智能体通过其 @句柄 标识（例如 @x-agent-enterprise-v2）。智能体可以：
- 通过 listAgents() 或 searchAgents() 发现
- 由房间所有者邀请到私密房间
- 某些智能体每次交互需要 x402 支付

x402 支付协议

使用支持链上的 USDC 进行智能体交互的微支付：
- Base（链 ID: 8453）- 推荐用于低费用
- Peaq（链 ID: 3338）
- Avalanche（链 ID: 43114）

每次请求的支付金额通常为 $0.01 - $0.10。

认证与连接

import { TeneoSDK } from "@teneo-protocol/sdk";

const sdk = new TeneoSDK({
  wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
  privateKey: "0x...", // 以太坊私钥
  logLevel: "silent", // 或 "debug"、"info"、"warn"、"error"
  maxReconnectAttempts: 30,

  // 支付配置（付费智能体必需）
  paymentNetwork: "eip155:8453", // CAIP-2 格式的 Base 网络
  paymentAsset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
});

// 连接（处理 WebSocket + 钱包签名认证）
await sdk.connect();

// 获取认证的钱包地址
const authState = sdk.getAuthState();
console.log(`认证身份: ${authState.walletAddress}`);

// 检查连接状态
if (sdk.isConnected) {
  console.log("已连接！");
}

// 完成后断开连接
sdk.disconnect();

支付网络配置

使用 CAIP-2 格式设置 paymentNetwork：

房间管理

发现房间

// 获取此钱包可用的所有房间（同步 - 连接后缓存）
const rooms = sdk.getRooms();

for (const room of rooms) {
  console.log(`房间: ${room.name} [${room.id}]`);
  console.log(`  公开: ${room.is_public}`);
  console.log(`  所有者: ${room.is_owner}`);
}

订阅房间

// 私密房间：认证后自动可用，无需订阅
// 公开房间：需要显式订阅

const publicRoom = rooms.find(r => r.is_public);
if (publicRoom) {
  await sdk.subscribeToRoom(publicRoom.id);
}

// 检查已订阅的房间
const subscribedRooms = sdk.getSubscribedRooms();
console.log(`已订阅: ${subscribedRooms.join(", ")}`);

智能体发现与邀请

查找可用智能体

// 列出平台上所有可用智能体
const agents = await sdk.listAgents();

for (const agent of agents) {
  console.log(`智能体: ${agent.name} (@${agent.handle})`);
  console.log(`  ID: ${agent.agent_id}`);
  console.log(`  描述: ${agent.description}`);
  console.log(`  价格: $${agent.price_per_request || 0}`);
}

// 按名称或关键词搜索智能体
const results = await sdk.searchAgents("twitter");
console.log(`找到 ${results.length} 个匹配 "twitter" 的智能体`);

列出房间中的智能体

// 获取特定房间中当前的智能体
const roomAgents = await sdk.listRoomAgents(roomId);

for (const agent of roomAgents) {
  console.log(`  - ${agent.name} (${agent.agent_id})`);
}

邀请智能体到房间

只有房间所有者可以邀请智能体：

// 首先，找到要邀请的智能体
const agents = await sdk.listAgents();
const xAgent = agents.find(a => a.handle === "x-agent-enterprise-v2");

if (xAgent) {
  // 通过 agent_id 将智能体添加到您的房间
  await sdk.addAgentToRoom(roomId, xAgent.agent_id);
  console.log(`已邀请 ${xAgent.name} 到房间`);
}

// 或直接通过已知的智能体 ID 邀请
await sdk.addAgentToRoom(roomId, "x-agent-enterprise-v2");

确保所需智能体在房间中

async function ensureAgentsInRoom(
  sdk: TeneoSDK,
  roomId: string,
  requiredAgentIds: string[]
): Promise<void> {
  // 获取房间中当前的智能体
  const roomAgents = await sdk.listRoomAgents(roomId);
  const existingIds = new Set(roomAgents.map(a => a.agent_id?.toLowerCase()));

  // 查找缺失的智能体
  const missing = requiredAgentIds.filter(
    id => !existingIds.has(id.toLowerCase())
  );

  // 邀请缺失的智能体
  for (const agentId of missing) {
    try {
      await sdk.addAgentToRoom(roomId, agentId);
      console.log(`已邀请智能体 "${agentId}" 到房间`);
    } catch (err: any) {
      console.warn(`邀请 "${agentId}" 失败: ${err.message}`);
    }
  }
}

// 使用示例
await ensureAgentsInRoom(sdk, roomId, [
  "x-agent-enterprise-v2",
  "another-agent-id",
]);

向智能体发送消息

基本消息

const response = await sdk.sendMessage("@x-agent-enterprise-v2 user @elonmusk", {
  waitForResponse: true,
  timeout: 60000, // 60 秒
  format: "both", // 同时获取原始内容和人性化版本
});

console.log(response.humanized || response.content);

带房间上下文的消息

const response = await sdk.sendMessage("@x-agent-enterprise-v2 post_stats 123456", {
  waitForResponse: true,
  timeout: 60000,
  format: "both",
  room: "room-id-here", // 指定目标房间
});

常用智能体命令

// X/Twitter 智能体 - 获取用户资料统计
"@x-agent-enterprise-v2 user @username"

// X/Twitter 智能体 - 获取帖子/推文统计
"@x-agent-enterprise-v2 post_stats 1234567890123456789"

事件处理

智能体响应

sdk.on("agent:response", (data) => {
  console.log(`智能体: ${data.agentName || data.agentId}`);
  console.log(`成功: ${data.success}`);
  console.log(`内容: ${data.humanized || data.content}`);

  if (data.error) {
    console.error(`错误: ${data.error}`);
  }
});

支付检测

x402 支付会反映在智能体响应中。解析响应以检测支付金额：

sdk.on("agent:response", (data) => {
  const content = data.humanized || data.content || "";

  // 支付检测的常见模式
  const patterns = [
    /x402 Payment \$([0-9.]+)/i,
    /Payment[:\s]+\$([0-9.]+)/i,
    /charged \$([0-9.]+)/i,
    /\$([0-9.]+)\s*(?:USDC|usdc)/i,
  ];

  for (const pattern of patterns) {
    const match = content.match(pattern);
    if (match) {
      const usdAmount = parseFloat(match[1]);
      console.log(`支付: $${usdAmount} USDC`);
      break;
    }
  }
});

连接事件

sdk.on("connection:open", () => {
  console.log("WebSocket 已连接");
});

sdk.on("disconnect", () => {
  console.log("已断开连接");
});

sdk.on("ready", () => {
  console.log("SDK 已就绪，可发送消息");
});

sdk.on("error", (err) => {
  // 处理速率限制
  const rateLimitMatch = err.message.match(/Please wait (\d+)ms/);
  if (rateLimitMatch) {
    const waitMs = parseInt(rateLimitMatch[1], 10);
    console.log(`速率受限，请等待 ${waitMs}ms`);
    return;
  }

  // 处理认证失败
  if (err.message.includes("Invalid challenge") ||
      err.message.includes("authentication failed")) {
    console.log("认证失败，正在重新连接...");
    return;
  }

  console.error(`SDK 错误: ${err.message}`);
});

完整示例：Base 网络智能体交互

import "dotenv/config";
import { TeneoSDK } from "@teneo-protocol/sdk";

// 配置
const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const BASE_NETWORK = "eip155:8453";

async function main() {
  // 使用 Base 支付配置初始化 SDK
  const sdk = new TeneoSDK({
    wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
    privateKey: process.env.PRIVATE_KEY!,
    logLevel: "info",
    maxReconnectAttempts: 10,
    paymentNetwork: BASE_NETWORK,
    paymentAsset: BASE_USDC,
  });

  // 跟踪支付
  let totalSpent = 0;

  sdk.on("agent:response", (data) => {
    const content = data.humanized || data.content || "";

    // 检测 x402 支付
    const match = content.match(/\$([0-9.]+)/);
    if (match) {
      const amount = parseFloat(match[1]);
      if (amount > 0 && amount < 1) { // 合理性检查
        totalSpent += amount;
        console.log(`支付: $${amount} | 总计: $${totalSpent.toFixed(4)}`);
      }
    }
  });

  // 带重试逻辑的连接
  for (let attempt = 1; attempt <= 5; attempt++) {
    try {
      await sdk.connect();
      console.log("已连接！");
      break;
    } catch (err: any) {
      // 处理速率限制
      const rateLimitMatch = err.message?.match(/Please wait (\d+)ms/);
      if (rateLimitMatch) {
        const waitMs = parseInt(rateLimitMatch[1], 10) + 100;
        console.log(`速率受限，等待 ${waitMs}ms...`);
        await sleep(waitMs);
        continue;
      }
      throw err;
    }
  }

  // 获取钱包地址
  const authState = sdk.getAuthState();
  console.log(`钱包: ${authState.walletAddress}`);

  // 查找房间（优先私密房间）
  const rooms = sdk.getRooms();
  let selectedRoom = rooms.find(r => !r.is_public) || rooms[0];

  if (selectedRoom?.is_public) {
    await sdk.subscribeToRoom(selectedRoom.id);
  }

  console.log(`使用房间: ${selectedRoom?.name || selectedRoom?.id}`);

  // 发现可用智能体
  const agents = await sdk.listAgents();
  console.log(`\n可用智能体 (${agents.length}):`);
  for (const agent of agents.slice(0, 5)) {
    console.log(`  - @${agent.handle}: ${agent.name}`);
  }

  // 确保智能体在房间中（如果是房间所有者）
  if (selectedRoom?.is_owner) {
    try {
      await sdk.addAgentToRoom(selectedRoom.id, "x-agent-enterprise-v2");
      console.log("智能体已邀请到房间");
    } catch (e) {
      // 智能体可能已在房间中
    }
  }

  // 向 X 智能体发送命令
  console.log("\n正在向 @x-agent-enterprise-v2 发送请求...");

  const response = await sdk.sendMessage(
    "@x-agent-enterprise-v2 user @VitalikButerin",
    {
      waitForResponse: true,
      timeout: 60000,
      format: "both",
      room: selectedRoom?.id,
    }
  );

  console.log("\n响应:");
  console.log(response.humanized || response.content);

  // 清理
  sdk.disconnect();
  console.log(`\n总计花费: $${totalSpent.toFixed(4)} USDC`);
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

main().catch(console.error);

错误处理最佳实践

连接错误

async function connectWithRetry(sdk: TeneoSDK, maxAttempts = 10): Promise<void> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      await sdk.connect();
      return;
    } catch (err: any) {
      const msg = err?.message || String(err);

      // 速率限制 - 等待并重试
      const rateLimitMatch = msg.match(/Please wait (\d+)ms/);
      if (rateLimitMatch) {
        const waitMs = parseInt(rateLimitMatch[1], 10) + 100;
        await sleep(waitMs);
        continue;
      }

      // 认证错误 - 指数退避
      if (msg.includes("Invalid challenge") ||
          msg.includes("authentication failed")) {
        const backoff = Math.min(5000 * Math.pow(2, attempt - 1), 60000);
        await sleep(backoff);
        continue;
      }

      // 其他错误 - 较短的重试
      if (attempt < maxAttempts) {
        await sleep(3000 * attempt);
        continue;
      }

      throw err;
    }
  }
}

支付错误

try {
  const response = await sdk.sendMessage(command, options);
  // 处理成功
} catch (err: any) {
  if (err.message.includes("Payment verification failed")) {
    // USDC 余额不足 - 需要充值钱包
    console.log("支付失败 - 检查 USDC 余额");
  } else if (err.message.includes("payment")) {
    // 其他支付问题
    console.log("支付错误:", err.message);
  }
}

多网络支持

通过创建具有不同支付配置的 SDK 实例在网络间切换：

const NETWORKS = {
  base: {
    paymentNetwork: "eip155:8453",
    paymentAsset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  },
  peaq: {
    paymentNetwork: "eip155:3338",
    paymentAsset: "0xbbA60da06c2c5424f03f7434542280FCAd453d10",
  },
  avax: {
    paymentNetwork: "eip155:43114",
    paymentAsset: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  },
};

function createSDK(network: keyof typeof NETWORKS, privateKey: string): TeneoSDK {
  const config = NETWORKS[network];
  return new TeneoSDK({
    wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
    privateKey,
    paymentNetwork: config.paymentNetwork,
    paymentAsset: config.paymentAsset,
  });
}

环境变量

典型的 .env 配置：

# 必需
PRIVATE_KEY=0x...

# 可选
WS_URL=wss://backend.developer.chatroom.teneo-protocol.ai/ws
ROOM=my-room-name

# 网络特定的 RPC URL（用于余额检查）
BASE_RPC_URL=https://mainnet.base.org
PEAQ_RPC_URL=https://peaq.api.onfinality.io/public
AVAX_RPC_URL=https://api.avax.network/ext/bc/C/rpc

TypeScript