{"id":29248738,"url":"https://github.com/hkuds/graphagent","last_synced_at":"2025-07-04T00:08:41.517Z","repository":{"id":270446985,"uuid":"905224596","full_name":"HKUDS/GraphAgent","owner":"HKUDS","description":"\"GraphAgent: Agentic Graph Language Assistant\"","archived":false,"fork":false,"pushed_at":"2025-02-08T08:58:54.000Z","size":163,"stargazers_count":245,"open_issues_count":1,"forks_count":31,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-02-08T09:37:55.753Z","etag":null,"topics":["agent","graph-data","language-assistant","large-language-models"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2412.17029","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HKUDS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-18T12:02:10.000Z","updated_at":"2025-02-08T08:58:58.000Z","dependencies_parsed_at":"2024-12-31T08:37:06.117Z","dependency_job_id":null,"html_url":"https://github.com/HKUDS/GraphAgent","commit_stats":null,"previous_names":["hkuds/graphagent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HKUDS/GraphAgent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FGraphAgent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FGraphAgent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FGraphAgent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FGraphAgent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HKUDS","download_url":"https://codeload.github.com/HKUDS/GraphAgent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FGraphAgent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263421914,"owners_count":23464051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","graph-data","language-assistant","large-language-models"],"created_at":"2025-07-04T00:08:40.009Z","updated_at":"2025-07-04T00:08:41.443Z","avatar_url":"https://github.com/HKUDS.png","language":"Jupyter Notebook","readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/cover_pic.jpg\" height=\"300px\"\u003e\n\u003c/div\u003e\n\n\u003ch1 align=\"center\"\u003eGraphAgent: Agentic Graph Language Assistant\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n📖 \u003ca href=\"https://arxiv.org/abs/2412.17029\" target=\"_blank\"\u003e Paper at Arxiv\u003c/a\u003e · 🤗 \u003ca href=\"https://huggingface.co/GraphAgent/GraphAgent-7B\" target=\"_blank\"\u003eGraphAgent Model\u003c/a\u003e · 🤗 \u003ca href=\"https://huggingface.co/GraphAgent/GraphTokenizer\" target=\"_blank\"\u003eGraph Tokenizer Model\u003c/a\u003e \n · 🤗 \u003ca href=\"https://huggingface.co/datasets/GraphAgent/GraphAgent-Datasets\" target=\"_blank\"\u003eGraphAgent Datasets\u003c/a\u003e\n\u003c/p\u003e \n\n\n## 📋 To-Do List\n- [x] Release inference code\n- [x] Release model checkpoints\n- [x] Release training and evaluation datasets\n- [x] Release training code\n\n## 🌟 Overview\n\nReal-world data is represented in both structured (e.g., graph connections) and unstructured (e.g., textual, visual information) formats, encompassing complex relationships that include explicit links (such as social connections and user behaviors) and implicit interdependencies among semantic entities, often illustrated through knowledge graphs. In this work, we propose GraphAgent, an automated agent pipeline that addresses both explicit graph dependencies and implicit graph-enhanced semantic inter-dependencies, aligning with practical data scenarios for predictive tasks (e.g., node classification) and generative tasks (e.g., text generation). GraphAgent comprises three key components: (i) a Graph Generator Agent that builds knowledge graphs to reflect complex semantic dependencies; (ii) a Task Planning Agent that interprets diverse user queries and formulates corresponding tasks through agentic self-planning; and (iii) a Task Execution Agent that efficiently executes planned tasks while automating tool matching and invocation in response to user queries. These agents collaborate seamlessly, integrating language models with graph language models to uncover intricate relational information and data semantic dependencies. Through extensive experiments on various graph-related predictive and text generative tasks on diverse datasets, we demonstrate the effectiveness of our GraphAgent across various settings.\n\n## 🚀 Getting Started\n\n### Invoking GraphAgent (Inference)\n#### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/GraphAgent.git\ncd GraphAgent\n\n# Create a conda environment\nconda create -n graphagent python=3.11\nconda activate graphagent\n\n# Install requirements for GraphAgent inference\npip install -r GraphAgent-inference/requirements.txt\n```\n\n#### Get Pre-trained Models\n\nWe provide several pre-trained checkpoints on 🤗 Hugging Face to power the full potential of GraphAgent:\n\n- `GraphAgent/GraphAgent-8B`: Graph action model for GraphAgent as a multimodal llama3 that can take graph tokens as input.\n- `GraphAgent/GraphTokenizer`: A multimodal graph-text tokenizer for tokenizing graphs into continuous tokens.\n- `sentence-transformers/all-mpnet-base-v2`: The sentence transformer for text graph embedding.\n\nYou can download these checkpoints to a local dir and replace them in `GraphAgent-inference/run.sh`. Or, the program would also automatically download them for you.\n\n#### Set the Planner and API Token\n\nWe utilize API-based LLM calls for task planning and graph generation. The default planner here is `deepseek`, where you can find in `GraphAgent-inference/run.sh`. Put your API key in \n```bash\nexport OPENAI_API_KEY=\"\"\n```\nthat is corresponding to the planner.\n\n#### Inference Examples\n\n```bash\nbash GraphAgent-inference/run.sh\n\n\u003e\u003e\u003e Please enter a user instruction or file path (or type 'exit' to quit):\n\n# use GraphAgent-inference/demo/use_cases/teach_me_accelerate.txt as an example\n\u003e\u003e\u003e Please enter a user instruction or file path (or type 'exit' to quit): GraphAgent-inference/demo/use_cases/teach_me_accelerate.txt\n```\n\nThen you will have a close look on how GraphAgent works to achieve your task.\n\nFor more detailed and diverse examples on what GraphAgent can do for you, check out our [use_cases](GraphAgent-inference/demo/use_cases) directory.\n\n\u003c!-- ## 📖 Documentation\n\n### Model Inference\n\n\n```python\n# Load specific model variant\nmodel = GraphAgent.from_pretrained(\"graphagent-base\")\n```\n\n#### Input Formats\n\nGraphAgent supports multiple input formats:\n- NetworkX graphs\n- PyTorch Geometric Data objects\n- DGL graphs\n- Edge list formats\n\n```python\n# Using NetworkX\nimport networkx as nx\nG = nx.random_geometric_graph(200, 0.125)\nresult = model.predict(G)\n\n# Using edge lists\nedges = [(0, 1), (1, 2), (2, 3)]\nresult = model.predict_from_edges(edges)\n``` --\u003e\n\n### GraphAgent Dataset (Coming Soon!)\n| | IMDB | ACM | Arxiv-Papers | ICLR-Peer Reviews | Related Work Generation | GovReport Summarization |\n|---|---|---|---|---|---|---|\n| Task Type | Predictive | Predictive | Predictive | Predictive | Generative | Generative |\n| Sub-Task | NC | NC | Paper Classification | Paper Judgement Prediction | Text Generation | Text Summarization |\n| Pre-defined Graph? | ✓ | ✓ | × | × | × | × |\n| #Train Samples | 2,400 | - | 5,175 | 3,141 | 4,155 | - |\n| #Eval Samples | - | 1000 | 500 | 500 | 500 | 304 |\n| #Tokens | 10M | 0.8M | 30M | 45M | 93M | 2M |\n| #Pre-defined Graph Nodes | 11,616 | 10,942 | - | - | - | - |\n| SKG Source | People Entities | Paper | Paper | Paper, Reviews | Multiple Papers | Documents |\n| #SKG Nodes | 57,120 | 20,388 | 153,555 | 161,592 | 875,921 | 15,621 |\n\n\n### Training GraphAgent with Your Own Data (Coming Soon!)\n\nThe training code and procedures will be released in future updates. Stay tuned!\n\n## 📊 Benchmarks\n\n#### Zero-shot classification task on ACM-1000\n| Metric | Trained on | SAGE | GAT | HAN | HGT | HetGNN | HiGPT | GraphAgent | Imprv. |\n|---|---|---|---|---|---|---|---|---|---|\n| Micro-F1 (%) | IMDB-1 | 32.93±4.18 | 35.67±0.53 | 34.07±1.11 | 32.40±0.14 | 37.43±4.34 | 45.40±0.89 | **51.21±1.32** | 12.8% |\n| | IMDB-40 | 31.73±0.05 | 23.93±1.44 | 26.97±1.94 | 35.60±0.99 | 31.80±0.16 | 50.50±0.77 | **74.98±1.24** | 48.5% |\n| Macro-F1 (%) | IMDB-1 | 26.47±2.69 | 29.08±1.31 | 22.50±4.16 | 16.31±0.05 | 31.39±4.68 | 41.77±1.24 | **46.82±1.43** | 12.1% |\n| | IMDB-40 | 31.17±0.17 | 21.41±0.71 | 23.13±1.32 | 27.49±1.22 | 31.44±0.17 | 45.85±0.89 | **74.98±1.12** | 63.5% |\n| AUC (%) | IMDB-1 | 49.34±2.47 | 52.48±0.38 | 51.28±0.86 | 50.00±0.00 | 53.18±2.95 | 59.69±0.82 | **64.10±1.25** | 7.4% |\n| | IMDB-40 | 48.67±0.13 | 43.20±1.08 | 45.45±1.46 | 51.48±0.43 | 48.72±0.06 | 63.60±0.51 | **80.90±1.01** | 27.2% |\n\n#### Complex graph predictive tasks on Arxiv-Papers and ICLR-Peer Reviews\n| Method | Model Size | Arxiv-Papers |  |  | ICLR-Peer Reviews |  |  |\n|---|---|---|---|---|---|---|---|\n| | | Mi-F1 | Ma-F1 | AUC | Mi-F1 | Ma-F1 | AUC |\n| **Open-sourced LLMs** | | | | | | | |\n| Llama3-8b | 8B | 0.514 | 0.289 | 0.527 | 0.402 | 0.394 | 0.502 |\n| Mistral-Nemo | 12B | 0.510 | 0.292 | 0.615 | 0.272 | 0.246 | 0.380 |\n| Llama3-70b | 70B | 0.630 | 0.330 | 0.635 | 0.434 | 0.421 | 0.551 |\n| Qwen2-72b | 72B | 0.632 | 0.472 | 0.700 | 0.344 | 0.277 | 0.509 |\n| **API-based Commercial LLMs** | | | | | | | |\n| Deepseek-Chat-V2 | 236B→21B | 0.746 | 0.580 | 0.757 | 0.362 | 0.312 | 0.516 |\n| GPT4o-mini | - | 0.592 | 0.343 | 0.634 | **0.692*** | 0.592 | 0.591 |\n| Gemini-1.5-Flash | - | 0.748 | 0.504 | 0.714 | 0.684 | 0.487 | 0.533 |\n| **Finetuned LLMs** | | | | | | | |\n| Llama3-8b Finetuned | 8B | 0.794 | 0.593 | 0.736 | 0.620 | 0.554 | 0.553 |\n| **GraphRAG Implementations** | | | | | | | |\n| Llama3-8b + GraphRAG | 8B | 0.516 | 0.288 | 0.601 | 0.430 | 0.427 | 0.517 |\n| Llama3-70b + GraphRAG | 70B | 0.603 | 0.324 | 0.623 | 0.308 | 0.296 | 0.401 |\n| GraphAgent-Task Expert | 8B | 0.820 | 0.620 | 0.768 | 0.686 | **0.620*** | **0.615*** |\n| GraphAgent-General | 8B | **0.840*** | **0.621*** | **0.769*** | 0.667 | 0.604 | 0.607 |\n| GraphAgent-Zero-Shot | 8B | 0.739 | 0.512 | 0.701 | 0.538 | 0.531 | 0.563 |\n\n#### Content generation on ACL-EMNLP related work instructions.\n| Method | Model Size | PPL-Llama3-70b |  | PPL-Qwen2-72b |  |\n|---|---|---|---|---|---|\n| | | Mean | Max | Mean | Max |\n| **Open-sourced LLMs** | | | | | |\n| Llama3-8b | 8B | 7.016 | 13.061 | 7.491 | 12.787 |\n| Mistral-Nemo | 12B | 7.367 | 15.967 | 6.872 | 12.065 |\n| Llama3-70b | 70B | 6.168 | 14.436 | 5.877 | 12.897 |\n| Qwen2-72b | 72B | 6.043 | 11.675 | 5.325 | 11.302 |\n| **API-based Commercial LLMs** | | | | | |\n| Deepseek-Chat-V2 | 236B→21B | 5.632 | 13.483 | 5.144 | 10.337 |\n| GPT4o-mini | - | 7.277 | 15.480 | 6.818 | 13.267 |\n| Gemini-1.5-Flash | - | 5.188 | 10.399 | 5.377 | 10.779 |\n| **Finetuned LLMs** | | | | | |\n| Llama3-8b Finetuned | 8B | 7.682 | 19.452 | 7.629 | 18.757 |\n| **GraphRAG Implementations** | | | | | |\n| Llama3-8b + GraphRAG | 8B | 7.098 | 18.092 | 6.539 | 14.722 |\n| Llama3-70b + GraphRAG | 70B | 6.590 | 14.827 | 6.135 | 14.163 |\n| GraphAgent-Task Expert | 8B | 3.805 | 10.316 | 4.069 | 11.685 |\n| GraphAgent-General | 8B | **3.618*** | **8.000*** | **3.867*** | **8.775*** |\n\n\n## 📝 Citation\n\nIf you find this repository useful, please cite our paper:\n\n```bibtex\n\n@article{graphagent,\n      title={GraphAgent: Agentic Graph Language Assistant}, \n      author={Yuhao Yang and Jiabin Tang and Lianghao Xia and Xingchen Zou and Yuxuan Liang and Chao Huang},\n      year={2024},\n      journal={arXiv preprint arXiv:2412.17029},\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkuds%2Fgraphagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhkuds%2Fgraphagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkuds%2Fgraphagent/lists"}