一文读懂a13n核心概念:Agent、Thread、Run与Session的完整关系图
一文读懂a13n核心概念:Agent、Thread、Run与Session的完整关系图
a13n(Agent Foundation)是一个开源的 AI Agent 运行时平台,让你在自己的基础设施上构建、运行和管理 Agent。很多新手第一次接触 a13n 时,最容易被 Agent、Thread、Run、Session 这四个核心概念绕晕:它们到底是什么?彼此之间是什么关系?为什么消息发出去后要关注 Run 状态?这篇文章用一张关系图 + 控制台真实截图,带你 10 分钟完全搞懂 a13n 核心概念。
1️⃣ 先看全局:a13n 如何把一条消息变成一次执行
理解四个核心概念之前,先记住 a13n 的一条主线:
你在 Console 或应用里发出一条消息 → Service 把它持久化 → Worker 领取并执行一个 Run → 执行中断后可从检查点(Checkpoint)自动恢复。
这就是 a13n 的核心卖点:持久化执行(Durable Execution)。即使客户端断开、Worker 崩溃,Agent 的工作也不会丢失。上面这张架构图里,PostgreSQL 保存 Threads、Runs 和执行租约,Worker 通过 Harness 调用模型、工具和沙箱环境。
2️⃣ Agent:定义"它会怎么干活"的配置包
Agent 不是一个进程,而是一份配置,它告诉模型:用什么模型、遵循什么指令、能调用哪些工具、挂载哪些环境和记忆。在上图的控制台里,你可以看到每个 Agent 及其绑定的模型(如 Claude Opus 5、GPT-5.6)和启用状态。
Agent 配置中常见的组成部分:
| 组成部分 | 作用 |
|---|---|
| 模型(Model) | 理解请求并生成回复或工具调用 |
| 工具(Tool) | 查任务、读文件、执行命令等 |
| 连接(Connection) | 通过 MCP 或应用账号访问外部工具 |
| 环境(Environment) | 为工具提供文件与命令执行能力 |
| 记忆(Memory) | 跨对话保存和检索项目决策 |
一个容易忽略的细节:每次修改 Agent 配置,都会生成一个不可变的修订版本(Revision)。新的对话默认使用最新版本,而已在执行的 Run 会沿用它开始时锁定的版本——这保证了执行过程中配置不会被"偷偷换掉"。
3️⃣ Session 与 Thread:会话与对话线程的层级关系
这是新手最容易混淆的一对概念,记住一句话即可:
- Session(会话):一组相关 Thread 的容器,相当于 Console 里的"一次对话项目"。
- Thread(线程):一条独立推进的对话历史,拥有自己的收件箱(Inbox)和环境/记忆挂载。
层级关系可以记成:Session ⊃ Thread ⊃ Run。
两个进阶玩法也建立在这对概念上:
- 子线程(Child Thread):Agent 委派子任务时,会在同一 Session 下自动创建子 Thread 异步执行,结果完成后回传给父线程。
- 分叉(Fork):从某个已结束的 Run 分叉出一个新 Thread,探索另一个方向,而原线程历史保持不变。
4️⃣ Run 与 Attempt:一条消息如何变成一次运行
**Run(运行)**是线程历史上的一次"前进":一条被接受的消息 + 一个锁定的 Agent 修订版本,就构成一个 Run。上图展示的是一个 Run 的完整细节视图——每次模型调用、每次工具调用(如 view、shell_exec、write)、Token 消耗和耗时都一目了然。
而 **Attempt(执行尝试)**则是 Run 的实际执行过程:
一个 Run 可能有多个 Attempt。Worker A 执行到一半崩溃了,租约(Lease)过期后,Worker B 会领取同一个 Run,从最近的 Checkpoint 继续执行——而不是从头再来。
也就是说:Run 是"做什么",Attempt 是"第几次做"。恢复机制不会创建新的 Run,所以你不用担心一次故障产生多个重复的对话轮次。
5️⃣ 完整关系图:一张表记住全部
| 概念 | 一句话理解 | 生命周期特点 |
|---|---|---|
| Agent | 定义 Agent 行为的配置 | 可修改,每次修改生成不可变 Revision |
| Session | 一组相关 Thread 的分组 | 长期存在,代表一个对话项目 |
| Thread | 一条独立推进的对话历史 + 收件箱 | 按消息顺序推进,可 Fork、可归档 |
| Run | 一次被接受的输入处理 | 状态流转:accepted → running → completed / waiting / failed |
| Attempt | Run 的一次实际执行 | 故障后自动换 Worker 恢复,无需人工干预 |
用一条链串起来:
Agent(配置好)→ 在 Session 中创建 Thread → 发送消息触发 Run → Worker 以 Attempt 执行,中断可从 Checkpoint 恢复。
当 Run 需要人做决定时(比如审批一次危险工具调用、回答 Agent 的提问),它会进入 waiting 状态,等待你提交完整的回应批次后,由一个"后继 Run"继续工作。
6️⃣ 新手常见疑问 FAQ
Q1:客户端断开了,Agent 还会继续干活吗? 会。a13n 的设计原则就是"长时任务不依赖连接",执行状态保存在服务端,断开只是断开"观看"。
Q2:想继续昨天的对话,该找哪个 ID? 找 Thread ID。对话历史保存在 Thread 上;跨对话共享的知识应挂载 Memory;工作文件则存在 Environment 中。
Q3:Run 失败了怎么办? 失败或被取消的 Run 就是线程历史的一部分。你再发一条新消息,下一个 Run 会从最后的 Checkpoint 继续;如果失败是历史内容本身导致的(比如模型拒绝某段上下文),可以从更早的 Run 分叉重来。
7️⃣ 下一步:去哪里看官方资料
掌握了核心概念后,建议按下面的路径深入:
- 核心概念入门(官方文档):docs/a13n-service/core-concepts.md
- Agent、Thread 与 Run 的完整操作指南:docs/a13n-service/agents-and-runs.md
- Run 生命周期的设计规范(进阶阅读):spec/a13n-service/05-runs.md
- 每个术语的权威定义:spec/a13n-service/glossary.md
- Service 整体架构与概念总览:spec/a13n-service/00-overview.md
一句话总结:Agent 定义"会做什么",Session 和 Thread 管理"和谁在聊",Run 记录"做了哪一步",Attempt 保证"这一步做不完也能接着做"。把这四件事分清,你就读懂了 a13n 的核心。



