随用户的使用成长和学习的智能体框架 Agent Zero

Agent Zero不是预设好的代理框架，它能在使用中自然成长、学习。

Agent Zero没有为特定任务预先编程（但可以编程），它能作为通用个人助手，接收任务后，会收集信息、执行命令和代码、与其他代理实例协作，尽力完成任务。

Agent Zero有持久内存，能记住之前的解决方案、代码、事实、指令等，以后解决任务时更快、更可靠。

Agent Zero把操作系统当作工具完成任务，没有预先编程的单一用途工具。能自己写代码，用终端创建和使用需要的工具。

Agent Zero自带的工具只有在线搜索、内存功能、通信（与用户和其他代理）、代码/终端执行。

工具使用功能从零开发，兼容性和可靠性强，即使小模型也能运行。

• 默认工具：包含知识、网页内容、代码执行、通信等工具。

• 自定义工具：创建自己的工具，扩展功能。

• 工具集：一种新工具类型，能创建自定义函数和程序，供Agent Zero调用。

多代理协作

每个代理都有上级代理分配任务和指令。每个代理完成后向上级汇报。

如果是链条中的第一个代理（Agent 0），上级就是人类用户；代理对此没有区别。

每个代理都能创建下属代理，帮忙分解和解决子任务。这样所有代理能保持上下文清晰、专注。

完全可定制和扩展

框架中几乎没有硬编码内容。没有隐藏内容。用户能扩展或更改所有内容。

整个行为由prompts/default/agent.system.md文件中的系统提示定义。修改这个提示，就能大幅改变框架。

框架不会以任何方式引导或限制代理。没有代理必须遵循的硬编码规则。

发送给代理的每个提示、每个小消息模板，都能在prompts/文件夹中找到并修改。

每个默认工具都能在python/tools/文件夹中找到，可修改或复制来创建新的预设工具。

沟通是关键

给代理合适的系统提示和指令，它能创造奇迹。

代理能与上级和下属沟通，提问、下达指令、提供指导。在系统提示中指导代理如何有效沟通。

终端界面实时流式传输，可互动。任何时候都能停止并干预。如果发现代理方向错误，随时可以纠正。

这个框架有很大自由度。可以指示代理定期向上级汇报，请求继续许可。可以指示它们在决定何时委托子任务时使用评分系统。上级可以仔细检查下属的结果并提出异议。可能性无穷无尽。

Agent Zero提供基于Kali Linux的黑客版，带有针对网络安全任务的修改提示。

设置和普通版本一样，只需使用frdel/agent-zero-run:hacking镜像，而不是frdel/agent-zero-run。、

Agent Zero安装指南

安装Docker Desktop

Docker Desktop提供运行环境，确保跨平台行为一致、安全。

整个框架在Docker容器中运行，隔离性好，部署方便。

支持所有主流操作系统，有友好的GUI应用。

1、进入Docker Desktop下载页面。如果链接无效，搜索“docker desktop download”。

2、下载对应操作系统的版本。Windows用户，Intel/AMD版本在主下载按钮。

3、运行安装程序，使用默认设置。macOS上，将应用拖到Applications文件夹。

4、安装完成后，启动Docker Desktop。

重要配置

macOS配置：在Docker Desktop偏好设置（Docker菜单）→ 设置 → 高级，启用“允许使用默认Docker套接字（需要密码）”。

运行Agent Zero

注意：Agent Zero提供基于Kali linux的黑客版，带网络安全任务修改提示。设置和普通版本相同，只需使用frdel/agent-zero-run:hacking镜像，而非frdel/agent-zero-run。

1、拉取Agent Zero Docker镜像：

在Docker Desktop中搜索frdel/agent-zero-run，点击“Pull”按钮。镜像几分钟内下载到本地。

也能在终端运行：docker pull frdel/agent-zero-run。

2、创建数据目录用于持久化：

选择或创建一个目录，存储Agent Zero数据。可以是任何位置（如C:/agent-zero-data或/home/user/agent-zero-data）。

这个目录包含所有文件，如：

• /memory - 代理的记忆和学习信息

• /knowledge - 知识库

• /instruments - 工具和函数

• /prompts - 提示文件

• /work_dir - 工作目录

• .env - API密钥

• settings.json - 设置

选择容易访问和备份的位置。所有数据都能直接在这个目录中访问。

3、运行容器：

在Docker Desktop，回到“镜像”标签，点击frdel/agent-zero-run镜像旁的“运行”按钮。

打开“可选设置”菜单，在第二个“主机端口”字段中设置端口为0（自动分配端口）。

可选：映射本地文件夹用于文件持久化。在“卷”下配置：

• 主机路径：选择的目录（如C:\agent-zero-data）

• 容器路径：/a0

