Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

25.2 KB
Raw Blame

title: 智能体 description: 创建 Agent,配置它的提示词、工具、Skill、钩子、记忆、密钥保险柜、定时任务和 API。

Agent 是 Project 里配置好的助手。每个 Agent 都有自己的指令、运行参数、工具、Skill、钩子包、记忆、密钥保险柜变量和定时任务,这些内容存放在一起,构成它的 Agent State。创建 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 会替你把它创建出来。

  1. 在智能体页面选择用 AI 创建,打开用 AI 创建 Agent 对话框。
  2. 描述这个 Agent 做什么、为谁服务、产出什么。想从示例开始,就在试试这些示例下选一个:随记智能体、金融 Copilot、文档 RAG 智能体、深度研究报告智能体或报告写作智能体。
  3. 可选:展开完整提示词,查看会随描述一起发送的指令;也可以选择复制提示词。
  4. 选择在新对话中编辑。会打开一个新对话,提示词已填好,此时还没有发送。
  5. 检查提示词并发送。

对话框会写明由哪个 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

  1. 在智能体页面选择手动创建,打开创建 Agent 对话框。
  2. 可选:在名称中填写名称。名称留空时用 Agent id。
  3. 在 Agent id 中输入 id,也可以点击输入框旁边的用 AI 生成,由 Project 里一个免费(0 定价)的模型根据名称生成一个,一个不行就换下一个;名称为空时则根据描述生成。这一步不花钱,默认模型不参与。id 长度为 2–64 个字符,以小写字母开头,只能用小写字母、数字和下划线。生成的 id 会覆盖框里原有的内容,之后仍可以手动修改。创建后 id 不能再改。
  4. 可选:填写描述。
  5. 可选:在插件中从插件库选择要装到新 Agent 上的插件。Agent 创建时会一并装上这些插件的 Skill 和钩子包。
  6. 可选:在从项目目录导入技能中选择一个目录。Adelie 会读取这个目录下 .agents/skills 和 .claude/skills 文件夹里的 Skill,从中勾选要安装的。目录里的 Skill 与所选插件里的 Skill 同名时,装的是目录里的那个。
  7. 选择创建,打开新 Agent 的设置。

任何 Project 成员都能创建 Agent。

从快照创建

快照包是导出的 Agent State。可以基于它创建 Agent,例如把 Agent 复制到另一个 Project 或另一台机器。

开始之前

  • 要复制的 Agent 的快照包(.tar.gz)。单个包最大 14 MB。制作方法见导出和导入快照。
  1. 在创建 Agent 对话框中,在从快照初始化下点击选择快照包,选定包文件。Agent id 为空时,会按文件名自动填入。
  2. 名称和描述留空则沿用包里的值,填写则覆盖。
  3. 选择创建。

[!NOTE] 快照包自带 Skill 和钩子。选定快照包后,插件和从项目目录导入技能会隐藏。

删除 Agent

只有 Project owner 能删除 Agent。内置的 default_agent 不能删除。

  1. 在 Agent 卡片上选择删除按钮(删除 Agent)。
  2. 确认。

