Upsonic/Upsonic · 上手攻略

仓库：Upsonic/Upsonic
链接：https://github.com/Upsonic/Upsonic
分类：skill（Python AI Agent 框架）
作者：spark
更新：2026-07-15

是什么

Upsonic 是一个面向生产场景的 Python AI Agent 框架，强调「可靠性 / Reliability」。它同时提供两类抽象：

Agent：传统 tool-use 风格的代理，按下工具（函数 / MCP）去做单任务。
AutonomousAgent：类似 OpenClaw、Claude Cowork 那样的自治代理，能在受限沙盒里读写文件、跑 shell，适合「给我分析日志 / 处理 CSV」这种开放式任务。

配套能力还包括：

Prebuilt Agents（仓库 src/upsonic/prebuilt/）：社区贡献的开箱即用代理，自带技能 + system prompt + 首发消息。
MCP Tools：原生支持把任意 MCP 服务接进来。
Sandbox Provider：默认本地 workspace 沙盒，可挂 E2B 等云端隔离执行环境。
OCR 流水线：分层 OCR 接口（Layer 0 文档预处理 / Layer 1 OCR 引擎），支持 EasyOCR、RapidOCR、Tesseract、PaddleOCR、DeepSeek OCR、DeepSeek via Ollama。

最新 PyPI 版本：0.74.4（2026-04 发布），MIT 协议。

解决什么问题

「写完 prompt 不知道怎么落到生产」：很多框架停留在 demo 玩具，Upsonic 把模型调用、工具注册、沙盒隔离、结果回执做成统一接口。
自治代理的安全焦虑：用 AutonomousAgent(workspace=...) 显式限制文件 / shell 操作范围，path traversal 和危险命令默认拦截。
OCR 工程链路散乱：自己拼 PDF→图像→OCR→后处理很乱，OCR(layer_1_ocr_engine=engine).get_text(file) 一行调通。
工具扩展门槛高：除了 @tool 装饰器写函数，还能直接挂 MCP 服务，几千个现成工具复用。
不知道怎么起步：仓库自带 prebuilt/ 目录与官方 Quickstart，5 分钟拉一个能跑的代理。

快速安装

# 官方推荐 uv
uv pip install upsonic

# 或者
pip install upsonic

# 只装 OCR 子模块
pip install "upsonic[ocr]"

# 如需 MCP 客户端（一般不必单独装，框架已自带 client）
pip install "upsonic[mcp]"

环境变量（用 OpenAI 兼容协议时设一下）：

export OPENAI_API_KEY=sk-...
# 或者 Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

框架默认走 model="anthropic/claude-sonnet-4-5" 这种 provider/model 字符串（OpenRouter / LiteLLM 风格）。要切到原生 OpenAI，用 model="openai/gpt-4o" 等；想完全本地 Ollama，加 ollama pull 后用 model="ollama/llama3.1"。具体 provider 列表以官方文档为准。

核心用法（可直接复制）

1. 最小 Agent + 自定义工具

from upsonic import Agent, Task
from upsonic.tools import tool

@tool
def sum_tool(a: float, b: float) -> float:
    """Add two numbers together."""
    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)
print(result)

2. 自治代理 + workspace 沙盒

from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/logs",          # 所有读写只能在 /path/to/logs
)

task = Task("Analyze server logs and detect anomaly patterns")
agent.print_do(task)

所有文件 / shell 操作被限制在 workspace。路径穿越（../）和危险命令（rm -rf /、mkfs 等）默认拦截。要进一步隔离，可接 E2B 云沙盒。

3. 接 MCP 服务

from upsonic import Agent, Task
from upsonic.mcp import MCPServerStdio

# 任意 MCP server（stdio 协议）
mcp = MCPServerStdio(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
)

agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    name="Filesystem Agent",
    mcp_servers=[mcp],
)
agent.print_do(Task("List all .md files and summarize"))

4. Prebuilt 代理直接用

仓库 src/upsonic/prebuilt/ 收录了社区预置的代理，例如调研类、数据分析类。

# 假设 prebuilt 里有 "DeepResearchAgent"
from upsonic.prebuilt import DeepResearchAgent

