Upsonic AI Agent项目学习心得

Upsonic AI Agent框架学习心得与流程解析

先说说这次学习的几个核心判断：Upsonic 在降低 AI Agent 搭建门槛这件事上，做得相当出色。它的代码结构清晰直观，对于想要快速入门 Agent 开发的人来说，是一个很不错的切入点。下面就把学习过程中的一些关键收获梳理出来。

学习目标

掌握 Upsonic 的主要流程。

学习内容

Upsonic 项目的主要源代码。

学习时间

2025-03-15 10:00-15:00

学习产出

一份相对完整的心得总结。

---

心得总结如下

Upsonic 极大地降低了搭建 AI Agent 的使用门槛，其优秀的代码结构直观易懂，对理解 Agent 相关知识、运行流程帮助很大。

1. 整体架构

Upsonic 提供的是一个面向企业级的框架，核心思路是用简洁的方式编排 LLM 调用、Agent 和计算机操作，从而高效完成任务。它的主要优势在于：更可靠的 Agent、更好的可扩展性，以及一个任务导向的结构——这些特性在真实业务场景中非常实用。

2. AI Agent 执行主要流程

用通俗的语言讲一遍流程：

• 首先创建一个 Graph，这个 Graph 由 TaskChain（任务链）、TaskNode（任务节点）、决策节点（DecisionLLM 或 DecisionFunc）以及运行状态 State 组成。
• 然后按照顺序执行 Graph，把待执行的节点放到一个执行队列（execution_queue）中。
• 每次执行时从队列头部弹出一个节点，根据节点类型做不同处理：如果是 TaskNode，就直接执行任务，把结果保存到运行状态中；如果是 DecisionLLM，就生成决策提示词并调用大模型，让大模型决定走哪个分支；如果是 DecisionFunc，则在本地执行函数，根据执行结果决定走哪个分支。根据分支类型，把对应的 TaskNode、TaskChain 中的 TaskNode、另一个 DecisionLLM 或 DecisionFunc 插入到队列头部。

TaskNode 执行流程

进一步拆解 TaskNode 内部：

• 根据任务配置的 Agent、Graph 默认 Agent 或已运行节点的 Agent 获取一个 runner。
• runner 分为 Direct 和 AgentConfiguration 两种，都需要通过 get_or_create_client 方法获取 UpsonicClient。Direct 类型获取的是 level one 的 Call client，而 AgentConfiguration 获取的是 Agent client 或 MultiAgent client。
• 拿到 UpsonicClient 后，直接调用 call 方法就能拿到返回结果。
• 最后通过 ReliabilityProcessor 对结果进行二次处理，提高准确性。

给出的准确性指标如下：

Client call 执行流程

这是整体发起 HTTP 调用的完整链路：

• Client 发起 HTTP 请求到 Level One Server 或 Level Two Server。
• Upsonic Server 根据请求参数（llm_model、tools、prompt、system_prompt 等）统一调用 agent_creator 来创建 Pydantic Agent。创建时会根据 llm_model 选择对应的模型类型（比如 OpenAiModel、AnthropicModel、AsyncAnthropicBedrock）。如果传了 tools 参数，则会发起 HTTP 请求到 tool server，拿到 tools 列表并进行名称匹配，匹配到的 tool 会生成动态函数并包装成 Callable，最后通过 Pydantic tool plain 传入 Agent。当 Pydantic AI 需要调用 tool 时，就会调用这个 Callable 函数，间接通过 HTTP 调用 tool server。
• 获取到 Pydantic Agent 后直接调用 run 得到结果，再对结果进行拆封装成 UpsonicClient 需要的格式。

---

写在最后

现在各种 AI Agent 框架层出不穷、五花八门，但底层原理其实并不是特别复杂的技术，本质上还是一些 API 的封装和编排。不用刻意把每种 Agent 框架都用一遍，只需要把一个 Agent 框架的执行过程吃透就够了。通过对 Upsonic 项目的学习，对 Agent 的认知又加深了一层。可以预见，今后工作中 Agent 的应用场景会越来越多。