也能在终端运行：

docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run

替换$PORT为要使用的端口（如50080），/path/to/your/data为选择的目录路径。

4、访问Web界面：

框架初始化需要几秒，Docker日志会显示进度。

在Docker Desktop中找到映射的端口（格式为<PORT>:80），或点击容器ID下方的端口。

在浏览器中打开http://localhost:<PORT>。Web界面打开后，Agent Zero即可配置！

启动容器后，所有文件会在选择的目录中。直接在本地机器上访问和编辑这些文件，修改会立即反映在运行的容器中。

配置Agent Zero

以下部分介绍如何全面配置Agent Zero。

设置配置

Agent Zero提供全面的设置界面，自定义各种功能。点击侧边栏带齿轮图标的“设置”按钮访问设置。

代理配置

• 提示子目录：选择/prompts中的子目录，自定义代理行为。“default”目录包含标准提示。

• 内存子目录：选择代理内存存储的子目录，区分不同实例。

• 知识子目录：指定自定义知识文件的位置，增强代理理解。

聊天模型设置

• 提供商：选择聊天模型提供商（如Ollama）。

• 模型名称：选择具体模型（如llama3.2）。

• 温度：调整响应随机性（0为确定，值越高越有创造性）。

• 上下文长度：设置LLM上下文窗口的最大令牌限制。系统提示、聊天历史、RAG和响应都计入这个限制。

• 聊天历史的上下文窗口空间：上下文窗口中用于聊天历史的部分。聊天历史会自动优化以适应。比例越小，历史越短、越精简。剩余空间用于系统提示、RAG和响应。

• 聊天模型附加参数：模型支持的其他参数。格式为每行KEY=VALUE，类似.env文件。

实用模型配置

• 提供商和模型：选择更小、更快的模型，用于内存组织和总结等实用任务。

• 温度：调整实用响应的确定性。

嵌入模型设置

• 提供商：选择嵌入模型提供商（如OpenAI）。

• 模型名称：选择具体嵌入模型（如text-embedding-3-small）。

语音转文字选项

• 模型大小：选择语音识别模型大小。

• 语言代码：设置语音识别的主要语言。

• 静音设置：配置静音阈值、持续时间和超时参数，优化语音输入。

API密钥

在Web界面中直接配置各种服务提供商的API密钥，点击“保存”确认设置。

认证

• UI登录：设置Web界面访问的用户名。

• UI密码：配置Web界面的安全密码。

• root密码：管理Docker容器的root密码，用于SSH访问。

开发设置

• RFC参数（仅本地实例）：配置实例间远程函数调用的URL和端口。

• RFC密码：配置远程函数调用的密码。

选择LLM

设置页面是选择驱动Agent Zero的大型语言模型（LLM）的中心。可以为不同角色选择不同的LLM：

LLM角色

描述

chat_llm

用于对话和生成响应的主要LLM。

utility_llm

处理内部任务，如消息总结、内存管理、内部提示处理的LLM。用更小、更便宜的模型能提高效率。

embedding_llm

生成嵌入的LLM，用于内存检索和知识库查询。更改embedding_llm会重新索引所有内存。

打开Web界面的设置页面，为每个角色（聊天模型、实用模型、嵌入模型）选择提供商，输入模型名称，点击“保存”应用更改。

注意事项

更改embedding_llm会重新索引所有内存和知识，需要清空memory文件夹避免错误，因为向量数据库中不能混合嵌入。注意这会删除Agent Zero的所有记忆。

安装和使用Ollama（本地模型）

如果想使用Ollama（能在本地运行各种大型语言模型的工具），按以下步骤安装和使用：

第一步：安装

• Windows：从官网下载Ollama并安装。

• macOS：运行brew install ollama，或从官网下载安装程序。

• Linux：运行curl -fsSL https://ollama.com/install.sh | sh。

查找模型名称：访问Ollama模型库，查看可用模型及对应名称。格式通常是provider/model-name（有时只需model-name）。

第二步：拉取模型

在Windows、macOS和Linux上运行：

ollama pull <model-name>

替换<model-name>为要使用的模型名称。例如，拉取Mistral Large模型，运行ollama pull mistral-large。

终端会确认模型已下载到系统。

在Agent Zero中选择模型

下载模型后，必须在GUI的设置页面中选择。

在聊天模型、实用模型或嵌入模型部分，选择Ollama作为提供商，按Ollama要求输入模型代码（如llama3.2或qwen2.5:7b），点击“保存”确认设置。

管理已下载的模型

• 列出已下载的模型：运行ollama list。

• 删除模型：运行ollama rm <model-name>。

尝试不同的模型组合，找到适合的性能和成本平衡。例如，更快、延迟更低的LLM有帮助，也能在内存中用faiss_gpu替代faiss_cpu。

