Upsonic Agent Framework
A Python framework for autonomous and task-based agents with workspace-bounded execution, callable functions, MCP integration, and optional OCR.
Per-dimension scores and reasoning
Evidence shows: README claims all file and shell operations are restricted to workspace, blocking path traversal and dangerous commands, but no implementation details or tests prove this. SECURITY.md provides responsible disclosure process, but no mention of least privilege or user confirmation. Dependencies include sentry-sdk (telemetry) and opentelemetry, but conftest.py forces telemetry off, suggesting default may be on. No user confirmation mechanism found. Data flow transparency limited, no explanation of how data is processed or transmitted. Sensitive data handling not explicit. Dependencies mostly use range versions, posing supply chain risk. External effects: tools like web_search may make external calls, but not explicitly restricted. Rollback mechanism not mentioned. Source attribution: author info in pyproject.toml, but publisher unverified. Deductions: lack of user confirmation, insufficient data flow transparency, unclear sensitive data handling, wide dependency version ranges, external effects not explicitly limited, no rollback.
Evidence shows: CI workflow (.github/workflows/ci.yml) runs unit tests on Python 3.10-3.12, indicating some consistency. Many dependencies but no lock file, dependency availability risk. Failure messages: test hook handles DisallowedOperation, but production failure messages not assessed. Deductions: dependencies not pinned, failure messages not fully demonstrated.
Evidence shows: README demonstrates multiple use cases (autonomous agents, traditional agents, OCR), audience clearly Python developers. Capability boundaries: workspace restriction declared, but not detailed. Trigger precision: tool definitions have docstrings, but no precise trigger mechanism shown. Environment fit: supports multiple Python versions and optional dependencies, but no specific environment requirements. Deductions: trigger precision evidence insufficient, environment fit details limited.
Evidence shows: README structure clear, includes installation, quick start, documentation links. Install notes explicit (uv pip install upsonic). Naming stability: version 0.77.3, but no changelog. Examples and FAQ: multiple example code snippets. Known limitations not explicitly listed. License MIT in README and pyproject.toml. Versioning: pyproject.toml version, but no CHANGELOG. Maintenance responsibility: authors and community links present. Deductions: missing changelog and known limitations.
Evidence shows: Output usability: examples show how to get results (print_do), but output format not specified. Marginal value: provides multiple features (autonomous agents, OCR, tool integration), differentiated. Cost-benefit: no performance or cost data. Deductions: output format not explicit, cost-benefit no evidence.
Evidence shows: README claims (e.g., workspace restriction) not verified in code, but test files exist (tests/_pipeline_injection.py) indicating tests. Cross-source corroboration: documentation links exist but not verified. Fact-inference separation: README claims are assertions, not distinguishing fact and inference. Deductions: claims lack code verification, cross-source corroboration insufficient.
- Dependency version ranges are wide; consider pinning versions to reduce supply chain risk.
- Telemetry may be enabled by default; verify data privacy.
- Workspace restriction claim not verified in code; review implementation.
- Lack of user confirmation mechanism; autonomous agents may perform unintended actions.
What does this agent do, and when should you use it?
Upsonic is a Python framework for building autonomous agents in the style of OpenClaw and Claude Cowork, as well as traditional agent systems. Its documented interfaces include `AutonomousAgent`, `Agent`, and `Task`, with a model identifier supplied at initialization. Autonomous-agent file and shell operations are restricted to a specified `workspace`; the README says path traversal and dangerous commands are blocked. Traditional tasks can receive Python functions declared with `@tool`, and the project documents MCP Tools as an integration path. It also exposes a layered OCR interface in which Layer 0 prepares documents and Layer 1 runs an OCR engine, with several listed engine options.
A developer creates an AutonomousAgent(model=..., workspace=...) and a Task, then invokes agent.print_do(task) for work such as analyzing server logs and detecting anomaly patterns; associated file and shell operations are bounded by workspace. For a traditional flow, the developer creates an Agent, puts a description and optional tools into Task, and calls agent.print_do(task); the documented @tool example adds two floating-point values. For OCR, OCR(layer_1_ocr_engine=EasyOCREngine(...)) configures an engine, and ocr.get_text("invoice.pdf") returns text from a document.
- An operations or engineering team wants an autonomous agent to inspect server logs and identify anomaly patterns within a designated workspace.
- A Python developer needs a named traditional agent for a natural-language task such as analyzing current market trends.
- An application team wants to expose an existing Python calculation or business function to a task through the
@tooldecorator. - A team connecting agents to external data sources and services wants to follow the documented MCP Tools integration path.
- A document-processing project needs to extract text from invoices or similar files by installing the OCR extra and configuring
EasyOCREngine.
What are this agent's strengths and limitations?
- It documents a
workspaceboundary for autonomous-agent file and shell operations, including blocking of path traversal and dangerous commands. - It provides both
AutonomousAgentandAgent, covering autonomous execution and a more conventional task-oriented agent interface. - Tasks can carry Python functions declared with
@tool, and MCP Tools are documented as an integration path. - It includes a unified layered OCR abstraction and explicitly lists EasyOCR, RapidOCR, Tesseract, PaddleOCR, and DeepSeek-related engines.
- The examples only show
anthropic/claude-sonnet-4-5; the supplied material does not document configuration or compatibility for other model providers. - The supplied material does not specify model credentials, environment variables, cost, or request-failure handling.
- The workspace boundary is explicitly described for file and shell operations, but permissions, authentication, and network boundaries for external MCP services are not described.
- An isolated cloud environment is presented as a next step requiring connection to an E2B Sandbox Provider, rather than as a documented out-of-the-box deployment procedure.
How do you install or deploy this agent?
Install the base package with uv pip install upsonic. Install OCR support with uv pip install "upsonic[ocr]". The documented model examples use model="anthropic/claude-sonnet-4-5", but the supplied material does not specify credentials, environment variables, or authentication setup.
How do you use this agent?
For a minimal autonomous invocation, import AutonomousAgent and Task; create AutonomousAgent(model="anthropic/claude-sonnet-4-5", workspace="/path/to/logs"); then call agent.print_do(Task("Analyze server logs and detect anomaly patterns")). For a traditional agent, import Agent, Task, create Agent(model="anthropic/claude-sonnet-4-5", name="Stock Analyst Agent"), and call agent.print_do(Task(description="Analyze the current market trends")).
How does this agent compare with similar options?
The README positions Upsonic as a framework for building autonomous agents like OpenClaw and Claude Cowork, while also supporting traditional agent systems. The supplied material does not provide a feature comparison or compatibility claim among them.
FAQ
Does it need local file-system or shell access?
workspace supplied at initialization. The README says path traversal and dangerous commands are blocked.Can I expose my own Python functions to a task?
@tool in Task(tools=[...]); the README demonstrates this with a sum function.