Upsonic: an MIT-licensed Python framework for autonomous agents with a workspace sandbox

The gap Upsonic fills: an agent that can touch the filesystem without touching everything

Most Python agent libraries give you a loop that calls a model and returns text. The moment the agent needs to read a log file or run a command, you are writing your own path validation, your own subprocess wrapper, and your own allowlist. Upsonic takes a position on that layer. Its AutonomousAgent class takes a workspace argument, and the README states that all file and shell operations are restricted to that directory, with path traversal and dangerous commands blocked. That single sentence is the reason to look at the project, because it moves a security-relevant decision out of your application code and into the framework.

The audience is narrower than the tagline suggests. This is for Python developers who already have a model endpoint and want an agent that operates on a local directory: log analysis, file triage, a coding assistant scoped to one repository. Teams that only need a chat completion with a tool call do not gain anything from the autonomous path. The README also lists a second, plainer class, Agent, for what it calls traditional agent systems, so the project is not forcing the autonomous model on everyone.

AutonomousAgent versus Agent: two classes, two threat models

The README presents the two classes as separate entry points rather than one class with a flag. AutonomousAgent is constructed with a model string and a workspace path, then given a Task and invoked with print_do. Agent is constructed with a model string and a name, and its Task carries a description and an optional tools list. The example for Agent defines a sum_tool with the @tool decorator and passes it into the Task, not into the Agent constructor. That asymmetry is worth noting: tools attach at the task level in the documented example, which means one agent instance can run tasks with different tool sets.

What the README does not say is what distinguishes the autonomous loop from the traditional one at runtime. There is no description of planning, reflection, or iteration counts. If you need to know how many model calls a single print_do produces, or whether the autonomous agent replans after a failed shell command, that has to come from the documentation site rather than the repository front page. Treat the class split as a declared distinction, not an explained one.

The workspace restriction is the design centre, and the README is thin on it

The workspace argument is the most consequential line in the README. It is also the least specified. The text says path traversal and dangerous commands are blocked, but it does not enumerate the blocklist, state whether symlinks that resolve outside the workspace are rejected, or say whether the restriction applies to the model's tool calls only or also to any code the agent generates and executes.

That matters because the failure mode of a workspace sandbox is almost always the same: a path that passes a string check and then resolves elsewhere, or a permitted command that can write outside the tree. A string-level check on the command text is a different guarantee from a filesystem-level one. The README does not tell you which you are getting. The honest reading is that this is a guardrail, not a container. The README itself points to a Sandbox Provider (E2B) for isolated cloud execution environments, which is a reasonable signal that the authors do not consider the workspace argument sufficient for untrusted workloads. If your agent runs on inputs you did not write, the workspace argument is the wrong control and E2B or an equivalent is the right one.

Getting it running: install, model strings, and the OCR extra

Installation is a single command, with uv given first in the README and pip as a comment:

uv pip install upsonic

The minimal autonomous example from the README is:

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)

Note the model string format: a provider prefix, a slash, then the model name. The README uses anthropic/claude-sonnet-4-5 in every example, so the provider-prefixed convention is the documented one. Which other prefixes resolve is not stated on the page.

OCR is a separate extra and a separate import path:

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")

The README describes a two-layer pipeline: Layer 0 handles document preparation such as PDF to image conversion and preprocessing, Layer 1 runs the OCR engine. The engine is injected into the OCR object rather than selected by a string, which is why the import comes from upsonic.ocr.layer_1.engines. Listed engines are EasyOCR, RapidOCR, Tesseract, PaddleOCR, DeepSeek OCR, and DeepSeek via Ollama. Each of those carries its own system dependencies and model downloads, none of which the install extra can fully cover, so expect the OCR path to be heavier to set up than the agent path.

Prebuilt agents are a distribution channel, and a maintenance question

The repository contains a prebuilt directory, and the README describes each prebuilt as packaging a skill, a system prompt, and a first message so that a user can go from install to running quickly. The collection is open to contribution through pull requests.

