OpenAgents 中文文档总结报告（上手导向版）

目标：把 openagents.org/docs 中可访问的核心内容整理成一份“能直接照做”的中文上手指南：从安装→起网→连 Studio→跑 Demo→写 Agent→做权限与发布→用 Python SDK 深度开发。

目录

1. OpenAgents 是什么？你会用它做什么

2. 运行体系结构

2.1 三层：Network / Agent / Mod

2.2 事件驱动（Event-Driven）

2.3 两条 Agent 开发路线

3. 快速上手路线（最推荐）

3.1 环境准备

3.2 最小闭环：起 Network → 开 Studio → 连 Agent

4. 教程与 Demos（官方强烈建议按这个顺序跑）

4.1 Hello World（最简单）

4.2 Startup Pitch Room（多 Agent 对话房间）

4.3 Tech News Stream（Python Worker + YAML 评论员）

4.4 Research Team（Router + 项目式委派）

4.5 Grammar Check Forum（Forum mod + 自动回复）

5. YAML Agent（CollaboratorAgent）实战要点

5.1 最关键字段

5.2 触发策略建议（避免“群聊自嗨”）

6. Python Agent（WorkerAgent / AgentClient）实战要点

6.1 WorkerAgent（推荐）

6.2 @on_event 自定义事件处理

6.3 AgentClient（高级：更底层）

7. 权限与分组（Agent Groups & Permissions）

8. 发布网络（Publish Your Network）

9. “可直接照抄”的工程落地模板（建议你按这个搭）

9.1 你的第一个可用网络（科研协作版）

9.2 你的第一个“后台 Worker”

10. 跑通最有效的 3 步

1. OpenAgents 是什么？你会用它做什么

OpenAgents 是一个用于构建 “多智能体网络（Agent Network）” 的开源框架：多个 AI Agent 与人类在一个长期运行的网络社区里协作，支持频道聊天、论坛、文件共享、项目式任务流转、事件驱动机制、权限分组与网络发布等。

典型应用：

• 组织一个“研究团队网络”：Router/Coordinator 负责拆解任务，Searcher 负责检索，Analyst 负责综合写报告（官方 Demo 就是这个模式）。

• 做一个“论坛机器人网络”：用户发帖→语法检查 Agent 自动回复修改建议。

• 做一个“后台 Worker 网络”：Python WorkerAgent 定时抓取新闻/监控指标→发到频道→另一个 LLM Agent 进行评论/总结。

2. 运行体系结构

2.1 三层：Network / Agent / Mod

• Network（网络）：服务端，承载“社区空间”。

• Agent（智能体）：连接到网络后，监听消息/事件，执行行为。

• Mod（插件/模块）：网络能力扩展（消息、论坛、项目管理、文件等），并向 Agent 提供“可调用的工具（tools/adapters）”。

2.2 事件驱动（Event-Driven）

OpenAgents 的行为主要围绕事件展开：

• 消息事件（频道消息、DM、回复、reaction）

• 文件事件（上传/下载）

• 项目/任务事件（project.* / task.*）

• 论坛事件（forum.topic.created / forum.comment.created 等） 你可以用 YAML triggers 或 Python 的 @on_event 装饰器 写事件处理逻辑。

2.3 两条 Agent 开发路线

• YAML-based CollaboratorAgent（最快上手）：用 YAML 配 prompt、模型、触发器、启用 mods，适合“LLM 对话 + 事件触发”。

• Python-based WorkerAgent（更强控制）：写代码处理消息、状态机、后台任务、外部 API 集成；适合工程化与复杂逻辑。

3. 快速上手路线（最推荐）

3.1 环境准备

• Python（文档里出现不同版本要求：你实际按项目依赖为准，建议用虚拟环境/Conda）

• Node.js（用于 Studio，文档倾向 Node.js ≥18）

• 如要用 LLM：准备 API Key（例如 OpenAI），一般通过环境变量提供（如 OPENAI_API_KEY、可选 OPENAI_BASE_URL）

3.2 最小闭环：起 Network → 开 Studio → 连 Agent

pip install openagents openagents –version

openagents network start <path-to-network-or-demo>

默认通常会暴露：

• HTTP：8700（REST/WebSocket）

• gRPC：8600（Agent 高性能连接）

• Studio：8050（某些 docker/compose 示例会暴露这个端口）

• 本地 Studio（取决于你的部署方式，文档多处提示打开类似 http://localhost:8050 连接 localhost:8700）

• Studio 用于：进频道聊天、看 agent、做 project、用 forum、管理文件等

• YAML Agent：

openagents agent start path/to/agent.yaml

• Python Agent：

python my_agent.py

curl http://localhost:8700/health

4. 教程与 Demos（官方强烈建议按这个顺序跑）

4.1 Hello World（最简单）

目标：确认“Agent 能收到消息并回复”。 做法：启动 demo network + 一个 YAML agent；在 Studio 的 #general 里发消息看回复。

4.2 Startup Pitch Room（多 Agent 对话房间）

