Content
<div align="center">
⭐ **If this project helps you, please give us a Star!** ⭐
<p align="center">
<img src="docs/assets/logo.jpg" alt="ZipAgent Logo" width="120"/>
<img src="https://readme-typing-svg.herokuapp.com?font=Fira+Code&size=45&duration=3000&pause=1000&color=2E86AB¢er=true&vCenter=true&width=300&height=60&lines=ZipAgent" alt="ZipAgent Title"/>
</p>
[](https://badge.fury.io/py/zipagent)
[](https://pepy.tech/project/zipagent)
[](https://pypi.org/project/zipagent/)
[](https://opensource.org/licenses/MIT)
[📚 Documentation](https://jiayuxu0.github.io/zipagent) | [🚀 Quick Start](#-quick-start) | [💬 Discussion](https://github.com/JiayuXu0/ZipAgent/discussions) | [🐛 Issue Report](https://github.com/JiayuXu0/ZipAgent/issues) | [🌍 English](README_EN.md)
</div>
ZipAgent is a modern Python AI Agent framework that focuses on simplicity, efficiency, and extensibility. **With only 700 lines of core code, it implements a complete intelligent agent framework including Agent engine, tool system, and dialogue management, allowing you to quickly build your own AI assistant.**
## 🎯 Application Scenarios
<table>
<tr>
<td align="center">
<img src="docs/assets/icon_chatbot.png" width="60px" alt="Chatbot"/>
<br/><b>Chatbot</b><br/>
<small>Automatically answer common questions<br/>Handle order inquiries</small>
</td>
<td align="center">
<img src="docs/assets/icon_code.png" width="60px" alt="Code Assistant"/>
<br/><b>Code Assistant</b><br/>
<small>Code review and generation<br/>Bug repair suggestions</small>
</td>
<td align="center">
<img src="docs/assets/icon_data.png" width="60px" alt="Data Analysis"/>
<br/><b>Data Analysis</b><br/>
<small>Automatically generate reports<br/>Data insights discovery</small>
</td>
</tr>
<tr>
<td align="center">
<img src="docs/assets/icon_content.png" width="60px" alt="Content Generation"/>
<br/><b>Content Generation</b><br/>
<small>Article writing assistant<br/>Marketing copy generation</small>
</td>
<td align="center">
<img src="docs/assets/icon_automation.png" width="60px" alt="Workflow Automation"/>
<br/><b>Workflow Automation</b><br/>
<small>Task scheduling execution<br/>Process automation</small>
</td>
<td align="center">
<img src="docs/assets/icon_qa.png" width="60px" alt="Knowledge Q&A"/>
<br/><b>Knowledge Q&A</b><br/>
<small>Enterprise knowledge base<br/>Intelligent Q&A system</small>
</td>
</tr>
</table>
## ✨ Core Features
- **🎯 Simple API**: Minimalist design, build AI Agent in a few lines of code
- **🔧 Tool System**: Powerful `@function_tool` decorator, easily extend AI capabilities
- **🌊 Streaming Output**: Complete streaming processing support, providing real-time interaction experience
- **📝 Context Management**: Automatically manage dialogue history and context state
- **🔗 MCP Integration**: Native support for Model Context Protocol, integrating external tools
- **⚡ Modern**: Based on Python 3.10+, supporting asynchronous programming
- **🧪 High Quality**: 120+ test cases, 78% code coverage
## 🚀 Quick Start
### Installation
```bash
pip install zipagent
```
### Get Started in 5 Minutes
```python
from zipagent import Agent, Runner, function_tool
# 1. Define tool
@function_tool
def calculate(expression: str) -> str:
"""Evaluate mathematical expression"""
return str(eval(expression))
# 2. Create Agent
agent = Agent(
name="MathAssistant",
instructions="You are a math assistant",
tools=[calculate]
)
# 3. Start conversation
result = Runner.run(agent, "Calculate 23 + 45")
print(result.content) # "23 + 45 calculation result is 68"
```
## 📚 Function Showcase
### 🌊 Streaming Output
```python
from zipagent import StreamEventType
# Real-time streaming response
for event in Runner.run_stream(agent, "Explain what is artificial intelligence"):
if event.type == StreamEventType.ANSWER_DELTA:
print(event.content, end="", flush=True) # Typewriter effect
elif event.type == StreamEventType.TOOL_CALL:
print(f"🔧 Calling tool: {event.tool_name}")
```
### 📝 Context Management
```python
from zipagent import Context
# Multi-turn dialogue
context = Context()
result1 = Runner.run(agent, "My name is Xiaoming", context=context)
result2 = Runner.run(agent, "What is my name?", context=context)
print(result2.content) # "Your name is Xiaoming"
# Dialogue statistics
print(f"Dialogue turns: {context.turn_count}")
print(f"Token usage: {context.usage}")
```
### 🔗 MCP Tool Integration
```python
from zipagent import MCPTool
# Connect external MCP tool
async def demo():
# Connect Amap tool
amap_tools = await MCPTool.connect(
command="npx",
args=["-y", "@amap/amap-maps-mcp-server"],
env={"AMAP_MAPS_API_KEY": "your_key"}
)
# Mix and match local tools and MCP tools
agent = Agent(
name="MapAssistant",
instructions="You are a map assistant",
tools=[calculate, amap_tools] # Unified interface!
)
result = Runner.run(agent, "What is the weather like in Beijing today?")
print(result.content)
```
## 🔧 Advanced Features
### Exception Handling
```python
from zipagent import ToolExecutionError, MaxTurnsError
try:
result = Runner.run(agent, "Calculate 10 / 0", max_turns=3)
except ToolExecutionError as e:
print(f"Tool execution failed: {e.details['tool_name']}")
except MaxTurnsError as e:
print(f"Maximum turns reached: {e.details['max_turns']}")
```
### Custom Model
```python
from zipagent import OpenAIModel
# Custom model configuration
model = OpenAIModel(
model="gpt-4",
api_key="your_api_key",
base_url="https://api.openai.com/v1"
)
agent = Agent(
name="CustomAgent",
instructions="You are an assistant",
tools=[calculate],
model=model
)
```
## 🎯 Use Cases
- **💬 Chatbot**: Customer service, Q&A, chatbots
- **🔧 Intelligent Assistant**: Code assistant, writing assistant, data analysis assistant
- **🌐 Tool Integration**: Integrate APIs, databases, third-party services
- **📊 Workflow Automation**: Complex multi-step task automation
- **🔍 Knowledge Q&A**: Intelligent Q&A system based on knowledge base
## 📖 Complete Examples
Check the `examples/` directory for more examples:
- [`basic_demo.py`](examples/basic_demo.py) - Basic functionality demo
- [`stream_demo.py`](examples/stream_demo.py) - Streaming output demo
- [`mcp_demo.py`](examples/mcp_demo.py) - MCP tool integration demo
```bash
# Run examples
python examples/basic_demo.py
python examples/stream_demo.py
python examples/mcp_demo.py
```
## 🏗️ Project Architecture
```
ZipAgent/
├── src/zipagent/ # Core framework
│ ├── agent.py # Agent core class
│ ├── context.py # Context management
│ ├── model.py # LLM model abstraction
│ ├── runner.py # Execution engine
│ ├── tool.py # Tool system
│ ├── stream.py # Streaming processing
│ ├── mcp_tool.py # MCP tool integration
│ └── exceptions.py # Exception system
├── examples/ # Usage examples
├── tests/ # Test suite (120+ tests)
└── docs/ # Documentation
```
## 🛠️ Development
### Local Development Environment
```bash
# Clone project
git clone https://github.com/JiayuXu0/ZipAgent.git
cd ZipAgent
# Use uv to manage dependencies (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
# Run tests
uv run pytest
# Code inspection
uv run ruff check --fix
uv run pyright
```
### Contribution Guidelines
We welcome contributions of all forms!
1. 🐛 **Report Bugs**: Submit [Issue](https://github.com/JiayuXu0/ZipAgent/issues)
2. 💡 **Feature Suggestions**: Discuss new feature ideas
3. 📝 **Documentation Improvements**: Improve documentation and examples
4. 🔧 **Code Contributions**: Submit Pull Request
## 📄 License
MIT License - See [LICENSE](LICENSE) file
## 🤝 Acknowledgements
Thanks to all contributors and community support!
- OpenAI - Provides powerful LLM API
- MCP Community - Model Context Protocol standard
- Python ecosystem - Excellent development toolchain
