A local-first multi-agent app development platform, built on PenguinHarness
title: 智能体 description: 创建 Agent,配置它的提示词、工具、Skill、钩子、记忆、密钥保险柜、定时任务和 API。
Agent 是 Project 里配置好的助手。每个 Agent 都有自己的指令、运行参数、工具、Skill、钩子包、记忆、密钥保险柜变量和定时任务,这些内容存放在一起,构成它的 Agent State。创建 Agent、修改设置,都在智能体页面上完成。
- 要查看 Project 里的 Agent,见智能体页面。
- 要添加 Agent,见用 AI 创建 Agent 或手动创建 Agent。
- 要修改 Agent,见 Agent 设置和各标签页对应的章节。
- 要备份、迁移或重置 Agent,见概览标签页。
- 要删除 Agent,见删除 Agent。
智能体页面
在侧边栏选择智能体。页面列出当前 Project 里的所有 Agent。可以用搜索框(搜索 Agent:id / 名称 / 描述)过滤列表。
每个 Project 都自带内置 Agent default_agent。当它还是唯一的 Agent 时,它下方会出现一张卡片,提示你创建第一个自己的 Agent:「还没有自己的智能体」。
每个 Agent 卡片显示:
- Agent 的名称、id、Agent State 版本(例如
v3)和描述;已开启 API 的 Agent 名称后带有 API 图标(已开启 API 访问); - 一排数字:Session、工具、Skill、钩子包、记忆、密钥保险柜变量、定时任务的数量,以及最近一次修改的时间。点击任一数字即可打开对应的设置标签页;
- 这个 Agent 最近 30 天的 Session 活动;
- 新建对话:和这个 Agent 开始对话;设置:打开它的设置;一个图标:在成本中心查看成本;以及一个删除按钮。
部分 Agent 有新内核可用时,卡片上会显示内核需要更新,页面顶部的通知会提供现在升级和忽略。见更新内核。
也可以从侧边栏进入某个 Agent。对话按 Agent 分组显示时,每个分组标题上有新建对话和 Agent 设置按钮;侧边栏还有创建 Agent 按钮,点击打开创建 Agent 对话框。
用 AI 创建 Agent
描述你想要的 Agent,一个现有的 Agent 会替你把它创建出来。
- 在智能体页面选择用 AI 创建,打开用 AI 创建 Agent 对话框。
- 描述这个 Agent 做什么、为谁服务、产出什么。想从示例开始,就在试试这些示例下选一个:随记智能体、金融 Copilot、文档 RAG 智能体、深度研究报告智能体或报告写作智能体。
- 可选:展开完整提示词,查看会随描述一起发送的指令;也可以选择复制提示词。
- 选择在新对话中编辑。会打开一个新对话,提示词已填好,此时还没有发送。
- 检查提示词并发送。
对话框会写明由哪个 Agent 执行:「将由『Agent』在新对话中完成」。执行者是 Project 的 default_agent;没有 default_agent 时,用第一个 Agent。
固定指令要求执行 Agent 使用 agent-initialization Skill,并且:
- 使用你给定的 Agent id,或者起一个简短、能体现用途的 id;如果这个 Agent 已经存在,就停下来,不要覆盖;
- 以
default_agent的配置为基础,设置名称和描述,把新 Agent 的角色和规则写进它的AGENTS.md; - 只从插件库复制新 Agent 需要的 Skill,其他 Agent 一概不动;
- 报告新 Agent 的 id、安装了哪些 Skill,以及怎样和它开始对话。
报告写作智能体示例会创建 id 为 report-writer 的 Agent。评估中心里有配套的 Benchmark 示例,创建后可以继续对这个 Agent 做评估和优化。
手动创建 Agent
- 在智能体页面选择手动创建,打开创建 Agent 对话框。
- 可选:在名称中填写名称。名称留空时用 Agent id。
- 在 Agent id 中输入 id,也可以点击输入框旁边的用 AI 生成,由 Project 里一个免费(0 定价)的模型根据名称生成一个,一个不行就换下一个;名称为空时则根据描述生成。这一步不花钱,默认模型不参与。id 长度为 2–64 个字符,以小写字母开头,只能用小写字母、数字和下划线。生成的 id 会覆盖框里原有的内容,之后仍可以手动修改。创建后 id 不能再改。
- 可选:填写描述。
- 可选:在插件中从插件库选择要装到新 Agent 上的插件。Agent 创建时会一并装上这些插件的 Skill 和钩子包。
- 可选:在从项目目录导入技能中选择一个目录。Adelie 会读取这个目录下
.agents/skills和.claude/skills文件夹里的 Skill,从中勾选要安装的。目录里的 Skill 与所选插件里的 Skill 同名时,装的是目录里的那个。 - 选择创建,打开新 Agent 的设置。
任何 Project 成员都能创建 Agent。
从快照创建
快照包是导出的 Agent State。可以基于它创建 Agent,例如把 Agent 复制到另一个 Project 或另一台机器。
开始之前
- 要复制的 Agent 的快照包(
.tar.gz)。单个包最大 14 MB。制作方法见导出和导入快照。
- 在创建 Agent 对话框中,在从快照初始化下点击选择快照包,选定包文件。Agent id 为空时,会按文件名自动填入。
- 名称和描述留空则沿用包里的值,填写则覆盖。
- 选择创建。
[!NOTE] 快照包自带 Skill 和钩子。选定快照包后,插件和从项目目录导入技能会隐藏。
删除 Agent
只有 Project owner 能删除 Agent。内置的 default_agent 不能删除。
- 在 Agent 卡片上选择删除按钮(删除 Agent)。
- 确认。
[!WARNING] 删除 Agent 会删除它在服务端的目录,包括全部 Trace,删除后无法恢复。
Agent 设置
要打开某个 Agent 的设置,可以在卡片上选择设置,可以点击卡片上的某个数字,也可以在侧边栏对应分组上选择 Agent 设置。设置分为几个标签页:
| 标签页 | 配置内容 |
|---|---|
| 概览 | 名称和描述、Agent State 快照、内核更新、还原为默认配置 |
| 系统提示词 | AGENTS.md 和系统提示词模板 |
| 运行参数 | 轮次上限、输出 Token、思考等级、超时和上下文压缩 |
| 工具 | 内置工具设置和 MCP Server |
| 技能 | 已安装的 Skill 和技能提示词 |
| 钩子 | 已安装的钩子包和运行开关 |
| 记忆 | Agent 的记忆和记忆提示词 |
| 密钥保险柜 | Agent 命令用的环境变量 |
| 定时任务 | 定时任务 |
| API | 是否允许程序经 Agent API 调用这个 Agent、这些对话的审批模式,以及密钥 |
每个标签页都有自己的地址:/agents/<agentId>?tab=<tab>,其中 <tab> 是 overview、prompt、runtime、tools、skills、hooks、memory、vault、schedules 或 api。
保存修改
在概览、系统提示词、运行参数和工具四个标签页,以及各个提示词区块,选择保存并确认。确认框写着:「确定保存这些修改吗?修改将写入服务器上的配置文件。」
- 大多数修改立即对新对话生效;正在运行的对话要在下一次压缩后才生效。
- 运行参数的修改如果只涉及上下文压缩字段,则立即生效,正在运行的对话也不例外。
- 启用技能这类开关一拨动就保存,不需要按保存。
这些设置对应的文件格式见 Agent 配置。
权限
大多数设置,任何 Project 成员都能修改。以下操作只有 Project owner 能做:
- 删除 Agent、导入快照;
- 打开或关闭启用钩子;
- 编辑密钥保险柜变量、启用密钥保险柜开关和保险柜提示词;
- 创建、编辑、启用、停用和删除定时任务,编辑启用定时任务开关和定时任务提示词(成员仍可使用用 AI 创建);
- 导入记忆;
- API 标签页上的一切:开关、审批模式、无密钥访问和密钥。
概览标签页
修改名称和描述
修改名称或描述,然后选择保存。
导出和导入快照
Agent State 区块显示 Agent State 版本和 State 路径(Agent State 在服务端所在的文件夹),点击复制按钮可以复制路径。
- 导出快照:把 Agent State 下载为
.tar.gz包。包里不含密钥保险柜,密钥不会随快照流出。 - 导入快照:用包整体替换 Agent State,并采用包内的版本,但保留 Agent 当前的密钥保险柜。导入前会先对当前版本做一次快照。只有 Project owner 能导入。如果包内版本不比当前版本新,会弹出版本冲突对话框,要求确认覆盖。
版本和快照的工作机制见自我进化。
更新内核
Agent 的内核版本记录它的配置基于哪一代内置默认设置。已有的 Agent 永远不会自动采用更新的默认值。Adelie 发布新默认值后,内核区块会显示当前内核版本和最新内核版本,概览标签页上出现红点。
- 在内核区块选择更新内核。
- 确认。
没有自定义过的标签页会更新为当前的内置默认值。编辑过的标签页整个保持不变,并在结果中列出。名称、描述、Agent State 版本和 MCP Server 不受影响。详情见内核更新。
[!TIP] 要一次更新多个 Agent,可以在智能体页面顶部的通知里选择现在升级。
还原为默认配置
- 在内核区块选择还原为默认配置。
- 确认。
[!WARNING] 还原为默认配置的操作无法撤销。
还原时用当前默认值覆盖 Agent 的配置:自定义系统提示词、工具列表、模型和压缩设置、MCP Server 全部替换,只保留名称、描述和 Agent State 版本。
系统提示词标签页
- AGENTS.md 保存 Agent 的角色、规则和工作指令。
- system_prompt 模板:系统提示词由这个模板生成。
在「可用占位符(点击插入)」下选择一个占位符,即可插入到模板中光标所在位置:
| 占位符 | 插入内容 |
|---|---|
{{AGENTS_MD}} |
AGENTS.md 的内容 |
{{VAULT}} |
密钥保险柜区块:保险柜提示词加变量名列表;启用密钥保险柜关闭时为空 |
{{SKILLS}} |
Skill 区块:技能提示词加已安装 Skill 的元数据;启用技能关闭时为空 |
{{MEMORY}} |
记忆区块:主记忆提示词,持久 Workspace 中还包括工作区附加段;记忆关闭时为空 |
{{SCHEDULES}} |
定时任务区块:定时任务提示词加任务名列表;启用定时任务关闭时为空 |
{{PLATFORM}} |
运行平台 |
{{OS_VERSION}} |
操作系统版本 |
{{SHELL}} |
执行命令所用的 shell |
{{DATE}} |
当前日期 |
{{PROJECT_DIR}} |
Adelie 应用数据根目录,存放所有 Agent 数据和 Project 数据;不是 Task 的工作目录 |
{{AGENT_ID}} |
Agent 的 id |
{{CWD}} |
Workspace 的绝对路径 |
{{PROVIDER}} |
模型的供应商分组 |
{{MODEL_ID}} |
上游模型 id |
{{SESSION_ID}} |
Session id |
密钥保险柜、Skill、记忆和定时任务区块的开关和提示词,分别在各自的标签页里。另见系统提示词占位符。
运行参数标签页
| 字段 | 含义 |
|---|---|
max_turns |
一个 Task 允许的最大轮次;-1 表示不限 |
model.max_tokens |
每次请求的输出 Token 上限 |
model.thinking_level |
low、medium、high、xhigh 或 max。新建 Agent 默认 medium。在部分模型上,xhigh 和 max 的实际表现与低一档相同。保存过旧档位 none 的 Agent 会继续保留,但选项中不再提供 |
model.timeoutMs |
等待模型供应商事件的时间上限,单位毫秒;不限制整个请求的时长 |
max_context_length |
触发压缩的上下文大小 |
max_session_turns |
触发压缩的轮数 |
mode |
summarize(默认):让模型总结旧上下文,然后在新的窗口里从总结继续;discard:直接丢弃旧上下文,不做总结 |
prompt |
总结上下文时使用的提示词 |
max_turns 和 model.timeoutMs 接受大于 0 的数字或 -1。思考等级在各模型上的表现见思考等级。压缩的工作方式见压缩。
工具标签页
内置工具
表格列出全部内置工具,每个工具可以设置:
| 列 | 含义 |
|---|---|
permission |
Read-only(r):工具只读取,「放行只读」审批模式会自动放行。Read & write(rw):工具可能修改内容,「放行只读」审批模式会先询问你 |
timeoutMs |
工具的时限,单位毫秒 |
maxOutputLength |
工具最多可返回的输出量 |
call_description |
模型是否为每次调用写一句话描述,调用运行时会显示给你。默认开启;只有支持描述的工具才能切换 |
字段留空即使用默认值。点击保存即可保存表格。审批模式见审批。
添加 MCP Server
MCP Server 给 Agent 增加外部工具,工具名形如 mcp__<name>__<tool>。MCP Server 区块里的改动立即保存。
- 在工具标签页选择添加 MCP Server。
- 选择传输方式:
http(默认):Streamable HTTP,当前的远程传输方式。stdio:本地进程,由 Adelie 启动,通过 stdin 和 stdout 通信。sse:旧的 HTTP+SSE 传输方式,供尚未迁移的 Server 使用。
- 在 name 中输入工具名前缀,可以用字母、数字、
_和-,以字母或数字开头。 - 填写连接字段:
stdio:command;args,每行一个参数;env,每行一个KEY=value;cwd,默认是 Session 的 Workspace。Agent 的密钥保险柜变量不会传给 MCP Server 进程。http和sse:url;headers,每行一个Header-Name: value,例如Authorization请求头。
- 选择 permission:
- Auto(readOnlyHint):工具声明了
readOnlyHint注解就按只读处理,否则按 Read & write 处理。 - Read-only:Server 的所有工具都按只读处理。
- Read & write:Server 的所有工具都按 Read & write 处理。
- Auto(readOnlyHint):工具声明了
- 可选:调整 connectTimeoutMs(连接和发现工具,默认 10000)、timeoutMs 和 maxOutputLength,这些设置对 Server 的所有工具生效。
- 可选:保存前选择测试连接验证配置,它会报告发现的工具数量和耗时。
- 选择保存。
[!NOTE] permission 级别只在「放行只读」审批模式下起作用,其他审批模式都会忽略它。它也不限制 Server 能做什么:把 Server 标为只读,只是让这个审批模式跳过本该弹出的确认。
要修改某个 Server,在它的行上选择编辑。要移除,选择删除并确认;从下一个 Session 开始,它的工具不再可用。更多关于 MCP Server 的内容见 MCP Server。
测试 MCP Server
- 在 MCP Server 区块选择测试连接。
- 选择开始测试。
Adelie 依次连接每个 Server 并发现它的工具,不会保存任何内容。每行显示工具数量和耗时;失败则显示连接失败和原因。
技能标签页
技能标签页列出 Agent 已安装的 Skill。可以导出或卸载 Skill,用导入技能导入新的 Skill,用启用技能控制系统提示词里的 Skill 区块,还可以编辑技能提示词。见管理 Agent 的 Skill。
钩子标签页
钩子标签页列出 Agent 已安装的钩子包。可以导出、卸载钩子包,用导入钩子导入新的钩子包,用启用钩子为这个 Agent 开关钩子。从插件库安装,要到插件市场页面操作。见钩子包。
记忆标签页
记忆让 Agent 跨 Session 保留学到的东西。Agent 在工作过程中会自己保存值得记住的内容,你也可以让它记住指定内容。用户记忆对这个 Agent 的所有 Session 生效;Workspace 记忆按 Workspace 分别保存。
- 启用记忆开关控制记忆的开与关,切换后立即保存。关闭后只是阻止记忆进入 Agent 的上下文、不再为新 Session 准备记忆,不会删除任何内容。
- 系统提示词模板里没有
{{MEMORY}}占位符时,标签页会给出提示,选择插入 {{MEMORY}} 占位符即可补上。记忆功能出现之前创建的 Agent 会有这种情况。
记忆按范围分组:用户记忆排在最前,之后每个 Workspace 一组。点击分组标题可以折叠或展开;浏览器会为每个用户、Project 和 Agent 记住折叠状态。
查看、编辑和删除记忆
每条记忆一行,行上有三个按钮:
- 查看:在侧边面板显示这条记忆的标题、日期、描述和内容;窄屏下则从底部弹出面板,可以半屏或全屏高度打开。
- 编辑:打开编辑记忆对话框。在修改要求里描述要改什么(可选),然后选择打开新对话。会打开和这个 Agent 的新对话,提示词已填好;如果编辑的是 Workspace 记忆,还会使用对应的 Workspace。发送消息后,Agent 会同时更新记忆文件和
MEMORY.md索引。 - 删除:确认后删除这条记忆,并从
MEMORY.md里移除对应的行。
记忆内容要通过对话交给 Agent 修改,不能就地编辑。
添加记忆
- 在分组标题上选择添加,打开添加记忆对话框。
- 在要记住的内容或来源里粘贴内容、文件路径或 URL。
- 选择打开新对话,然后发送消息。Agent 会把内容整理成这个分组里的记忆。
导出和导入记忆
- 分组标题上的导出:把分组里的全部记忆连同
MEMORY.md下载为一个 JSON 文件。文件名包含导出日期和时间,多次导出不会互相覆盖。 - 分组标题上的导入:把这类文件读回分组。只有 Project owner 能导入。
导入时,如果分组里已有同名记忆,需要选择处理方式:
| 选项 | 结果 |
|---|---|
| 保留现有的这条(默认) | 只添加分组里没有的记忆。不丢失任何内容 |
| 改用文件里的版本 | 替换同名记忆。文件里没有的记忆保持不变 |
| 整组替换 | 删除文件里没有的全部记忆 |
如果导入会覆盖或删除记忆,或者替换分组的 MEMORY.md,会先弹出确认导入对话框,列出将要发生的变化。
记忆提示词
在记忆提示词下编辑 {{MEMORY}} 占位符展开后的文本:
- 主提示词(
memory.prompt):注入每个 Session。 - 工作区附加段(
memory.workspace_prompt):只注入带持久 Workspace 的 Session。
这些提示词可以用 {{USER_MEMORY_INDEX}}(用户 MEMORY.md 索引)、{{WORKSPACE_MEMORY_INDEX}}(Workspace 的 MEMORY.md 索引)和 {{WORKSPACE_MEMORY_DIR}}(当前 Workspace 的记忆文件夹)。后两个只在工作区附加段里生效。每个索引最多 200 行、25,000 字符。
点击 Agent 卡片上的记忆数字即可打开这个标签页。
密钥保险柜标签页
密钥保险柜存放 Agent 用的环境变量,比如 API key。Adelie 把它们传给 Agent 的 shell 命令。模型只能看到变量名,永远看不到值。子 Agent 用各自的密钥保险柜,不继承这里的变量。修改从下一个 Task 起生效;正在运行的 Task 不受影响。
只有 Project owner 能修改密钥保险柜。成员能看到变量名,值以掩码显示。
添加变量
- 在密钥保险柜标签页选择手动创建,打开添加环境变量对话框。
- 在键名中输入变量名,例如
OPENAI_API_KEY。可以用字母、数字和下划线,不能以数字开头。 - 在值中输入变量值。
- 选择添加。变量已存在时,确认后覆盖原值。
要删除变量,在它的行上选择删除并确认。值无法恢复。
用 AI 添加变量
选择用 AI 创建会打开让 AI 添加密钥。描述需要的变量,或选一个示例:盘点这个智能体需要的 key、重置一个过期 token 或 接入一个内部服务。然后选择在新对话中编辑并发送提示词。Project 的默认 Agent 会用 penguin config vault set 写入变量。
[!WARNING] 在这个对话框里输入的密钥值会发送给模型供应商,记录进对话的 Trace,还会在 Agent 运行的命令里再次出现。更安全的做法是让 AI 只创建变量名并说明各自用途,然后你在密钥保险柜标签页自己填入值。
保险柜提示词
- 启用密钥保险柜控制密钥保险柜区块是否进入系统提示词。关闭时,变量仍然会传给 Agent 的命令。
- 保险柜提示词:
{{VAULT}}占位符展开后的文本。其中的{{VAULT_KEYS}}占位符列出变量名,每行一个。
定时任务标签页
定时任务按计划给 Agent 发送提示词:发一次,或按周期反复发。这个标签页上的修改立即生效。
[!NOTE] 定时任务只在 Adelie 服务运行时触发。
也可以在对话里创建和管理定时任务,见定时任务。
创建定时任务
只有 Project owner 能手动创建定时任务。
- 在定时任务标签页选择手动创建,打开新建定时任务对话框。
- 在名称中输入任务的文件名,不带
.toml。创建后不能修改。 - 在周期中输入任务运行频率,例如
30m、12h或7d。一次性任务留空。最短周期为 5 分钟。 - 设置开始时间,也可以设置结束时间。一次性任务的开始时间必须晚于当前时刻,结束时间不能早于当前时刻。
- 在目标下选择提示词发到哪里:
- 每次新建会话:每次运行都新建一个 Session。可以再选 Model(不选就用 Project 默认值)和 Workspace(不选就用临时 Workspace)。
- 绑定 Session:每次运行都发给同一个已有的 Session。在 Session 中选择。
- 在 Prompt 中输入要发送的内容。
- 保持勾选启用以激活任务,然后选择创建。
也可以用描述的方式创建:选择用 AI 创建,或从列表为空时显示的建议中选一个:每日简报、每周回顾、跟进提醒或监控更新。然后选择在新对话中编辑并发送提示词。Project 的默认 Agent 会为这个 Agent 创建任务。任何成员都能使用用 AI 创建。
管理定时任务
表格显示每个任务的名称、状态、周期、目标、下次 / 最近触发和排队。状态可能是生效、停用、已过期、已完成、已错过或无效;指向无效可查看原因。已完成、已错过和已过期的任务会归档,随即移出表格,见结束的任务会归档。
owner 可以在每一行选择停用或启用、编辑、删除。无法解析的文件列在「解析失败的文件(已跳过调度)」下。
定时任务提示词
- 启用定时任务控制定时任务区块是否进入系统提示词。关闭时,任务照常运行。
- 定时任务提示词:
{{SCHEDULES}}占位符展开后的文本。它教模型用文件工具管理定时任务,其中的{{SCHEDULE_LIST}}占位符列出任务名。
API 标签页
API 标签页让 Adelie 之外的程序经 HTTP 与这个 Agent 对话:开启 API 访问、API 会话的审批模式、连接下的 Base URL 和 Agent ID、密钥、允许无密钥访问、调用示例,以及只对 Project 所有者显示的试一试:经 API 运行一次这个 Agent,按程序会收到的样子显示事件流。这个标签页没有保存按钮:开关和审批模式改动即生效,关闭 API 访问和删除密钥前会先确认。如何设置、如何调用,见 Agent API。
工作原理
Agent 的配置和数据存放在它的 Agent State 里,也就是概览标签页上 State 路径显示的 agent_state/ 文件夹。里面有 system_config.yaml、AGENTS.md、密钥保险柜、工具、Skill、钩子包、定时任务和记忆。Agent 的 Trace 不在其中,而是存放在它旁边、这个 Agent 自己的文件夹里,见数据目录。