---

概述

Upsonic是一个开源的AI智能体框架，用于构建生产就绪的智能体。它支持多家AI服务提供商（OpenAI、Anthropic、Azure、Bedrock），并内置了安全策略、OCR、记忆功能、多智能体协作以及MCP工具集成。

你能构建什么？

• 文档分析：从图片和PDF中提取并处理文本
• 客户服务自动化：具备记忆和会话上下文的智能体
• 财务分析：能够分析数据、生成报告并提供洞察的智能体
• 合规性监控：在所有智能体交互中强制执行安全策略
• 研究与数据收集：通过多智能体协作自动化研究流程
• 多智能体工作流：协调专业智能体团队之间的任务

快速开始

安装

uv pip install upsonic
# pip install upsonic

基本智能体

from upsonic import Agent, Task

agent = Agent(model="anthropic/claude-sonnet-4-5", name="股票分析师智能体")

task = Task(description="分析当前市场趋势")

agent.print_do(task)

带工具的智能体

from upsonic import Agent, Task
from upsonic.tools.common_tools import YFinanceTools

agent = Agent(model="anthropic/claude-sonnet-4-5", name="股票分析师智能体")

task = Task(
    description="给我一份关于特斯拉股票及特斯拉车型的摘要",
    tools=[YFinanceTools()]
)

agent.print_do(task)

带记忆功能的智能体

from upsonic import Agent, Task
from upsonic.storage import Memory, InMemoryStorage

memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_001",
    full_session_memory=True
)

agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

task1 = Task(description="我的名字是John")
agent.print_do(task1)

task2 = Task(description="我叫什么名字？")
agent.print_do(task2)  # 智能体会记住："你的名字是John"

想了解更多吗？ 请查看快速入门指南，其中包含更多示例，如知识库和团队工作流。

核心特性

• 自主智能体：能够在沙盒化的工作空间内读取、写入并执行代码的智能体，无需设置工具
• 安全引擎：基于策略的内容过滤，应用于用户输入、智能体输出以及工具交互
• OCR支持：统一的接口支持多种OCR引擎，并可处理PDF和图像
• 内存管理：会话内存和长期存储，支持多种后端选项
• 多智能体团队：顺序和并行的智能体协调
• 工具集成：MCP工具、自定义工具以及人机协作工作流
• 生产就绪：监控、指标和企业级部署支持

核心能力

自主智能体

AutonomousAgent扩展了Agent类，内置了文件系统和Shell工具、自动会话内存以及工作空间沙盒化功能。适用于编码助手、DevOps自动化以及任何需要直接访问文件或终端的任务。

from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/project"
)

task = Task("读取main.py文件，并为每个函数添加错误处理")
agent.print_do(task)

所有文件和Shell操作都被限制在workspace目录内。路径遍历和危险命令将被阻止。

---

安全引擎

安全引擎在三个环节应用策略：用户输入、智能体输出以及工具交互。这些策略可以对匹配的内容进行拦截、匿名化、替换或抛出异常。

from upsonic import Agent, Task
from upsonic.safety_engine.policies.pii_policies import PIIAnonymizePolicy

agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    user_policy=PIIAnonymizePolicy,  // 在发送给LLM之前匿名化PII
)

task = Task(
    description="我的邮箱是john.doe@example.com，电话是555-1234。请问我的邮箱和电话是多少？"
)

# PII在到达LLM之前会被匿名化，然后在响应中解匿名
result = agent.do(task)
print(result)  // "您的邮箱是john.doe@example.com，电话是555-1234"

预置策略涵盖PII、成人内容、脏话、金融数据等。同时也支持自定义策略。

了解更多信息：安全引擎文档

---

OCR与文档处理

Upsonic提供了一个统一的OCR接口，采用分层管道设计：第0层负责文档准备（PDF转图像、预处理），第1层运行OCR引擎。

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")
print(text)

支持的引擎包括：EasyOCR、RapidOCR、Tesseract、PaddleOCR、DeepSeek OCR以及通过Ollama调用的DeepSeek OCR。

了解更多信息：OCR文档

Upsonic AgentOS

AgentOS是一个可选的部署平台，用于在生产环境中运行智能体。它提供了基于Kubernetes的运行时、指标仪表盘以及自托管部署功能。