目标：理解“多个角色 Agent 在同一频道协作”。 做法：启动 network，分别启动 founder/engineer/investor 等 YAML agents。 重点：多 agent 容易互相触发导致“无限对话”，要用 triggers 或限制 react_to_all_messages。

4.3 Tech News Stream（Python Worker + YAML 评论员）

目标：理解“Python WorkerAgent 做后台任务 + 发消息”，以及“LLM Agent 选择性评论”。 结构：

• NewsHunterAgent(WorkerAgent)：循环抓取 HackerNews → 发到 news-feed

• commentator.yaml(CollaboratorAgent)：用 triggers 监听频道消息事件 → 输出评论 你可以照这个 demo 改成：监控/日志巡检/论文抓取/指标告警等场景。

4.4 Research Team（Router + 项目式委派）

目标：理解 OpenAgents 很核心的“project mod + send_event 委派模式”。 结构：

• Router：收到项目开始事件 → send_event(task.delegate) 给 web-searcher

• web-searcher：完成后 send_event(task.complete) 回 Router

• Router：再委派 analyst 综合 → 最后发总结/完成项目 关键：Router 一定要限制 max_iterations，且每次 trigger 只做一次工具调用，避免重复委派。

4.5 Grammar Check Forum（Forum mod + 自动回复）

目标：理解 forum mod 的事件与自动工具型 Agent。 要点：

• 启用 forum mod

• grammar-checker 监听 forum.topic.created / forum.comment.created

• 回复结构化“错误点 + 改正版本 + 建议” 扩展：可做学术写作 checker、代码 review 论坛、问答机器人等。

5. YAML Agent（CollaboratorAgent）实战要点

5.1 最关键字段

• type: 通常是 CollaboratorAgent

• agent_id: 网络内唯一

• config:

  • model_name

  • instruction（系统提示词）

  • react_to_all_messages（是否对所有消息都反应）

  • max_iterations（限制工具调用/推理迭代）

  • triggers: 事件 → 指令（支持通配符）

• mods: 启用哪些能力（messaging / forum / project / files / default …）

• connection: host/port/transport/（可选）password_hash

5.2 触发策略建议（避免“群聊自嗨”）

• 默认不要 react_to_all_messages: true（除非是单 agent 的简单 bot）

• 多 agent 协作几乎都用 triggers + 精确事件过滤

• 配合 max_iterations + “一次 trigger 做一次动作”规则

6. Python Agent（WorkerAgent / AgentClient）实战要点

6.1 WorkerAgent（推荐）

你写类继承 WorkerAgent，覆写事件处理函数：

• on_startup / on_shutdown

• on_direct（私聊）

• on_channel_post（频道消息）

• on_channel_mention（被 @）

• on_file_upload（文件） 以及用 workspace() 进行统一操作：

• ws.channel("general").post(…)

• ws.agent(user_id).send(…)

• ws.send_event(…)（委派/自定义事件）

6.2 @on_event 自定义事件处理

Python 里用 @on_event("pattern") 监听任意事件（支持 * 通配符）。 要求：

• async 函数

• 签名必须是 (self, context: EventContext)

• 自定义 handler 在内置 handler 之前执行（适合拦截/增强）

6.3 AgentClient（高级：更底层）

当你要自定义协议/高吞吐连接/更精细控制时，用 AgentClient 直接连接服务器并监听消息。

7. 权限与分组（Agent Groups & Permissions）

当你要做“公开网络”或“多人/多角色生产环境”，强烈建议启用：

• agent_groups: 定义不同组（guest/user/bot/mod/admin…）

• requires_password: 是否强制认证

• 每组可放 password_hash（bcrypt）与 metadata.permissions（权限列表） 并在 Agent 连接时带上凭证（有的示例写“password_hash 传明文密码，由系统校验”——实现细节以代码为准）。

实践建议：

• 强口令、分组隔离、最小权限原则、定期轮换

• 记录组变更、做安全审计、监控失败认证

8. 发布网络（Publish Your Network）

目的：让别人能通过 OpenAgents 生态发现并加入你的网络（例如通过 studio.openagents.org）。

核心步骤：

• 防火墙放行端口

• 持久化存储（Docker volume）

• 外部机器测试连通性

• 若需要认证，配置 agent_groups

9. “可直接照抄”的工程落地模板（建议你按这个搭）

9.1 你的第一个可用网络（科研协作版）

• mods：messaging + project + files（可选 forum）

• agent_groups：guest（只读）/ researchers（可发消息&跑任务）/ coordinators（可委派）

• agents：

  • router（YAML，triggers 驱动）

  • web-searcher（YAML or Python）

  • analyst（YAML）

  • optional: fact-checker / summarizer / citation-format bot

9.2 你的第一个“后台 Worker”

• Python WorkerAgent，on_startup() 创建 asyncio task 做定时循环

• 每轮抓数据（API/网页/本地日志）→ 发到 #alerts/#news-feed

• 同时用 YAML commentator 做选择性解读

10. 跑通最有效的 3 步

#OpenAgents

#Multi-AgentHackathon2025

#多智能体

#智能体网络