agent-builder

Agent Builder

构建专注于 1–2 项任务并能出色完成它们的微型 Agent。

路由（你必须做出判断）

当用户要求创建 Agent 时，选择合适的路径：

agent_build（单个） — 1 项技能、1 个数据源、简单的重复性任务、1–5 次工具调用。

agent_build + always_on=True — 24/7 运行的 Agent，每 5 分钟轮询一次收件箱以检查消息。就像坐在办公桌前的员工。

agent_team（团队） — 2 项或更多技能、并行收集数据、需要综合整理、10 次或更多工具调用。

agent_loop（长时间运行） — 开放式研究、迭代积累、没有固定终点。

agent_message — 向任意 Agent 的收件箱发送消息。支持用户→Agent 和 Agent→Agent。

不确定时： 从单个 Agent 开始。成本最低。用户之后可以升级。

工具

工具	用途
agent_build	创建或更新 Agent。设置 always_on=True 可启用守护进程模式。
agent_task	添加/更新/完成/移除/列出任务。也可使用 set_status 暂停/归档/重新激活。
agent_run	执行 Agent 一次（选取优先级最高的待处理任务）
agent_list	列出所有 Agent 及其状态和任务数量。可按团队/状态筛选。
agent_team	创建并运行团队（负责人 + 使用成本优化模型的工作者）
agent_loop	以循环模式运行 Agent——不断迭代，直到满足目标或用尽预算
agent_message	向某个 Agent 的收件箱发送消息。守护进程会在下次轮询时处理。

单个 Agent 工作流

1. 创建

agent_build(
  name="market-scout",
  display_name="Market Scout",
  role="Crypto market surveillance specialist",
  goal="Monitor BTC and ETH prices, flag anomalies",
  skills=["coingecko", "chart"],
  template="monitor",
  mode="research",
  schedule="0 8 * * *",
  timezone="Asia/Kuala_Lumpur"
)

模板： default、monitor、researcher

模式：

• default — 自由思考
• research — 防幻觉护栏：必须说明“我不知道”、引用来源，并在分析前摘录引文

计划： Cron（"0 8 * * *"）、间隔（"every 30 minutes"）、延迟（"in 2 hours"）、指定时间（"at 2026-05-01 14:00"）

2. 添加任务

agent_task(agent="market-scout", action="add",
  title="Check BTC price",
  priority="high",
  due_date="2026-04-26",
  recurring=True,
  depends_on=["task-id-of-prerequisite"]
)

• 优先级： low（60 秒，2 次调用）、medium（120 秒，5 次调用）、high（180 秒，10 次调用）、critical（300 秒，20 次调用）
• 重复任务： 完成后重置为待处理状态，并记录历史
• depends_on： 任务串联——在依赖项完成前处于阻塞状态

3. 运行

agent_run(agent="market-scout")

4. 管理

agent_task(agent="market-scout", action="set_status", status="paused")
agent_list(team="market-sentiment", verbose=True)

团队工作流

1. 创建团队

agent_team(action="create",
  name="market-sentiment",
  leader={"name": "analyst", "role": "Synthesize sentiment", "skills": ["chart"]},
  workers=[
    {"name": "btc-fetcher", "role": "Fetch BTC tweets", "skills": ["twitter"]},
    {"name": "eth-fetcher", "role": "Fetch ETH tweets", "skills": ["twitter"]},
  ]
)

负责人：Sonnet（$3/$15）。工作者：Haiku（$1/$5）。节省约 67%。

2. 运行团队

agent_team(action="run", name="market-sentiment",
  goal="Cross-chain sentiment comparison for BTC and ETH"
)

负责人负责整个流程：创建工作者任务 → 运行工作者 → 等待（bash 轮询）→ 读取输出 → 综合整理。

循环模式（长时间运行）

适用于没有固定终点的开放式任务：

agent_loop(agent="uni-scout",
  goal="Find universities with AI programs open to collaboration",
  max_iterations=10,
  output_file="candidates.json",
  timeout=1800
)

Agent 会不断迭代：读取进展 → 搜索 → 添加结果 → 评估 → 继续/停止。

预算阶段会随迭代进展调整策略：

