分析多智能体协作的team和资源节点之间的关系

[catface996]

分析多智能体协作的team和资源节点之间的关系，使用mermaid语法写入到markdown文件中，来表述智能体和资源节点之间的关系。

[ghostyappzeta]

Taking a look at this issue and I'll get started soon.

---

_{Comment /kiro any time and I'll update the task.}

[ghostyappzeta]

Multi-Agent Collaboration Architecture Analysis

Overview

This document analyzes the relationship between Teams and Resource Nodes in the multi-agent collaboration system within the op-stack-service repository. The system implements a hierarchical agent architecture for orchestrating complex operational tasks.

---

1. Core Concepts

1.1 Key Entities

Entity	Description
Topology	A graph-based representation of resource dependencies and execution workflows
Node	Individual resource units within a topology (servers, services, databases, etc.)
Agent	Intelligent entities capable of executing tasks with specific roles and capabilities
Team	A collection of agents organized hierarchically for collaborative task execution
Agent Binding	The association between agents and entities (Topology or Node)

1.2 Agent Hierarchy Levels

The system defines three hierarchy levels for agents:

public enum AgentHierarchyLevel {
    GLOBAL_SUPERVISOR,    // Top-level orchestrator for entire topology
    TEAM_SUPERVISOR,      // Manages a team of worker agents within a node
    TEAM_WORKER          // Executes specific tasks within a team
}

1.3 Agent Roles

Different roles determine agent capabilities:

public enum AgentRole {
    ORCHESTRATOR,    // Coordinates multiple agents
    EXECUTOR,        // Performs direct actions
    ANALYZER,        // Analyzes data and provides insights
    MONITOR         // Observes system state
}

---

2. Architecture Relationship Diagrams

2.1 Overall System Architecture

graph TB
    subgraph "System Layer"
        UI[Frontend UI]
        API[REST API Layer]
    end
    
    subgraph "Application Layer"
        TS[Topology Service]
        AS[Agent Service]
        ABS[Agent Bound Service]
        ES[Execution Service]
    end
    
    subgraph "Domain Layer"
        TD[Topology Domain]
        AD[Agent Domain]
        ND[Node Domain]
        BD[Binding Domain]
    end
    
    subgraph "Data Layer"
        TDB[(Topology DB)]
        ADB[(Agent DB)]
        NDB[(Node DB)]
        BDB[(Binding DB)]
    end
    
    UI --> API
    API --> TS
    API --> AS
    API --> ABS
    API --> ES
    
    TS --> TD
    AS --> AD
    ABS --> BD
    ES --> BD
    
    TD --> TDB
    AD --> ADB
    ND --> NDB
    BD --> BDB
    
    style UI fill:#e1f5ff
    style API fill:#fff3e0
    style TS fill:#f3e5f5
    style AS fill:#f3e5f5
    style ABS fill:#f3e5f5
    style ES fill:#f3e5f5

Loading

2.2 Topology-Team-Node Relationship

graph TD
    T[Topology<br/>拓扑图]
    GS[Global Supervisor Agent<br/>全局协调智能体]
    
    N1[Node 1<br/>资源节点1]
    N2[Node 2<br/>资源节点2]
    N3[Node 3<br/>资源节点3]
    
    Team1[Team 1<br/>智能体团队1]
    Team2[Team 2<br/>智能体团队2]
    Team3[Team 3<br/>智能体团队3]
    
    TS1[Team Supervisor 1<br/>团队主管]
    TS2[Team Supervisor 2<br/>团队主管]
    TS3[Team Supervisor 3<br/>团队主管]
    
    W11[Worker 1.1]
    W12[Worker 1.2]
    W21[Worker 2.1]
    W22[Worker 2.2]
    W23[Worker 2.3]
    W31[Worker 3.1]
    
    T -->|binds| GS
    T -->|contains| N1
    T -->|contains| N2
    T -->|contains| N3
    
    N1 -->|forms| Team1
    N2 -->|forms| Team2
    N3 -->|forms| Team3
    
    Team1 -->|led by| TS1
    Team2 -->|led by| TS2
    Team3 -->|led by| TS3
    
    TS1 -->|manages| W11
    TS1 -->|manages| W12
    TS2 -->|manages| W21
    TS2 -->|manages| W22
    TS2 -->|manages| W23
    TS3 -->|manages| W31
    
    GS -.->|coordinates| TS1
    GS -.->|coordinates| TS2
    GS -.->|coordinates| TS3
    
    style T fill:#ffebee
    style GS fill:#e8f5e9
    style N1 fill:#fff3e0
    style N2 fill:#fff3e0
    style N3 fill:#fff3e0
    style Team1 fill:#e3f2fd
    style Team2 fill:#e3f2fd
    style Team3 fill:#e3f2fd
    style TS1 fill:#f3e5f5
    style TS2 fill:#f3e5f5
    style TS3 fill:#f3e5f5

Loading

2.3 Agent Binding Mechanism

graph LR
    subgraph "Binding Types"
        BT1[TOPOLOGY Binding]
        BT2[NODE Binding]
    end
    
    subgraph "Hierarchy Levels"
        HL1[GLOBAL_SUPERVISOR]
        HL2[TEAM_SUPERVISOR]
        HL3[TEAM_WORKER]
    end
    
    subgraph "Entities"
        TOP[Topology]
        NODE[Node]
    end
    
    subgraph "Agents"
        GS_A[Global Supervisor Agent]
        TS_A[Team Supervisor Agent]
        W_A[Worker Agent]
    end
    
    BT1 --> TOP
    BT2 --> NODE
    
    HL1 --> GS_A
    HL2 --> TS_A
    HL3 --> W_A
    
    TOP -->|binds via BT1| GS_A
    NODE -->|binds via BT2| TS_A
    NODE -->|binds via BT2| W_A
    
    GS_A -.->|at level| HL1
    TS_A -.->|at level| HL2
    W_A -.->|at level| HL3
    
    style BT1 fill:#e1f5ff
    style BT2 fill:#e1f5ff
    style TOP fill:#ffebee
    style NODE fill:#fff3e0

Loading

2.4 Execution Flow

sequenceDiagram
    participant User
    participant Frontend
    participant ExecutionAPI
    participant TopologyService
    participant AgentBoundService
    participant ExecutorService
    
    User->>Frontend: Trigger execution with topology_id
    Frontend->>ExecutionAPI: POST /api/v1/execution/trigger
    ExecutionAPI->>TopologyService: Get topology details
    TopologyService-->>ExecutionAPI: Topology data
    
    ExecutionAPI->>AgentBoundService: Query hierarchy structure
    AgentBoundService->>AgentBoundService: Get global supervisor binding
    AgentBoundService->>AgentBoundService: Get all node bindings
    AgentBoundService->>AgentBoundService: Group agents by node (teams)
    AgentBoundService-->>ExecutionAPI: HierarchyStructureDTO
    
    ExecutionAPI->>ExecutorService: Create hierarchy
    ExecutorService-->>ExecutionAPI: hierarchy_id
    
    ExecutionAPI->>ExecutorService: Start run
    ExecutorService-->>Frontend: SSE events stream
    
    loop Execution Progress
        ExecutorService-->>Frontend: Event updates
    end
    
    ExecutorService-->>Frontend: Completion event

Loading

2.5 Data Model Relationships

erDiagram
    TOPOLOGY ||--o{ NODE : contains
    TOPOLOGY ||--o| AGENT_BINDING : "has global supervisor"
    NODE ||--o{ AGENT_BINDING : "has team agents"
    AGENT ||--o{ AGENT_BINDING : "bound to entities"
    NODE ||--o{ NODE_2_NODE : "depends on"
    
    TOPOLOGY {
        bigint id PK
        string name
        string description
        enum status
        timestamp created_at
    }
    
    NODE {
        bigint id PK
        bigint topology_id FK
        string name
        string node_type
        int layer
        enum status
    }
    
    AGENT {
        bigint id PK
        string name
        string description
        enum role
        enum hierarchy_level
        string model
        string prompt_template
    }
    
    AGENT_BINDING {
        bigint id PK
        bigint bound_id FK
        enum bound_entity_type
        bigint agent_id FK
        enum hierarchy_level
        string agent_role
        timestamp bound_at
    }
    
    NODE_2_NODE {
        bigint id PK
        bigint upstream_node_id FK
        bigint downstream_node_id FK
        string dependency_type
    }

Loading

---

3. Key Relationship Patterns

3.1 Topology → Global Supervisor (1:1)

• Each Topology can bind one Global Supervisor Agent
• Binding type: BoundEntityType.TOPOLOGY
• Hierarchy level: AgentHierarchyLevel.GLOBAL_SUPERVISOR
• Responsibility: Orchestrate all teams within the topology

3.2 Node → Team (1:1)

• Each Node forms one Team
• A team consists of:
  • One Team Supervisor (optional but recommended)
  • Multiple Team Workers (at least one required for execution)

3.3 Node → Agents (1:N)

• Each Node can bind multiple Agents
• Binding type: BoundEntityType.NODE
• Hierarchy levels allowed:
  • AgentHierarchyLevel.TEAM_SUPERVISOR (max 1 per node)
  • AgentHierarchyLevel.TEAM_WORKER (multiple allowed)

3.4 Hierarchy Structure

Topology (拓扑图)
    ├─ Global Supervisor Agent (全局协调者)
    └─ Nodes (资源节点集合)
        ├─ Node 1
        │   └─ Team 1
        │       ├─ Team Supervisor
        │       └─ Workers [W1, W2, ...]
        ├─ Node 2
        │   └─ Team 2
        │       ├─ Team Supervisor
        │       └─ Workers [W1, W2, W3, ...]
        └─ Node N
            └─ Team N
                ├─ Team Supervisor
                └─ Workers [W1, ...]

---

4. Implementation Details

4.1 Key Classes

Class	Package	Responsibility
Topology	domain.model.topology	Represents a topology entity
Node	domain.model.node	Represents a resource node
Agent	domain.model.agent	Represents an intelligent agent
AgentBinding	domain.model.agentbound	Links agents to entities
HierarchyStructureDTO	application.api.dto.agentbound	Hierarchical structure for execution
TopologyApplicationService	application.impl.service.topology	Manages topology operations
AgentBoundApplicationService	application.impl.service.agentbound	Manages agent bindings
ExecutionApplicationService	application.impl.service.execution	Orchestrates multi-agent execution

4.2 Database Tables

-- Core tables
topology                 -- 拓扑图定义
node                     -- 资源节点
agent                    -- 智能体定义
agent_binding            -- 绑定关系表
node_2_node              -- 节点依赖关系

-- Supporting tables
node_type                -- 节点类型字典
topology_report_template -- 报告模板

4.3 API Endpoints

# Topology Management
POST   /api/v1/topology                    # Create topology
PUT    /api/v1/topology/{id}              # Update topology
GET    /api/v1/topology/{id}              # Get topology details
DELETE /api/v1/topology/{id}              # Delete topology
GET    /api/v1/topology/graph             # Query topology graph

# Agent Binding
POST   /api/v1/agent-bound/global-supervisor    # Bind global supervisor
DELETE /api/v1/agent-bound/global-supervisor    # Unbind global supervisor
POST   /api/v1/agent-bound/team-agent          # Bind team agent to node
DELETE /api/v1/agent-bound/team-agent          # Unbind team agent
GET    /api/v1/agent-bound/hierarchy           # Query hierarchy structure

# Execution
POST   /api/v1/execution/trigger               # Trigger multi-agent execution
POST   /api/v1/execution/cancel                # Cancel execution
GET    /api/v1/execution/stream                # Stream execution events (SSE)

---

5. Execution Workflow

5.1 Trigger Execution

1. User Request: Frontend sends topology_id and user message
2. Query Hierarchy: System retrieves hierarchy structure via AgentBoundService.queryHierarchy()
3. Transform Data: Convert HierarchyStructureDTO to CreateHierarchyRequest
4. Create Hierarchy: Call external Executor Service to create hierarchy
5. Start Run: Initialize execution with user message
6. Stream Events: Return SSE connection for real-time updates

5.2 Hierarchy Query Logic

// From AgentBoundApplicationServiceImpl.java
public HierarchyStructureDTO queryHierarchy(Long topologyId) {
    // 1. Get global supervisor binding
    AgentBinding globalBinding = findSupervisorBinding(
        BoundEntityType.TOPOLOGY, 
        topologyId, 
        AgentHierarchyLevel.GLOBAL_SUPERVISOR
    );
    
    // 2. Get all node bindings for this topology
    List<AgentBinding> nodeBindings = agentBindingRepository
        .findByEntityTypeAndTopologyId(BoundEntityType.NODE, topologyId);
    
    // 3. Group bindings by node_id to form teams
    Map<Long, List<AgentBinding>> bindingsByNode = nodeBindings.stream()
        .collect(Collectors.groupingBy(AgentBinding::getBoundId));
    
    // 4. Build team structures
    List<TeamDTO> teams = bindingsByNode.entrySet().stream()
        .map(this::buildTeamFromBindings)
        .collect(Collectors.toList());
    
    // 5. Return hierarchy structure
    return HierarchyStructureDTO.builder()
        .topologyId(topologyId)
        .globalSupervisor(buildAgentDTO(globalBinding))
        .teams(teams)
        .build();
}

5.3 Team Building Logic

private TeamDTO buildTeamFromBindings(Map.Entry<Long, List<AgentBinding>> entry) {
    Long nodeId = entry.getKey();
    List<AgentBinding> bindings = entry.getValue();
    
    // Find node details
    Node node = nodeRepository.findById(nodeId);
    
    // Separate supervisor and workers
    AgentDTO supervisor = null;
    List<AgentDTO> workers = new ArrayList<>();
    
    for (AgentBinding binding : bindings) {
        if (binding.getHierarchyLevel() == AgentHierarchyLevel.TEAM_SUPERVISOR) {
            supervisor = buildAgentDTO(binding);
        } else if (binding.getHierarchyLevel() == AgentHierarchyLevel.TEAM_WORKER) {
            workers.add(buildAgentDTO(binding));
        }
    }
    
    return TeamDTO.builder()
        .nodeId(nodeId)
        .nodeName(node.getName())
        .supervisor(supervisor)
        .workers(workers)
        .build();
}

---

6. Key Design Patterns

6.1 Binding Pattern

The system uses a unified binding mechanism to associate agents with entities:

• Flexibility: Same agent can be bound to different entities
• Polymorphism: bound_entity_type (TOPOLOGY/NODE) determines binding context
• Hierarchy Enforcement: hierarchy_level ensures proper agent placement

6.2 Hierarchical Team Organization

Teams are dynamically formed based on agent bindings:

• Dynamic Formation: Teams created at runtime from bindings
• Node-centric: Each node becomes a team
• Role Clarity: Clear supervisor-worker relationships

6.3 Event-Driven Execution

Execution progress is communicated via Server-Sent Events (SSE):

• Real-time Updates: Frontend receives immediate feedback
• Streaming: Efficient for long-running tasks
• Event Types: Status changes, agent messages, errors, completion

---

7. Summary

The multi-agent collaboration system in op-stack-service implements a three-tier hierarchy:

1. Global Supervisor → Bound to Topology (orchestrates entire workflow)
2. Team Supervisors → Bound to Nodes (manage team coordination)
3. Team Workers → Bound to Nodes (execute specific tasks)

Key Insights:

• Resource Nodes are the foundation for forming Teams
• One Node = One Team mapping ensures clear ownership
• Agent Binding is the glue connecting agents to topology/nodes
• Hierarchical Structure enables scalable multi-agent collaboration
• Dynamic Team Formation provides flexibility in agent assignment

This architecture supports complex operational tasks by decomposing them across resource nodes and coordinating execution through a hierarchical agent structure.