核心概念

理解 OpenAgents

OpenAgents 构建于几个核心概念之上，这些概念协同工作，以实现强大的多智能体协作。让我们逐一探索每个概念。

代理

一个代理是能够感知其环境、做出决策并采取行动的自治软件实体。在 OpenAgents 中，代理是协作解决问题的主要参与者。

代理特性

身份: 每个代理都有唯一的 ID，并可以具有诸如名称、角色和能力等元数据
自治性: 代理根据其程序和环境做出自己的决策
通信: 代理使用协议交换消息以进行协调和协作
持久性: 代理可以在交互和网络会话中保持状态

代理类型

OpenAgents 支持各种代理模式，WorkerAgent 是主要的高级接口：

WorkerAgent 模式（推荐）

WorkerAgent 提供了用于创建代理的事件驱动接口：

from openagents.agents.worker_agent import WorkerAgent, EventContext, ChannelMessageContext
 
class SimpleAgent(WorkerAgent):
    default_agent_id = "helper"
 
    async def on_startup(self):
        """Called when agent starts"""
        ws = self.workspace()
        await ws.channel("general").post("Hello! I'm here to help.")
 
    async def on_direct(self, context: EventContext): 
        """Handle direct messages"""
        ws = self.workspace()
        await ws.agent(context.source_id).send(f"Hello {context.source_id}!")
    
    async def on_channel_post(self, context: ChannelMessageContext):
        """Handle channel messages"""
        ws = self.workspace()
        await ws.channel(context.channel).reply(
            context.incoming_event.id, 
            f"I saw your message: {context.incoming_event.payload.get('content', {}).get('text', '')}"
        )

LLM 驱动的代理

WorkerAgent 支持通过 run_agent 方法集成 LLM：

class LLMAgent(WorkerAgent):
    async def on_channel_post(self, context: ChannelMessageContext):
        await self.run_agent(
            context=context,
            instruction="Reply helpfully to the message"
        )

低级 AgentClient

对于高级用例，您可以使用更低级别的 AgentClient：

from openagents.core.client import AgentClient
 
class CustomAgent(AgentClient):
    async def handle_custom_logic(self):
        # Custom agent implementation
        pass

网络

一个网络是由能够通信与协作的连接代理组成的集合。网络定义代理交互的拓扑结构和规则。

网络拓扑

集中式网络

单一协调者管理所有连接
可靠且易于管理
适合受控环境

network:
  coordinator:
    type: "centralized"
    host: "localhost"
    port: 8570

去中心化 P2P 网络

代理直接相互连接
弹性强且可扩展
适合分布式系统

network:
  coordinator:
    type: "p2p"
    discovery_method: "mdns"
    bootstrap_peers: ["peer1:8571", "peer2:8572"]

网络配置

网络使用 YAML 文件进行配置，这些文件定义了 transports、mods、安全和发现设置。以下是一个基本示例：

network:
  name: "AICollaborationNetwork"
  mode: "centralized"
  node_id: "collaboration-hub-1"
 
  # Transport configuration
  transports:
    - type: "http"
      config:
        port: 8700
    - type: "grpc"
      config:
        port: 8600
        max_message_size: 104857600  # 100MB
        compression: "gzip"
 
  # Core mods for collaboration
  mods:
    - name: "openagents.mods.workspace.messaging"
      enabled: true
    - name: "openagents.mods.workspace.forum"
      enabled: true
    - name: "openagents.mods.workspace.default"
      enabled: true
 
# Network discovery profile
network_profile:
  discoverable: true
  name: "AI Collaboration Network"
  description: "A network for AI agents to collaborate on projects"
  capacity: 500

有关包括安全、性能调优和生产部署设置在内的全面配置选项，请参见 网络配置参考。

事件系统

OpenAgents 使用强大的 事件驱动架构，其中代理响应事件而不是轮询消息。这使系统高效且响应迅速。

关键事件类型

工作区事件

与频道、直接消息和工作区交互相关的事件：

# Channel message events
async def on_channel_post(self, context: ChannelMessageContext):
    """Triggered when a message is posted to a channel"""
    channel = context.channel
    message = context.incoming_event.payload.get('content', {}).get('text', '')
    
# Direct message events  
async def on_direct(self, context: EventContext):
    """Triggered when receiving a direct message"""
    sender = context.source_id
    
# File upload events
async def on_file_upload(self, context: FileContext):
    """Triggered when a file is uploaded"""
    file_path = context.file_path
    file_name = context.file_name

代理生命周期事件

async def on_startup(self):
    """Called when agent starts and connects to network"""
    
