Agents

Agents 模块：一步一步教程

本页从 0 到可用路由，完整覆盖 agents 模块。按顺序执行，每一步都给出验收点。

步骤 1：查看当前 agent 状态

mosaic --project-state agents list
mosaic --project-state agents default

预期：看到 agent 列表（可以为空）以及默认 agent（如果已设置）。

步骤 2：创建第一个自定义 agent

mosaic --project-state agents add \
  --name Writer \
  --id writer \
  --skill writer \
  --temperature 0.2 \
  --max-turns 8 \
  --tools-enabled true \
  --guard-mode confirm_dangerous \
  --set-default \
  --route ask \
  --route chat

预期：writer 创建成功并被设置为默认。

步骤 3：查看详情并验证路由

mosaic --project-state agents show writer
mosaic --project-state agents route list
mosaic --project-state agents route resolve --route ask
mosaic --project-state agents default

预期：ask/chat 路由解析到 writer。

步骤 4：在 ask/chat 中使用 agent

# 显式指定
mosaic --project-state ask --agent writer "summarize this repository"
mosaic --project-state chat --agent writer

# 使用默认/路由
mosaic --project-state ask "hello from default agent"
mosaic --project-state chat

预期：响应可以正常返回，且使用的是你定义的 agent 配置。

步骤 5：安全更新 agent 配置

mosaic --project-state agents update writer \
  --name "Writer V2" \
  --skill reviewer \
  --temperature 0.15 \
  --max-turns 10 \
  --route ask

mosaic --project-state agents update writer --clear-skills
mosaic --project-state agents show writer

预期：show 输出中能看到更新后的字段。

步骤 6：管理路由映射

mosaic --project-state agents route set chat writer
mosaic --project-state agents route list
mosaic --project-state agents route resolve --route chat
mosaic --project-state agents route remove chat

预期：route set/remove 立即反映在 route resolve 结果中。

步骤 7：切换默认与回滚

mosaic --project-state agents default writer
mosaic --project-state agents default

# 可选清理
mosaic --project-state agents remove writer

仅在确认该 agent 不再被路由使用时再 remove。

步骤 8：排障清单

• ask --agent writer 失败：先看 agents show writer。
• 绑定 skill 的 agent 失败：执行 skills list，确认每个 --skill id 存在。
• 路由异常：执行 agents route list 与 route resolve。
• 执行被拦截：检查 approvals get 与 sandbox get。
• 上下文诊断：用 doctor 和 logs --tail 120。