Introduction
# Teneo SDK Skill
## Overview
The Teneo SDK (`@teneo-protocol/sdk`) enables connection to AI agents on the Teneo Protocol platform. It provides:
- WebSocket-based real-time communication with AI agents - Wallet-based authentication using Ethereum private keys - Room management (private/public rooms, agent invitations) - x402 micropayment protocol for paid agent interactions - Multi-chain payment support (Base, Peaq, Avalanche)
## Installation
```bash npm install @teneo-protocol/sdk # or pnpm add @teneo-protocol/sdk ```
## Core Concepts
### Rooms Rooms are communication channels where users interact with AI agents: - **Private rooms**: Auto-available after authentication, no subscription needed - **Public rooms**: Require explicit subscription via `subscribeToRoom()` - Room ownership determines ability to invite agents
### Agents AI agents are identified by their `@handle` (e.g., `@x-agent-enterprise-v2`). Agents can be: - Discovered via `listAgents()` or `searchAgents()` - Invited to private rooms by room owners - Some require x402 payments for each interaction
### x402 Payment Protocol Micropayments for agent interactions using USDC on supported chains: - **Base** (chain ID: 8453) - Recommended for low fees - **Peaq** (chain ID: 3338) - **Avalanche** (chain ID: 43114)
Payment amounts are typically $0.01 - $0.10 per request.
## Authentication & Connection
```typescript import { TeneoSDK } from "@teneo-protocol/sdk";
const sdk = new TeneoSDK({ wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws", privateKey: "0x...", // Ethereum private key logLevel: "silent", // or "debug", "info", "warn", "error" maxReconnectAttempts: 30,
// Payment configuration (required for paid agents) paymentNetwork: "eip155:8453", // Base network in CAIP-2 format paymentAsset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC });
// Connect (handles WebSocket + wallet signature auth) await sdk.connect();
// Get authenticated wallet address const authState = sdk.getAuthState(); console.log(`Authenticated as: ${authState.walletAddress}`);
// Check connection status if (sdk.isConnected) { console.log("Connected!"); }
// Disconnect when done sdk.disconnect(); ```
### Payment Network Configuration
Use CAIP-2 format for `paymentNetwork`:
| Network | CAIP-2 ID | Chain ID | USDC Contract | |---------|-----------|----------|---------------| | Base | `eip155:8453` | 8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | | Peaq | `eip155:3338` | 3338 | `0xbbA60da06c2c5424f03f7434542280FCAd453d10` | | Avalanche | `eip155:43114` | 43114 | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` |
## Room Management
### Discovering Rooms
```typescript // Get all rooms available to this wallet (sync - cached after connect) const rooms = sdk.getRooms();
for (const room of rooms) { console.log(`Room: ${room.name} [${room.id}]`); console.log(` Public: ${room.is_public}`); console.log(` Owner: ${room.is_owner}`); } ```
### Subscribing to Rooms
```typescript // Private rooms: auto-available after auth, no subscription needed // Public rooms: require explicit subscription
const publicRoom = rooms.find(r => r.is_public); if (publicRoom) { await sdk.subscribeToRoom(publicRoom.id); }
// Check subscribed rooms const subscribedRooms = sdk.getSubscribedRooms(); console.log(`Subscribed to: ${subscribedRooms.join(", ")}`); ```
## Agent Discovery & Invitation
### Finding Available Agents
```typescript // List all available agents on the platform const agents = await sdk.listAgents();
for (const agent of agents) { console.log(`Agent: ${agent.name} (@${agent.handle})`); console.log(` ID: ${agent.agent_id}`); console.log(` Description: ${agent.description}`); console.log(` Price: $${agent.price_per_request || 0}`); }
// Search for agents by name or keyword const results = await sdk.searchAgents("twitter"); console.log(`Found ${results.length} agents matching "twitter"`); ```
### Listing Agents in a Room
```typescript // Get agents currently in a specific room const roomAgents = await sdk.listRoomAgents(roomId);
for (const agent of roomAgents) { console.log(` - ${agent.name} (${agent.agent_id})`); } ```
### Inviting Agents to Rooms
Only room owners can invite agents:
```typescript // First, find the agent you want to invite const agents = await sdk.listAgents(); const xAgent = agents.find(a => a.handle === "x-agent-enterprise-v2");
if (xAgent) { // Add agent to your room by their agent_id await sdk.addAgentToRoom(roomId, xAgent.agent_id); console.log(`Invited ${xAgent.name} to room`); }
// Or invite directly by known agent ID await sdk.addAgentToRoom(roomId, "x-agent-enterprise-v2"); ```
### Ensuring Required Agents Are in Room
```typescript async function ensureAgentsInRoom( sdk: TeneoSDK, roomId: string, requiredAgentIds: string[] ): Promise<void> { // Get agents currently in the room const roomAgents = await sdk.listRoomAgents(roomId); const existingIds = new Set(roomAgents.map(a => a.agent_id?.toLowerCase()));
// Find missing agents const missing = requiredAgentIds.filter( id => !existingIds.has(id.toLowerCase()) );
// Invite missing agents for (const agentId of missing) { try { await sdk.addAgentToRoom(roomId, agentId); console.log(`Invited agent "${agentId}" to room`); } catch (err: any) { console.warn(`Failed to invite "${agentId}": ${err.message}`); } } }
// Usage await ensureAgentsInRoom(sdk, roomId, [ "x-agent-enterprise-v2", "another-agent-id", ]); ```
## Sending Messages to Agents
### Basic Message
```typescript const response = await sdk.sendMessage("@x-agent-enterprise-v2 user @elonmusk", { waitForResponse: true, timeout: 60000, // 60 seconds format: "both", // Get both raw content and humanized version });
console.log(response.humanized || response.content); ```
### Message with Room Context
```typescript const response = await sdk.sendMessage("@x-agent-enterprise-v2 post_stats 123456", { waitForResponse: true, timeout: 60000, format: "both", room: "room-id-here", // Specify target room }); ```
### Common Agent Commands
```typescript // X/Twitter agent - Get user profile stats "@x-agent-enterprise-v2 user @username"
// X/Twitter agent - Get post/tweet stats "@x-agent-enterprise-v2 post_stats 1234567890123456789" ```
## Event Handling
### Agent Responses
```typescript sdk.on("agent:response", (data) => { console.log(`Agent: ${data.agentName || data.agentId}`); console.log(`Success: ${data.success}`); console.log(`Content: ${data.humanized || data.content}`);
if (data.error) { console.error(`Error: ${data.error}`); } }); ```
### Payment Detection
x402 payments are reflected in agent responses. Parse the response to detect payment amounts:
```typescript sdk.on("agent:response", (data) => { const content = data.humanized || data.content || "";
// Common patterns for payment detection 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(`Payment: $${usdAmount} USDC`); break; } } }); ```
### Connection Events
```typescript sdk.on("connection:open", () => { console.log("WebSocket connected"); });
sdk.on("disconnect", () => { console.log("Disconnected"); });
sdk.on("ready", () => { console.log("SDK ready for messages"); });
sdk.on("error", (err) => { // Handle rate limiting const rateLimitMatch = err.message.match(/Please wait (\d+)ms/); if (rateLimitMatch) { const waitMs = parseInt(rateLimitMatch[1], 10); console.log(`Rate limited, wait ${waitMs}ms`); return; }
// Handle auth failures if (err.message.includes("Invalid challenge") || err.message.includes("authentication failed")) { console.log("Authentication failed, reconnecting..."); return; }
console.error(`SDK Error: ${err.message}`); }); ```
## Complete Example: Base Network Agent Interaction
```typescript import "dotenv/config"; import { TeneoSDK } from "@teneo-protocol/sdk";
// Configuration const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; const BASE_NETWORK = "eip155:8453";
async function main() { // Initialize SDK with Base payment config 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, });
// Track payments let totalSpent = 0;
sdk.on("agent:response", (data) => { const content = data.humanized || data.content || "";
// Detect x402 payment const match = content.match(/\$([0-9.]+)/); if (match) { const amount = parseFloat(match[1]); if (amount > 0 && amount < 1) { // Sanity check totalSpent += amount; console.log(`Payment: $${amount} | Total: $${totalSpent.toFixed(4)}`); } } });
// Connect with retry logic for (let attempt = 1; attempt <= 5; attempt++) { try { await sdk.connect(); console.log("Connected!"); break; } catch (err: any) { // Handle rate limiting const rateLimitMatch = err.message?.match(/Please wait (\d+)ms/); if (rateLimitMatch) { const waitMs = parseInt(rateLimitMatch[1], 10) + 100; console.log(`Rate limited, waiting ${waitMs}ms...`); await sleep(waitMs); continue; } throw err; } }
// Get wallet address const authState = sdk.getAuthState(); console.log(`Wallet: ${authState.walletAddress}`);
// Find a room (prefer private rooms) 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(`Using room: ${selectedRoom?.name || selectedRoom?.id}`);
// Discover available agents const agents = await sdk.listAgents(); console.log(`\nAvailable agents (${agents.length}):`); for (const agent of agents.slice(0, 5)) { console.log(` - @${agent.handle}: ${agent.name}`); }
// Ensure agent is in room (if we own it) if (selectedRoom?.is_owner) { try { await sdk.addAgentToRoom(selectedRoom.id, "x-agent-enterprise-v2"); console.log("Agent invited to room"); } catch (e) { // Agent may already be in room } }
// Send command to X agent console.log("\nSending request to @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("\nResponse:"); console.log(response.humanized || response.content);
// Cleanup sdk.disconnect(); console.log(`\nTotal spent: $${totalSpent.toFixed(4)} USDC`); }
function sleep(ms: number): Promise<void> { return new Promise(resolve => setTimeout(resolve, ms)); }
main().catch(console.error); ```
## Error Handling Best Practices
### Connection Errors
```typescript 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);
// Rate limiting - wait and retry const rateLimitMatch = msg.match(/Please wait (\d+)ms/); if (rateLimitMatch) { const waitMs = parseInt(rateLimitMatch[1], 10) + 100; await sleep(waitMs); continue; }
// Auth errors - exponential backoff if (msg.includes("Invalid challenge") || msg.includes("authentication failed")) { const backoff = Math.min(5000 * Math.pow(2, attempt - 1), 60000); await sleep(backoff); continue; }
// Other errors - shorter retry if (attempt < maxAttempts) { await sleep(3000 * attempt); continue; }
throw err; } } } ```
### Payment Errors
```typescript try { const response = await sdk.sendMessage(command, options); // Handle success } catch (err: any) { if (err.message.includes("Payment verification failed")) { // Insufficient USDC balance - need to fund wallet console.log("Payment failed - check USDC balance"); } else if (err.message.includes("payment")) { // Other payment issue console.log("Payment error:", err.message); } } ```
## Multi-Network Support
Switch between networks by creating SDK instances with different payment configs:
```typescript 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, }); } ```
## Environment Variables
Typical `.env` configuration:
```bash # Required PRIVATE_KEY=0x...
# Optional WS_URL=wss://backend.developer.chatroom.teneo-protocol.ai/ws ROOM=my-room-name
# Network-specific RPC URLs (for balance checks) 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 Types
```typescript interface SDKConfig { wsUrl: string; privateKey: string; logLevel?: "silent" | "debug" | "info" | "warn" | "error"; maxReconnectAttempts?: number; paymentNetwork?: string; // CAIP-2 format: "eip155:chainId" paymentAsset?: string; // USDC contract address }
interface Room { id: string; name: string; is_public?: boolean; is_owner?: boolean; }
interface Agent { agent_id: string; name: string; handle: string; description?: string; price_per_request?: number; }
interface AgentResponse { taskId: string; agentId: string; agentName?: string; content: string; success: boolean; error?: string; humanized?: string; }
interface MessageOptions { waitForResponse?: boolean; timeout?: number; format?: "raw" | "humanized" | "both"; room?: string; }
interface AuthState { walletAddress?: string; } ```
## Tips
1. **Always check USDC balance** before sending paid requests 2. **Use private rooms** when possible - no subscription needed 3. **Handle rate limits gracefully** - the SDK enforces connection limits 4. **Set appropriate timeouts** - agent responses can take 30-60 seconds 5. **Prefer Base network** for lowest transaction fees 6. **Disconnect cleanly** to avoid orphaned WebSocket connections 7. **Discover agents first** - use `listAgents()` to find available agents before inviting