Upsonic 快速上手：用 Python 构建自主 AI 智能体的完整指南-育师

Upsonic 快速上手：用 Python 构建自主 AI 智能体的完整指南

【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant

每天早上花 40 分钟拼一份市场简报，在新闻站、行情页和 PDF 研报之间来回切换？Upsonic 是一个 Python AI 智能体框架，把大模型包装成能查数据、调工具、处理文件的“数字员工”，还能组队协作。看完这篇，你会用 5 分钟跑通第一个智能体，并掌握“数据获取 → 处理 → 分析 → 输出”的完整工作流。

场景：每天 40 分钟的市场简报，能自动化吗

先说一个真实处境。某基金公司的运营同学，每天早上要做的动作固定不变：查两个网站看隔夜外盘新闻，打开行情页记录五只指数收盘价，翻 30 页研报挑三条要点，写一段 200 字简报发到工作群。每天 40 分钟，重复、机械、容易漏。

问题不在数据找不到，而在每一步都靠人肉完成：取数、整理、成文、交付。如果把中间这个“人”换成一个 AI 智能体——给它一句任务“生成今日市场简报”，它自己查数据、调接口、写总结——这套流程就活了。Upsonic 的定位正是如此：你用代码告诉模型“做什么”，工具调用、记忆、协作这些事由框架接管。

能力拆解：四个模块各管一件事

Agent + Task：把任务说清楚，剩下交给框架

框架最基本的单元。Agent是配置好的“数字员工”（指定模型、起名字、挂工具），Task是一张工单（一句话描述要做什么）。调用agent.print_do(task)后开始执行，推理和工具调用过程会实时打印在终端，多步推理的循环不用你手写。

@tool 装饰器：一个函数变成模型可调用的工具

只会聊天的模型干不了活。Upsonic 用@tool装饰器把任意 Python 函数包装成模型能调用的工具，函数签名和 docstring 就是工具的说明书。仓库还内置了一批现成工具，包括金融数据工具 YFinanceTools 和多个联网搜索工具，清单见 src/upsonic/tools/common_tools/。

AutonomousAgent：能动手读文件、跑命令的自主智能体

比普通 Agent 多一层动手能力。指定一个 workspace 目录后，智能体可以在其中读写文件、执行 shell 命令，框架会拦截路径穿越和危险命令，越权操作出不去这个沙箱。扫描版研报、散落一地的日志这类非结构化材料可以整目录丢给它，PDF 文字提取也有内置 OCR 模块可选。

Team：多个智能体分工协作

任务复杂时，把流程拆给几个智能体再交给Team。它提供三种协作模式：sequential按顺序接力、coordinate由领导者智能体统一分派、route由路由器把任务分给最合适的成员。成员还可以是另一个 Team，天然支持多层级流水线。

五分钟跑通第一个智能体

先安装，要求 Python 3.10 以上：

uv pip install upsonic

把模型 API 密钥放进运行目录下的.env文件（OpenAI、Anthropic 等多平台均支持），框架启动时会自动读取。然后运行第一个智能体：

from upsonic import Agent, Task agent = Agent(model="anthropic/claude-sonnet-4-5", name="市场简报助手") task = Task(description="总结今日A股三大指数表现，输出200字以内要点") agent.print_do(task)

终端开始滚动输出推理过程和最终简报，就算跑通了。

工作流：从数据获取到报告输出

第一步：接入数据源，把行情接口包成工具

做什么：让模型能“查你自己的系统”。为什么：模型不知道今天收盘价是多少，这是它唯一补不齐的信息。怎么做：把内部行情接口用@tool包一层，挂到任务上即可。

@tool def get_index_close(symbol: str) -> float: """查询指定指数今日收盘价""" return quotes_api.query_close(symbol)

第二步：加工数据，让智能体自己算

做什么：把原始数据交给智能体做对比和计算。为什么：涨跌幅、环比这类手算步骤最容易出错。怎么做：在任务描述里直接写“与昨日对比并计算涨跌幅”，智能体会自己决定何时调工具、取数后自己算完。

第三步：挂上记忆，让分析支持追问

做什么：给智能体加一个记忆模块。为什么：追问“昨天大跌的原因”时，它得记得前面的上下文。怎么做：创建 Agent 时传memory参数，存储可选手动内存或 SQLite；知识量再大，用内置的 KnowledgeBase 做检索增强问答，把研报库变成它的长期记忆。

第四步：固定格式输出报告

做什么：最后一步按固定结构产出简报。为什么：简报要发群、要存档，格式乱套没法用。怎么做：Task支持指定结构化输出（如 Pydantic 模型），智能体交付前会按格式自检，字段缺失会自己补。

进阶：把单点能力拼成流水线

多智能体分工接力。活量一大，单个智能体就忙不过来了。分别定义数据、分析、写作三个智能体，用Team以sequential模式串起来，每个只干自己擅长的事，最终产出明显好于一个智能体从头干到尾：

team = Team(name="简报团队", entities=[data_a, analyst_a, writer_a], mode="sequential") team.print_do(Task(description="生成今日市场简报"))

扫描版研报交给 AutonomousAgent。研报是扫描 PDF 时，可以先用 OCR 模块提文字，也可以把整个目录直接交给 AutonomousAgent，让它在沙箱里自己解析、摘录、归档。输出敏感场景下，src/upsonic/safety_engine/ 里的安全引擎可以做内容合规检查。

从现成智能体起步。仓库自带一组预构建自主智能体（如 applied_scientist），提示词、技能包和开场指令都配好了，装完就能跑，看懂行为后再按需改造复用，列表见 prebuilt_autonomous_agents/。