# ZipAgent

> 轻量级AI Agent框架，让你5分钟构建专属智能助手。Lightweight AI Agent framework. Build your AI assistant in 5 minutes.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jiayuxu0-zipagent`
- **Verified:** Pending review
- **Seller:** [JiayuXu0](https://agentstack.voostack.com/s/jiayuxu0)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JiayuXu0](https://github.com/JiayuXu0)
- **Source:** https://github.com/JiayuXu0/ZipAgent
- **Website:** https://github.com/JiayuXu0/ZipAgent

## Install

```sh
agentstack add mcp-jiayuxu0-zipagent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

⭐ **如果这个项目对你有帮助，请给我们一个 Star！** ⭐

  
      
  

[](https://badge.fury.io/py/zipagent)
[](https://pepy.tech/project/zipagent)
[](https://pypi.org/project/zipagent/)
[](https://opensource.org/licenses/MIT)

[📚 文档](https://jiayuxu0.github.io/zipagent) | [🚀 快速开始](#-快速开始) | [💬 讨论](https://github.com/JiayuXu0/ZipAgent/discussions) | [🐛 问题反馈](https://github.com/JiayuXu0/ZipAgent/issues) | [🌍 English](README_EN.md)

ZipAgent 是一个现代化的 Python AI Agent 框架，专注于简洁、高效和易扩展。**仅用 700 行核心代码实现 Agent 引擎、工具系统、对话管理的完整智能体框架，让你快速构建专属的 AI 助手。**

## 🎯 应用场景

  
  智能客服
  自动回答常见问题处理订单查询

  
  代码助手
  代码review和生成bug修复建议

  
  数据分析
  自动生成报表数据洞察发现

  
  内容生成
  文章写作助手营销文案生成

  
  工作流自动化
  任务调度执行流程自动化

  
  知识问答
  企业知识库智能问答系统

## ✨ 核心特性

- **🎯 简洁 API**: 极简设计，几行代码构建 AI Agent
- **🔧 工具系统**: 强大的 `@function_tool` 装饰器，轻松扩展 AI 能力
- **🌊 流式输出**: 完整的流式处理支持，提供实时交互体验
- **📝 上下文管理**: 自动管理对话历史和上下文状态
- **🔗 MCP 集成**: 原生支持 Model Context Protocol，集成外部工具
- **⚡ 现代化**: 基于 Python 3.10+，支持异步编程
- **🧪 高质量**: 120+ 测试用例，78% 代码覆盖率

## 🚀 快速开始

### 安装

```bash
pip install zipagent
```

### 5分钟上手

```python
from zipagent import Agent, Runner, function_tool

# 1. 定义工具
@function_tool
def calculate(expression: str) -> str:
    """计算数学表达式"""
    return str(eval(expression))

# 2. 创建 Agent
agent = Agent(
    name="MathAssistant",
    instructions="你是一个数学助手",
    tools=[calculate]
)

# 3. 开始对话
result = Runner.run(agent, "计算 23 + 45")
print(result.content)  # "23 + 45 的计算结果是 68"
```

## 📚 功能展示

### 🌊 流式输出

```python
from zipagent import StreamEventType

# 实时流式响应
for event in Runner.run_stream(agent, "解释什么是人工智能"):
    if event.type == StreamEventType.ANSWER_DELTA:
        print(event.content, end="", flush=True)  # 打字机效果
    elif event.type == StreamEventType.TOOL_CALL:
        print(f"🔧 调用工具: {event.tool_name}")
```

### 📝 上下文管理

```python
from zipagent import Context

# 多轮对话
context = Context()

result1 = Runner.run(agent, "我叫小明", context=context)
result2 = Runner.run(agent, "我叫什么名字？", context=context)
print(result2.content)  # "你叫小明"

# 对话统计
print(f"对话轮数: {context.turn_count}")
print(f"Token 使用: {context.usage}")
```

### 🔗 MCP 工具集成

```python
from zipagent import MCPTool

# 连接外部 MCP 工具
async def demo():
    # 连接高德地图工具
    amap_tools = await MCPTool.connect(
        command="npx",
        args=["-y", "@amap/amap-maps-mcp-server"],
        env={"AMAP_MAPS_API_KEY": "your_key"}
    )
    
    # 混合使用本地工具和 MCP 工具
    agent = Agent(
        name="MapAssistant",
        instructions="你是一个地图助手",
        tools=[calculate, amap_tools]  # 统一接口！
    )
    
    result = Runner.run(agent, "北京今天天气怎么样？")
    print(result.content)
```

## 🔧 高级功能

### 异常处理

```python
from zipagent import ToolExecutionError, MaxTurnsError

try:
    result = Runner.run(agent, "计算 10 / 0", max_turns=3)
except ToolExecutionError as e:
    print(f"工具执行失败: {e.details['tool_name']}")
except MaxTurnsError as e:
    print(f"达到最大轮次: {e.details['max_turns']}")
```

### 自定义模型

```python
from zipagent import OpenAIModel

# 自定义模型配置
model = OpenAIModel(
    model="gpt-4",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1"
)

agent = Agent(
    name="CustomAgent",
    instructions="你是一个助手",
    tools=[calculate],
    model=model
)
```

## 🎯 使用场景

- **💬 聊天机器人**: 客服、问答、闲聊机器人
- **🔧 智能助手**: 代码助手、写作助手、数据分析助手  
- **🌐 工具集成**: 集成 API、数据库、第三方服务
- **📊 工作流自动化**: 复杂的多步骤任务自动化
- **🔍 知识问答**: 基于知识库的智能问答系统

## 📖 完整示例

查看 `examples/` 目录获取更多示例：

- [`basic_demo.py`](examples/basic_demo.py) - 基础功能演示
- [`stream_demo.py`](examples/stream_demo.py) - 流式输出演示
- [`mcp_demo.py`](examples/mcp_demo.py) - MCP 工具集成演示

```bash
# 运行示例
python examples/basic_demo.py
python examples/stream_demo.py
python examples/mcp_demo.py
```

## 🏗️ 项目架构

```
ZipAgent/
├── src/zipagent/           # 核心框架
│   ├── agent.py            # Agent 核心类
│   ├── context.py          # 上下文管理
│   ├── model.py            # LLM 模型抽象
│   ├── runner.py           # 执行引擎
│   ├── tool.py             # 工具系统
│   ├── stream.py           # 流式处理
│   ├── mcp_tool.py         # MCP 工具集成
│   └── exceptions.py       # 异常系统
├── examples/               # 使用示例
├── tests/                  # 测试套件（120+ 测试）
└── docs/                   # 文档
```

## 🛠️ 开发

### 本地开发环境

```bash
# 克隆项目
git clone https://github.com/JiayuXu0/ZipAgent.git
cd ZipAgent

# 使用 uv 管理依赖（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# 运行测试
uv run pytest

# 代码检查
uv run ruff check --fix
uv run pyright
```

### 贡献指南

我们欢迎各种形式的贡献！

1. 🐛 **报告 Bug**: 提交 [Issue](https://github.com/JiayuXu0/ZipAgent/issues)
2. 💡 **功能建议**: 讨论新功能想法
3. 📝 **文档改进**: 完善文档和示例
4. 🔧 **代码贡献**: 提交 Pull Request

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 致谢

感谢所有贡献者和社区支持！

- OpenAI - 提供强大的 LLM API
- MCP 社区 - Model Context Protocol 标准
- Python 生态 - 优秀的开发工具链

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JiayuXu0](https://github.com/JiayuXu0)
- **Source:** [JiayuXu0/ZipAgent](https://github.com/JiayuXu0/ZipAgent)
- **License:** MIT
- **Homepage:** https://github.com/JiayuXu0/ZipAgent

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jiayuxu0-zipagent
- Seller: https://agentstack.voostack.com/s/jiayuxu0
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.