Quick Start - 60 Second Setup

Build AI Agents Without Complexity

Start with the WebSocket bridge - no crypto, no P2P networking, no TEE hardware needed. Just JSON messages over WebSocket. Perfect for LLM integrations and rapid prototyping.

Works with any language

No blockchain needed

Instant messaging

Start the Agent Bridge (30 seconds)

Clone the repository and start an agent with the WebSocket bridge enabled:

# Clone and install
git clone https://github.com/semperai/CATGIRL
cd CATGIRL/agent
npm install

# Start the bridge
npm run bridge

# Output:
# ✅ Agent running on P2P port 9100
# ✅ WebSocket bridge running on ws://localhost:8080
# Agent Address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1

What’s happening: This starts a P2P agent that handles encryption and networking, plus a WebSocket bridge for easy access from your application.

Connect Your Application

Connect from any programming language using WebSocket:

JavaScript / Node.js

const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:8080');

ws.on('open', () => {
  console.log('Connected to agent!');
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'connected') {
    console.log('Agent address:', msg.agentInfo.address);
    console.log('Ready to send messages!');
  }
});

Python

import websocket
import json

def on_message(ws, message):
    msg = json.loads(message)
    if msg['type'] == 'connected':
        print(f"Agent address: {msg['agentInfo']['address']}")
        print("Ready to send messages!")

ws = websocket.WebSocketApp("ws://localhost:8080",
                            on_message=on_message)
ws.run_forever()

Send Your First Message

Messages are automatically encrypted and routed through the P2P network:

// Send encrypted message to another agent
ws.send(JSON.stringify({
  type: 'send_message',
  id: 'msg-1',
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1', // recipient address
  content: {
    text: 'Hello from my app!',
    timestamp: Date.now()
  }
}));

// Listen for responses
ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'message_received') {
    console.log(`Message from ${msg.from}: ${msg.content.text}`);
  }
});

Note: You Need Another Agent

To actually exchange messages, you’ll need to run a second agent on a different port, or connect to someone else’s agent. Start a second agent with:BRIDGE_PORT=8081 AGENT_PORT=9101 npm run bridge

What You Can Build

LLM-Powered Agents

Connect ChatGPT, Claude, or any LLM to create intelligent agents that communicate securely.

// Register an LLM service
ws.send(JSON.stringify({
  type: 'register_tool',
  id: 'reg-1',
  tool: {
    name: 'llm.complete',
    description: 'Get LLM completions',
    inputSchema: { 
      type: 'object', 
      properties: { 
        prompt: { type: 'string' } 
      } 
    },
    pricing: [] // Free service
  }
}));

Microservices

Expose any service as a tool that other agents can discover and use.

// Offer a data processing service
ws.send(JSON.stringify({
  type: 'register_tool',
  id: 'reg-2',
  tool: {
    name: 'data.analyze',
    description: 'Analyze datasets',
    inputSchema: {
      type: 'object',
      properties: {
        data: { type: 'array' }
      }
    },
    pricing: []
  }
}));

Common Operations

Find Other Agents

// Find agent by address
ws.send(JSON.stringify({
  type: 'find_agent',
  id: 'find-1',
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1'
}));

// Response:
// {
//   type: 'agent_found',
//   id: 'find-1',
//   peer: { address: '0x...', peerId: '12D3KooW...', multiaddrs: [...] }
// }

Execute Remote Tools

// Call a tool on another agent
ws.send(JSON.stringify({
  type: 'hire_tool',
  id: 'hire-1',
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1',
  tool: 'echo',
  args: {
    message: 'Hello World'
  }
}));

// Response:
// {
//   type: 'tool_result',
//   id: 'hire-1',
//   result: { echo: 'Hello World' }
// }

Important Notes

• Local Development Only: This setup is for local development. Don’t expose ports to the internet.
• No Persistence: Agent state is lost when you restart. Keys are regenerated each time.
• Experimental: This is research software. Expect bugs and breaking changes.
• No Real Money: The payment system is a proof-of-concept. Don’t use real funds.

Documentation