• 探索（早期）→ 收敛（中期）→ 聚焦（后期）→ 完成（结束）

停止条件： Agent 表示完成、达到最大迭代次数，或连续 2 次迭代没有新进展。

常驻 Agent（守护进程模式）

创建 24/7 运行、轮询消息和任务的 Agent：

agent_build(name="ai-scout", display_name="AI Scout",
    role="Research AI content creators on Twitter",
    goal="Build a database of high-quality AI creators",
    skills=["twitter"], template="researcher", mode="research",
    always_on=True, team="marketing"
)

然后激活守护进程：

scheduled_task(action="activate", job_id="<daemon_job_id from output>")

每 5 分钟，守护进程会：

1. 检查 inbox.json——有新消息吗？处理消息、回复，并推送给用户。
2. 检查 tasks.json——有待处理任务吗？运行优先级最高的任务。
3. 两者都没有？自主工作——读取目标、记忆和现有输出，然后主动执行最有价值的下一步来推进目标。每 30 分钟运行一次（冷却机制可避免每次轮询都消耗令牌）。

如果 Agent 没有可执行的有效工作（目标已完全实现），它会输出 AUTONOMOUS_IDLE，成本为 $0.00。

消息传递

向任意 Agent 发送消息——支持用户向 Agent 发送，也支持 Agent 之间发送：

agent_message(agent="ai-scout", message="Focus on creators with 100K+ followers who post about LLMs")
agent_message(agent="marketing-lead", message="5 new creators found", from_agent="ai-scout")

消息会排入 inbox.json。Agent 的守护进程会在下次轮询时处理消息（最长约 5 分钟）。 回复会显示在 outbox.json 中，并推送给用户。

管理 Agent

所有内容都可以随时修改：

• 暂停： agent_task(agent="x", action="set_status", status="paused") — 守护进程会跳过已暂停的 Agent
• 恢复： agent_task(agent="x", action="set_status", status="active")
• 终止守护进程： scheduled_task(action="cancel", job_id="<id>") — 取消操作不可逆，请参阅下文的守护进程生命周期
• 更改角色/技能/模式： 使用新参数重新运行 agent_build — 会覆盖配置
• 发送新指令： agent_message(agent="x", message="change focus to...")
• 检查发现： read_file("agents/team/agent/output/results.json")
• 删除： 移除目录 — Agent 只是文件

守护进程生命周期（重要）

取消操作不可逆。 scheduled_task(action="cancel") 会删除任务。你无法重新激活它。要重启已取消的守护进程：

1. 使用 always_on=True 重新运行 agent_build — 注册一个新的计划任务
2. 新任务会获得新的 job_id — 旧 run.py 中的 JOB_ID 现已过时
3. agent_build 会自动将正确的 JOB_ID 写入新的 run.py
4. 激活：scheduled_task(action="activate", job_id="<new_id>")

JOB_ID 必须与活动任务匹配。 run.py 中的 JOB_ID 用于将推送通知路由到正确的任务。如果你手动复制 run.py，请更新 JOB_ID 常量，否则推送通知会悄无声息地发送到已失效的任务。

Agent 执行前推理

现在，每个 Agent 模板都包含一个在调用工具前必须遵循的推理框架：

• 影响对象（WHO）：会影响谁？
• 具体操作（WHAT）：你具体要做什么？
• 目标关联（WHY）：这如何推进你的目标？
• 风险（RISK） — 安全 / 中等 / 破坏性？

对于破坏性操作（删除、覆盖、清空），Agent 必须先停止并生成预览，然后才能执行。这可以防止意外丢失数据。

输出约定

每个 Agent 的提示词中都内置了强制输出约定：

• 主要输出始终是 JSON 文件（output/results.json）
• 先输出 JSON，再输出人类可读的摘要
• 每次运行时：读取现有内容 → 追加新内容 → 写回（绝不从头覆盖）
• 下游 Agent 和系统读取 JSON，而不是 Markdown

这可以避免“报告写得很好看，数据库却是空的”问题，即 Agent 只写说明文字，却从未更新结构化输出。

去重

所有模板都要求 Agent 在添加条目之前检查重复项：

