WorkBuddy_新建任务与工作模式5_Agent（默认）模式

Agent（默认）模式

摘要

在构建基于大语言模型（LLM）的智能应用时，"Agent 模式"是最基础也是最常用的一种运行范式。本文聚焦于 Agent（默认）模式——一种目标明确、直接执行的智能体工作方式，特别适合文档生成与文件处理类任务。我们将从概念定义出发，剖析其运行机制、适用场景、实现方式，并通过多个完整可运行的代码示例，带你从零理解并落地一个默认模式的 Agent。无论你是刚接触 Agent 的开发者，还是希望优化现有工作流的工程师，本文都能为你提供清晰、可操作的参考。

引言

随着大模型能力的增强，"Agent（智能体）“已经成为 AI 应用开发的核心概念。简单来说，Agent 就是**让模型自己决定"做什么、怎么做、做到什么程度”**的一套封装机制。而在众多 Agent 设计模式中，默认模式（Default Mode） 是最直接、最符合直觉的一种：

给定一个明确的目标，Agent 不绕弯子、不做过多规划与反思，而是直接调用工具、执行动作、产出结果。

这种模式牺牲了一部分"深思熟虑"的能力，换来了低延迟、低成本、高确定性。它非常适合那些任务边界清晰、步骤相对固定的场景，例如：

• 根据模板批量生成文档（合同、报告、周报）
• 读取文件内容并做结构化处理（PDF 转 Markdown、CSV 清洗）
• 按照指令生成代码文件、配置文件
• 对目录下的文件做批量重命名、格式转换

本文将以"文档生成与文件处理"为主线，系统讲解 Agent（默认）模式的原理与实现。

一、什么是 Agent（默认）模式

1.1 概念定义

Agent（默认）模式指的是：Agent 接收一个明确的目标（Goal）与输入上下文，按照预设的工具集，直接进入"执行"环节，循环调用工具直到任务完成或达到终止条件。它通常遵循经典的 ReAct（Reason + Act） 简化循环：

观察（Observation） → 思考（Thought） → 行动（Action） → 观察 → …

与"规划型 Agent""反思型 Agent"不同，默认模式不额外插入规划阶段和结果校验阶段，而是把"思考"压缩成每一步的即时决策。

1.2 核心特征

1.3 与其他模式的对比

• 规划型 Agent（Plan-and-Execute）：先出完整计划再执行，适合复杂多步任务，但延迟高。
• 反思型 Agent（Reflexion）：执行后自我评估并重试，质量高但成本翻倍。
• 默认模式：一步一决策，快速收敛，是"够用就好"的工程选择。

二、默认模式的运行机制

2.1 执行循环

一个默认模式 Agent 的核心是一个 while 循环，每一轮：

2.2 关键控制点

• 最大步数限制：防止死循环，通常设为 5~15。
• 工具白名单：只暴露完成任务所需的工具，降低误用概率。
• 终止判定：以"模型不再请求工具"作为完成信号。

下面用一个简化的流程图展示：

┌─────────────┐
│ 用户目标 │
└──────┬──────┘
▼
┌─────────────┐ 工具调用 ┌─────────────┐
│ 调用 LLM │ ────────────▶ │ 执行工具 │
└──────┬──────┘ └──────┬──────┘
│ 最终答案 │ 观察结果
▼ │
┌─────────────┐ │
│ 输出结果 │ ◀────────────────────┘
└─────────────┘

三、适用场景：文档生成与文件处理

3.1 为什么默认模式特别适合这类任务

文档生成与文件处理通常具备以下特点，与默认模式高度契合：

3.2 典型任务清单

• 根据 Markdown 模板生成项目 README
• 读取 PDF 并提取关键信息生成摘要文档
• 批量处理目录下的文本文件（清洗、替换、合并）
• 根据数据生成报表文件（CSV/Excel/Markdown）

四、动手实现：一个文档生成 Agent

下面我们用 Python 实现一个最小可运行的 Agent（默认）模式，聚焦"根据数据生成 Markdown 报告"这一任务。为便于演示，这里用一个模拟的 LLM 客户端，你可以替换为 OpenAI、通义千问等任意支持函数调用的模型。

4.1 定义工具

import os
import json
from datetime import datetime

# 工具 1：读取文件内容
def read_file(path: str) –> str:
"""读取指定路径的文本文件，返回内容。"""
if not os.path.exists(path):
return f"[错误] 文件不存在: {path}"
with open(path, "r", encoding="utf-8") as f:
return f.read()

# 工具 2：写入文件
def write_file(path: str, content: str) –> str:
"""将内容写入指定路径，自动创建目录。"""
os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
with open(path, "w", encoding="utf-8") as f:
f.write(content)
return f"[成功] 已写入 {len(content)} 字符到 {path}"

# 工具 3：获取当前时间（用于报告落款）
def get_current_time() –> str:
"""返回当前时间字符串。"""
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