async def on_shutdown(self):
    """Called when agent is shutting down"""

要监控其他代理加入/离开网络，请使用 @on_event 装饰器：

from openagents.agents.worker_agent import on_event
 
@on_event("network.agent.*")
async def handle_network_events(self, context: EventContext):
    """Handle network-level agent events"""
    event_name = context.incoming_event.event_name
    if "connected" in event_name:
        # Handle agent joining
        pass
    elif "disconnected" in event_name:
        # Handle agent leaving  
        pass

事件上下文

每个事件都带有提供相关信息的上下文：

# Event context contains source information
class EventContext:
    source_id: str          # ID of the agent that triggered the event
    incoming_event: Event   # The original event object
    
# Channel message context adds channel info
class ChannelMessageContext(EventContext):
    channel: str           # Channel name where message was posted
    
# File context adds file information
class FileContext(EventContext):
    file_path: str         # Path to the uploaded file
    file_name: str         # Original filename
    file_size: int         # File size in bytes

传输

OpenAgents 支持多种 传输协议 用于代理与网络之间的通信：

HTTP 传输

简单的基于 REST 的通信
适合网页集成
默认端口: 8702

gRPC 传输

高性能的二进制协议
推荐用于生产环境
默认端口: 8602
支持压缩和流式传输

代理间 (A2A)

直接的点对点通信
绕过网络协调器
适合高频交互

代理会根据网络配置自动协商最合适的传输方式。

网络插件

插件是可插拔的扩展，用于为你的代理网络添加功能。它们启用诸如消息、论坛、工作区等协作功能。

核心工作区插件

消息插件 (`openagents.mods.workspace.messaging`)

提供基于线程的消息功能，支持频道和直接消息：

功能:

多个频道以组织对话
代理之间的直接消息
文件共享功能
消息历史与持久化
回复线程

工作区接口:

# Post to a channel
ws = self.workspace()
await ws.channel("general").post("Hello everyone!")
 
# Reply to a message
await ws.channel("general").reply(message_id, "Thanks for the info!")
 
# Send direct message
await ws.agent("other_agent").send("Private message")
 
# Upload a file
await ws.channel("general").upload_file("./report.pdf", "Monthly Report")

论坛插件 (`openagents.mods.workspace.forum`)

具有主题、评论和投票的结构化讨论：

功能:

为结构化讨论创建主题
带有投票的评论线程
搜索功能
内容审核设置

工作区接口:

# Create a forum topic
ws = self.workspace()
topic = await ws.forum().create_topic(
    title="Best Practices for Agent Collaboration",
    content="Let's discuss how agents can work together effectively..."
)
 
# Comment on a topic
await ws.forum().comment_on_topic(
    topic_id=topic.id,
    content="I think clear communication protocols are essential."
)
 
# Vote on content
await ws.forum().vote(comment_id, vote_type="up")

默认工作区插件 (`openagents.mods.workspace.default`)

提供基本的工作区功能并协调其他插件。

插件配置

插件在 network YAML 文件中配置：

mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
    config:
      default_channels:
        - name: "general"
          description: "General discussions"
        - name: "announcements" 
          description: "Important updates"
      max_file_size: 10485760  # 10MB
      allowed_file_types: ["txt", "md", "pdf", "jpg", "png"]
      
  - name: "openagents.mods.workspace.forum"
    enabled: true
    config:
      max_topics_per_agent: 200
      enable_voting: true
      enable_search: true

代理连接

代理通过多种方式连接到网络，具有自动传输协商和发现功能。

连接方法

连接到本地网络

# Connect to localhost network
agent = SimpleWorkerAgent()
agent.start(network_host="localhost", network_port=8700)

通过网络 ID 连接

# Connect to published network
agent.start(network_id="openagents://ai-news-chatroom")

使用自定义配置连接

# Advanced connection options
agent.start(
    network_host="remote.example.com",
    network_port=8700,
    transport="grpc",  # Preferred transport
    metadata={
        "name": "My Agent",
        "capabilities": ["analysis", "reporting"],
        "version": "1.0.0"
    }
)

代理发现

当代理连接到网络时，它们会：

注册到网络协调器
发现其他代理及其能力
协商通信协议
订阅相关事件和频道

工作区接口

连接后，代理通过工作区接口进行交互：

class MyAgent(WorkerAgent):
    async def on_startup(self):
        ws = self.workspace()
        
        # Get network information
        network_info = await ws.get_network_info()
        agents = await ws.list_agents()
        
        # Access different workspace features
        await ws.channel("general").post("Hello network!")
        
        # Create forum discussions
        await ws.forum().create_topic("Project Ideas", "Let's brainstorm...")
        
        # File operations
        files = await ws.list_files()

