🚀 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

🔗 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).

Built with ❤️ by developers, for developers

⭐ Star us on GitHub

Navigation Menu

Uh oh!

🚀 ConnectOnion TypeScript SDK

✨ What is ConnectOnion?

🎯 Why Use This?

🐍 Build Agents in Python

📱 Use Agents in TypeScript

🌐 Zero Infrastructure

🔒 Secure by Design

🚀 Quick Start (60 seconds)

1. Install

2. Connect to a Python Agent

3. Create the Python Agent (Optional)

🎨 Real-World Examples

Example 1: Connect to ML Agent from React App

Example 2: Node.js Backend Using Python Agent

Example 3: Electron App with Python Backend

🔧 Connection Options

Custom Relay URL

Timeout Configuration

Multiple Agents

📚 Documentation

Building Agents in TypeScript (Experimental)

🏗️ Architecture

System Overview

Agent Execution Flow

Tool Conversion

LLM Provider Routing

Project Structure

SDK Internal Structure

💬 Join the Community

⭐ Show Your Support

🤝 Contributing

Development Setup

📄 License

🔗 Links

🌟 Why This Architecture?

Python for Agents

TypeScript for Apps

Best of Both Worlds

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🚀 ConnectOnion TypeScript SDK

✨ What is ConnectOnion?

🎯 Why Use This?

🐍 Build Agents in Python

📱 Use Agents in TypeScript

🌐 Zero Infrastructure

🔒 Secure by Design

🚀 Quick Start (60 seconds)

1. Install

2. Connect to a Python Agent

3. Create the Python Agent (Optional)

🎨 Real-World Examples

Example 1: Connect to ML Agent from React App

Example 2: Node.js Backend Using Python Agent

Example 3: Electron App with Python Backend

🔧 Connection Options

Custom Relay URL

Timeout Configuration

Multiple Agents

📚 Documentation

Building Agents in TypeScript (Experimental)

🏗️ Architecture

System Overview

Agent Execution Flow

Tool Conversion

LLM Provider Routing

Project Structure

SDK Internal Structure

💬 Join the Community

⭐ Show Your Support

🤝 Contributing

Development Setup

📄 License

🔗 Links

🌟 Why This Architecture?

Python for Agents

TypeScript for Apps

Best of Both Worlds