# Upsonic — Python Framework for Autonomous Agents

> Upsonic offers a Python-first path to autonomous and traditional agents, prebuilt agents, and MCP tools for fast internal pilots.

## Install

Save as a script file and run:

## Quick Use

1. Install from PyPI:
   ```bash
   uv pip install upsonic
   ```
2. Create a minimal autonomous agent:
   ```python
   from upsonic import AutonomousAgent, Task
   agent = AutonomousAgent(model="anthropic/claude-sonnet-4-5", workspace="/tmp/upsonic")
   agent.print_do(Task("Analyze server logs and detect anomaly patterns"))
   ```
3. Verify:
   - Confirm the task runs inside the declared workspace and does not escape it.

## Intro

Upsonic offers a Python-first path to autonomous and traditional agents, prebuilt agents, and MCP tools for fast internal pilots.

- **Best for:** Python teams that want a lightweight SDK for autonomous agents with guardrails
- **Works with:** Python, Anthropic/OpenAI-style models, workspace sandboxing, MCP tools, E2B sandbox providers
- **Setup time:** 10-20 minutes

## Practical Notes

- Quant: the README positions prebuilt autonomous agents as ready-to-run assets, shortening time to first useful run.
- Quant: path traversal and dangerous shell operations are explicitly blocked to the declared `workspace` boundary.

## Why it matters

Upsonic is not the biggest framework in the field, but it is useful because it pairs agent abstractions with practical guardrails rather than assuming a blank-slate runtime.

- The SDK shows both autonomous and traditional agent APIs, which is helpful when teams are not ready to go all-in on one execution style.
- Workspace-bound execution is a concrete safety feature, not a vague promise about future permissions.
- The docs point directly to MCP tools and sandbox providers, making external connectivity part of the normal upgrade path.

## Rollout pattern

- Start with one autonomous task that reads files or logs inside a disposable workspace.
- Adopt prebuilt agents only after you inspect the prompt, tools, and initial message they package.
- Add MCP tools and cloud sandboxes as separate steps so you can measure what each capability changes.

## Watchouts

Because the framework makes it easy to move fast, teams should still review prebuilt agents and external tools instead of treating them as trusted defaults.

### FAQ

**Q: Is it only for autonomous agents?**
A: No. The README shows both `AutonomousAgent` and traditional `Agent` flows.

**Q: What is the main built-in guardrail?**
A: Workspace-scoped file and shell operations with path-traversal and dangerous-command blocking.

**Q: What is a good first use case?**
A: Internal log analysis or structured triage in a disposable workspace with one model and no external tools.

## Source & Thanks

> Source: https://github.com/Upsonic/Upsonic
> License: MIT
> GitHub stars: 7,846 · forks: 733

---

<!-- ZH -->

## 快速使用

1. 从 PyPI 安装：
   ```bash
   uv pip install upsonic
   ```
2. 创建最小自主 Agent：
   ```python
   from upsonic import AutonomousAgent, Task
   agent = AutonomousAgent(model="anthropic/claude-sonnet-4-5", workspace="/tmp/upsonic")
   agent.print_do(Task("Analyze server logs and detect anomaly patterns"))
   ```
3. 验证：
   - 确认任务只在声明的 workspace 内运行，不会越界访问路径。

## 简介

Upsonic 提供 Python 优先的自主 Agent 与传统 Agent 代码路径，还内置社区预制 Agent 与 MCP 工具接入，适合想快速试点内部 Agent 工作流的工程团队。

- **适合谁：** 想用较轻量 SDK 试点自主 Agent 且需要基本护栏的 Python 团队
- **可搭配：** Python、Anthropic/OpenAI 风格模型、workspace 沙箱、MCP tools 与 E2B 等沙箱提供方
- **准备时间：** 10-20 分钟

## 实战建议

- 量化信息：README 把 prebuilt autonomous agents 当作即装即跑资产，可明显缩短首次可用时间。
- 量化信息：它明确限制文件和 shell 操作在声明的 `workspace` 内，并阻止危险越界操作。 

## 为什么值得收录

Upsonic 不是最大最重的框架，但它把 Agent 抽象和实际护栏一起给出来，这对内部试点很有价值。

- README 同时展示自主 Agent 和传统 Agent 两条 API 路径，方便团队逐步迁移而不是一次性重构。
- workspace 边界是明确的安全特性，不是模糊的“未来会支持权限控制”。
- 文档直接把 MCP tools 与沙箱提供方列为扩展路径，外部连接不是附属功能。

## 落地路径

- 先在一次性 workspace 里做 1 个读取日志或文件的自主任务试点。
- 在使用预制 Agent 前，先检查它打包了什么 prompt、工具和初始消息。
- MCP tools 与云沙箱分步骤接入，这样才能看清每一层带来的变化。 

## 注意事项

它让上手速度很快，但这并不代表你可以把预制 Agent 和外部工具默认视为可信资产。

### FAQ

**它只适合 autonomous agents 吗？**
答：不是。README 同时给出了 `AutonomousAgent` 和传统 `Agent` 的用法。

**最核心的内建护栏是什么？**
答：workspace 范围内的文件与 shell 操作限制，并阻止路径穿越和危险命令。

**第一批试点适合什么？**
答：适合做内部日志分析或结构化排障，先不用外部工具。

## 来源与感谢

> Source: https://github.com/Upsonic/Upsonic
> License: MIT
> GitHub stars: 7,846 · forks: 733


---
Source: https://tokrepo.com/en/workflows/upsonic-python-framework-for-autonomous-agents
Author: Agent Toolkit