# Upsonic
**Build Autonomous AI Agents in Python**
[Documentation](https://docs.upsonic.ai) • [Quickstart](https://docs.upsonic.ai/get-started/quickstart) • [Examples](https://docs.upsonic.ai/examples) • [Discord](https://discord.gg/pmYDMSQHqY)
---
## 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](https://github.com/Upsonic/Upsonic/tree/master/src/upsonic/prebuilt), bring your agent and open a PR.
Learn more: [Prebuilt Autonomous Agents](https://docs.upsonic.ai/concepts/prebuilt-autonomous-agents/overview)
> **Next steps:** Connect a [Sandbox Provider (E2B)](https://docs.upsonic.ai/concepts/autonomous-agent/overview) 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](https://docs.upsonic.ai/concepts/tools/mcp-tools/overview) 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](https://docs.upsonic.ai/concepts/ocr/overview)
---
## Check Our Videos
