Agent 概览
Agent 是 Elftia 的核心能力之一。它让 AI 不再只是被动回答问题，而是具备了主动执行任务的能力 —— 读写文件、运行命令、搜索网页、调用外部工具，甚至协调多个子 Agent 并行工作。
什么是 Agent
在传统聊天中，AI 只能输出文字。而 Agent 模式下，AI 可以：
- 分析任务 — 理解你的需求，制定执行计划
- 调用工具 — 读取文件、编辑代码、执行命令
- 迭代优化 — 检查结果、修正错误、继续执行
- 返回结果 — 完成任务后给出最终回复
这个「思考 → 执行 → 观察 → 再思考」的循环，就是 Agent 循环（Agent Loop）。
用户消息 → 引擎分发 → LLM 思考 → 工具调用 → 结果观察 → 继续循环或返回回复
↑ ↓
└──────────────────────────────┘
多引擎架构
Elftia 支持多种 Agent 引擎，不同引擎适合不同场景：
| 引擎类型 | 标识 | 说明 | 适用场景 |
|---|---|---|---|
| TinyElf | tinyelf | Elftia 内置的轻量级 Agent 引擎 | 日常编程、文件操作、自动化任务 |
| Claude SDK | claude-sdk | 基于 Anthropic 官方 Agent SDK | 需要 Claude 原生工具链的场景 |
| CLI Runner | cli | 外部命令行工具（Claude Code、Codex） | 需要使用外部 CLI Agent |
| Chat | chat | 纯聊天引擎（无工具调用） | 简单问答、翻译、写作 |
| STChat | st-chat | 单轮对话引擎 | 快速单轮任务 |
| API | api | 轻量 API 调用 | 媒体生成等非聊天场景 |
TinyElf 引擎
TinyElf 是 Elftia 默认的 Agent 引擎，具有以下特点：
- 进程内运行 — 无需启动子进程或代理服务器，启动快速
- 多 LLM 支持 — 通过 TinyElfLLMAdapter 适配任意 LLM 提供商
- 内置工具链 — 文件读写、Shell 命令、网页搜索、MCP 工具
- 子 Agent 协作 — 支持前台和后台子 Agent 并行执行
- 技能系统 — 可加载可复用的 SKILL.md 技能指令
- 安全管控 — 三层安全防护（防火墙 + 守护 Agent + 权限确认）
Claude SDK 引擎
基于 @anthropic-ai/claude-agent-sdk，适合需要 Claude 原生能力的场景：
- 使用 Claude 官方预设的系统提示和工具
- 支持非 Anthropic 提供商（通过内置代理服务器转换格式）
- 多 API Key 负载均衡
CLI Runner 引擎
通过 ProcessSupervisor 管理外部 CLI 工具进程：
- 支持 Claude Code CLI 和 Codex CLI
- PTY 终端模式和普通子进程模式
- 自动超时处理和输出解析
核心能力
工具调用
Agent 可以使用多种工具完成任务：
| 工具类别 | 包含工具 | 说明 |
|---|---|---|
| 文件系统 | Read、Write、Edit、ListDir、Glob、Grep | 读写和搜索项目文件 |
| Shell | Bash | 执行终端命令 |
| 网页 | WebSearch、WebFetch | 搜索和抓取网页内容 |
| 子 Agent | spawn_agent | 启动子 Agent 处理子任务 |
| 会话管理 | SessionsSpawn、SessionsList、SessionsSend | 跨会话协作 |
| 技能 | list_skills、read_skill | 查看和读取技能内容 |
| MCP | mcp__*（动态加载） | 外部 MCP 服务器工具 |
| 控制 | Notify、SessionsYield | 通知和流程控制 |
子 Agent 协作
Agent 可以启动子 Agent 来并行处理子任务：
- 前台子 Agent — 阻塞等待结果，直接返回给主 Agent
- 后台子 Agent — 在后台异步执行，完成后结果注入主循环
- Agent 配置继承 — 子 Agent 可继承父 Agent 的 MCP 工具和技能
- 安全继承 — 子 Agent 继承父 Agent 的安全设置和权限模式
技能系统
技能（Skill）是可复用的指令集，以 SKILL.md 文件形式存在：
- 项目技能 — 放在
.claude/skills/目录下，随项目共享 - 个人技能 — 放在
~/.claude/skills/目录下，全局可用 - 社区技能 — 通过 SkillHub 搜索和安装
Agent 市场
Elftia 内置了多种预配置的 Agent，覆盖不同场景：
- 编程助手、代码审查、测试编写
- 文档写作、翻译校对
- 研究分析、数据处理
- 任务自动化、工作流编排
Agents 页面：单层平铺模型
0.1.7 完成两步合并 —— 不再有 "Persona / Avatar / Agent 三层结构"。所有 agent 在 Agents 页面 (
/agents) 一个网格里平铺管理。
一个 agent = 一个独立的对话目标
页面布局：
- 左侧分类栏：13 个分类（Featured、My、工作、编程、创意、研究、写作、生活、教育、娱乐、社交、自动化、Tools）
- 顶部搜索：按 agent 名称 / 描述 / 标签匹配
- 右侧网格：所有内置 + 用户自定义 agent 的卡片
内置 agent
- Clawia — 通用 Agent，主对话入口
- Cocoia — 定时任务专用
- Canvas — 可视化原型
- ClaudeCode — 代码开发
- Design Studio — 设计工坊
- Artia — 创意助手
- 动态加载的 datia 类 package：Deep Research、Visual Layout、Novel Writer 等
底层的媒体生成 agent（Chat / Image / Video / Music）保留在系统中，由各自的专用面板入口调用，不在 Agents 页单独露出。
数据迁移说明
底层数据迁移在升级时自动进行：
- v82（0.1.7 第一步）：回归平铺 agent 模型，Codia 下的 Canvas / ClaudeCode 拆为独立顶层 agent
- v87（0.1.7 第二步）：合并底层 Persona 与 Agent 表为唯一的 agent 表，简化数据模型
历史会话完整保留：原本归在 Codia 下的会话现在分别按使用的 agent 独立成行；历史消息无任何丢失。如需回滚，支持团队可通过 <userData>/migrations/ 下的快照文件恢复。
快速开始
使用内置 Agent
- 打开 Agent 面板（侧边栏 Agent 图标）
- 浏览 Agent 市场，选择一个适合的 Agent
- 开始对话，Agent 会自动调用需要的工具
创建自定义 Agent
- 在 Agent 面板中点击「创建 Agent」
- 设置名称、描述和系统提示
- 选择可用的工具和权限模式
- 保存后即可使用
详细步骤请参考 创建自定义 Agent。
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Agent 无法执行工具 | 引擎类型为 chat（无工具支持） | 切换到 tinyelf 或 claude-sdk 引擎 |
| 工具执行需要频繁确认 | 权限模式为 default | 设置为 acceptEdits 或 bypassPermissions |
| Agent 循环太快就停了 | maxIterations 设置过小 | 调整最大迭代次数（默认 40） |
| MCP 工具未出现 | 未关联 MCP 服务器 | 在 Agent 配置中添加 MCP 服务器 |
| 子 Agent 执行失败 | 子 Agent 配置文件有误 | 检查 .claude/agents/*.md 格式 |
相关链接
- 内置 Agent — 浏览和使用预置 Agent
- 创建自定义 Agent — 编写自定义 Agent 配置
- 工具权限与安全 — 权限模式和安全设置
- 技能系统 — 使用和创建技能