# 工具注册表：名称 -> 函数
TOOLS = {
"read_file": read_file,
"write_file": write_file,
"get_current_time": get_current_time,
}

4.2 定义 Agent 主循环

class DefaultAgent:
"""Agent（默认）模式：目标明确、直接执行。"""

def __init__(self, llm_client, tools: dict, max_steps: int = 8):
self.llm = llm_client # 任意支持工具调用的 LLM 客户端
self.tools = tools # 工具注册表
self.max_steps = max_steps # 最大执行步数，防止死循环

def run(self, goal: str) –> str:
"""执行一个明确目标，返回最终结果。"""
messages = [
{"role": "system", "content": "你是一个直接执行的 Agent，"
"请根据目标调用工具完成任务，完成后直接给出结果。"},
{"role": "user", "content": goal},
]

for step in range(self.max_steps):
# 1) 请求模型决策
response = self.llm.chat(messages, tools=self.tools)

# 2) 若模型不再调用工具，视为完成
if not response.get("tool_calls"):
return response.get("content", "")

# 3) 执行工具调用，把结果作为观察追加
for call in response["tool_calls"]:
name = call["name"]
args = call.get("arguments", {})
result = self.tools[name](**args)
messages.append({
"role": "tool",
"name": name,
"content": result,
})

return "[终止] 达到最大步数，任务未完成。"

4.3 模拟 LLM 客户端

为了让你能直接跑通，下面提供一个模拟客户端：它按预设脚本依次返回工具调用，最后给出总结。真实场景中替换为真实 API 调用即可。

class MockLLM:
"""模拟 LLM：按脚本依次返回工具调用，便于本地演示。"""

def __init__(self):
self.step = 0

def chat(self, messages, tools):
self.step += 1
if self.step == 1:
# 第一步：读取数据文件
return {"tool_calls": [{
"name": "read_file",
"arguments": {"path": "data/sales.csv"},
}]}
if self.step == 2:
# 第二步：获取时间
return {"tool_calls": [{
"name": "get_current_time",
"arguments": {},
}]}
if self.step == 3:
# 第三步：生成并写入报告
report = (
"# 销售报告\\n\\n"
f"生成时间：{messages[–1]['content']}\\n\\n"
"| 月份 | 销售额 |\\n|——|——–|\\n"
"| 1月 | 12000 |\\n| 2月 | 15000 |\\n| 3月 | 18000 |\\n"
)
return {"tool_calls": [{
"name": "write_file",
"arguments": {"path": "output/report.md", "content": report},
}]}
# 完成：给出最终答复
return {"content": "报告已生成：output/report.md"}

4.4 运行示例

if __name__ == "__main__":
# 准备测试数据
os.makedirs("data", exist_ok=True)
with open("data/sales.csv", "w", encoding="utf-8") as f:
f.write("month,sales\\n1月,12000\\n2月,15000\\n3月,18000\\n")

# 启动 Agent
agent = DefaultAgent(llm_client=MockLLM(), tools=TOOLS)
result = agent.run("根据 data/sales.csv 生成一份 Markdown 销售报告，保存到 output/report.md")
print(result)

运行后你会看到 output/report.md 被正确生成。这个例子完整体现了默认模式的精髓：目标明确 → 直接调用工具 → 产出文件，没有多余的规划与反思。

五、工程实践建议

5.1 提示词设计

默认模式的提示词应尽量简洁、指令化，避免让模型"过度思考"。推荐结构：

你是直接执行的 Agent。
– 目标：{goal}
– 可用工具：{tools}
– 规则：优先调用工具完成动作，禁止编造文件内容，完成后直接返回结果。

5.2 工具设计原则

5.3 错误处理与重试

def safe_call(func, **kwargs):
"""工具调用的安全包装，捕获异常并返回可读错误。"""
try:
return func(**kwargs)
except Exception as e:
return f"[工具异常] {type(e).__name__}: {e}"

在 Agent 循环中调用 safe_call 替代直接调用，可避免单个工具报错导致整个流程崩溃。

5.4 何时不该用默认模式

• 任务需要多方案权衡（如架构设计）
• 需要严格质量校验（如法律文书终稿）
• 步骤高度不确定、需要动态规划

这些场景应考虑规划型或反思型 Agent。

总结

本文系统介绍了 Agent（默认）模式：

• 它是一种目标明确、直接执行的智能体范式，核心是"观察—思考—行动"的简化循环；
• 它特别适合文档生成与文件处理这类目标清晰、步骤固定的任务；
• 我们通过一个完整可运行的 Python 示例，演示了工具定义、Agent 主循环、模拟 LLM 与运行结果；
• 工程实践中要注意提示词简洁化、工具单一职责、错误安全包装，并清楚其边界。

默认模式不是"最聪明"的 Agent，但往往是最实用、最易维护的那一个。对于大量日常的文件与文档自动化任务，它足以胜任。建议你在真实项目中先将任务跑通于默认模式，再根据质量需求逐步引入规划或反思机制——这正是渐进式构建 Agent 系统的稳妥路径。