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 Feedback](https://github.com/JiayuXu0/ZipAgent/issues) | [🌍 中文](README.md)
</div>
ZipAgent is a modern Python AI Agent framework focused on simplicity, efficiency, and extensibility. **With just 700 lines of core code, it implements a complete agent framework for the 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="Intelligent Customer Service"/>
<br/><b>Intelligent Customer Service</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 fix 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 with just a few lines of code
- **🔧 Tool System**: Powerful `@function_tool` decorator, easily extend AI capabilities
- **🌊 Streaming Output**: Full support for streaming processing, providing real-time interactive experience
- **📝 Context Management**: Automatically manages conversation history and context state
- **🔗 MCP Integration**: Native support for Model Context Protocol, integrating external tools
- **⚡ Modernization**: Based on Python 3.10+, supports asynchronous programming
- **🧪 High Quality**: 120+ test cases, 78% code coverage
## 🚀 Quick Start
### Installation
```bash
pip install zipagent
```
### 5-Minute Quick Start
```python
from zipagent import Agent, Runner, function_tool
```
# 1. Define Tool
@function_tool
def calculate(expression: str) -> str:
"""Calculate mathematical expression"""
return str(eval(expression))
# 2. Create Agent
agent = Agent(
name="MathAssistant",
instructions="You are a math assistant",
tools=[calculate]
)
# 3. Start a Conversation
```python
result = Runner.run(agent, "Calculate 23 + 45")
print(result.content) # "The result of 23 + 45 is 68"
```
## 📚 Feature Showcase
### 🌊 Stream Output
```python
from zipagent import StreamEventType
```
# Real-time Streaming Response
for event in Runner.run_stream(agent, "Explain what artificial intelligence is"):
if event.type == StreamEventType.ANSWER_DELTA:
print(event.content, end="", flush=True) # Typing effect
elif event.type == StreamEventType.TOOL_CALL:
print(f"🔧 Tool called: {event.tool_name}")
### 📝 Context Management
```python
from zipagent import Context
```
# Multi-turn Dialogue
context = Context()
result1 = Runner.run(agent, "My name is Xiao Ming", context=context)
result2 = Runner.run(agent, "What is my name?", context=context)
print(result2.content) # "Your name is Xiao Ming"
# Conversation Statistics
print(f"Turn Count: {context.turn_count}")
print(f"Token Usage: {context.usage}")
```
### 🔗 MCP Tool Integration
```python
from zipagent import MCPTool
```
# Connecting External MCP Tools
```python
async def demo():
# Connect to Amap tools
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, "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"Reached maximum turns: {e.details['max_turns']}")
```
### Custom Model
```python
from zipagent import OpenAIModel
```
# Custom Model Configuration
```python
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
- **💬 Chatbots**: Customer service, Q&A, casual chatbots
- **🔧 Intelligent Assistants**: Code assistants, writing assistants, data analysis assistants
- **🌐 Tool Integration**: Integrating APIs, databases, third-party services
- **📊 Workflow Automation**: Automating complex multi-step tasks
- **🔍 Knowledge Q&A**: Intelligent Q&A systems based on knowledge bases
## 📖 Complete Example
Check the `examples/` directory for more examples:
- [`basic_demo.py`](examples/basic_demo.py) - Basic functionality demonstration
- [`stream_demo.py`](examples/stream_demo.py) - Stream output demonstration
- [`mcp_demo.py`](examples/mcp_demo.py) - MCP tool integration demonstration
```bash
# Running Examples
```bash
python examples/basic_demo.py
python examples/stream_demo.py
python examples/mcp_demo.py
```
## 🏗️ Project Architecture
```
ZipAgent/
├── src/zipagent/ # Core framework
│ ├── agent.py # Core class of Agent
│ ├── context.py # Context management
│ ├── model.py # LLM (Large Language Model) abstraction
│ ├── runner.py # Execution engine
│ ├── tool.py # Tool system
│ ├── stream.py # Stream processing
│ ├── mcp_tool.py # MCP (Multi-Channel Processing) 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
# Managing Dependencies with uv (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 all forms of contributions!
1. 🐛 **Report Bugs**: Submit an [Issue](https://github.com/JiayuXu0/ZipAgent/issues)
2. 💡 **Feature Suggestions**: Discuss ideas for new features
3. 📝 **Documentation Improvements**: Enhance documentation and examples
4. 🔧 **Code Contributions**: Submit a Pull Request
## 📄 License
MIT License - See the [LICENSE](LICENSE) file for details.
## 🤝 Acknowledgments
Thanks to all contributors and community support!
- OpenAI - Provides a powerful LLM API
- MCP Community - Model Context Protocol standard
- Python Ecosystem - Excellent development toolchain