在移动设备上使用Agent Zero

Agent Zero的Web界面可通过Docker容器在网络中的任何设备上访问：

Docker容器自动在所有网络接口上暴露Web界面。

在Docker Desktop中找到映射的端口（格式通常为<PORT>:80），例如32771:80，端口就是32771。

从任何设备访问Web界面：

• 本地访问：http://localhost:<PORT>

• 网络访问：http://<你的电脑IP>:<PORT>

电脑的IP地址通常是192.168.x.x或10.0.x.x，可通过运行ipconfig（Windows）或ifconfig（Linux/Mac）查看。

端口由Docker自动分配，除非手动指定。

如果不使用Docker，直接在系统上运行Agent Zero，需要在run_ui.py中手动配置主机，设置host="0.0.0.0"。

开发者或需要直接在系统上运行Agent Zero的用户，查看完整二进制安装的深入指南。

如何更新Agent Zero

如果从旧版本升级：

数据安全存储在Agent Zero文件夹的多个目录和文件中。

要更新到新的Docker运行版本，建议备份以下文件和目录：

• /memory - 代理的记忆

• /knowledge - 自定义知识库（如果导入了自定义知识文件）

• /instruments - 自定义工具和函数（如果创建了自定义内容）

• /tmp/settings.json - 设置

• /tmp/chats/ - 聊天历史

保存这些文件和目录后，按上面的安装指南安装Docker运行时版本。

将保存数据的文件夹复制到安装时设置的新Agent Zero文件夹中。

Agent Zero会自动检测保存的数据，在内存、知识、工具集、提示和设置中使用。

注意：如果加载设置时遇到问题，可以尝试删除/tmp/settings.json文件，让Agent Zero生成新文件。/tmp/chats/中的聊天记录也可能与新版本不兼容。

更新流程（Docker Desktop）

1、在Docker Desktop的“容器”标签停止容器。

2、右键点击，选择“删除”移除容器。

3、进入“镜像”标签，删除frdel/agent-zero-run镜像，或点击三个点拉取更新镜像。

4、搜索并拉取新镜像（如果选择删除旧镜像）。

5、用与旧容器相同的卷设置运行新容器。

确保运行新容器时使用相同的卷挂载路径，以保留数据。具体路径取决于Agent Zero数据目录的存储位置。

也能在终端运行以下命令：

# 停止当前容器
docker stop agent-zero

# 删除容器（数据在文件夹中安全存储）
docker rm agent-zero

# 删除旧镜像
docker rmi frdel/agent-zero-run

# 拉取最新镜像
docker pull frdel/agent-zero-run

# 用相同的卷挂载运行新容器
docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run

完整二进制文件

使用Git/GitHub：拉取Agent Zero仓库的最新版本。

自定义知识、解决方案、内存和其他数据会被忽略，不用担心丢失自定义数据。.env文件（含所有API密钥）和settings.json也是如此。

警告：如果手动更新，注意保存含API密钥的.env文件，查看requirements.txt中的新依赖。

如果更新版本的依赖有变化，激活a0 conda环境后，在环境中执行： pip install -r requirements.txt

Agent Zero使用指南

基本操作

Agent Zero通过界面提供多项基本操作：

重启框架

“重启”按钮能快速重启Agent Zero框架，不用终端：

1、点击侧边栏的“重启”按钮。

2、会出现蓝色通知“正在重启...”。

3、完成后，显示绿色成功消息“已重启”。

4、框架重新初始化，同时保留当前聊天历史和上下文。

重启功能适合：

• 遇到意外行为时重置框架

• 代理无响应时重新初始化系统

操作按钮

在聊天输入框下方，Agent Zero提供一组操作按钮，增强控制和可见性：

聊天流程控制

暂停/恢复代理：切换按钮，暂停和恢复聊天流程。

• 点击暂停正在进行的代理操作。

• 暂停时按钮变为“恢复代理”。

• 再次点击恢复聊天流程和命令执行。

知识和文件管理

导入知识：将外部文件导入代理的知识库。

支持.txt、.pdf、.csv、.html、.json和.md格式。

文件存储在\knowledge\custom\main，成功导入会显示确认消息。

文件浏览器：管理Agent Zero环境中的文件。

• 上传新文件和文件夹。

• 下载文件（点击文件名）或文件夹（作为zip压缩包）。

• 删除文件和文件夹。

• 用“上一级”按钮导航目录。

• 即将支持文件重命名和搜索。

调试和监控

上下文：查看发送给LLM的完整上下文窗口，包括系统提示、当前对话上下文、活动指令和参数。

历史：访问JSON格式的聊天历史，查看LLM处理的对话，方便调试和理解代理行为。