• 基于Kubernetes的FastAPI运行时：将智能体部署为隔离且可扩展的微服务
• 指标仪表盘：跟踪LLM成本、token使用情况以及每笔交易的性能
• 自托管：完全掌控您的数据和基础设施
• 一键部署：自动化部署流水线

IDE 集成

在您的编码工具中添加 Upsonic 文档作为源：

Cursor： 设置 → 索引与文档 → 添加 https://docs.upsonic.ai/llms-full.txt

同样适用于 VSCode、Windsurf 及其他类似工具。

文档与资源

• 文档 - 完整指南和 API 参考
• 快速入门指南 - 5 分钟内开始使用
• 示例 - 实际应用示例和用例
• API 参考 - 详细的 API 文档

社区与支持

💬 加入我们的 Discord 社区！ — 提问、分享您的项目、获得团队帮助，并与其他使用 Upsonic 的开发者交流。

• Discord - 与社区聊天并获取实时支持
• 问题跟踪器 - 报告错误和请求功能
• 更新日志 - 查看每次发布的新内容

许可证

Upsonic 采用 MIT 许可证发布。详情请参阅 LICENCE。

贡献

我们欢迎社区的贡献！请在提交拉取请求前阅读我们的贡献指南和行为准则。

---

访问 upsonic.ai 了解更多

Upsonic 快速上手指南

Upsonic 是一个面向生产环境的开源 AI Agent 框架，主打“安全优先”。它支持多种大模型提供商（OpenAI, Anthropic, Azure, Bedrock），内置安全策略、OCR 识别、记忆管理、多智能体协作以及 MCP 工具集成。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.9 或更高版本
• 前置依赖：
  • 推荐安装 uv (高性能 Python 包管理器) 以加速安装过程。
  • 若未安装 uv，可使用标准 pip。
• API Key：需准备对应大模型服务商的 API Key（如 Anthropic, OpenAI 等），并通过环境变量配置（例如 export ANTHROPIC_API_KEY=your_key）。

国内开发者提示：如遇网络连接问题，建议配置国内镜像源加速安装。

• 使用 uv 时：uv pip install upsonic --index-url https://pypi.tuna.tsinghua.edu.cn/simple
• 使用 pip 时：pip install upsonic -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

推荐使用 uv 进行安装，以获得更快的解析和下载速度：

uv pip install upsonic
# 或者使用标准 pip
# pip install upsonic

若需要使用 OCR 功能（文档分析），请安装额外依赖：

uv pip install "upsonic[ocr]"

基本使用

1. 创建基础 Agent

最简单的用法是实例化一个 Agent 并分配任务。以下示例使用 Anthropic 模型分析市场趋势：

from upsonic import Agent, Task

# 初始化 Agent，指定模型和名称
agent = Agent(model="anthropic/claude-sonnet-4-5", name="Stock Analyst Agent")

# 定义任务
task = Task(description="Analyze the current market trends")

# 执行任务并打印结果
agent.print_do(task)

2. 使用工具增强 Agent

Upsonic 支持直接挂载工具。以下示例让 Agent 调用金融数据工具来分析特斯拉股票：

from upsonic import Agent, Task
from upsonic.tools.common_tools import YFinanceTools

agent = Agent(model="anthropic/claude-sonnet-4-5", name="Stock Analyst Agent")

task = Task(
    description="Give me a summary about tesla stock with tesla car models",
    tools=[YFinanceTools()]  # 挂载金融工具
)

agent.print_do(task)

3. 赋予 Agent 记忆能力

通过配置 Memory 模块，Agent 可以在会话中记住上下文信息：

from upsonic import Agent, Task
from upsonic.storage import Memory, InMemoryStorage

# 配置内存存储
memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_001",
    full_session_memory=True
)

# 将内存绑定到 Agent
agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

# 第一轮对话：告知名字
task1 = Task(description="My name is John")
agent.print_do(task1)

# 第二轮对话：询问名字（Agent 将能回忆起上一轮内容）
task2 = Task(description="What is my name?")
agent.print_do(task2)  # 输出: "Your name is John"

4. 高级特性：自主代理 (Autonomous Agent)

对于需要操作文件系统或执行代码的场景，可使用 AutonomousAgent。它在沙箱环境中运行，自动具备文件读写和 Shell 执行能力：

from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/project"  # 限制操作范围在此目录
)

task = Task("Read the main.py file and add error handling to every function")
agent.print_do(task)

---

更多详细用法（如多智能体团队协作、安全策略定制、知识库集成等），请访问 官方文档。