ZipAgent

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

🎯 应用场景

智能客服 自动回答常见问题 处理订单查询	代码助手 代码review和生成 bug修复建议	数据分析 自动生成报表 数据洞察发现
内容生成 文章写作助手 营销文案生成	工作流自动化 任务调度执行 流程自动化	知识问答 企业知识库 智能问答系统

✨ 核心特性

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

🚀 快速开始

安装

pip install zipagent

5分钟上手

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"

📚 功能展示

🌊 流式输出

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}")

📝 上下文管理

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 工具集成

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)

🔧 高级功能

异常处理

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']}")

自定义模型

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 - 基础功能演示
• stream_demo.py - 流式输出演示
• mcp_demo.py - MCP 工具集成演示

# 运行示例
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/                   # 文档

🛠️ 开发

本地开发环境

# 克隆项目
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
2. 💡 功能建议: 讨论新功能想法
3. 📝 文档改进: 完善文档和示例
4. 🔧 代码贡献: 提交 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 致谢

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

• OpenAI - 提供强大的 LLM API
• MCP 社区 - Model Context Protocol 标准
• Python 生态 - 优秀的开发工具链## ❓ 常见问题 (FAQ)

基础问题

Q: ZipAgent 是什么？

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

Q: ZipAgent 与 LangChain/CrewAI 有什么区别？

A: ZipAgent 的特点：

• 极简设计：700 行核心代码，几行代码构建 Agent
• 原生 MCP 支持：无缝集成 Model Context Protocol 工具
• 流式输出：完整的流式处理支持，实时交互体验
• 中文友好：原生支持中文，文档完善

Q: ZipAgent 适合什么场景？

A: 适用场景：

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

安装与配置

Q: 如何安装 ZipAgent？

A:

pip install zipagent

Q: 需要什么环境？

A:

• Python 3.10+
• OpenAI API Key（或其他兼容的 LLM API）

Q: 如何配置 API Key？

A:

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",
    tools=[calculate],
    model=model
)

工具系统

Q: 如何定义工具？

A: 使用 @function_tool 装饰器：

from zipagent import function_tool

@function_tool
def calculate(expression: str) -> str:
    """计算数学表达式"""
    return str(eval(expression))

Q: 如何使用 MCP 工具？

A:

from zipagent import MCPTool

# 连接外部 MCP 工具
amap_tools = await MCPTool.connect(
    command="npx",
    args=["-y", "@amap/amap-maps-mcp-server"],
    env={"AMAP_MAPS_API_KEY": "your_key"}
)

agent = Agent(
    name="MapAssistant",
    tools=[amap_tools]
)

Q: 本地工具和 MCP 工具可以混合使用吗？

A: 可以！ZipAgent 提供统一接口：

agent = Agent(
    tools=[calculate, amap_tools]  # 混合使用
)

执行与输出

Q: 如何运行 Agent？

A:

from zipagent import Runner

result = Runner.run(agent, "计算 23 + 45")
print(result.content)

Q: 如何获取流式输出？

A:

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}")

Q: 如何管理多轮对话？

A:

from zipagent import Context

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

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

异常处理

Q: 如何处理异常？

A:

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']}")

开发与贡献

Q: 如何本地开发？

A:

# 克隆项目
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

Q: 如何贡献代码？

A:

1. 🐛 报告 Bug: 提交 Issue
2. 💡 功能建议: 讨论新功能想法
3. 📝 文档改进: 完善文档和示例
4. 🔧 代码贡献: 提交 Pull Request

故障排查

Q: API Key 无效？

A:

• 检查 API Key 是否正确
• 确认 base_url 配置是否正确
• 检查 API Key 是否有额度

Q: 工具执行失败？

A:

• 检查工具函数参数是否正确
• 确认工具返回类型是否匹配
• 查看 ToolExecutionError.details 获取详细信息

Q: MCP 工具连接失败？

A:

• 检查 MCP server 是否安装正确
• 确认环境变量配置正确
• 查看 MCP server 日志

Q: 流式输出中断？

A:

• 检查网络连接稳定性
• 确认模型是否支持流式输出
• 检查 max_turns 设置是否合理

Q: 获取更多帮助？

A:

• 📚 文档
• 💬 讨论
• 🐛 问题反馈