This is a useful pattern and an awkward one at the same time. Useful, because the hardest part of an agent is often the prompt and the opening message, and a curated example beats a blank file. Awkward, because a prebuilt agent is only as good as the model it was written against. The README does not state whether prebuilt agents pin a model version, whether they declare a minimum Upsonic version, or how they are tested when the framework changes. The release cadence visible in the supplied material is fast: v0.77.1, v0.77.2, and v0.77.3 landed within four days of each other in May 2026. A directory of community-contributed agents under that cadence will drift unless something checks it. Before relying on a prebuilt agent, read its source in src/upsonic/prebuilt rather than trusting the doc page.

What Upsonic is not, and what to compare it against

Upsonic is not a graph orchestrator. There is no mention in the README of nodes, edges, state machines, or a durable execution model, and no example of two agents handing work to each other. If your problem is a deterministic multi-step pipeline where each step must be retried and resumed, a graph-based framework such as LangGraph is the closer fit: it models the workflow explicitly and lets you inspect and replay state, at the cost of writing the graph yourself. Upsonic's approach is the inverse. You hand the agent a task in natural language and a workspace, and the framework decides the steps. That is less code and less control.

The second comparison is the sandbox itself. Upsonic's workspace argument is an in-process restriction. E2B, which the README names as the next step, is a separate service providing an isolated execution environment. The difference is not one of degree: an in-process path check and an out-of-process VM fail in different ways. A bug in the check exposes your host filesystem. A bug in the sandbox exposes a disposable VM. For anything reading untrusted input, that distinction should decide the architecture before the framework choice does.

The third point of comparison is the OCR module, which is unusual for an agent framework and worth evaluating on its own. A layered pipeline with a swappable Layer 1 engine is a sensible shape, but it means Upsonic carries dependencies that have nothing to do with agents. That is exactly why it is behind an extra rather than in the base install.

Licence, versioning, and the cost of keeping up

Upsonic is MIT licensed, and the repository ships a LICENCE file that the README points to. MIT is permissive: you can use it commercially, modify it, and redistribute it, provided the copyright notice and permission notice are retained. That is a description of the licence text, not legal advice, and it says nothing about the licences of the OCR engines or the model providers you connect to, which are separate agreements.

The maintenance signal to weigh is the release cadence. Three patch releases in four days, all in the 0.77 line, indicate active work and also indicate that the API is still moving inside a minor version. Pin the version in your dependency file rather than tracking the latest patch, and read the changelog at docs.upsonic.ai/changelog before upgrading, because a patch bump under this cadence can carry behaviour changes. The upgrade cost is not the install; it is re-validating that your workspace assumptions and your model strings still hold.

Who should pick this up, and what to check before committing

Reach for Upsonic when you want a Python agent that reads and writes files inside one directory, you are comfortable reading the source to learn what the workspace check actually enforces, and the MIT licence matters to you. The two-class API is small enough to learn from the README alone, and the tool decorator example is complete enough to copy.

Walk away if you need a documented orchestration graph, if you need a hard isolation boundary without adding a second service, or if you need the framework to tell you exactly how the autonomous loop plans and retries. None of that is on the front page.

Before you write production code, resolve three open questions against the installed package. First, run the AutonomousAgent example with your own model string and confirm the provider prefix you need is accepted, since only the anthropic form is documented. Second, test the workspace boundary with a path that escapes via a symlink and with a command that writes outside the tree, and see what comes back; the README asserts a block but does not define it. Third, open src/upsonic/prebuilt and confirm the agent you intend to use is present on master at the version you pinned, because the README links to a docs page that may describe more than the repository contains.

Editorial conclusion

Adopt Upsonic if you want a Python agent that can touch files and run shell commands inside a directory you name, and you accept that the workspace restriction is the only isolation the README describes. Do not adopt it if you need a documented multi-agent scheduler or a hardened container boundary out of the box; the README points at E2B for that. Before writing production code, verify three things yourself: which model identifiers the installed version accepts, what the workspace blocklist actually rejects, and whether the prebuilt agent you want exists on master rather than only in a doc page.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Upsonic/Upsonic on GitHub