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

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

[1. OpenAgents 是什么？你会用它做什么](#1. OpenAgents 是什么？你会用它做什么)

[2. 运行体系结构](#2. 运行体系结构)

[2.1 三层：Network / Agent / Mod](#2.1 三层：Network / Agent / Mod)

[2.2 事件驱动（Event-Driven）](#2.2 事件驱动（Event-Driven）)

[2.3 两条 Agent 开发路线](#2.3 两条 Agent 开发路线)

[3. 快速上手路线（最推荐）](#3. 快速上手路线（最推荐）)

[3.1 环境准备](#3.1 环境准备)

[3.2 最小闭环：起 Network → 开 Studio → 连 Agent](#3.2 最小闭环：起 Network → 开 Studio → 连 Agent)

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

[4.1 Hello World（最简单）](#4.1 Hello World（最简单）)

[4.2 Startup Pitch Room（多 Agent 对话房间）](#4.2 Startup Pitch Room（多 Agent 对话房间）)

[4.3 Tech News Stream（Python Worker + YAML 评论员）](#4.3 Tech News Stream（Python Worker + YAML 评论员）)

[4.4 Research Team（Router + 项目式委派）](#4.4 Research Team（Router + 项目式委派）)

[4.5 Grammar Check Forum（Forum mod + 自动回复）](#4.5 Grammar Check Forum（Forum mod + 自动回复）)

[5. YAML Agent（CollaboratorAgent）实战要点](#5. YAML Agent（CollaboratorAgent）实战要点)

[5.1 最关键字段](#5.1 最关键字段)

[5.2 触发策略建议（避免"群聊自嗨"）](#5.2 触发策略建议（避免“群聊自嗨”）)

[6. Python Agent（WorkerAgent / AgentClient）实战要点](#6. Python Agent（WorkerAgent / AgentClient）实战要点)

[6.1 WorkerAgent（推荐）](#6.1 WorkerAgent（推荐）)

[6.2 @on_event 自定义事件处理](#6.2 @on_event 自定义事件处理)

[6.3 AgentClient（高级：更底层）](#6.3 AgentClient（高级：更底层）)

[7. 权限与分组（Agent Groups & Permissions）](#7. 权限与分组（Agent Groups & Permissions）)

[8. 发布网络（Publish Your Network）](#8. 发布网络（Publish Your Network）)

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

[9.1 你的第一个可用网络（科研协作版）](#9.1 你的第一个可用网络（科研协作版）)

[9.2 你的第一个"后台 Worker"](#9.2 你的第一个“后台 Worker”)

[10. 跑通最有效的 3 步](#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

启动网络（Network）

从 demo 或 workspace 目录启动（官方 demos 多为：demos/xx_xxx/）：

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

默认通常会暴露：

HTTP：8700（REST/WebSocket）
gRPC：8600（Agent 高性能连接）
Studio：8050（某些 docker/compose 示例会暴露这个端口）

启动 Studio

本地 Studio（取决于你的部署方式，文档多处提示打开类似 http://localhost:8050 连接 localhost:8700）
Studio 用于：进频道聊天、看 agent、做 project、用 forum、管理文件等

启动 Agent

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）。

核心步骤：

网络必须能从公网访问（域名/IP + 端口映射，HTTP 8700 / gRPC 8600）
在官网 Dashboard 发布（填网络地址、名称、描述、标签）
配 network_profile（展示信息、readme、tags、capacity、icon、website 等）
生产检查清单：

防火墙放行端口
持久化存储（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 步

先跑通 demo-research-team（最能体现 OpenAgents 核心：project mod + send_event 委派）
基于它改你的网络：替换 web-searcher/analyst 为你自己的工具链（论文检索、资料整理、代码生成等）
做 agent_groups 权限：把网络从"玩具"升级到"可共享/可发布"的生产形态

#OpenAgents

#Multi-AgentHackathon2025

#多智能体

#智能体网络