Content
<div align="center">
⭐ If this project is helpful to 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)
[📚 Docs](https://jiayuxu0.github.io/zipagent) | [🚀 Quick Start](#-quick-start) | [💬 Discussions](https://github.com/JiayuXu0/ZipAgent/discussions) | [🐛 Bug Report](https://github.com/JiayuXu0/ZipAgent/issues) | [🌍 English](README_EN.md)
</div>
ZipAgent is a modern Python AI Agent framework focused on simplicity, efficiency, and extensibility. **It implements a complete agent framework with Agent engine, tool system, and dialogue management in only 700 lines of core code, 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="智能客服"/>
<br/><b>Customer Service</b><br/>
<small>Automatically answer FAQs<br/>Handle order inquiries</small>
</td>
<td align="center">
<img src="docs/assets/icon_code.png" width="60px" alt="代码助手"/>
<br/><b>Code Assistant</b><br/>
<small>Code review and generation<br/>Bug fix suggestions</small>
</td>
<td align="center">
<img src="docs/assets/icon_data.png" width="60px" alt="数据分析"/>
<br/><b>Data Analysis</b><br/>
<small>Automatically generate reports<br/>Data insight discovery</small>
</td>
</tr>
<tr>
<td align="center">
<img src="docs/assets/icon_content.png" width="60px" alt="内容生成"/>
<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="工作流自动化"/>
<br/><b>Workflow Automation</b><br/>
<small>Task scheduling and execution<br/>Process automation</small>
</td>
<td align="center">
<img src="docs/assets/icon_qa.png" width="60px" alt="知识问答"/>
<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 Agents in a few lines of code
- **🔧 Tool System**: Powerful `@function_tool` decorator for easy extension of AI capabilities
- **🌊 Streaming Output**: Full streaming support for real-time interactive experience
- **📝 Context Management**: Automatically manage conversation history and context state
- **🔗 MCP Integration**: Native support for Model Context Protocol, integrate external tools
- **⚡ Modern**: Based on Python 3.10+, supports 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 a tool
@function_tool
def calculate(expression: str) -> str:
"""Calculate a mathematical expression"""
return str(eval(expression))
# 2. Create an Agent
agent = Agent(
name="MathAssistant",
instructions="You are a math assistant",
tools=[calculate]
)
# 3. Start the conversation
result = Runner.run(agent, "Calculate 23 + 45")
print(result.content) # "The result of calculating 23 + 45 is 68"
```
## 📚 Feature Demonstration
### 🌊 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 conversation
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"
# Conversation statistics
print(f"Number of turns: {context.turn_count}")
print(f"Token usage: {context.usage}")
```
### 🔗 MCP Tool Integration
```python
from zipagent import MCPTool
# Connect to external MCP tools
async def demo():
# Connect to the AMap Maps tool
amap_tools = await MCPTool.connect(
command="npx",
args=["-y", "@amap/amap-maps-mcp-server"],
env={"AMAP_MAPS_API_KEY": "your_key"}
)
# Mix 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, "How is the weather 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 number of 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
)
```
## 🎯 Usage Scenarios
- **💬 Chatbots**: Customer service, Q&A, and general chat bots
- **🔧 Intelligent Assistants**: Code assistants, writing assistants, data analysis assistants
- **🌐 Tool Integration**: Integrate APIs, databases, and third-party services
- **📊 Workflow Automation**: Automation of complex multi-step tasks
- **🔍 Knowledge Q&A**: Knowledge base-based intelligent Q&A systems
## 📖 Complete Examples
See the `examples/` directory for more examples:
- [`basic_demo.py`](examples/basic_demo.py) - Basic feature demonstration
- [`stream_demo.py`](examples/stream_demo.py) - Streaming output demonstration
- [`mcp_demo.py`](examples/mcp_demo.py) - MCP tool integration demonstration
```bash
# Run the 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 the 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 check
uv run ruff check --fix
uv run pyright
```
### Contribution Guide
We welcome contributions of all kinds!
1. 🐛 **Report Bugs**: Submit an [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 a Pull Request
## 📄 License
MIT License - See [LICENSE](LICENSE) file for details
## 🤝 Acknowledgments
Thanks to all contributors and community support!
- OpenAI - Provides powerful LLM APIs
- MCP Community - Model Context Protocol standard
- Python Ecosystem - Excellent development toolchain