轻推：重启代理的最后一个进程，适合代理无响应时重试上次操作，帮助从停滞状态恢复。

文件附件

Agent Zero支持在聊天界面中直接附加文件，方便文件操作：

附加文件

点击聊天输入框左侧的附件图标（📎），选择一个或多个文件附加。

发送前可预览附加文件：

• 显示文件名及类型（HTML、PDF、JPG等）。

• 图片会显示缩略图（如果有）。

• 文件列在聊天输入区域，等待发送。

处理附加文件

可以在消息中直接引用文件。

Agent Zero能：

• 处理附加文件。

• 将文件移动到特定目录。

• 同时对多个文件执行操作。

• 详细响应，确认文件操作成功。

处理多个文件时，可以一次附加所有文件，然后给出处理指令。代理会批量处理，并随时告知进度。

工具使用

Agent Zero的优势在于使用工具的能力。以下是有效使用工具的方法：

了解工具：Agent Zero包含默认工具，如知识（由SearXNG支持）、网页内容、代码执行、通信。了解这些工具的功能和调用方式。

工具使用示例：网页搜索和代码执行

如果想让Agent Zero执行财务分析任务，提示可以是：

“请作为专业金融分析师。找到上个月比特币/美元价格趋势，在环境中制作图表。图表必须突出显示与加密货币重大新闻日期对应的关键点。用'knowledge_tool'查找价格和新闻，用'code_execution_tool'完成其余工作。”

Agent Zero可能会：

1、用knowledge_tool查询可靠来源，获取比特币价格和加密货币新闻。

2、从搜索结果中提取价格，保存新闻，提取日期和可能对价格的影响。

3、用code_execution_tool执行Python脚本，使用提取的数据和新闻日期创建图表，突出显示关键点。

4、返回最终图表（在/work_dir中找到），用response_tool向用户回复。

注意：code_execution_tool第一次运行可能需要一段时间，因为要下载和构建Agent Zero Docker镜像。后续运行会更快。

这个例子展示了如何组合多个工具完成分析任务。掌握提示工程和工具使用，能充分发挥Agent Zero解决复杂问题的能力。

多代理协作

Agent Zero的独特功能之一是多代理协作。

创建子代理：代理能创建子代理，委托子任务。有助于管理复杂性，分配工作量。

通信：代理之间能相互通信，共享信息，协调行动。系统提示和消息历史在引导通信中起关键作用。

层级：Agent Zero采用层级结构，上级代理向下属委托任务。这样能结构化解决问题，高效分配资源。

语音界面

Agent Zero提供文字转语音（TTS）和语音转文字（STT）功能，支持自然语音交互：

文字转语音

启用代理的语音响应：

在侧边栏的偏好设置中，切换“语音”开关。

代理会用系统内置语音合成器朗读消息。

点击输入区域上方的“停止语音”按钮，可立即停止正在进行的语音。

界面允许用户随时停止语音，如果响应太长，或想在对话中干预。

TTS使用现代浏览器提供的标准语音接口，可能听起来像机器人，但有效，不需要复杂的AI模型。这样能确保低延迟，在包括移动设备在内的各种平台上快速响应。

文字转语音功能适合：

• 接收代理响应时同时处理其他任务

• 无障碍使用

• 创造更互动的体验

语音转文字

用OpenAI的Whisper模型向代理发送语音消息（不需要OpenAI API密钥！）：

点击输入区域的麦克风按钮开始录音。

按钮颜色表示当前状态：

• 灰色：未激活

• 红色：正在监听

• 绿色：正在录音

• 青色：等待

• 青色（脉冲）：处理中

用户能调整静音阈值和消息发送前的时长等设置，优化交互体验。

在设置页面配置STT：

• 模型大小：选择基础版（74M，英语）或其他模型（注意：只有大型和涡轮模型支持多种语言）。

• 语言代码：设置偏好语言（如'en'、'fr'、'it'、'cz'）。

• 静音检测：

• 阈值：调整灵敏度（值越低越敏感）。

• 时长：设置静音持续多久后结束录音。

• 超时：设置关闭麦克风前的最长等待时间。

数学表达式

Agent Zero支持KaTeX，能美观地排版数学表达式：

• 行内数学：用单美元符号$...$表示行内表达式。

例如：输入圆的面积是$A = πr^2$，显示为：圆的面积是A = πr²。

• 显示数学：用双美元符号$$...$$表示居中显示的等式。

例如：输入$$F = G\frac{m_1m_2}{r^2}$$，显示为居中的等式。

复杂数学：支持完整的KaTeX语法，包括分数、指数、根号、矩阵、数组、希腊字母、数学符号、积分、求和、极限、数学对齐和等式。

询问代理数学问题时，它会自动用KaTeX格式响应，让数学表达式清晰、专业。