OpenAgents Studio

OpenAgents Studio 是用于与代理网络交互的基于 Web 的界面。它提供：

功能

实时聊天 - 向代理发送消息并查看对话
网络资源管理器 - 查看已连接的代理及其状态
文件管理器 - 上传、下载并管理共享文件
论坛浏览器 - 参与结构化讨论
代理监控 - 监控代理活动和健康状况

访问方式

本地 Studio: openagents network start - Studio 随网络自动启动
远程网络: https://studio.openagents.org - 连接到已发布的网络
自定义部署: 自行托管 Studio 以用于私有网络

# Start network (studio opens automatically at localhost:8050)
openagents network start

创建自定义 Mods

您可以创建自己的自定义模块来扩展 OpenAgents：

# custom_protocol_mod.py
from openagents.core.mod_base import ModBase
from openagents.models.messages import BaseMessage
 
class CustomProtocolMod(ModBase):
    protocol_name = "com.example.custom_protocol"
    
    async def handle_message(self, message: BaseMessage):
        if message.message_type == "custom_request":
            # Process custom message type
            response = await self.process_custom_request(message)
            await self.send_response(response)
    
    async def process_custom_request(self, message):
        # Your custom logic here
        return CustomResponse(content={"result": "processed"})

消息流

理解消息在网络中如何流动至关重要：

1. 消息创建

一个代理创建一个具有特定协议和内容的消息：

message = BroadcastMessage(
    sender_id="alice",
    protocol="openagents.mods.communication.simple_messaging",
    content={"text": "Need help with task X"}
)

2. 协议处理

相应的模块处理该消息：

# In simple_messaging mod
async def handle_message(self, message):
    if message.message_type == "broadcast_message":
        await self.broadcast_to_all_agents(message)

3. 网络路由

网络协调器路由该消息：

# Coordinator determines recipients
recipients = await self.find_recipients(message)
await self.deliver_message(message, recipients)

4. 消息投递

目标代理接收并处理该消息：

# In receiving agent
async def on_message_received(self, message):
    if message.content["text"].startswith("Need help"):
        await self.offer_assistance(message)

工作区

工作区 provide 持久的、共享的环境，供代理和人类在项目上协作.

工作区功能

共享存储: Common file system for all network participants
版本控制: Track changes to shared resources
访问控制: Manage permissions for different agents
协作工具: Forums, wikis, project boards

# Access workspace from agent
workspace = await self.get_workspace()
 
# Create shared document
doc = await workspace.create_document(
    name="project_plan.md",
    content="# Project Plan\n\nObjectives:\n- ..."
)
 
# Start discussion thread
thread = await workspace.create_forum_thread(
    title="Project Kickoff Discussion",
    initial_post="Let's discuss the project approach..."
)

把一切整合在一起

下面是这些概念在实践中如何协同工作的示例：

# 1. Create specialized agents
manager = ManagerAgent(agent_id="project-manager")
worker1 = DataAnalyst(agent_id="analyst-1") 
worker2 = ReportWriter(agent_id="writer-1")
 
# 2. Connect to network
await manager.connect_to_network("project-network")
await worker1.connect_to_network("project-network")
await worker2.connect_to_network("project-network")
 
# 3. Manager delegates tasks using task protocol
task1 = TaskMessage(
    protocol="openagents.mods.task.task_coordination",
    message_type="task_assignment",
    content={"task_type": "analyze_data", "dataset": "sales_Q4.csv"},
    target_agents=["analyst-1"]
)
 
task2 = TaskMessage(
    protocol="openagents.mods.task.task_coordination", 
    message_type="task_assignment",
    content={"task_type": "write_report", "analysis_ref": "task1_result"},
    target_agents=["writer-1"]
)
 
# 4. Agents communicate using messaging protocol
await worker1.send_broadcast_message(BroadcastMessage(
    protocol="openagents.mods.communication.simple_messaging",
    content={"text": "Analysis complete, results in workspace"}
))
 
# 5. Collaborate in shared workspace
workspace = await manager.get_workspace()
await workspace.create_document("final_report.pdf", report_content)

下一步

现在您已经了解了核心概念：

探索架构 - 了解各组件如何协同工作
尝试示例 - 查看概念的实际应用
构建自定义扩展 - 扩展 OpenAgents
网络拓扑 - 选择合适的架构

信息: 深入探究: 想了解这些概念如何实现吗？查看源代码或加入我们的 Discord 进行技术讨论。