{"id":35453827,"url":"https://github.com/a03hcy/agenticle","last_synced_at":"2026-01-03T05:02:28.251Z","repository":{"id":316078440,"uuid":"1061556596","full_name":"A03HCY/Agenticle","owner":"A03HCY","description":"A lightweight, extensible Python framework for building and orchestrating single or multi-agent AI systems. | 一个轻量、可扩展的 Python 框架，用于构建和编排单智能体或多智能体 AI 系统。","archived":false,"fork":false,"pushed_at":"2025-10-22T10:55:57.000Z","size":1099,"stargazers_count":85,"open_issues_count":0,"forks_count":9,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-12-22T00:34:15.417Z","etag":null,"topics":["agent-framework","ai-agents","mutil-agent","python"],"latest_commit_sha":null,"homepage":"","language":"Python","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/A03HCY.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T04:48:51.000Z","updated_at":"2025-11-24T06:16:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"e6860934-101b-433f-bdc0-24653e075007","html_url":"https://github.com/A03HCY/Agenticle","commit_stats":null,"previous_names":["a03hcy/agentframe"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/A03HCY/Agenticle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A03HCY%2FAgenticle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A03HCY%2FAgenticle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A03HCY%2FAgenticle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A03HCY%2FAgenticle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/A03HCY","download_url":"https://codeload.github.com/A03HCY/Agenticle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A03HCY%2FAgenticle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28183988,"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":"2026-01-03T02:00:06.471Z","response_time":75,"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-framework","ai-agents","mutil-agent","python"],"created_at":"2026-01-03T05:02:20.963Z","updated_at":"2026-01-03T05:02:28.245Z","avatar_url":"https://github.com/A03HCY.png","language":"Python","readme":"[中文](./README_zh.md)\n\n# Agenticle\n\n[![PyPI version](https://badge.fury.io/py/agenticle.svg)](https://badge.fury.io/py/agenticle)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python Version](https://img.shields.io/pypi/pyversions/agenticle.svg)](https://pypi.org/project/agenticle)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/A03HCY/Agenticle)\n\nAgenticle is a lightweight, event-driven Python framework for building and orchestrating multi-agent systems. It provides simple yet powerful abstractions to create individual agents, equip them with tools, and make them collaborate in groups to solve complex tasks.\n\n## ✨ Highlights\n\n-   ✅ **Declarative Multi-Agent Systems**: Easily define, manage, and version complex multi-agent workflows using a single YAML file.\n-   ✅ **Built-in Real-Time Dashboard**: Instantly visualize agent thoughts and collaboration flows without extra setup, making debugging intuitive.\n-   ✅ **Flexible Collaboration Modes**: Natively supports various team dynamics like `manager_delegation`, `voting`, and `competition` to orchestrate complex agent interactions.\n-   ✅ **Extensible \u0026 Interoperable**: Seamlessly integrate with external tools and services written in any language via the Model Context Protocol (MCP).\n-   ✅ **Parallel Tool Execution**: Agents can execute multiple tools concurrently, dramatically speeding up I/O-bound tasks.\n\n## Installation\n\nInstall the package directly from PyPI:\n\n```bash\npip install agenticle\n```\n\nFor development, clone the repository and install in editable mode:\n\n```bash\ngit clone https://github.com/A03HCY/Agenticle.git\ncd Agenticle\npip install -e .\n```\n\n## 🚀 Quick Start\n\nThere are two ways to get started: the programmatic Python approach (great for quick experiments) and the declarative YAML approach (recommended for managing complex systems).\n\n### Option 1: The Programmatic Way (Python)\n\nYou can define all agents and groups directly in Python.\n\n```python\nfrom agenticle import Agent, Group, Tool, Endpoint\n\n# 1. Define the tool function\ndef get_current_weather(location: str) -\u003e str:\n    \"\"\"Gets the current weather for a specified location.\"\"\"\n    return f\"Weather in {location}: 15 degrees Celsius, sunny.\"\n\n# 2. Create an endpoint configuration\nopenai_endpoint = Endpoint(\n    api_key='YOUR_API_KEY',\n    base_url='YOUR_API_BASE_URL'\n)\n\n# 3. Create the specialist agent\nweather_agent = Agent(\n    name=\"Weather_Specialist\",\n    description=\"Specializes in fetching weather information for a given city.\",\n    tools=[Tool(get_current_weather)],\n    endpoint=openai_endpoint,\n    model_id='your-model-id'\n)\n\n# 4. Create the manager agent\nplanner_agent = Agent(\n    name=\"Planner_Manager\",\n    description=\"A smart planner that breaks down requests and delegates tasks to specialists.\",\n    input_parameters=[{\"name\": \"user_request\"}],\n    tools=[], # The manager delegates, it doesn't work\n    endpoint=openai_endpoint,\n    model_id='your-model-id'\n)\n\n# 5. Assemble the group\ntravel_agency = Group(\n    name=\"Travel_Agency\",\n    agents=[planner_agent, weather_agent],\n    manager_agent_name=\"Planner_Manager\",\n    mode='manager_delegation'\n)\n\n# 6. Run the group\nuser_query = \"I want to travel to Beijing. How is the weather?\"\nevent_stream = travel_agency.run(stream=True, user_request=user_query)\n\nfor event in event_stream:\n    print(event)\n```\n\n### Option 2: The Declarative Way (YAML)\n\nThis is the recommended approach for building and managing complex multi-agent systems.\n\n**1. Create `agents.yaml`:**\n\nDefine a manager and a specialist. The manager will delegate the task to the specialist.\n\n```yaml\n# agents.yaml\nendpoints:\n  default:\n    api_key: \"YOUR_API_KEY\" # Or use environment variable API_KEY\n    base_url: \"YOUR_API_BASE_URL\"\n\nagents:\n  - name: Weather_Specialist\n    description: \"Specializes in fetching weather information for a given city.\"\n    input_parameters: [{name: \"city\"}]\n    tools: [\"get_current_weather\"] # This tool will be provided in Python\n    model_id: \"your-model-id\"\n    endpoint: \"default\"\n\n  - name: Planner_Manager\n    description: \"A smart planner that breaks down requests and delegates tasks to the appropriate specialist.\"\n    input_parameters: [{name: \"user_request\"}]\n    tools: [\"Weather_Specialist\"] # Uses the other agent as a tool\n    model_id: \"your-model-id\"\n    endpoint: \"default\"\n\ngroups:\n  - name: Travel_Agency\n    agents: [\"Planner_Manager\", \"Weather_Specialist\"]\n    manager_agent_name: \"Planner_Manager\"\n    mode: \"manager_delegation\"\n```\n\n**2. Create `main.py`:**\n\nLoad the YAML file and provide the Python function for the `get_current_weather` tool.\n\n```python\nfrom agenticle import Model, Tool\n\n# Define the Python function for the tool mentioned in the YAML\ndef get_current_weather(location: str) -\u003e str:\n    \"\"\"Gets the current weather for a specified location.\"\"\"\n    return f\"Weather in {location}: 15 degrees Celsius, sunny.\"\n\n# Load the entire system from the YAML file\n# The Tool object is automatically created from the function\nmodel = Model(path=\"agents.yaml\", tools=[get_current_weather])\n\n# Access the group defined in YAML\ntravel_agency = model.groups[\"Travel_Agency\"]\n\n# Run the group and stream the events\nevent_stream = travel_agency.run(stream=True, user_request=\"How is the weather in Beijing?\")\nfor event in event_stream:\n    print(event)\n```\n\n**3. Run it!**\n\n```bash\npython main.py\n```\n\nYou will see a real-time stream of events as the `Planner_Manager` receives the request, decides to delegate to the `Weather_Specialist`, and gets the final result.\n\n## Built-in Tools\n\nAgenticle comes with powerful tools for monitoring and integration out-of-the-box.\n\n### Real-Time Monitoring Dashboard\n\nVisualize the event stream from any `Agent` or `Group` in real-time. It's perfect for debugging and observing agent behavior.\n\n![Dashboard Screenshot](examples/dashboard.png)\n\n**How to Use:**\n\n1.  Install dashboard dependencies: `pip install \"agenticle[dashboard]\"`\n2.  Wrap your agent/group with the `Dashboard` and run it.\n\n```python\nfrom agenticle import Agent, Dashboard\n\n# Assume 'my_agent' is an already configured Agent instance\nagent_args = {\"query\": \"What is the weather in London?\"}\n\n# Wrap the agent and run the dashboard server\ndashboard = Dashboard(my_agent, **agent_args)\ndashboard.run() # Server starts at http://127.0.0.1:8000\n```\n\n### RESTful API Server\n\nExpose your agents and groups through a RESTful API to integrate Agenticle into larger applications.\n\n**How to Use:**\n\n1.  Install API dependencies: `pip install \"agenticle[api]\"`\n2.  Register your agents and start the server.\n\n```python\n# in run_api.py\nimport agenticle.server as server\nfrom agenticle.agent import Agent\n\n# 1. Define your agent\nmy_agent = Agent(...)\n\n# 2. Register it with a unique name\nserver.register(\"my_agent_api_name\", my_agent)\n\n# 3. Start the server\nif __name__ == \"__main__\":\n    server.start_server()\n```\n\nNow you can interact with your agent via HTTP endpoints for streaming or asynchronous task execution.\n\n## Key Concepts\n\n### Architecture\n\nThe core components of Agenticle work together to enable complex multi-agent collaboration.\n\n```mermaid\ngraph TD\n    subgraph group [\"Group\"]\n        direction LR\n        Manager_Agent -- \"Delegates to\" --\u003e Specialist_Agent\n    end\n\n    subgraph tools [\"Tools\"]\n        direction TB\n        Python_Function -- \"Wrapped by\" --\u003e Tool\n        External_API -- \"Accessed via\" --\u003e MCP_Client\n    end\n\n    subgraph resources [\"Shared Resources\"]\n        Workspace[\"\u003cbr\u003eWorkspace\u003c/br\u003eShared Files\"]\n    end\n\n    Manager_Agent -- \"Uses\" --\u003e Tool\n    Specialist_Agent -- \"Uses\" --\u003e Tool\n    Manager_Agent -- \"Accesses\" --\u003e Workspace\n    Specialist_Agent -- \"Accesses\" --\u003e Workspace\n    group -- \"Manages\" --\u003e Workspace\n    Tool -- \"Can be\" --\u003e MCP_Client\n\n    style group fill:#f9f,stroke:#333,stroke-width:2px\n    style tools fill:#ccf,stroke:#333,stroke-width:2px\n    style resources fill:#cfc,stroke:#333,stroke-width:2px\n```\n\n### Agent\n\nThe `Agent` is the fundamental actor. It's defined by its `name`, `description`, `tools`, and the LLM `endpoint` it uses. An agent follows a \"Think-Act\" cycle to reason about a task and decide which tool to use.\n\n### Group\n\nA `Group` orchestrates multiple `Agent` instances. Its behavior is determined by the `mode`:\n-   `'manager_delegation'`: A manager agent delegates tasks to specialist agents.\n-   `'broadcast'`: Every agent can communicate with every other agent.\n-   `'round_robin'`: Agents execute sequentially, forming a processing pipeline.\n-   `'voting'`: Agents run in parallel and vote on a final answer.\n-   `'competition'`: Agents compete to produce the best answer, which is then selected by an optimizer agent.\n\n### Workspace\n\nA `Workspace` is a sandboxed directory that can be shared by all agents in a `Group`. This allows them to collaborate by reading and writing files, enabling stateful, long-running tasks.\n\n### Understanding the Event Stream\n\nEvery action in Agenticle generates an `Event`. By streaming these events, you get a transparent, real-time view of the entire execution process, from an agent's internal `reasoning_stream` to its final `decision` and `tool_result`. This is the foundation for the monitoring dashboard and makes debugging easy.\n\n### Integrating with External Tools via MCP\n\nAgenticle supports the **Model Context Protocol (MCP)**, allowing agents to connect to external, language-agnostic tool servers. This means you can integrate with microservices, external APIs, or tools written in other languages as easily as using a local Python function.\n\n## Advanced Usage\n\n### Declarative Setup with YAML\n\nDefining your system in YAML separates architecture from code, making complex setups easy to manage.\n-   **`model = Model(path=\"...\", tools=[...])`**: Load a system from a YAML file. You must provide any non-serializable tools (like Python functions) at runtime.\n-   **`modelize(agents=[...], groups=[...], path=\"...\")`**: Serialize a programmatically created system into a YAML file. This is great for snapshotting a dynamic setup.\n\n### Customizing Agent Behavior with Prompts\n\nYou can completely redefine an agent's behavior, personality, and reasoning structure by providing a custom Jinja2 prompt template.\n\n```python\ncustom_agent = Agent(\n    name=\"Custom_Agent\",\n    # ... other parameters\n    prompt_template_path=\"path/to/your/custom_prompt.md\"\n)\n```\n\nYour template can use variables like `{{ agent_name }}`, `{{ agent_description }}`, and lists of `{{ tools }}` to dynamically generate the system prompt at runtime.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa03hcy%2Fagenticle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa03hcy%2Fagenticle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa03hcy%2Fagenticle/lists"}