agent = DeepResearchAgent(model="anthropic/claude-sonnet-4-5")
agent.print_do(Task("Survey the latest agent frameworks in 2026"))

每个 prebuilt 代理 = 一个 Agent 子类 + 内置 system prompt + 首条 user message，加载即可。

5. 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)

要中文识别：

from upsonic.ocr.layer_1.engines import PaddleOCREngine
ocr = OCR(layer_1_ocr_engine=PaddleOCREngine(lang="ch"))
text = ocr.get_text("扫描件.pdf")

要 DeepSeek-OCR / DeepSeek-via-Ollama 等大模型路线，直接换 engine 即可。

6. IDE 文档索引（Cursor / Windsurf / VSCode）

Upsonic 把整站文档导出成 https://docs.upsonic.ai/llms-full.txt，Cursor 在 Settings → Indexing & Docs 里加这个 URL，你的 IDE 就能在写代码时引用框架 API。

典型适用场景

企业里把 LLM 能力塞进生产流水线：需要沙盒、可观测、可回滚，Upsonic 的 AutonomousAgent + workspace 就是为这个设计的。
客服 / 文档处理类 agent：接 MCP 拉内部 API + 调 OCR 处理附件，一条 Task 拉通。
批量研究 / 报告生成：用 Prebuilt 里的 DeepResearchAgent 之类，或自建一个长上下文代理。
替代 n8n / Coze / Dify 这类工具的代码侧：团队不愿上可视化平台但又要拿现成工具时，Upsonic 是「代码版 Coze」。
OCR 替代方案：发票 / 合同 / 扫描件批量文字化，支持中英混排。

坑与注意

0.x 版本，API 仍在演进。Task / Agent 的参数在 0.74.x 之间偶有破坏性更新，老代码贴新库可能 TypeError，以官方 changelog 为准。
模型路由字符串。model="anthropic/claude-sonnet-4-5" 是约定式协议字符串，框架会把它转给底层 LiteLLM 风格的客户端；不是所有 provider 都自动配齐 API Key，记得自己 export 环境变量。
workspace 沙盒 ≠ 完整安全。AutonomousAgent 拦截的是「文件系统 + shell」两类操作，对网络（HTTP 外发）默认放行——要做严格隔离要上 E2B。
OCR 引擎依赖重。装 upsonic[ocr] 会拖 PaddleOCR / DeepSeek 模型；Docker 部署时镜像会变大，按需选引擎。
Prebuilt 是社区贡献。质量参差，正式上生产要审代码；开源协议一致（MIT），可二次改。
MCP server 必须装好。MCPServerStdio(command="npx", ...) 这种调用假设你机器上有 npx 与 npm 包，CI 里要补 Node 环境。
错误处理：框架默认走 print_do()，失败会 raise；要拿到原始 response 用 agent.do(task)。

与同类对比

框架	抽象层级	自治代理	MCP 原生	OCR	上手难度	适合
Upsonic	Agent + AutonomousAgent 双层	✅ workspace 沙盒	✅	✅ 分层流水线	中	想直接出活的工程团队
LangGraph	状态图 / Graph	自己拼	间接	无	高	复杂可控的多步工作流
LangChain	链式 / Runnable	自己拼	✅	无	低	快速原型 / 最大生态
CrewAI	多角色协作	角色化	间接	无	低	多代理协作 demo
LlamaIndex	RAG / 数据	自己拼	✅	无	中	检索 / 文档问答
PydanticAI	类型安全	自己拼	✅	无	中	强类型输出 / 后端集成
OpenAI Agents SDK	OpenAI 原生	✅	✅	无	低	锁 OpenAI 工具链

Upsonic 的差异化是「自治代理 + 沙盒 + MCP + OCR」打包：单仓库内同时搞定「写代理」「管工具」「防误操作」「读文档」四件事，免去拼四五个库的麻烦。

一句话推荐结论

「代码版的 Coze + 自带 OCR」：如果你不想搭 LangGraph 又想要生产级的自治代理 + MCP + OCR 一站式体验，Upsonic 是值得一试的工程框架；前提是能接受 0.x API 变动节奏，并愿意在沙盒 / 模型路由上自己把一道关。