🚀 ConnectOnion TypeScript SDK

Connect to Python agents from TypeScript - Use powerful Python agents in your TypeScript apps

✨ What is ConnectOnion?

ConnectOnion TypeScript SDK lets you connect to and use AI agents built with Python from standalone TypeScript, Node.js, or Electron applications. React applications should use @connectonion/react, which includes its own browser connection layer and does not depend on this package.

// Connect to a Python agent and use it
import { connect } from 'connectonion';

// Connect to a remote agent by address
const agent = connect('0x3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c');

// Use it like a local function
const result = await agent.input('Search for TypeScript tutorials');
console.log(result);

That's it. No server setup. No complex configuration. Just connect and use.

🎯 Why Use This?

🐍 Build Agents in Python

Python has the richest AI ecosystem - LangChain, LlamaIndex, transformers, and countless ML libraries. Build your agents where the tools are best.

📱 Use Agents in TypeScript

Your Node.js backends, Electron apps, and other TypeScript clients can use powerful Python agents directly. React frontends use the dedicated @connectonion/react SDK.

🌐 Zero Infrastructure

No servers to manage. No API endpoints to deploy. Agents connect peer-to-peer through the relay network.

🔒 Secure by Design

Ed25519 cryptographic addressing. No passwords. No auth tokens to leak. Just public/private key pairs.

🚀 Quick Start (60 seconds)

1. Install

npm install connectonion
# or
yarn add connectonion
# or
pnpm add connectonion

2. Connect to a Python Agent

import { connect } from 'connectonion';

// Connect to a remote Python agent
const agent = connect('0x3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c');

// Use it!
const response = await agent.input('Analyze this data and create a report');
console.log(response);

3. Create the Python Agent (Optional)

If you need to create your own agent in Python:

# pip install connectonion
from connectonion import Agent, announce

def analyze_data(data: str) -> str:
    """Analyze data and create a report"""
    # Your Python logic with pandas, numpy, etc.
    return f"Analysis: {data}"

agent = Agent(
    name="data-analyst",
    tools=[analyze_data]
)

# Announce to the network
announce(agent)
# Prints: Agent address: 0x3d401...

Then connect from TypeScript as shown above!

🎨 Real-World Examples

Example 1: Connect to ML Agent from React App

// React uses the self-contained React SDK
import { useAgentForHuman } from '@connectonion/react';

function DataAnalyzer() {
  const { input, sendMessage } = useAgentForHuman('0xYourPythonMLAgent');

  const analyze = async () => {
    await sendMessage(
      'Analyze sales data and predict next quarter trends'
    );
  };

  return <button onClick={analyze} disabled={!input}>Analyze Data</button>;
}

Example 2: Node.js Backend Using Python Agent

// Express API using a Python agent for complex processing
import express from 'express';
import { connect } from 'connectonion';

const app = express();
const pythonAgent = connect('0xYourPythonAgent');

app.post('/analyze', async (req, res) => {
  // Offload heavy processing to Python agent
  const result = await pythonAgent.input(req.body.query);
  res.json({ result });
});

app.listen(3000);

Example 3: Electron App with Python Backend

// Electron app using Python agent for system operations
import { connect } from 'connectonion';

const systemAgent = connect('0xYourSystemAgent');

async function handleFileOperation() {
  // Python agent has full system access and libraries
  const result = await systemAgent.input(
    'Find all PDFs in Downloads, extract text, and summarize'
  );
  return result;
}

🔧 Connection Options

Custom Relay URL

// Connect to local development relay
const agent = connect(
  '0xYourAgent',
  'ws://localhost:8000/ws/announce'
);

// Or use environment variable
process.env.RELAY_URL = 'ws://localhost:8000/ws/announce';
const agent = connect('0xYourAgent'); // uses RELAY_URL

Timeout Configuration

// Adjust timeout for long-running tasks
const result = await agent.input(
  'Process large dataset',
  60000 // 60 second timeout
);

Multiple Agents

// Connect to different specialized agents
const mlAgent = connect('0xMLAgent');
const nlpAgent = connect('0xNLPAgent');
const visionAgent = connect('0xVisionAgent');

// Use them in parallel
const [analysis, sentiment, objects] = await Promise.all([
  mlAgent.input('Analyze time series'),
  nlpAgent.input('Extract sentiment from reviews'),
  visionAgent.input('Detect objects in image')
]);

📚 Documentation

• Getting Started Guide - Complete setup walkthrough
• Connect API - Remote agent connection details
• API Reference - Full API documentation
• Troubleshooting - Common issues & solutions

Building Agents in TypeScript (Experimental)

While we recommend building agents in Python, you can also build simple agents directly in TypeScript:

• Tool System - How to create tools in TypeScript
• Examples - TypeScript agent examples

Important Notes:

• TypeScript agent features are experimental and may have bugs
• Python agent features are well-tested and fully supported
• For complex agents with ML, data processing, or extensive Python libraries, use Python and connect via connect()
• Full TypeScript agent support planned for Q1 2026

