{"id":32932482,"url":"https://github.com/yx-fan/multi-agent-orchestration-framework","last_synced_at":"2026-05-08T03:33:58.369Z","repository":{"id":323413680,"uuid":"1092907626","full_name":"yx-fan/multi-agent-orchestration-framework","owner":"yx-fan","description":"Modular multi-agent orchestration framework powered by LangGraph and FastAPI.","archived":false,"fork":false,"pushed_at":"2025-11-10T01:08:35.000Z","size":911,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-10T03:10:27.922Z","etag":null,"topics":["agent","ai-framework","fastapi","langchain","langgraph","llm","memory","multi-agent","orchestration","state","state-management","workflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yx-fan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-09T14:47:33.000Z","updated_at":"2025-11-10T01:19:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yx-fan/multi-agent-orchestration-framework","commit_stats":null,"previous_names":["yx-fan/agent-flow-framework"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yx-fan/multi-agent-orchestration-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yx-fan%2Fmulti-agent-orchestration-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yx-fan%2Fmulti-agent-orchestration-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yx-fan%2Fmulti-agent-orchestration-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yx-fan%2Fmulti-agent-orchestration-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yx-fan","download_url":"https://codeload.github.com/yx-fan/multi-agent-orchestration-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yx-fan%2Fmulti-agent-orchestration-framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283847765,"owners_count":26904850,"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","status":"online","status_checked_at":"2025-11-11T02:00:06.610Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","ai-framework","fastapi","langchain","langgraph","llm","memory","multi-agent","orchestration","state","state-management","workflow"],"created_at":"2025-11-11T18:00:58.224Z","updated_at":"2025-11-11T18:02:02.556Z","avatar_url":"https://github.com/yx-fan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 Multi-Agent Orchestration Framework  \n*A declarative LangGraph-based framework for building multi-agent workflows*\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)\n[![Stars](https://img.shields.io/github/stars/yx-fan/agent-flow-framework.svg?style=social)](https://github.com/yx-fan/agent-flow-framework)\n[![Framework](https://img.shields.io/badge/framework-LangGraph-blueviolet)](https://github.com/langchain-ai/langgraph)\n[![FastAPI](https://img.shields.io/badge/backend-FastAPI-009688)](https://fastapi.tiangolo.com/)\n[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)]()\n\nA plug-and-play **multi-agent orchestration framework** for developers building domain-specific AI systems with LangGraph — composable, declarative, and production-ready.\n\n## 🏷️ Topics\n\n`langgraph` `multi-agent` `llm` `ai-framework` `fastapi` `python` `orchestration` `yaml-config` `redis` `azure-openai` `agent-framework` `langchain` `workflow-engine` `conversational-ai` `state-management` `declarative` `modular` `production-ready`\n\n\n---\n\n## 🌍 Overview\n\n**Multi-Agent Orchestration Framework**  \nis a **developer-oriented orchestration framework** for building **multi-agent, multi-domain AI systems** powered by [LangGraph](https://github.com/langchain-ai/langgraph).\n\nIt provides a **structured, extensible runtime** for combining:\n- 🧠 **Agents** (decision-makers powered by LLMs)\n- 🔗 **Nodes** (graph-executable logic units)\n- 🧰 **Tools** (external integrations)\n- 💾 **Memory** (Redis-based short-term state)\n- ⚙️ **Providers** (Azure OpenAI, etc.)\n\nTogether, they form **intelligent conversational workflows** defined declaratively via YAML —  \nso developers can rapidly compose and extend domain-specific AI applications without reimplementing orchestration logic.\n\n**Build modular, reasoning-driven AI systems — without writing orchestration code.**\n\n---\n\n## ✨ Why This Framework?\n\n| Feature | Description |\n|----------|--------------|\n| 🧩 **Fully Modular** | Agents, Nodes, Tools, and Providers are decoupled and reusable. |\n| 🧠 **Intent + Workflow System** | Combine `intents.yaml` and `workflow.yaml` to define complex multi-domain logic. |\n| 🔄 **Node–Agent Hierarchy** | Nodes orchestrate, Agents decide — offering fine-grained control and LLM flexibility. |\n| 💾 **Stateful Memory Layer** | Redis backend for short-term conversational memory and context recall. |\n| 🚀 **LangGraph-Powered Runtime** | Build and execute dynamic computational graphs with full async support. |\n| 🌐 **FastAPI Integration** | Out-of-the-box `/chat` endpoint ready for serving agents as microservices. |\n| 🧭 **Extensible by Design** | Plug in your own domains, agents, or tools in minutes. |\n\n---\n\n## 🧱 Architecture Overview\n\n```\n+-----------------------------------------------------------+\n|              🧠 Multi-Agent Orchestrator                   |\n|-----------------------------------------------------------|\n|  AgentRouter  |  LangGraphBuilder  |  StateManager        |\n+-----------------------------------------------------------+\n|             YAML-defined Domain Workflows                 |\n|-----------------------------------------------------------|\n|  Nodes → Agents → Tools → Providers → LLMs                |\n|-----------------------------------------------------------|\n|  Redis Memory  |  FastAPI API  |  Extensible Providers    |\n+-----------------------------------------------------------+\n```\n\nThis structure allows you to **design your own domain workflows**  \n(e.g., `school`, `finance`, `support`) by simply defining intents and linking nodes/agents in YAML.\n\n---\n\n## 🧩 Execution Demo\n\n![Demo](docs/assets/demo.png)\n\u003e _Example: The framework orchestrating a full reasoning flow — from intent classification and LangGraph construction to AzureOpenAI inference and Redis state persistence._\n\n---\n\n## ⚙️ Installation\n\n```bash\ngit clone https://github.com/yx-fan/agent-flow-framework.git\ncd agent-flow-framework\npip install -r requirements.txt\ncp .env.example .env\n```\n\nThen edit `.env` to configure Redis and Azure OpenAI (or your preferred provider if you update related code).\n\n---\n\n## 🚀 Quick Start\n\n```bash\nuvicorn main:app --host 0.0.0.0 --port 8001 --reload\n```\n\nAccess the API at  \n👉 http://127.0.0.1:8001/chat  \n\n📚 **Interactive API Documentation**:  \n- Swagger UI: http://127.0.0.1:8001/docs  \n- ReDoc: http://127.0.0.1:8001/redoc  \n\n#### Example:\n```bash\ncurl -X POST \"http://127.0.0.1:8001/chat\"     \n-H \"Content-Type: application/json\"\n-d '{\"query\": \"hello. what is llm?\"}'\n```\n\nIn the body, you can also specify a domain and additional session_id if needed:\n```bash\n-d '{\"query\": \"hello. what is llm?\", \"domain\": \"hello\", \"session_id\": 20ffa3c6-4af9-4412-adc6-ed16ca1f71a7\"}'\n```\n\n#### Response:\n```json\n{\n    \"session_id\": \"20ffa3c6-4af9-4412-adc6-ed16ca1f71a7\",\n    \"query\": \"hello\",\n    \"domain\": \"hello\",\n    \"result\": {\n        \"domain\": \"hello\",\n        \"intent\": \"greet\",\n        \"result\": {\n            \"query\": \"hello. what is llm?\",\n            \"domain\": \"hello\",\n            \"greeting\": \"Hello there 👋! Let me think about that for you...\",\n            \"agent_reply\": \"👋 Hello! You said: 'hello. what is llm?'.\\nLLM says: Hi there! 😊 LLM stands for \\\"Large Language Model.\\\" It's a type of advanced AI designed to understand and generate human-like text. Think of it as a virtual assistant or brainy language buddy that can help with everything from answering questions to creating stories! Did you want to know more about it? 😄\",\n            \"timestamp\": \"2025-11-09T20:41:57.600949\",\n            \"llm_used\": true\n        }\n    }\n}\n```\n\n✅ The framework dynamically loads the `hello` domain workflow →  \nexecutes `GreetingNode` → calls `HelloAgent` → routes through `AzureOpenAIProvider`.\n\n---\n\n## 🧩 Domain Workflow Example\n\n**`data/hello/intents.yaml`**\n```yaml\nintents:\n  greet:\n    description: Simple greetings and small talk.\n    keywords: [\"hello\", \"hi\", \"hey\", \"morning\"]\n```\n\n**`data/hello/workflows/hello_workflow.yaml`**\n```yaml\ngreet:\n  nodes:\n    - name: Greeting\n      type: node\n      class: GreetingNode\n      agent: HelloAgent\n  edges: []\n```\n\n\n\nThis modular structure lets you **add new domains**  \nby simply creating a folder like `data/school/` or `data/finance/`  \nand defining custom `intents.yaml` + `workflow.yaml` files.\n\n---\n\n## 📂 Project Structure\n\nagent-flow-framework/\n├── core/                # Base abstractions \u0026 registry\n├── orchestrator/        # LangGraph builder \u0026 orchestration logic\n├── nodes/               # Domain-specific nodes\n├── agents/              # Domain-specific agents\n├── tools/               # External API / DB / function tools\n├── data/                # Domain intents \u0026 workflows (YAML)\n├── providers/           # LLM providers (AzureOpenAI, etc.)\n├── memory/              # Memory interface \u0026 Redis implementation\n├── api/                 # FastAPI endpoints\n├── main.py              # FastAPI entrypoint\n└── requirements.txt\n\n---\n\n## 🧠 Core Concepts\n\n**Multi-Agent Orchestration Framework** consists of three layers — from low-level abstraction to runtime orchestration — each clearly separated and independently extensible.\n\n| Layer | Role | Key Components | Purpose |\n|-------|------|----------------|----------|\n| 🧩 **Execution Layer** | Executes business and cognitive logic directly | `Node`, `Agent`, `Tool` | Executes domain rules and workflows, performs LLM reasoning, and interacts with external systems. |\n| ⚙️ **Core Layer** | Provides foundational abstractions and common capabilities | `BaseAgent`, `BaseNode`, `BaseTool`, `Config`, `Logger`, `MemoryInterface`, `Registry`, `Exceptions` | Ensures unified lifecycle, structured logging, configuration management, memory abstraction, dynamic registration, and error modeling. |\n| 🕹️ **Orchestration Layer** | Runtime orchestration and multi-domain routing | `LangGraphBuilder`, `AgentRouter`, `StateManager`, `OrchestratorImpl`, `ReflectionNode`, `FeedbackManager` | Builds LangGraph workflows from YAML, routes by domain or intent, manages session state and memory, and coordinates multi-agent execution. |\n\n---\n\n### ⚙️ Core Layer\n\n**Base Abstractions:**  \n`base_agent.py`, `base_node.py`, `base_tool.py`  \nDefine a consistent lifecycle (`pre_* → execute → post_*`) and encapsulate error handling across all components.\n\n**Configuration \u0026 Logging:**  \n`config.py` loads environment variables and system settings;  \n`logger.py` provides structured, contextual logging with traceable IDs.\n\n**Registry:**  \n`registry.py` enables dynamic registration and runtime discovery of nodes, agents, and tools — supporting modular plug-and-play extensibility.\n\n**Memory Interface:**  \n`memory_interface.py` unifies short-term (e.g., Redis) and long-term (e.g., vector store) memory operations through a consistent interface.\n\n**Exception Model:**  \n`exceptions.py` defines standardized errors (`AgentError`, `NodeError`, …) to ensure predictable error propagation and graceful recovery.\n\n---\n\n### 🕹️ Orchestration Layer\n\n**Responsibilities:**  \nDrives runtime orchestration, workflow construction, and multi-domain coordination.\n\n- **LangGraphBuilder:** Parses YAML definitions and constructs executable LangGraph workflows.  \n- **AgentRouter:** Selects the appropriate agent based on intent recognition or contextual routing.  \n- **StateManager:** Manages conversation state, context persistence, and execution cache.  \n- **OrchestratorImpl:** The central execution engine — handles unified entrypoints, async execution, exception flow, and callback control.  \n- **ReflectionNode / FeedbackManager:** Support reflective reasoning, evaluation, and multi-agent feedback loops.\n\n---\n\n### 🧩 Execution Layer\n\n**Node:**  \nEncapsulates deterministic logic or structured data transformation steps.\n\n**Agent:**  \nHandles reasoning and decision-making using LLMs, capable of invoking nodes and tools dynamically.\n\n**Tool:**  \nBridges the system to the external world (APIs, databases, file systems), designed to be declarative, stateless, and reusable.\n\n---\n\n## 🔧 Extending the Framework\n\nYou can easily extend the framework by adding:\n- a new **domain** (e.g., `data/finance/`)\n- a new **agent** that inherits from `BaseAgent`\n- or a new **tool** that implements `BaseTool`.\n\nThen just register it in your YAML workflow — no orchestration code changes required.\n\n---\n\n## 🤝 Contributing\n\nContributions, issues, and feature requests are welcome!  \nFeel free to open a [Pull Request](https://github.com/yx-fan/agent-flow-framework/pulls) or start a discussion.\n\nPlease read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n---\n\n## ⭐ Support\n\nIf you find this framework useful, please give it a **⭐️ star** — it helps others discover the project and keeps development active!\n\n---\n\n## 📜 License\nMIT License © 2025 [Yuxin Fan](https://github.com/yx-fan)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyx-fan%2Fmulti-agent-orchestration-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyx-fan%2Fmulti-agent-orchestration-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyx-fan%2Fmulti-agent-orchestration-framework/lists"}