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