1. 文档指引简述
这份指南面向第一次使用 AgentVis 的用户。帮助你把应用从“刚安装完成”带到“可以稳定让 Agent 工作”的状态。
推荐按这个顺序完成：
- 跟随初始引导完成 API 密钥、云端服务和预设技能依赖安装。
- 确认默认模型、Embedding 服务和记忆系统 LLM 已配置。
- 按需要补充 Tavily 搜索、图像生成服务、保护路径和数据备份策略。
- 检查常用技能依赖，特别是浏览器自动化与办公文档相关技能。
- 创建 Agent，并配置 Rules、知识库、定时任务和工作区文件。
- 用一个任务进行试运行，确认 Agent 能正常调用LLM并执行任务。
如果你只是想尽快开始，优先完成第 2、3、4、7、10 节即可。其他部分可以在使用过程中逐步补齐。
2. 完成初始设置
首次进入应用后，AgentVis 会显示「完成初始设置」引导。这个引导会带你跳转到「设置 -> API 密钥」和「设置 -> 云端服务」两个标签页，并提示安装预设技能所需的 Python 依赖。
2.1 配置 API 密钥
进入「设置 -> API 密钥」后，先配置你准备用来驱动 Agent 的模型供应商。常见供应商可以直接填写对应 API Key。
如果你使用自定义兼容 API、中转服务或私有网关，可以使用名为 local 的 provider。它适合接入 OpenAI / Anthropic / Gemini 兼容协议的自定义端点。
local provider 可用于接入自定义兼容 API 或中转服务。2.2 配置云端服务
进入「设置 -> 云端服务」后，至少需要完成 Embedding 模型供应商密钥和记忆系统 LLM 两类配置。建议同时申请并配置 Tavily 密钥，配置后 Agent 可以更稳定地使用网络搜索工具查询公开资料。
图像生成服务不是初始使用的必填项。如果你希望 Agent 直接生成图片、海报或视觉素材，可以按需配置。
2.3 安装预设技能依赖
初始引导顶部会提供安装预设技能 Python 依赖的按钮。点击后等待安装完成，部分内置的技能的完整功能才能正常使用。
依赖安装可能需要一点时间，若网络问题安装失败可以进行重试，或稍后在`设置-技能`标签中点击刷新技能重新检测安装依赖。安装期间不要关闭应用；完成后再创建或使用 Agent。
3. 设置默认模型与模型管理
进入「设置 -> 模型」后，选择默认 provider 和对应 model。这个默认配置会用于创建新 Agent 时的默认模型、技能安装或导入时的安全审查。
你可以在已有供应商下自行添加模型，也可以提供模型名称、API 端点、协议类型等信息，让 Agent 使用内置的 model-config 技能帮你添加或调整模型配置。
建议第一次使用时先选择一个稳定、响应速度合适的主模型。等基础流程跑通后，再为不同 Agent 配置不同模型。
4. 配置保护路径、回收站与数据备份
AgentVis 允许 Agent 读写本地文件、运行命令和处理项目，因此建议在开始处理真实项目之前，先设置好基础安全边界和数据备份。
4.1 自定义保护路径和 Trash Bin
进入「设置 -> 常规」，可以添加自定义保护路径。被保护的路径会在文件操作和命令执行时受到额外防护，降低误删或误改重要目录的风险。
Agent 删除的文件会进入 AgentVis Trash Bin。你也可以在「设置 -> 常规」中直接跳转到 Trash Bin 文件夹查看和恢复，也可定期对agent执行任务后删除的冗余截图或临时文件进行清理。
4.2 备份、恢复与迁移
「设置 -> 常规」中还会展示当前应用关键数据情况。你可以随时导出数据作为备份，也可以导入备份进行恢复。
这对换电脑、重装系统或在另一台设备中迁移 AgentVis 很有帮助。建议在长期使用前先熟悉一次导出和导入流程。
5. 检查技能依赖
进入「设置 -> 技能」后，可以查看已安装技能和它们的类型、启用状态、详情与依赖。
完成初始化向导并安装 Python 依赖后，大多数内置技能已经具备基础运行条件。但有些技能还需要额外的系统级工具依赖。
AgentVis 会对技能进行静态扫描，并在详情中展示可能需要安装的依赖或风险提示，推荐用户提前安装，目的是减少 Agent 在使用技能时遇到的阻塞，当然一般情况下 Agent 会尝试自动安装，但预先安装更利于减少网络失败或超时带来的不稳定。
agent-browser 需要额外安装浏览器自动化相关系统工具依赖。最常见的是 agent-browser。如果你需要让 Agent 使用浏览器自动化能力或内置的视频制作能力，请点开 agent-browser、hyperframes-video 并安装系统工具依赖。
部分办公文档技能也可能需要系统级工具，例如内置的 docx、xlsx、minimax-pdf 等。
建议首次使用浏览器自动化、视频制作、Office、PDF 或表格任务前，先检查对应技能依赖。导入第三方技能时，认真阅读安全审查结果；安装或修改技能后，点击「刷新列表」让技能定义生效。
6. 创建并配置 Agent
创建 Agent 后，建议先完成基础能力配置，再交给它处理复杂任务。
6.1 基础设置、Safety Footer 与决策轮次
进入「Agent 设置 -> 基础」，可以调整 Sub-Agent 的 Safety Footer 和 Planning 决策轮次。
Safety Footer 是 Sub-Agent 每步 LLM 调用尾部注意力区域追加的固定系统提醒。开启后，它会持续影响 Agent 的执行偏好，适合作为任务纠偏、交付质量测试或安全提示的实验性开关。一般用户可默认关闭。
Planning 决策轮次用于限制 Master Brain 的决策次数。默认值为 8，最低 3，最高 20。任务越复杂，可能需要更高轮次；但轮次过高也会增加成本和等待时间。
6.2 Rules：为 Agent 设定角色和行为边界
进入「Agent 设置 -> Rules」，可以分别为 Planning 模式和 Chat 模式设置提示词或规则。
适合写入这里的内容包括 Agent 的角色定位、输出偏好和行为边界。例如“前端工程助手”“先给结论，再给步骤”。
建议先写短规则，等使用中发现偏差后再逐步补充。
7. 配置知识库
进入「Agent 设置 -> 知识库」，可以为当前 Agent 上传文档，让它在任务中检索和引用这些资料。
知识库支持批量上传和批量删除。上传文件后需要点击保存，AgentVis 会调用 Embedding 模型建立索引。删除文件时，对应的向量数据也会同步删除。
如果你希望 Agent 把交付物自动同步到知识库，可以按需要开启或关闭「交付物同步」相关选项。AgentVis 的Rag机制有召回与过滤设计，对于同步到知识库中的文件，原则上“有关才召回，无关则过滤。” 开启时在一定程度上能提升Agent对历史任务的记忆，实际需求根据自身场景进行设置。修改知识库后，建议先用一个简单问题测试 Agent 是否能正确引用资料。
8. 配置定时任务
进入「Agent 设置 -> 定时任务」，可以查看、创建、修改或删除多个不同时间、周期和内容的定时任务。
你可以手动创建定时任务，也可以直接用自然语言让 Agent 帮你制定。例如：
明天下午两点半有个会议要开，提前一点发飞书通知我。Agent 会根据描述生成任务计划。保存后，AgentVis 会在指定时间以 Planning 模式执行。
9. 使用工作区文件和项目目录
AgentVis 的消息输入框和右侧工作区都可以帮助 Agent 获取任务文件来源。
@ 引用文件、拖入文件夹或关联项目目录，让 Agent 获得明确工作上下文。在消息输入框中输入 @，会显示当前工作区文件。你可以输入文件前缀或完整名称精确查找并引用文件。譬如告诉 Agent：“请根据这份计划方案进行实施”。
右侧工作区支持从电脑任意路径拖入文件或文件夹。你也可以通过消息输入框下方的「项目」功能关联目标文件夹。关联后，Agent 会以这个目标文件夹作为工作区开展工作，适合处理代码项目、网页项目或文档项目。
建议第一次试运行时选择一个低风险测试目录，不要直接让 Agent 操作重要生产项目。
10. 推荐第一次试运行任务
完成基础配置后，建议先用低风险任务验证链路是否正常：
请先阅读当前工作区的文件结构，总结这个项目是做什么的，不要修改任何文件。如果你已经关联了项目目录，可以继续测试：
请找出这个项目的启动方式，并告诉我应该运行哪些命令。不要直接执行，只给我建议。确认读文件、模型调用和回复正常后，再尝试让 Agent 执行命令或修改文件。涉及真实文件改动时，优先通过 Diff 审批确认。
11. 快速检查清单
- API 密钥已配置。
- 默认 provider 和 model 已选择。
- Embedding 服务和记忆系统 LLM 已配置。
- 预设技能 Python 依赖已安装。
- 需要联网搜索时，Tavily 已配置。
- 需要图像生成时，图像服务已配置。
- 保护路径和 Trash Bin 位置已了解。
- 重要数据已知道如何导出备份。
- 常用技能依赖已检查，尤其是
agent-browser。 - Agent 已配置 Rules、知识库或定时任务。
- 工作区文件或项目目录已正确关联。
- 第一次任务从只读、低风险任务开始。
12. 下一步可以阅读
- AgentVis 技能使用指南：了解技能安装、启用、绑定和排查。
- AgentVis 沙箱权限与安全审计指南：理解本机审计、受控联网、离线隔离和安全审计。
- IM 机器人配置指南：配置飞书或 Slack 机器人，让 IM 消息触发 Agent 任务。