README

Upsonic

Build Autonomous AI Agents in Python









Documentation • Quickstart • Examples • Discord



---

 Overview

Upsonic is a Python framework for building autonomous agents like OpenClaw and Claude Cowork, as well as more traditional agent systems.

 Quick Start

 Installation

bash
uv pip install upsonic
 pip install upsonic


 IDE Integration

Add Upsonic docs as a source in your coding tools:

Cursor: Settings → Indexing & Docs → Add https://docs.upsonic.ai/llms-full.txt

Also works with VSCode, Windsurf, and similar tools.

---

 Create Autonomous Agent

 Build Your Own

python
from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/logs"
)

task = Task("Analyze server logs and detect anomaly patterns")

agent.print_do(task)


All file and shell operations are restricted to workspace. Path traversal and dangerous commands are blocked.

 Use Our Prebuilt Ones

Prebuilt autonomous agents are ready-to-run agents built by the Upsonic community, each packaging a skill, system prompt, and first message so you can go from install to running in seconds. The collection is open to contributions, bring your agent and open a PR.

Learn more: Prebuilt Autonomous Agents

 Next steps: Connect a Sandbox Provider (E2B) for isolated cloud execution environments.

---

 Create Traditional Agent

python
from upsonic import Agent, Task

agent = Agent(model="anthropic/claude-sonnet-4-5", name="Stock Analyst Agent")

task = Task(description="Analyze the current market trends")

agent.print_do(task)


 Add Custom Tools

python
from upsonic import Agent, Task
from upsonic.tools import tool

@tool
def sum_tool(a: float, b: float) - float:
    """
    Add two numbers together.

    Args:
        a: First number
        b: Second number

    Returns:
        The sum of a and b
    """
    return a + b

task = Task(
    description="Calculate 15 + 27",
    tools=[sum_tool]
)

agent = Agent(model="anthropic/claude-sonnet-4-5", name="Calculator Agent")

result = agent.print_do(task)


 Next steps: Integrate MCP Tools to connect your agents to thousands of external data sources and services.

---

 OCR and Document Processing

Upsonic provides a unified OCR interface with a layered pipeline: Layer 0 handles document preparation (PDF to image conversion, preprocessing), Layer 1 runs the OCR engine.

bash
uv pip install "upsonic[ocr]"


python
from upsonic.ocr import OCR
from upsonic.ocr.layer_1.engines import EasyOCREngine

engine = EasyOCREngine(languages=["en"])
ocr = OCR(layer_1_ocr_engine=engine)

text = ocr.get_text("invoice.pdf")
print(text)


Supported engines: EasyOCR, RapidOCR, Tesseract, PaddleOCR, DeepSeek OCR, DeepSeek via Ollama.

Learn more: OCR Documentation

---

 Check Our Videos


  
    
      
        
      
    
    
      
        
      
    
  


---

 Documentation and Resources

- Documentation - Complete guides and API reference
- Quickstart Guide - Get started