Upsonic is an MIT-licensed Python framework for building autonomous AI agents and traditional tool-using agents, aimed at Python developers and teams who want to run agents on their own machines and connect them to their own models, tools, and documents.

What it is

Upsonic is a Python package published on PyPI under the name upsonic. It provides the classes needed to define an agent and the work it performs: Agent and AutonomousAgent for the agent itself, Task for the unit of work, and a @tool decorator for exposing plain Python functions to the model. Agents are constructed with a model string such as "anthropic/claude-sonnet-4-5", and a task is executed through calls like agent.print_do(task).

The concrete problem it solves is the glue code that otherwise has to be written by hand around every model call: prompt and tool dispatch, file and shell access, document extraction, and external data connections. AutonomousAgent confines all file and shell operations to a declared workspace path, and blocks path traversal and dangerous commands, so an agent that reads logs or edits files cannot wander outside the directory it was given. For document inputs, Upsonic ships a unified OCR interface with a layered pipeline — Layer 0 for document preparation such as PDF-to-image conversion, Layer 1 for the OCR engine itself — instead of leaving parsing to the caller.

Key capabilities

• AutonomousAgent with a mandatory workspace argument, restricting file and shell operations to that path and blocking path traversal and dangerous commands.
• Traditional Agent plus Task for non-autonomous, tool-driven workflows, invoked via agent.print_do(task).
• Custom tool definition through the @tool decorator, with the docstring and type hints of the Python function forming the tool schema.
• MCP (Model Context Protocol) tool integration, documented under MCP Tools, for connecting agents to external data sources and services.
• Prebuilt autonomous agents maintained by the community, each packaging a skill, a system prompt, and a first message, stored under src/upsonic/prebuilt and open to pull requests.
• OCR support installed through the upsonic[ocr] extra, with a choice of engines: EasyOCR, RapidOCR, Tesseract, PaddleOCR, DeepSeek OCR, and DeepSeek via Ollama.
• Optional isolated cloud execution through a Sandbox Provider (E2B), documented as the next step after building an autonomous agent.
• Documentation served in LLM-friendly form at https://docs.upsonic.ai/llms-full.txt, indexable directly from Cursor, VSCode, and Windsurf.

Who uses it and how

• Developers building autonomous agents of the kind the README names as OpenClaw and Claude Cowork, but as Python code they own and run themselves.
• Teams that need an agent to inspect local artifacts, for example a task reading "Analyze server logs and detect anomaly patterns" against a workspace directory of logs.
• Projects that need a conventional analyst-style agent, such as the documented "Stock Analyst Agent" performing "Analyze the current market trends".
• Applications that already have Python functions worth exposing, as with sum_tool, which is registered on a task via tools=[sum_tool].
• Pipelines that must extract text from scanned documents, using OCR(layer_1_ocr_engine=EasyOCREngine(languages=["en"])) and ocr.get_text("invoice.pdf").
• Contributors who publish reusable agents rather than applications, by opening a pull request against the prebuilt agent collection.

Getting started

Install from PyPI with uv pip install upsonic or pip install upsonic; OCR adds uv pip install "upsonic[ocr]". Guides and API reference live at https://docs.upsonic.ai, with a quickstart at /get-started/quickstart and examples at /examples.

How it compares

The README positions Upsonic as the means of building autonomous agents like OpenClaw and Claude Cowork, treating those as reference points for the category rather than as competing libraries. The distinction the facts support is licensing and ownership: Upsonic is MIT-licensed Python that is installed into your own environment and executed by your own process. No pricing, licence terms, or hosting model for the named systems appears in the facts provided, so no cost or deployment comparison can be made here.

When to use it — and when not to

A self-hoster runs the Python process, supplies model credentials and API access, installs OCR engines and their native dependencies when using the upsonic[ocr] extra, and provisions an E2B sandbox if isolated cloud execution is wanted; nothing in the facts describes a hosted option that removes that work. Choose it when an agent should operate inside a bounded local workspace under a permissive MIT licence. Do not choose it if the requirement is a turnkey managed service, since the facts show only a library and documentation site, and the prebuilt agents are community contributions with no stated review or support guarantees.

uv pip install upsonic
# pip install upsonic

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)

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)

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)

uv pip install "upsonic[ocr]"

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)