• 根据主要标识符（名称、用户名、URL 或 ID）进行匹配
• 跳过重复项，并记录跳过数量
• 从第 1 次运行开始就设计去重，而不是之后再进行清理

资源归属

一个 Agent 负责一个资源。每个模板都内置了以下规则：

• Agent 只能写入自己的 output/、memory/ 和 scripts/ 目录
• 如果多个 Agent 需要写入同一目标位置，每个 Agent 都写入自己的输出目录 — 指定一个同步 Agent 来处理合并
• 不应有两个 Agent 写入同一个文件

目标筛选标准

研究员 Agent 会设置明确的筛选范围：

• 匹配度评分：1–10 分，只纳入评分达到 6 分及以上的条目
• 可触达性 — 优先选择你实际能够联系到的联系人
• 相关性 — 必须与目标直接相关，不能只是相邻或间接相关
• 在任务说明中设置明确的上限和下限（关注者范围、地理位置等）

破坏性操作防护

Agent 必须先生成预览，才能删除、清空或覆盖关键数据。执行前推理框架会将每项操作归类为安全、中等或破坏性。破坏性操作必须：

1. 预览将发生哪些更改
2. 在执行前获得明确确认

平台工具可靠性

如果底层服务配置错误或仍在等待设置，平台工具（send_to_telegram、composio 集成等）可能会悄无声息地失败。对于依赖外部交付的守护进程 Agent：

• 在依赖守护进程中的工具之前，务必手动验证工具是否正常工作
• 为关键交付路径构建直接 API 回退方案
• 检查工具输出 — 悄无声息的失败会返回成功，但实际上并未交付

循环模式停止信号

对于 agent_loop，“无结果迭代”是指 Agent 进行了搜索，但没有找到可添加到输出文件中的新条目。Agent 会在该次迭代的 score.json 中写入 "new_items": 0 来发出此信号。连续两次无结果迭代 = 停止。

Agent 通过在最终消息中输出文本 LOOP_COMPLETE 来表示任务完成。如果目标已达成后它仍在运行，请在任务描述中添加明确的停止条件：“达到 20+ 个条目时停止”或“覆盖美国、英国和亚洲后停止。”

GUARDRAILS.md

每个 Agent 都会获得一个 GUARDRAILS.md 文件——一份持续更新的已知约束文档。Agent 发现失败模式时，应追加条目：

## Trigger: Writing to output without reading existing content
Instruction: ALWAYS read the output file before writing
Reason: Previous run overwrote 15 valid entries with 3 new ones

目录结构

agents/
├── marketing/                     ← team folder
│   ├── team.json                  ← team config (leader, workers, models)
│   ├── analyst/                   ← leader agent
│   │   ├── agent.yaml
│   │   ├── PROMPT.md
│   │   ├── GUARDRAILS.md          ← learned constraints
│   │   ├── tasks.json
│   │   ├── references/
│   │   ├── scripts/
│   │   ├── output/results.json    ← mandatory JSON output
│   │   ├── inbox.json             ← messages (always-on)
│   │   ├── outbox.json
│   │   └── memory/MEMORY.md
│   ├── btc-fetcher/               ← worker
│   └── eth-fetcher/               ← worker
├── btc-watcher/                   ← singular agent (flat)
└── hackathon-scout/               ← singular agent (flat)

设计原则

1. 专注 — 每个 Agent 只做 1-2 件事。避免范围蔓延。
2. 隔离 — 每个 Agent 管理自己的目录。禁止跨 Agent 写入。
3. 可观测 — 任务具有状态、优先级、截止日期、重试次数和历史记录。
4. 可组合 — 可独立创建、暂停、归档和删除。
5. 渐进式 — 上下文分层加载（L1 元数据 → L2 提示词 → L3 按需加载参考资料）。
6. 自我改进 — 每次运行后，Agent 都会将经验写入记忆和 GUARDRAILS.md。
7. 成本感知 — 优先级决定超时时间、工具调用预算和模型提示。
8. JSON 优先 — 先输出结构化内容，再输出散文。下游系统读取 JSON。
9. 去重优先 — 插入前先检查。从第 1 次运行起就设计去重机制。
10. 默认安全 — 破坏性操作需要先预览并确认。支持试运行模式。