<div align="center">
# ContextAgent
**A Context-Central Multi-Agent System Platform**
[](https://www.notion.so/zhimengg/Agent-Z-27f111ca2fa080a28de4d76c49f0b08d?source=copy_link)
[](YOUR_DOCS_LINK_HERE)
[](https://deepwiki.com/context-machine-lab/contextagent)
[](./assets/wechat.jpg)
[](https://discord.gg/74my3Wkn)
</div>
ContextAgent is a lightweight, context-central multi-agent systems framework designed for easy context engineering. It focuses on efficiently managing the context of each agent and binds all agents through simplified, centralized context operations. Unlike traditional multi-agent frameworks, ContextAgent treats agents simply as LLMs with different contexts, eliminating unnecessary complexity. Built with a PyTorch-like API, developers can create sophisticated multi-agent systems with minimal code.
## 🌟 Features
- **📋 Context = Template + State**: Dynamic context management based on [Anthropic's blog](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
- **🔀 Decoupled Agent Design**: Agent = LLM + Context. All agents are just LLMs with different contexts.
- **🎨 PyTorch-Like Pipeline API**: Inherit `BasePipeline`, define async `run()`, use `@autotracing` for tracing.
- **🌐 Multi-LLM Support**: Works with OpenAI, Claude, Gemini, DeepSeek, and more.
- **🧩 Modular Architecture**: Built on OpenAI Agents SDK with clear separation: context, agents, pipeline.
- **⚡ Easy to Use & Customize**: Reuse pipelines with just a query; create new ones with familiar patterns.
## 📢 News
- **[2025-10]** ContextAgent is released now!
## 🎬 Demo
## 📦 Installation
This project uses [uv](https://docs.astral.sh/uv/) for fast, reliable package management.
### Install uv
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for more options.
### Setup Environment
```bash
# Clone the repository
git clone https://github.com/context-machine-lab/contextagent.git
cd contextagent
# Sync dependencies
uv sync
```
#### Configure API Keys
ContextAgent requires API keys for LLM providers. Set up your environment in `.env` file:
```bash
# Copy the example environment file
cp .env.example .env
# Edit .env and add your API keys
```
See [.env.example](.env.example) for complete configuration options.
## 🚀 Quick Start
### Run Built-in Examples
Try out ContextAgent with pre-configured example pipelines:
**Data Science Pipeline** - Automated ML pipeline for data analysis and model building:
```bash
uv run python -m examples.data_science
```
**Web Research Pipeline** - Search-based research with information extraction:
```bash
uv run python -m examples.web_researcher
```
### Basic API Pattern
Here's how to use ContextAgent in your own code:
```python
from pipelines.data_scientist import DataScientistPipeline, DataScienceQuery
# Initialize pipeline with config
pipe = DataScientistPipeline("pipelines/configs/data_science.yaml")
# Create a query
query = DataScienceQuery(
prompt="Analyze the dataset and build a predictive model",
data_path="data/banana_quality.csv"
)
# Execute
pipe.run_sync(query)
```
### Web UI (Pipeline Manager)
Run the lightweight Flask web UI to submit and monitor pipelines with live logs:
```bash
uv run python frontend/app.py --host localhost --port 9090 --debug
```
Then open `http://localhost:9090` in your browser. The UI streams live status and panels from the running pipeline and lets you stop active runs.
## Steps to Build Your Own System
## 🛠️ Steps to Build Your Own System
ContextAgent uses a **PyTorch-like API** for building multi-agent systems. Follow these steps to create your own pipeline:
#### Step 1 - Define Pipeline Class
Inherit from `BasePipeline` and call `super().__init__(config)`:
```python
from pipelines.base import BasePipeline
from pydantic import BaseModel
class YourPipeline(BasePipeline):
def __init__(self, config):
super().__init__(config)
# Your initialization here
```
#### Step 2 - Create Context and Bind Agents
Create a centralized `Context`, get the LLM, and bind agents:
```python
from contextagent.agent import ContextAgent
from contextagent.context import Context
class YourPipeline(BasePipeline):
def __init__(self, config):
super().__init__(config)
self.context = Context(["profiles", "states"])
llm = self.config.llm.main_model
# Manager agent example
self.routing_agent = ContextAgent(self.context, profile="routing", llm=llm)
# Tool agents example
self.tool_agents = {
"data_loader": ContextAgent(self.context, profile="data_loader", llm=llm),
"analyzer": ContextAgent(self.context, profile="analyzer", llm=llm),
# ... add more agents
}
self.context.state.register_tool_agents(self.tool_agents)
```
#### Step 3 - Define Async Run with @autotracing
Define your workflow in an async `run()` method:
```python
import asyncio
from pipelines.base import autotracing
class YourPipeline(BasePipeline):
@autotracing()
async def run(self, query: YourQuery):
self.context.state.set_query(query)
while self.iteration < self.max_iterations:
self.iterate()
# Call agents directly
routing_result = await self.routing_agent(query)
```
#### Step 4 - Define Query Model and Execute
Create a Pydantic model and run your pipeline:
```python
class YourQuery(BaseModel):
prompt: str
# Add your custom fields
# Execute
pipe = YourPipeline("pipelines/configs/your_config.yaml")
query = YourQuery(prompt="Your task here")
result = pipe.run_sync(query)
```
#### Full Example Reference
See complete implementations in:
- **[examples/data_science.py](examples/data_science.py)** - Basic pipeline usage
- **[pipelines/data_scientist.py](pipelines/data_scientist.py)** - Full pipeline implementation reference
- **[Documentation](https://deepwiki.com/context-machine-lab/contextagent)** - Detailed design guide
## 🏗️ Architecture
ContextAgent is organized around a **central conversation state** and a profile-driven agent system. All agents are coordinated through a unified `Context` that manages iteration state and shared information.
### Core Components:
- **`pipelines/`** – Workflow orchestration and configuration management
- **`contextagent/agent/`** – ContextAgent implementation with context awareness and execution tracking
- **`contextagent/context/`** – Centralized conversation state and coordination
- **`contextagent/profiles/`** – Agent profiles defining capabilities (manager, data, web, code, etc.)
- **`contextagent/tools/`** – Tool implementations for data processing, web operations, and code execution
- **`examples/`** – Example pipelines demonstrating usage
- **`frontend/`** – Web UI for pipeline management and monitoring
### Project Structure:
```
contextagent/
├── pipelines/ # Workflow orchestration
├── contextagent/
│ ├── agent/ # ContextAgent implementation
│ ├── context/ # Conversation state management
│ ├── profiles/ # Agent profiles (manager, data, web, code)
│ ├── tools/ # Tool implementations
│ └── artifacts/ # Output formatting
├── examples/ # Example pipelines
└── frontend/ # Web UI
```
For more details, see the [full documentation](https://deepwiki.com/context-machine-lab/contextagent).
## 📊 Benchmarks
ContextAgent's context-central design has been validated on multiple research benchmarks:
- **Data Science Tasks**: Efficient context sharing enables streamlined automated ML pipelines
- **Complex Reasoning**: Centralized state tracking improves multi-step reasoning coordination
- **Deep Research**: Search based complex reasoning and report generation
*Detailed benchmark results and comparisons coming soon.*
## 🗺️ Roadmap
- [x] Persistence Process - Stateful agent workflows
- [x] Experience Learning - Memory-based reasoning
- [x] Tool Design - Dynamic tool creation
- [ ] Frontend Support - Enhanced web UI for system interaction and monitoring
- [ ] MCP Support - Full Model Context Protocol integration for extended agent capabilities
- [ ] Claude Code Skill Support - Native integration with Claude Code environment
- [ ] Workflow RAG - Retrieval-augmented generation for complex workflows
## 📚 Documentation
More details are available at [Documentation](https://deepwiki.com/context-machine-lab/contextagent).
## 🙏 Acknowledgements
ContextAgent's context-central design is inspired by the multi-agent systems research community and best practices in distributed state management. We are particularly grateful to:
- [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) - For providing a lightweight, powerful framework for multi-agent workflows and the financial research agent example that demonstrates structured research patterns.
- [Youtu-Agent](https://github.com/TencentCloudADP/youtu-agent) - For its flexible agent framework architecture with open-source model support and tool generation capabilities.
- [agents-deep-research](https://github.com/qx-labs/agents-deep-research) - For its iterative deep research implementation showcasing multi-agent orchestration for complex reasoning tasks.
We thank the developers of these frameworks and the broader LLM community whose work informed this architecture.
## 🤝 Contributing
We welcome contributions! ContextAgent is designed to be a community resource for multi-agent research. Please open an issue or submit a pull request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 📖 Citation
If you use ContextAgent in your research, please cite:
```bibtex
@misc{contextagent2025,
title={ContextAgent: Agent from Zero},
author={Zhimeng Guo, Hangfan Zhang, Siyuan Xu, Huaisheng Zhu, Teng Xiao, Jingyi Chen, Minhao Cheng},
year={2025},
publisher = {GitHub},
journal = {GitHub repository},
url={https://github.com/context-machine-lab/contextagent}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "contextagent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "agent, multi-agent, ai, llm, research, machine-learning, autonomous-agents",
"author": null,
"author_email": "Zhimeng Guo <gzjz07@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/2f/6f3032c37b41cfca1ea128c86ae7c6dbd60ccd0e984575de7a932f2d36f2/contextagent-0.1.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# ContextAgent\n\n**A Context-Central Multi-Agent System Platform**\n\n[](https://www.notion.so/zhimengg/Agent-Z-27f111ca2fa080a28de4d76c49f0b08d?source=copy_link)\n[](YOUR_DOCS_LINK_HERE)\n[](https://deepwiki.com/context-machine-lab/contextagent)\n[](./assets/wechat.jpg)\n[](https://discord.gg/74my3Wkn)\n\n\n</div>\n\nContextAgent is a lightweight, context-central multi-agent systems framework designed for easy context engineering. It focuses on efficiently managing the context of each agent and binds all agents through simplified, centralized context operations. Unlike traditional multi-agent frameworks, ContextAgent treats agents simply as LLMs with different contexts, eliminating unnecessary complexity. Built with a PyTorch-like API, developers can create sophisticated multi-agent systems with minimal code.\n\n\n## \ud83c\udf1f Features\n\n- **\ud83d\udccb Context = Template + State**: Dynamic context management based on [Anthropic's blog](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).\n- **\ud83d\udd00 Decoupled Agent Design**: Agent = LLM + Context. All agents are just LLMs with different contexts.\n- **\ud83c\udfa8 PyTorch-Like Pipeline API**: Inherit `BasePipeline`, define async `run()`, use `@autotracing` for tracing.\n- **\ud83c\udf10 Multi-LLM Support**: Works with OpenAI, Claude, Gemini, DeepSeek, and more.\n- **\ud83e\udde9 Modular Architecture**: Built on OpenAI Agents SDK with clear separation: context, agents, pipeline.\n- **\u26a1 Easy to Use & Customize**: Reuse pipelines with just a query; create new ones with familiar patterns.\n\n\n## \ud83d\udce2 News\n- **[2025-10]** ContextAgent is released now!\n\n\n## \ud83c\udfac Demo\n\n\n## \ud83d\udce6 Installation\n\nThis project uses [uv](https://docs.astral.sh/uv/) for fast, reliable package management.\n\n### Install uv\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nSee the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for more options.\n\n### Setup Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/context-machine-lab/contextagent.git\ncd contextagent\n\n# Sync dependencies\nuv sync\n```\n\n#### Configure API Keys\n\nContextAgent requires API keys for LLM providers. Set up your environment in `.env` file:\n\n```bash\n# Copy the example environment file\ncp .env.example .env\n# Edit .env and add your API keys\n```\nSee [.env.example](.env.example) for complete configuration options.\n\n\n## \ud83d\ude80 Quick Start\n\n### Run Built-in Examples\n\nTry out ContextAgent with pre-configured example pipelines:\n\n**Data Science Pipeline** - Automated ML pipeline for data analysis and model building:\n```bash\nuv run python -m examples.data_science\n```\n\n**Web Research Pipeline** - Search-based research with information extraction:\n```bash\nuv run python -m examples.web_researcher\n```\n\n### Basic API Pattern\n\nHere's how to use ContextAgent in your own code:\n\n```python\nfrom pipelines.data_scientist import DataScientistPipeline, DataScienceQuery\n\n# Initialize pipeline with config\npipe = DataScientistPipeline(\"pipelines/configs/data_science.yaml\")\n\n# Create a query\nquery = DataScienceQuery(\n prompt=\"Analyze the dataset and build a predictive model\",\n data_path=\"data/banana_quality.csv\"\n)\n\n# Execute\npipe.run_sync(query)\n```\n\n### Web UI (Pipeline Manager)\n\nRun the lightweight Flask web UI to submit and monitor pipelines with live logs:\n\n```bash\nuv run python frontend/app.py --host localhost --port 9090 --debug\n```\n\nThen open `http://localhost:9090` in your browser. The UI streams live status and panels from the running pipeline and lets you stop active runs.\n\n## Steps to Build Your Own System\n\n## \ud83d\udee0\ufe0f Steps to Build Your Own System\n\nContextAgent uses a **PyTorch-like API** for building multi-agent systems. Follow these steps to create your own pipeline:\n\n#### Step 1 - Define Pipeline Class\n\nInherit from `BasePipeline` and call `super().__init__(config)`:\n\n```python\nfrom pipelines.base import BasePipeline\nfrom pydantic import BaseModel\n\nclass YourPipeline(BasePipeline):\n def __init__(self, config):\n super().__init__(config)\n # Your initialization here\n```\n\n#### Step 2 - Create Context and Bind Agents\n\nCreate a centralized `Context`, get the LLM, and bind agents:\n\n```python\nfrom contextagent.agent import ContextAgent\nfrom contextagent.context import Context\n\nclass YourPipeline(BasePipeline):\n def __init__(self, config):\n super().__init__(config)\n\n self.context = Context([\"profiles\", \"states\"])\n llm = self.config.llm.main_model\n\n # Manager agent example\n self.routing_agent = ContextAgent(self.context, profile=\"routing\", llm=llm)\n\n # Tool agents example\n self.tool_agents = {\n \"data_loader\": ContextAgent(self.context, profile=\"data_loader\", llm=llm),\n \"analyzer\": ContextAgent(self.context, profile=\"analyzer\", llm=llm),\n # ... add more agents\n }\n self.context.state.register_tool_agents(self.tool_agents)\n```\n\n#### Step 3 - Define Async Run with @autotracing\n\nDefine your workflow in an async `run()` method:\n\n```python\nimport asyncio\nfrom pipelines.base import autotracing\n\nclass YourPipeline(BasePipeline):\n @autotracing()\n async def run(self, query: YourQuery):\n self.context.state.set_query(query)\n\n while self.iteration < self.max_iterations:\n self.iterate()\n\n # Call agents directly\n routing_result = await self.routing_agent(query)\n```\n\n#### Step 4 - Define Query Model and Execute\n\nCreate a Pydantic model and run your pipeline:\n\n```python\nclass YourQuery(BaseModel):\n prompt: str\n # Add your custom fields\n\n# Execute\npipe = YourPipeline(\"pipelines/configs/your_config.yaml\")\nquery = YourQuery(prompt=\"Your task here\")\nresult = pipe.run_sync(query)\n```\n\n#### Full Example Reference\n\nSee complete implementations in:\n- **[examples/data_science.py](examples/data_science.py)** - Basic pipeline usage\n- **[pipelines/data_scientist.py](pipelines/data_scientist.py)** - Full pipeline implementation reference\n- **[Documentation](https://deepwiki.com/context-machine-lab/contextagent)** - Detailed design guide\n\n\n## \ud83c\udfd7\ufe0f Architecture\n\nContextAgent is organized around a **central conversation state** and a profile-driven agent system. All agents are coordinated through a unified `Context` that manages iteration state and shared information.\n\n### Core Components:\n\n- **`pipelines/`** \u2013 Workflow orchestration and configuration management\n- **`contextagent/agent/`** \u2013 ContextAgent implementation with context awareness and execution tracking\n- **`contextagent/context/`** \u2013 Centralized conversation state and coordination\n- **`contextagent/profiles/`** \u2013 Agent profiles defining capabilities (manager, data, web, code, etc.)\n- **`contextagent/tools/`** \u2013 Tool implementations for data processing, web operations, and code execution\n- **`examples/`** \u2013 Example pipelines demonstrating usage\n- **`frontend/`** \u2013 Web UI for pipeline management and monitoring\n\n### Project Structure:\n\n```\ncontextagent/\n\u251c\u2500\u2500 pipelines/ # Workflow orchestration\n\u251c\u2500\u2500 contextagent/\n\u2502 \u251c\u2500\u2500 agent/ # ContextAgent implementation\n\u2502 \u251c\u2500\u2500 context/ # Conversation state management\n\u2502 \u251c\u2500\u2500 profiles/ # Agent profiles (manager, data, web, code)\n\u2502 \u251c\u2500\u2500 tools/ # Tool implementations\n\u2502 \u2514\u2500\u2500 artifacts/ # Output formatting\n\u251c\u2500\u2500 examples/ # Example pipelines\n\u2514\u2500\u2500 frontend/ # Web UI\n```\n\nFor more details, see the [full documentation](https://deepwiki.com/context-machine-lab/contextagent).\n\n\n## \ud83d\udcca Benchmarks\n\nContextAgent's context-central design has been validated on multiple research benchmarks:\n\n- **Data Science Tasks**: Efficient context sharing enables streamlined automated ML pipelines\n- **Complex Reasoning**: Centralized state tracking improves multi-step reasoning coordination\n- **Deep Research**: Search based complex reasoning and report generation\n\n*Detailed benchmark results and comparisons coming soon.*\n\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n- [x] Persistence Process - Stateful agent workflows\n- [x] Experience Learning - Memory-based reasoning\n- [x] Tool Design - Dynamic tool creation\n- [ ] Frontend Support - Enhanced web UI for system interaction and monitoring\n- [ ] MCP Support - Full Model Context Protocol integration for extended agent capabilities\n- [ ] Claude Code Skill Support - Native integration with Claude Code environment\n- [ ] Workflow RAG - Retrieval-augmented generation for complex workflows\n\n\n## \ud83d\udcda Documentation\n\nMore details are available at [Documentation](https://deepwiki.com/context-machine-lab/contextagent).\n\n\n## \ud83d\ude4f Acknowledgements\n\nContextAgent's context-central design is inspired by the multi-agent systems research community and best practices in distributed state management. We are particularly grateful to:\n\n- [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) - For providing a lightweight, powerful framework for multi-agent workflows and the financial research agent example that demonstrates structured research patterns.\n- [Youtu-Agent](https://github.com/TencentCloudADP/youtu-agent) - For its flexible agent framework architecture with open-source model support and tool generation capabilities.\n- [agents-deep-research](https://github.com/qx-labs/agents-deep-research) - For its iterative deep research implementation showcasing multi-agent orchestration for complex reasoning tasks.\n\nWe thank the developers of these frameworks and the broader LLM community whose work informed this architecture.\n\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! ContextAgent is designed to be a community resource for multi-agent research. Please open an issue or submit a pull request.\n\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n## \ud83d\udcd6 Citation\n\nIf you use ContextAgent in your research, please cite:\n\n```bibtex\n@misc{contextagent2025,\n title={ContextAgent: Agent from Zero},\n author={Zhimeng Guo, Hangfan Zhang, Siyuan Xu, Huaisheng Zhu, Teng Xiao, Jingyi Chen, Minhao Cheng},\n year={2025},\n publisher = {GitHub},\n journal = {GitHub repository},\n url={https://github.com/context-machine-lab/contextagent}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Context-Central Multi-Agent System Platform",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/TimeLovercc/contextagent/issues",
"Documentation": "https://github.com/TimeLovercc/contextagent#readme",
"Homepage": "https://github.com/TimeLovercc/contextagent",
"Repository": "https://github.com/TimeLovercc/contextagent"
},
"split_keywords": [
"agent",
" multi-agent",
" ai",
" llm",
" research",
" machine-learning",
" autonomous-agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "401392f33c0a6f4ca82f172916e9d3585855b091580e9b48b9aac4b207c00f7f",
"md5": "a10f2a18ffed598fe2d95f0a2f4c11c5",
"sha256": "1dbf254b6314534a670c8a561a7a41fb751982d9b520105949a78905357d0d07"
},
"downloads": -1,
"filename": "contextagent-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a10f2a18ffed598fe2d95f0a2f4c11c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 112012,
"upload_time": "2025-10-21T02:39:05",
"upload_time_iso_8601": "2025-10-21T02:39:05.663280Z",
"url": "https://files.pythonhosted.org/packages/40/13/92f33c0a6f4ca82f172916e9d3585855b091580e9b48b9aac4b207c00f7f/contextagent-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2f2f6f3032c37b41cfca1ea128c86ae7c6dbd60ccd0e984575de7a932f2d36f2",
"md5": "12299561a055f42d5cf8ceaf7092351d",
"sha256": "af0d3156cccae0e56aa37c29ec8745a9ddc0d913f2c059b3efa0e40139843138"
},
"downloads": -1,
"filename": "contextagent-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "12299561a055f42d5cf8ceaf7092351d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 86664,
"upload_time": "2025-10-21T02:39:07",
"upload_time_iso_8601": "2025-10-21T02:39:07.145716Z",
"url": "https://files.pythonhosted.org/packages/2f/2f/6f3032c37b41cfca1ea128c86ae7c6dbd60ccd0e984575de7a932f2d36f2/contextagent-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 02:39:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TimeLovercc",
"github_project": "contextagent",
"github_not_found": true,
"lcname": "contextagent"
}
JSON
