{"id":28676530,"url":"https://github.com/zjunlp/knowagent","last_synced_at":"2025-10-26T11:11:38.172Z","repository":{"id":222454810,"uuid":"688046236","full_name":"zjunlp/KnowAgent","owner":"zjunlp","description":"[NAACL 2025]  KnowAgent: Knowledge-Augmented Planning for LLM-Based Agents","archived":false,"fork":false,"pushed_at":"2025-01-29T07:31:53.000Z","size":4683,"stargazers_count":195,"open_issues_count":0,"forks_count":17,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-01-29T08:27:55.368Z","etag":null,"topics":["agent","agent-learning","artificial-intelligence","knowagent","knowledge-augment","knowledge-graph","large-language-models","llm","machine-learning","natural-language-processing","nlp","planning","planning-agents","reasoning","reasoning-agent"],"latest_commit_sha":null,"homepage":"https://zjunlp.github.io/project/KnowAgent/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zjunlp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2023-09-06T14:36:10.000Z","updated_at":"2025-01-29T07:31:58.000Z","dependencies_parsed_at":"2024-10-21T07:38:25.188Z","dependency_job_id":null,"html_url":"https://github.com/zjunlp/KnowAgent","commit_stats":null,"previous_names":["zjunlp/knowagent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zjunlp/KnowAgent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zjunlp%2FKnowAgent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zjunlp%2FKnowAgent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zjunlp%2FKnowAgent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zjunlp%2FKnowAgent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zjunlp","download_url":"https://codeload.github.com/zjunlp/KnowAgent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zjunlp%2FKnowAgent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259732771,"owners_count":22903087,"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","agent-learning","artificial-intelligence","knowagent","knowledge-augment","knowledge-graph","large-language-models","llm","machine-learning","natural-language-processing","nlp","planning","planning-agents","reasoning","reasoning-agent"],"created_at":"2025-06-13T23:05:01.836Z","updated_at":"2025-10-09T06:41:08.089Z","avatar_url":"https://github.com/zjunlp.png","language":"Python","readme":"\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"img/icon.png\" width=\"360px\"\u003e  \n\n\n  **Knowledge-Augmented Planning for LLM-Based Agents.**\n\n  \u003cp align=\"center\"\u003e\n  \u003ca href=\"https://arxiv.org/abs/2403.03101\"\u003e📄Paper\u003c/a\u003e •\n  \u003ca href=\"https://www.zjukg.org/project/KnowAgent/\"\u003e🌐Web\u003c/a\u003e\n\t\u003c/p\u003e  \n\n[![Awesome](https://awesome.re/badge.svg)](https://github.com/zjunlp/KnowAgent) \n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n![](https://img.shields.io/github/last-commit/zjunlp/KnowAgent?color=green) \n\n\u003c/div\u003e\n\n---\n\n\u003cimg src=\"img/method.gif\" alt=\"method\"/\u003e\n\n​\tOur development is grounded on several key steps: **Initially**, we create an extensive *action knowledge base*, which amalgamates action planning knowledge pertinent to specific tasks. This database acts as an external reservoir of information, steering the model's action generation process.  **Subsequently**, by converting action knowledge into text, we enable the model to deeply understand and utilize this knowledge in creating action trajectories. **Finally**, through a *knowledgeable self-learning* phase, we use trajectories developed from the model's iterative processes to continually improve its understanding and application of action knowledge. This process not only strengthens the agents' planning abilities but also enhances their potential for application in complex situations.\n\n\n\n## 🌟Table of Contents\n\n- [🌟Table of Contents](#table-of-contents)\n- [🔔News](#news)\n- [🔧Installation](#installation)\n- [:world_map:Planning Path Generation](#world_mapplanning-path-generation)\n- [📝Knowledgeable Self-Learning](#%EF%B8%8Fknowledgeable-self-learning)\n- [🔖Citation](#citation)\n- [✨Acknowledgement](#acknowledgement)\n\n\n  \n\n## 🔔News\n- **[2025-01]** Our paper has been accepted to the NAACL 2025 Findings!\n- **[2024-08]** Our paper received the Best Paper Award at the KnowledgeNLP workshop at ACL 2024! \n- **[2024-03]** We release a new paper: \"[KnowAgent: Knowledge-Augmented Planning for LLM-Based Agents](https://arxiv.org/abs/2403.03101)\".\n\n  \n## 🔧Installation\n\nTo get started with KnowAgent, follow these simple installation steps:\n\n```bash\ngit clone https://github.com/zjunlp/KnowAgent.git\ncd KnowAgent\npip install -r requirements.txt\n```\n\nWe have placed the HotpotQA and ALFWorld datasets under `Path_Generation/alfworld_run/data` and `Path_Generation/hotpotqa_run/data` respectively. For further configuration, we recommend proceeding with the original setup of [ALFWorld](https://github.com/alfworld/alfworld) and [FastChat](https://github.com/lm-sys/FastChat).\n\n## :world_map:Planning Path Generation\n\nThe Planning Path Generation process is integral to KnowAgent. You can find the scripts for running the Planning Path Generation in `Path_Generation` directory, specifically `run_alfworld.sh` and `run_hotpotqa.sh`. These scripts can be executed using bash commands. To tailor the scripts to your needs, you may modify the `mode` parameter to switch between training (`train`) and testing (`test`)modes, and change the `llm_name` parameter to use a different LLM:\n\n```\ncd Path_Generation\n\n# For training with HotpotQA\npython run_hotpotqa.py --llm_name llama-2-13b --max_context_len 4000 --mode train --output_path ../Self-Learning/trajs/\n\n# For testing with HotpotQA\npython run_hotpotqa.py --llm_name llama-2-13b --max_context_len 4000 --mode test --output_path output/\n    \n# For training with ALFWorld\npython alfworld_run/run_alfworld.py --llm_name llama-2-13b --mode train --output_path ../Self-Learning/trajs/\n\n# For testing with ALFWorld\npython alfworld_run/run_alfworld.py --llm_name llama-2-13b --mode test --output_path output/\n```\nHere we release the trajectories synthesized by Llama-{7,13,70}b-chat in [Google Drive](https://drive.google.com/drive/folders/1ULHFvplZhpmfLNE7Oty3dJcl1FCnkHNM?usp=sharing) before Filtering.\n\n## ♟️Knowledgeable Self-Learning\n\nAfter obtaining the planning paths and corresponding trajectories, the Knowledgeable Self-Learning process begins. The generated trajectories must first be converted into the Alpaca format using the scripts located in the Self-Learning directory.\n\nFor the initial iterations, follow the steps outlined in `traj_reformat.sh`:\n\n```\ncd Self-Learning\n# For HotpotQA\npython train/Hotpotqa_reformat.py --input_path trajs/KnowAgentHotpotQA_llama-2-13b.jsonl --output_path train/datas\n\n# For ALFWorld\npython train/ALFWorld_reformat.py --input_path trajs/KnowAgentALFWorld_llama-2-13b.jsonl --output_path train/datas\n```\n\nFor subsequent iterations, it is essential to perform Knowledge-Based Trajectory Filtering and Merging before running the trajectory reformatting script. \nYou can achieve this using `traj_merge_and_filter.sh`:\n\n```\npython trajs/traj_merge_and_filter.py \\\n    --task HotpotQA \\\n    --input_path1  trajs/datas/KnowAgentHotpotQA_llama-2-13b_D0.jsonl \\\n    --input_path2  trajs/datas/KnowAgentHotpotQA_llama-2-13b_D1.jsonl \\\n    --output_path   trajs/datas \n```\n\nNext, initiate the Self-Learning process by running `train.sh` and `train_iter.sh`, as specified in the scripts located in `Self-Learning/train.sh` and `Self-Learning/train_iter.sh`:\n\n```\nCUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 deepspeed train/train_lora.py \\\n    --model_name_or_path  llama-2-13b-chat\\\n    --lora_r 8 \\\n    --lora_alpha 16 \\\n    --lora_dropout 0.05 \\\n    --data_path datas/data_knowagent.json \\\n    --output_dir models/Hotpotqa/M1 \\\n    --num_train_epochs 5 \\\n    --per_device_train_batch_size 2 \\\n    --per_device_eval_batch_size 1 \\\n    --gradient_accumulation_steps 1 \\\n    --evaluation_strategy \"no\" \\\n    --save_strategy \"steps\" \\\n    --save_steps 10000 \\\n    --save_total_limit 1 \\\n    --learning_rate 1e-4 \\\n    --weight_decay 0. \\\n    --warmup_ratio 0.03 \\\n    --lr_scheduler_type \"cosine\" \\\n    --logging_steps 1 \\\n    --fp16 True \\\n    --model_max_length 4096 \\\n    --gradient_checkpointing True \\\n    --q_lora False \\\n    --deepspeed /data/zyq/FastChat/playground/deepspeed_config_s3.json \\\n    --resume_from_checkpoint False \n```\n\n## 🔖Citation\n\n```bibtex\n@article{zhu2024knowagent,\n  title={KnowAgent: Knowledge-Augmented Planning for LLM-Based Agents},\n  author={Zhu, Yuqi and Qiao, Shuofei and Ou, Yixin and Deng, Shumin and Zhang, Ningyu and Lyu, Shiwei and Shen, Yue and Liang, Lei and Gu, Jinjie and Chen, Huajun},\n  journal={arXiv preprint arXiv:2403.03101},\n  year={2024}\n}\n```\n\n## ✨Acknowledgement\n\n- We express our gratitude to the creators and contributors of the following projects, which have significantly influenced the development of KnowAgent:\n\n  - **FastChat**: Our training module code is adapted from FastChat. [Visit FastChat](https://github.com/lm-sys/FastChat)，and Integration with open models through LangChain is facilitated via FastChat. [Learn more about LangChain and FastChat Integration](https://github.com/lm-sys/FastChat/blob/main/docs/langchain_integration.md).\n  - **BOLAA**: The inference module code is implemented based on BOLAA. [Visit BOLAA](https://github.com/salesforce/BOLAA)\n  - Additional baseline codes from **ReAct**, **Reflexion**, **FireAct**, and others have been utilized, showcasing a diverse range of approaches and methodologies.\n\n  Our heartfelt thanks go out to all contributors for their invaluable contributions to the field!\n\n\n## 🎉Contributors\n\n\u003ca href=\"https://github.com/zjunlp/knowagent/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=zjunlp/knowagent\" /\u003e\u003c/a\u003e\n\nWe will offer long-term maintenance to fix bugs and solve issues. So if you have any problems, please put issues to us.  \n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzjunlp%2Fknowagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzjunlp%2Fknowagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzjunlp%2Fknowagent/lists"}