If you encounter bugs building agents in TypeScript, please report them on GitHub.

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                    ConnectOnion TypeScript SDK                    │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │    Agent      │  │   connect()  │  │      llmDo()           │ │
│  │  (local AI)   │  │  (remote)    │  │  (one-shot LLM call)   │ │
│  └──────┬───────┘  └──────┬───────┘  └────────────┬───────────┘ │
│         │                 │                        │             │
│         ▼                 ▼                        │             │
│  ┌─────────────────────────────┐                   │             │
│  │        LLM Factory          │◀──────────────────┘             │
│  │      createLLM(model)       │                                 │
│  └──────────┬──────────────────┘                                 │
│     ┌───────┼──────────┬────────────┐                            │
│     ▼       ▼          ▼            ▼                            │
│  Anthropic  OpenAI   Gemini    OpenOnion                         │
│  (claude-*) (gpt-*)  (gemini-*) (co/*)                          │
│                                                                  │
│  ┌──────────────┐  ┌──────────┐  ┌───────────┐  ┌───────────┐  │
│  │  Tool System  │  │  Trust   │  │  Console  │  │   Xray    │  │
│  │  func→schema  │  │  Levels  │  │  Logging  │  │  Debugger │  │
│  └──────────────┘  └──────────┘  └───────────┘  └───────────┘  │
└─────────────────────────────────────────────────────────────────┘

Agent Execution Flow

  agent.input("What is 2+2?")
       │
       ▼
  ┌─────────────────┐
  │  Init messages   │  [system prompt] + [user message]
  └────────┬────────┘
           │
           ▼
  ┌─────────────────────────────────────┐
  │        Main Loop (max 10 iter)       │
  │                                      │
  │  LLM.complete(messages, tools)       │
  │       │                              │
  │       ├── No tool calls ──▶ EXIT     │
  │       │                              │
  │       └── Tool calls found:          │
  │            Promise.all(              │
  │              tool_1.run(args),       │
  │              tool_2.run(args)        │
  │            )                         │
  │            │                         │
  │            ▼                         │
  │       Append results → LOOP          │
  └─────────────────────────────────────┘
       │
       ▼
  Return final text response

Tool Conversion

  Your code                        SDK internals

  function add(a: number,          Tool {
    b: number): number {    ──▶      name: "add",
    return a + b;                    description: "...",
  }                                  run(args) → add(a, b),
                                     toFunctionSchema() → {
  class API {                          type: "object",
    search(q: string) {}   ──▶        properties: {a: {type: "number"}, ...}
    fetch(id: number) {}             }
  }                                }

LLM Provider Routing

  createLLM(model)
       │
       ├── "co/*"     ──▶ OpenAI LLM + OpenOnion baseURL
       ├── "claude-*"  ──▶ Anthropic LLM (default)
       ├── "gpt-*"     ──▶ OpenAI LLM
       ├── "o*"        ──▶ OpenAI LLM
       ├── "gemini-*"  ──▶ Gemini LLM
       └── (unknown)   ──▶ Anthropic (fallback) or NoopLLM

Project Structure

your-project/
├── src/
│   ├── agents/        # Your agent definitions
│   ├── tools/         # Custom tool implementations
│   └── index.ts       # Main entry point
├── .env               # API keys (never commit!)
├── package.json
└── tsconfig.json

SDK Internal Structure

src/
├── core/
│   └── agent.ts            # Main Agent class (orchestrator)
├── llm/
│   ├── index.ts            # LLM factory (routes model names)
│   ├── anthropic.ts        # Anthropic Claude provider (default)
│   ├── openai.ts           # OpenAI GPT/O-series provider
│   ├── gemini.ts           # Google Gemini provider
│   ├── noop.ts             # Fallback for missing config
│   └── llm-do.ts           # One-shot llmDo() helper
├── tools/
│   ├── tool-utils.ts       # Function → Tool conversion
│   ├── tool-executor.ts    # Execution + trace recording
│   ├── xray.ts             # Debug context injection (@xray)
│   ├── replay.ts           # Replay decorator for debugging
│   └── email.ts            # Mock email tools for demos/tests
├── trust/
│   ├── index.ts            # Trust levels (open/careful/strict)
│   └── tools.ts            # Whitelist checks & verification
├── connect/
│   ├── index.ts            # connect() factory + re-exports
│   ├── types.ts            # ChatItem, Response, AgentStatus, ConnectOptions, etc.
│   ├── endpoint.ts         # resolveEndpoint, fetchAgentInfo, utils
│   └── remote-agent.ts     # RemoteAgent class
├── console.ts              # Dual logging (stderr + file)
├── types.ts                # Core TypeScript interfaces
└── index.ts                # Public API exports

💬 Join the Community

Get help, share agents, and discuss with 1000+ builders in our active community.

⭐ Show Your Support

If ConnectOnion helps you build better agents, give it a star! ⭐

It helps others discover the framework and motivates us to keep improving it.

⭐ Star on GitHub

🤝 Contributing

We love contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repo
git clone https://github.com/openonion/connectonion-ts
cd connectonion-ts

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

📄 License

MIT © OpenOnion Team

🔗 Links

• Python Version - Original Python SDK
• Discord Community - Get help & share ideas
• Blog - Tutorials and updates

🌟 Why This Architecture?

Python for Agents

• Rich AI Ecosystem: LangChain, transformers, pandas, scikit-learn, PyTorch, TensorFlow
• Data Processing: NumPy, SciPy, matplotlib for complex analysis
• Mature Libraries: Decades of proven Python libraries
• Simple Setup: pip install and you're ready

TypeScript for Apps

• Web & Mobile: React, Next.js, React Native, Electron
• Type Safety: Catch errors at compile time
• IDE Support: Unmatched IntelliSense and auto-completion
• NPM Ecosystem: Access to millions of UI/frontend packages

Best of Both Worlds

Build agents where the tools are rich (Python), use them where users are (TypeScript apps).