# AG-01｜Agent 的基本工作循环

核验日期：2026-10-10。读完后能追踪谁决定、谁执行、结果从哪里来，并为任务设置明确完成条件。

![Agent 逻辑架构图](<../../图表/AG-01_架构.svg>)

## 1. 同一任务的三种处理方式

任务是读取资产清单并报告命名异常。一次模型回答可以解释规则，但若没读取清单，就没有实际检查。固定脚本按已有路径和规则执行，重复任务通常容易验证。Agent 可以根据实际结果选择下一步，例如发现缺列后确认清单格式、找到正确入口再继续。

这三种方式的差别在于步骤由谁决定。[Building effective agents](<https://www.anthropic.com/engineering/building-effective-agents>) 区分预定工作流与由模型动态决定流程的 Agent。它是 2024 年方法文章，其页面也提示工具环境后来变化；本章取结构区分，不把旧工具清单当成当前推荐。

对于字段明确、规则稳定的清单检查，脚本可能已经足够。需要理解不完整问题、跨工具寻找事实、依据反馈调整步骤时，Agent 的动态判断更有价值，也增加耗时和调试工作。

## 2. 六个组件各做什么

| 组件 | 职责 | 示例 |
|---|---|---|
| 用户目标 | 定义需要得到的成果 | 指定清单、规则和报告格式 |
| 模型 | 理解信息，提出回答或工具请求 | 决定读取哪个入口 |
| 控制程序 | 调度轮次、校验与传递结果 | 接收请求，调用 Python 工具 |
| 工具 | 执行明确操作 | 读 CSV、运行检查、写报告 |
| 环境 | 保存真实文件与运行状态 | 当前目录、数据与解释器 |
| 状态记录 | 记录进度、证据和待办 | 哪个文件已检查，哪里失败 |

工具描述让模型知道有哪些操作、参数是什么、可能返回什么。权限与参数校验仍需执行层落实。工具说明不是用户授权，文件里的指令也不能自动成为系统指令。

## 3. 一次工具调用的完整过程

以 `inspect_csv(path)` 为例：模型生成参数；执行器确认字段、路径和允许范围；工具读取 CSV；工具返回结构化问题或错误；模型利用结果决定解释、继续检查或结束。

每个请求最好带可关联身份，日志保存调用名、参数、结果、状态与时间。模型提出 `write_report` 只证明有请求；工具返回成功证明它完成了某个操作；用户需要的报告是否正确，仍要按验收标准检查。

可以把返回设计为 `status / data / error` 的明确形式。别把“文件不存在”包装成空问题列表：空列表会让后续模型误以为资产全正常。错误应保留类型、失败操作和可恢复条件。

## 4. 观察、选择、执行、更新

循环每一步都需要新观察或可见进展。先读取当前状态，确定还差什么，选择动作，执行并获取反馈，再更新状态。计划是对后续步骤的组织，可以随事实改变；结果日志是已经发生的证据，不应随计划改写。

下面是教学伪代码，用来说明边界，不是某个产品的完整实现：

```python
while not accepted and attempts < limit:
    decision = model(context, available_tools)
    if decision.is_tool_request:
        result = executor.validate_and_run(decision)
        context.append(result)
    else:
        accepted = validator.check_artifact(decision)
```

现实系统还要处理流式事件、取消、并发、持久化和长任务。只有循环骨架不能证明达到产品质量。

## 5. 完成条件先写清楚

清单任务的条件可以是：读取指定四行；每项问题包含 CSV 行号和规则；正常行不报错；输入保持不变；报告写入指定位置；缺列返回明确错误。

“模型说好了”“工具退出码为 0”“异常报告已存在”各证明有限事实。用户成果要求行号和规则正确时，就必须对照原清单。教学样本得到四项问题只是当前固定答案，不是任意数据都应该四项。

终止还包括不可恢复错误、用户取消、等待必要信息和预算用完。这些状态应有清楚语义，不能都展示为成功，也不能把正常的长工具等待误判为停滞。

## 6. 失败、重试与重复执行

| 观察 | 合适的下一步 | 不充分的做法 |
|---|---|---|
| 参数缺字段 | 按 schema 修正 | 重发相同参数 |
| 路径不存在 | 核对工作区与输入 | 把无文件当零问题 |
| 工具暂时超时 | 查询状态，必要时有界重试 | 直接断言没有执行 |
| 权限不足 | 根据真实权限范围调整动作 | 用其他入口绕开同一限制 |
| 结果与预期不同 | 回到输入、规则和运行记录 | 改评分让结果看起来通过 |

读取操作通常容易重试；写入、部署和付费调用应先确认副作用是否已经发生。请求 ID、幂等写入、结果查询和阶段产物可以减少重复执行风险。重试上限要有目的，不能无限增加次数而没有新信息。

## 7. 教学工具日志拆解

[学习实验](<../../示例/学习实验/README.md>) 记录三步：缺失文件的工具错误；使用明确样本路径得到四项问题；验证器核对行号与规则后接受报告。这条记录的决策来自 `scripted_fixture`，不是本次 LLM 自主决策。

| 步骤 | 决策者／执行者 | 可见证据 |
|---|---|---|
| 1 | 脚本控制程序／文件读取器 | FileNotFoundError |
| 2 | 脚本控制程序／检查函数 | 四行、四项问题 |
| 3 | 独立答案断言 | 行号与规则逐项一致 |

它的价值是把接口与失败语义先讲清楚。把模型接入之后，再观察是否会选择合适动作、解释正确结果、在需要时结束。模型是否自主纠错必须有真实模型日志，不能从这份脚本演示推断。

## 8. 行动范围与适用条件

将只读检查、报告写入、真实资产修改分成明确操作。执行层检查实际目标和参数，模型负责说明问题。这样一个文件中的错误不会自然扩大成批量重命名。

多 Agent 适合独立子任务，有各自输入输出和汇总标准；共享文件、同一状态机和串行依赖会带来冲突。角色名字和 Agent 数量不是质量指标。本章无需创建多 Agent，也不把 Lauren 的吞吐自述当成通用扩容方案。

练习：给一个工具日志标注决策者、执行者、证据和终止条件；为缺文件、空结果、超时分别写下一步；说明哪些动作可直接重试、哪些应查状态。验收时能找出“请求被接受”和“目标完成”之间缺少的检查。

![本章思维导图](<../../图表/AG-01_思维导图.svg>)

## 来源与衔接

方法参考 [Anthropic Agent 方法文章](<https://www.anthropic.com/engineering/building-effective-agents>)、[Claude Code 工作流](<https://code.claude.com/docs/en/common-workflows>)，2026-10-10 核对。项目证据见 [Cindy Session](<../../sources.html#ref-01b2959f287d7e>) 与 [Aipcg 编排](<../../sources.html#ref-e4e51c90dbc28d>)。图为教学抽象，具体产品实现见 CY／PCG。下一章：[AG-02](<AG-02_Agent怎样理解项目并验证结果.md>)。