GraphAgent

Project Overview#

GraphAgent is an automated agentic framework developed by the Hong Kong University Data Science (HKUDS) lab, accepted at EMNLP 2025. The project aims to bridge the gap between structured graph data (e.g., social networks, citation networks) and unstructured content (e.g., text, visual information).

Core Mechanism#

GraphAgent introduces a multi-agent collaborative architecture through an automated pipeline:

1. Understanding & Construction: If no existing graph is available, the Graph Generator Agent automatically constructs a knowledge graph; otherwise, it utilizes the existing graph structure
2. Planning: The Task Planning Agent parses user natural language queries into concrete execution plans
3. Execution: The Task Execution Agent invokes tools and uses the Graph-Text Tokenizer to convert graphs into continuous tokens, combining with LLM for reasoning or generation

Problems Addressed#

• Heterogeneous Data Fusion: Unified handling of explicit links (e.g., user follow relationships) and implicit semantic dependencies (e.g., thematic correlations between documents)
• Cross-task Versatility: Simultaneously solving classification/regression problems (predictive tasks) and text generation/summarization problems (generative tasks) within a single framework
• Zero-shot Generalization: Demonstrating significantly superior zero-shot classification capabilities on unseen graph datasets compared to traditional GNNs

Core Components#

Key Features#

• Processes both structured (graph connections) and unstructured (text, visual information) data formats
• Handles explicit links (social connections, user behavior) and implicit semantic inter-dependencies between entities
• Integrates language models with graph language models to reveal complex relational information and data semantic dependencies
• Provides multi-modal graph-text tokenizer to transform graphs into continuous tokens

Model Variants#

• GraphAgent-Task Expert (8B): Expert model fine-tuned for specific tasks
• GraphAgent-General (8B): General-purpose version
• GraphAgent-Zero-Shot (8B): Specialized for zero-shot inference scenarios, works without specific dataset fine-tuning

Supported Tasks#

Predictive Tasks#

• Node Classification (NC)
• Paper Classification
• Paper Judgement Prediction

Generative Tasks#

• Text Generation
• Related Work Generation
• Text Summarization

Data Processing Capabilities#

• Multi-modal Input Support: Supports structured graph data (adjacency matrices, edge lists) and unstructured data (text, visual information)
• Graph-Text Unified Encoding: Provides specialized Graph-Text Tokenizer capable of converting graph structural information into continuous token sequences
• Implicit/Explicit Dependency Processing: Not only handles visible connections but also mines implicit semantic associations between data

Performance#

On the ACM-1000 zero-shot classification task, GraphAgent outperforms traditional graph neural network methods (SAGE, GAT, HAN, HGT, HetGNN, HiGPT) across multiple metrics, with improvements up to 63.5%.

Application Scenarios#

• Academic paper analysis and classification
• Peer review prediction
• Automatic generation of related work sections
• Government report summarization
• IMDB movie data analysis
• ACM paper network analysis

Installation#

# Clone repository
git clone https://github.com/HKUDS/GraphAgent.git
cd GraphAgent

# Create conda environment
conda create -n graphagent python=3.11
conda activate graphagent

# Install inference dependencies
pip install -r GraphAgent-inference/requirements.txt

Model Resources#

The project provides the following pre-trained checkpoints on Hugging Face:

• GraphAgent/GraphAgent-8B: 8.03B parameter multi-modal llama3 graph action model
• GraphAgent/GraphTokenizer: Multi-modal graph-text tokenizer
• sentence-transformers/all-mpnet-base-v2: Sentence transformer for text graph embeddings

Configuration Requirements#

Requires configuration of API-based LLM for task planning and graph generation. Default uses deepseek as the planner; set corresponding API key in GraphAgent-inference/run.sh.

Usage#

bash GraphAgent-inference/run.sh

>>> Please enter a user instruction or file path (or type 'exit' to quit):
>>> GraphAgent-inference/demo/use_cases/teach_me_accelerate.txt

The project provides a use_cases directory containing diverse usage examples demonstrating how GraphAgent completes different tasks.

Supported Datasets#

Citation#

@article{graphagent,
      title={GraphAgent: Agentic Graph Language Assistant}, 
      author={Yuhao Yang and Jiabin Tang and Lianghao Xia and Xingchen Zou and Yuxuan Liang and Chao Huang},
      year={2024},
      journal={arXiv preprint arXiv:2412.17029},
}