[!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 发布新默认值后,内核区块会显示当前内核版本和最新内核版本,概览标签页上出现红点。

  1. 在内核区块选择更新内核。
  2. 确认。

没有自定义过的标签页会更新为当前的内置默认值。编辑过的标签页整个保持不变,并在结果中列出。名称、描述、Agent State 版本和 MCP Server 不受影响。详情见内核更新。

[!TIP] 要一次更新多个 Agent,可以在智能体页面顶部的通知里选择现在升级。

还原为默认配置

  1. 在内核区块选择还原为默认配置。
  2. 确认。

[!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 区块里的改动立即保存。

  1. 在工具标签页选择添加 MCP Server。
  2. 选择传输方式:
    • http(默认):Streamable HTTP,当前的远程传输方式。
    • stdio:本地进程,由 Adelie 启动,通过 stdin 和 stdout 通信。
    • sse:旧的 HTTP+SSE 传输方式,供尚未迁移的 Server 使用。
  3. 在 name 中输入工具名前缀,可以用字母、数字、_ 和 -,以字母或数字开头。
  4. 填写连接字段:
    • stdio:command;args,每行一个参数;env,每行一个 KEY=value;cwd,默认是 Session 的 Workspace。Agent 的密钥保险柜变量不会传给 MCP Server 进程。
    • http 和 sse:url;headers,每行一个 Header-Name: value,例如 Authorization 请求头。
  5. 选择 permission:
    • Auto(readOnlyHint):工具声明了 readOnlyHint 注解就按只读处理,否则按 Read & write 处理。
    • Read-only:Server 的所有工具都按只读处理。
    • Read & write:Server 的所有工具都按 Read & write 处理。
  6. 可选:调整 connectTimeoutMs(连接和发现工具,默认 10000)、timeoutMs 和 maxOutputLength,这些设置对 Server 的所有工具生效。
  7. 可选:保存前选择测试连接验证配置,它会报告发现的工具数量和耗时。
  8. 选择保存。

[!NOTE] permission 级别只在「放行只读」审批模式下起作用,其他审批模式都会忽略它。它也不限制 Server 能做什么:把 Server 标为只读,只是让这个审批模式跳过本该弹出的确认。

要修改某个 Server,在它的行上选择编辑。要移除,选择删除并确认;从下一个 Session 开始,它的工具不再可用。更多关于 MCP Server 的内容见 MCP Server。

测试 MCP Server

  1. 在 MCP Server 区块选择测试连接。
  2. 选择开始测试。

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 修改,不能就地编辑。

添加记忆

  1. 在分组标题上选择添加,打开添加记忆对话框。
  2. 在要记住的内容或来源里粘贴内容、文件路径或 URL。
  3. 选择打开新对话,然后发送消息。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 能修改密钥保险柜。成员能看到变量名,值以掩码显示。

添加变量

  1. 在密钥保险柜标签页选择手动创建,打开添加环境变量对话框。
  2. 在键名中输入变量名,例如 OPENAI_API_KEY。可以用字母、数字和下划线,不能以数字开头。
  3. 在值中输入变量值。
  4. 选择添加。变量已存在时,确认后覆盖原值。

要删除变量,在它的行上选择删除并确认。值无法恢复。

用 AI 添加变量

选择用 AI 创建会打开让 AI 添加密钥。描述需要的变量,或选一个示例:盘点这个智能体需要的 key、重置一个过期 token 或 接入一个内部服务。然后选择在新对话中编辑并发送提示词。Project 的默认 Agent 会用 penguin config vault set 写入变量。

[!WARNING] 在这个对话框里输入的密钥值会发送给模型供应商,记录进对话的 Trace,还会在 Agent 运行的命令里再次出现。更安全的做法是让 AI 只创建变量名并说明各自用途,然后你在密钥保险柜标签页自己填入值。

保险柜提示词

  • 启用密钥保险柜控制密钥保险柜区块是否进入系统提示词。关闭时,变量仍然会传给 Agent 的命令。
  • 保险柜提示词:{{VAULT}} 占位符展开后的文本。其中的 {{VAULT_KEYS}} 占位符列出变量名,每行一个。

定时任务标签页

定时任务按计划给 Agent 发送提示词:发一次,或按周期反复发。这个标签页上的修改立即生效。

[!NOTE] 定时任务只在 Adelie 服务运行时触发。

也可以在对话里创建和管理定时任务,见定时任务。

创建定时任务

只有 Project owner 能手动创建定时任务。

  1. 在定时任务标签页选择手动创建,打开新建定时任务对话框。
  2. 在名称中输入任务的文件名,不带 .toml。创建后不能修改。
  3. 在周期中输入任务运行频率,例如 30m、12h 或 7d。一次性任务留空。最短周期为 5 分钟。
  4. 设置开始时间,也可以设置结束时间。一次性任务的开始时间必须晚于当前时刻,结束时间不能早于当前时刻。
  5. 在目标下选择提示词发到哪里:
    • 每次新建会话:每次运行都新建一个 Session。可以再选 Model(不选就用 Project 默认值)和 Workspace(不选就用临时 Workspace)。
    • 绑定 Session:每次运行都发给同一个已有的 Session。在 Session 中选择。
  6. 在 Prompt 中输入要发送的内容。
  7. 保持勾选启用以激活任务,然后选择创建。

也可以用描述的方式创建:选择用 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 自己的文件夹里,见数据目录。

  • 记忆是 agent_state/memory/ 下的文件,每个分组有一个 MEMORY.md 索引。存储方式见记忆。
  • 密钥保险柜变量保存在 agent_state/.vault.toml。文件格式见密钥保险柜。
  • 定时任务以 TOML 文件保存在 agent_state/schedule/ 下,也可以手动编辑。文件格式见定时任务。