9.9 KiB
13. Agent
agent 是与 class、function 并列、可归属于 namespace 的语言资源声明。它为共有的变量、函数和其他合法结构建立 agent 内部作用域，并将这些成员与模型驱动的执行、工具使用、记忆、状态和控制流关联起来。
agent 的语言地位和本章各项职责已经确定；声明骨架及成员关联的具体写法仍是设计稿，见规范状态。这些能力由语言与平台共同提供，不以安装某个宿主语言的 Agent 包作为声明前提。
13.1 声明、成员与作用域
agent 声明拥有名称和 namespace 归属。内部使用 Endorphin 共有的变量、函数、class 和其他允许的声明或表达式；每种结构仍遵守自身的语法位置与类型规则。允许共有结构不表示可以在任意位置直接使用 return 等语句。
基本结构示意，不是可执行源码：
agent 名称 {
成员变量与资源引用
成员函数
成员类型或其他合法声明
工具、记忆、状态及控制规则的关联
}
同一个 function 定义在 agent 内部时仍是函数；区别在于它的名称查找、可见范围以及与所属 agent 实例的关联。变量同样保留引用资源的语义，但实例成员需要明确状态归属和存续范围。内部作用域与 namespace 路径及成员定位的对应关系仍待定义。
成员可以服务于普通计算、工具实现、状态迁移或上下文处理。哪些成员函数向模型暴露为工具，以及是否存在默认暴露规则，仍需定义；声明骨架本身不决定这个范围。成员可见性、实例成员与共享成员的区分、嵌套声明和接收者引用形式也需明确。
Agent 的输入与结果需要类型契约，可以通过入口或成员函数表达，具体形式待定；声明体不预设固定的 input、output、instructions、environment 字段表。模型配置和行为指令可以参与声明，但不替代工具及运行控制语义。
13.2 运行职责
| 职责 | 使用的共有资源或结构 | agent 内部需要建立的关系 |
|---|---|---|
| tools | 外部函数引用或内部成员函数 | 哪些函数向模型提供工具能力，以及怎样调用它们 |
| memory | 记忆内容、读写函数及保存策略 | 内容如何保留、检索，以及运行状态如何保存和恢复 |
| state | 类型化变量与数据结构 | 当前业务状态、执行位置及允许的迁移 |
| 控制流与路由 | 函数、条件逻辑及节点关联 | 下一步执行工具、继续模型计算、等待输入或终止 |
| 人工在环 | 待执行操作、暂停状态及人类输入 | 哪些操作需要确认，以及确认后如何恢复 |
| 上下文管理 | 文本、资源引用及处理函数 | 每次模型调用前如何选择、裁剪或总结输入 |
这些名称首先表示职责，不自动成为保留字、固定字段或新的资源类型。职责如何通过普通成员和语言关联结构表达，需与完整文法一起确定；本章不规定全部职责必须以同一种声明形式出现。
13.3 Tools 与逻辑实现
工具以函数为基础。agent 可以引用其他 namespace 中获准使用的函数，也可以在内部实现成员函数，再将其关联为可供模型选择的工具。内部工具仍使用普通表达式、调用和类型规则，不要求另一套工具函数语言。
每个关联工具应有可检查的目标、参数和结果类型，并使模型能够理解其用途。工具描述、关联形式和模型参数到类型化实参的转换规则待定；仅有名称或描述文本不足以替代真实函数定义。
外部函数引用或内部成员函数
→ 关联为工具
→ 模型提出工具选择及参数
→ 平台检查目标、实参与执行条件
→ inflight 函数调用
→ 类型化结果进入后续逻辑
模型提出调用意图不表示函数已经执行。参数或执行条件不满足时，不能将调用描述当作成功结果；关联为工具也不增加函数的访问权限。
agent 还可以编写一套新的逻辑，在其中组合已有函数，执行临时代码，或将定义提交到获准修改的 namespace。新的可执行定义必须经过 Preflight；生成、提交和执行之间的生命周期见运行中产生新定义。工具使用不限制 agent 只能选择现成函数。
13.4 Memory 与保存恢复
memory 承担信息保留与恢复，至少需要区分三种用途：
| 用途 | 保存的内容 | 使用时机 |
|---|---|---|
| 会话记忆 | 消息、工具结果及本次任务上下文 | 同一会话继续工作 |
| 执行检查点 | 恢复所需的状态、执行位置和待处理操作 | 暂停后恢复或故障后继续 |
| 长期记忆 | 需要跨任务使用的事实、偏好或知识 | 后续任务检索并使用 |
memory 的声明与保存策略属于定义层；实际消息、检查点和记忆内容属于 inflight。保存后的运行状态不会因此变成 Preflight 定义，任务完成也不自动删除全部记忆。
外部术语参考：LangGraph 将检查点和跨会话的长期存储分开；其 MemorySaver／InMemorySaver 在内存中保存检查点，本身不保证进程重启后的保留。Endorphin 应明确保存范围、保留时长和恢复能力，而不是直接照搬这个构造器名称。LangGraph 持久化说明
平台承担底层保存与读取，agent 使用类型化的记忆内容和操作。实例隔离、共享记忆、检查点粒度、保留策略、删除与恢复一致性尚待定义。
13.5 State、有限状态机与路由
state 表达当前业务与执行状态，memory 表达如何保留和恢复信息。state 可以被保存进 memory，但二者不是同一种职责。
有限状态机需要定义状态集合、当前状态、迁移条件及迁移效果。控制流与路由依据当前状态、函数结果或外部输入，决定下一步。函数可以承担节点逻辑或路由计算，节点如何声明和关联仍需定义。
当前状态与节点输入
→ 执行本节点逻辑
→ 取得结果并更新状态
→ 按条件选择下一步
→ 工具调用
→ 下一次模型计算或其他节点
→ 等待用户输入
→ 终止本次任务
模型的建议需要经过已声明的路由和迁移规则才能改变执行位置。等待输入不等于成功完成；任务终止与整个 agent 实例结束也分别处理。
完整条件、循环、状态类型、迁移与节点关联语法待定。有限状态机是 agent 应支持的控制形式，不要求每个普通成员变量都成为一个状态机节点。
13.6 人工在环与中断
涉及发邮件、扣款、删除数据库等高风险操作时，agent 必须在操作发生前暂停，等待人类确认或修改意见。中断需要保存待执行操作、相关参数、当前状态和恢复所需的位置，并将请求交付给用户。
形成待执行操作
→ 保存恢复所需的状态
→ 暂停并请求人类决定
→ 确认、拒绝或修改
→ 检查恢复输入与操作条件
→ 继续执行、重新规划或结束
等待期间不得执行待确认的操作。确认应对应具体操作及参数；参数改变时，原确认不能直接覆盖新操作。恢复不能任意重复已经完成的业务修改。
LangGraph 的中断机制提供“保存状态、等待外部输入、恢复执行”的参考，但其具体 API 和节点重启规则不自动成为 Endorphin 语义。LangGraph 中断说明
风险判定、审批关联、确认有效期、恢复接口及重复效果控制的具体规则见规范状态。
13.7 上下文选择、裁剪与总结
每次模型调用前，上下文管理逻辑从指令、消息、state、memory、工具结果及其他资源中构造输入，并按所用模型的输入容量进行检查。
超出容量时，可以选择相关内容、裁剪历史或进行增量总结。完整保存的记忆与本次送入模型的上下文是不同集合；裁剪模型输入不自动删除原始记忆或待审批操作。
裁剪和总结策略可以由 agent 内的函数实现，也可以引用已有能力。处理后仍应保留当前任务、必要的工具契约、关键状态及待处理控制信息；具体保留规则、预算计算、摘要类型和失败处理待定。输入长度控制不单独保证模型输出的事实正确性。
13.8 定义、实例与任务的生命周期
| 层次 | 所属生命周期 | 含义 |
|---|---|---|
| agent 声明 | Preflight | 定义成员、工具关联、记忆与控制规则，并供引用 |
| agent 实例 | inflight | 持有具体状态和上下文，执行或等待任务 |
| 一次任务 | inflight | 具有本次输入、执行过程、暂停或完成状态及结果 |
引用 agent 声明不自动创建实例或启动任务。一个定义可用于多个实例；实例之间的状态归属与共享必须明确。任务完成后，实例可以继续存在；长期记忆的保留由其自身规则决定。
Preflight 检查可静态确定的成员、函数类型、引用关系和控制约束；inflight 执行实际模型交互、函数调用、状态迁移、记忆读写及中断恢复。模型选择和业务调用仍可能在运行时失败，检查通过不能替代结果与状态检查。
实例化、任务交付、对外入口、实例标识和版本更新的具体形式仍待定义。本章不为它们补造 start、run 或 submit 等默认 API。