Upsonic: a Python framework for autonomous agents with a workspace sandbox

What Upsonic actually solves for Python teams

Most agent frameworks start from chat completion and add tool calling on top. Upsonic starts from a different premise: the README describes it as a Python framework for building autonomous agents like OpenClaw and Claude Cowork, as well as more traditional agent systems. That phrasing splits the library into two products that share a package.

The traditional half is an Agent class with a name, a model string such as anthropic/claude-sonnet-4-5, and tasks that can carry a list of tools. This is the familiar pattern: you describe a task, attach Python functions, and call the agent. The autonomous half is an AutonomousAgent that takes a workspace path in addition to a model. The README states that all file and shell operations are restricted to that workspace, and that path traversal and dangerous commands are blocked. That restriction is the actual differentiator. An agent that can read logs and run shell commands is useful precisely because it can touch the filesystem, and that is also what makes it hard to ship. Upsonic's answer is to make the boundary part of the constructor rather than something you bolt on.

The audience is therefore narrow and specific: Python developers who want an agent to inspect a directory of files, run commands, and report back, without giving it the whole machine. If your agent only calls APIs and never touches disk, the AutonomousAgent class adds nothing over the plain Agent.

The two agent classes and how a task flows through them

The data flow visible in the README is short. You construct an agent with a model identifier, construct a Task with a description, optionally attach tools to the task, and then call print_do on the agent with the task. The method name suggests it prints the result as it goes, which fits a framework that depends on rich for terminal output.

The tool path is worth reading closely. In the README example, the tools list is passed to Task, not to Agent. That is a deliberate placement: the same agent instance can run different tasks with different capabilities, and a tool is scoped to the work rather than to the worker. The @tool decorator reads the function signature and its docstring, including the Args and Returns sections, to build the schema the model sees. That means the docstring is not documentation, it is the interface. A vague docstring produces a vague tool description.

The autonomous class adds a workspace argument. Everything the agent does with files or a shell is supposed to resolve inside that path. The README does not describe the resolution algorithm, so treat the guarantee as a documented claim rather than something you can reason about from the repository layout. There is also a pointer to a sandbox provider, E2B, for isolated cloud execution environments. That is the escape hatch when a local workspace is not enough isolation.

Installing Upsonic and running a first agent

The README gives uv pip install as the primary install command, with plain pip as a commented alternative. The package requires Python 3.10 or newer according to the classifiers in pyproject.toml, which list 3.10, 3.11 and 3.12.

uv pip install upsonic
# pip install upsonic

After that, the smallest useful program is the traditional agent. Note the model string format: provider slash model name. The README uses anthropic/claude-sonnet-4-5 throughout.

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)

Expect the result to be printed to the terminal rather than returned as a value, since the example calls print_do and assigns nothing. The README also shows a result variable in the custom tool example, where agent.print_do(task) is assigned to result, so both usages appear in the documentation.

To see the tool mechanism, define a function with a typed signature and a docstring that documents each argument.

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)

The autonomous variant swaps the class and adds a workspace path. The README example points workspace at a logs directory and asks the agent to analyze server logs for anomaly patterns.

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)

Replace /path/to/logs with a real directory before running. If you plan to use the OCR pipeline, it is a separate extra: uv pip install "upsonic[ocr]", and the README's example builds an OCR object around an EasyOCREngine with languages=["en"], then calls get_text on a file path. Supported engines listed there are EasyOCR, RapidOCR, Tesseract, PaddleOCR, DeepSeek OCR and DeepSeek via Ollama.

Where the workspace guarantee gets thin

The README states that path traversal and dangerous commands are blocked, and that operations are restricted to the workspace. It does not say how. There is no description of whether the check is a prefix match on the resolved path, whether symlinks are followed before or after resolution, or which commands are classified as dangerous. Those are exactly the questions a security reviewer will ask, and the README does not answer them.

That matters because the failure mode is asymmetric. If the workspace check is too loose, an autonomous agent with shell access is a much larger problem than a chatbot with a bad answer. If it is too strict, legitimate work breaks: an agent asked to read a config file one directory up will refuse, and the error may not explain why. Either way, you find out by testing, not by reading the documentation.

The E2B pointer is the honest signal here. The README recommends connecting a sandbox provider for isolated cloud execution environments, which implies the local workspace is a guardrail for convenience and not a substitute for process or container isolation. If your threat model includes prompt injection from untrusted file contents, a directory restriction inside the same process is not the boundary you want.

There is a second limitation in the release cadence. The most recent release listed is v0.77.3 from 2026-05-19, and the last push to the repository was on 2026-06-18. The version number itself is the warning: this is pre-1.0 software, and the minor version has moved dozens of times. Pin the version in production.

Upsonic versus a general-purpose agent framework

The closest comparison in the related search data is PraisonAI, another Python multi-agent framework. The difference in approach is where the framework puts its weight. Upsonic's README spends its examples on two things: a tool decorator that derives its schema from type hints and docstrings, and an autonomous agent whose file and shell access is scoped to a workspace path. Multi-agent coordination is not what the README leads with.

A framework built around agent teams, role assignment and inter-agent messaging solves a different problem. If your work is decomposing a research question across several specialized agents that talk to each other, Upsonic's README does not show that pattern, and you would be evaluating it on ground it does not advertise. If your work is one agent that needs to read a directory, run a command and report, the workspace constructor is a more direct fit than wiring up a sandbox yourself.

The honest framing is that these are not competing on the same axis. Upsonic's claim is about the boundary between an agent and the machine it runs on. That is a narrower claim than general orchestration, and it is easier to evaluate: either the workspace restriction holds up under your testing or it does not.

Licence, upgrades and the cost of tracking 0.77.x

Upsonic is MIT licensed, and the README points to the LICENCE file for details. MIT is permissive: you can use it in commercial and closed-source products, and you carry the usual obligation to include the licence text. The repository also ships a SECURITY.md and a CODE_OF_CONDUCT.md, and the contributing guide is referenced from the README. None of that is legal advice, and if you are redistributing the package you should read the LICENCE file rather than a summary of it.

The upgrade cost is the part worth budgeting. The project uses release-please, visible in the repository root as release-please-config.json and .release-please-manifest.json, which means releases are generated from commit conventions. The published versions run v0.77.1 through v0.77.3 across four days in May 2026. That is a healthy release pipeline and also a moving target. The pyproject.toml pins some dependencies exactly (psutil==6.1.1) and floors others (pydantic>=2.10.5, openai>=2.2.0), so a fresh install months later resolves to a different dependency set than the author tested.

The practical mitigation is to pin upsonic itself and to check CHANGELOG.md, which the README links through the docs site, before bumping. The optional extras make this more complicated: the OCR, vector store and MCP dependencies are separate installs, so an upgrade of the core package does not tell you whether the chroma or pgvector extra still works with the same code.

Editorial conclusion

Adopt Upsonic if you want a Python-only agent layer where the autonomous variant is sandboxed to a workspace directory by default, and you are comfortable tracking a fast-moving 0.77.x release line. Skip it if you need a stable API surface or a non-Python runtime. Before writing production code, verify two things in your own environment: that the model string format your provider expects is accepted by the installed version, and that the workspace restriction behaves as documented when your agent is handed an absolute path outside that directory.

Frequently asked questions

Official sources

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