创建你的第一个 Agent

本教程带你完整跑通从零开始的配置流程，并最终由一个具名 Agent 回答一个简单请求。在发送请求前先配置模型，随后无论在终端还是浏览器中都可以与同一个 Agent 交互。

前置条件

你需要一个终端环境以及对受支持模型提供商的访问权限。如果使用本地模型提供商，必须确保其模型服务已正常运行且网络可达。第一次执行无需准备模板、项目工作区或外部事件集成。

brew tap holon-run/tap
brew install holon

从 GitHub Releases 下载适用于你操作系统与架构的二进制文件，根据需要添加执行权限，并放入系统的 PATH 路径中。

如果你打算对 Holon 自身进行开发，请遵循本地编译工作流程。

holon --help

若提示找不到命令，请在继续前检查并修正你的 PATH 环境变量。

holon onboard
holon config doctor

交互式向导会引导你选择模型提供商、配置凭据并选定模型。如果你在提示过程中需要指导，请参考引导配置指南。在继续之前解决所有凭据缺失或模型不可用的报错；切勿在 Agent 对话中直接粘贴敏感密钥。

holon daemon start
holon daemon status

检查状态命令是否报告守护进程处于运行中。守护进程负责托管 Agent 及其工作状态，支持各类客户端随时连接与断开。

选择一个未被使用的 ID；本示例使用 first-helper：

holon agent create first-helper
holon agent list
holon run --agent first-helper "用三句话解释 Rust 的所有权机制。不要修改任何文件。"

确认列表中包含 first-helper，且请求输出了有效解答。Agent 出现在列表中仅代表创建成功，不代表模型一定能正常应答；这句简短的请求同时对这两者进行了验证。如果报错，请检查错误提示并再次运行 holon config doctor。

全新的运行时也内置提供了 main Agent。你可以直接使用它，而无需专门创建具名 Agent。不过，具名 Agent 有助于将持续的独立职责与其他日常交互分离开来；详见 Agent、角色与指引。

holon tui

在发送后续请求前，先选择 first-helper。输入 / 可打开命令菜单，输入 /help 可查看当前快捷键。有关界面导航和命令用法，请参阅 TUI 参考。

你也可以使用 Web GUI。无论使用哪种客户端，先确认当前选中的 Agent ID，以确保后续交互递送给同一个 Agent。

对于不需要持久守护进程会话的有界请求，可以直接单次运行：

holon run "用三句话解释 Rust 的所有权机制"

单次运行可能包含多轮模型与工具交互才能最终退出。请不要将其用作需要等待 CI 或后续人工决策的跟踪手段；长生命周期工作请参阅运行长生命周期任务。

所有工作结束后，可以通过 holon daemon stop 停止本地守护进程。不要单纯为了关闭某个客户端窗口而停止守护进程，因为其他 Agent 可能仍在后台推进任务。

原“快速示例”页面现已重定向至此。若要了解初次运行之外的进阶工作流，请参阅下列专项指南：

执行 holon daemon status 与 holon daemon logs 检查日志。根据报告的启动报错进行针对性排查，不要随意删除运行时数据或反复重复启动。

确认守护进程正在目标主机上正常运行。对于远程连接，请遵循前述远程指南进行配置，不要假设本地套接字可以跨机器通信。

运行 holon config doctor 检查模型与凭据状态。可结合前述模型配置指南进行核对。如果请求已被受理但执行报错或停滞不前，请参阅排查 Holon 任务问题。