ZipAgent 是一个现代化的 Python AI Agent 框架，它专注于提供简洁、高效和易于扩展的开发体验。 该框架的核心设计思想是“轻量”，仅用大约700行核心代码就实现了一个功能完整的智能体系统，包括 Agent 引擎、工具系统和对话管理。 这使得开发者可以在短短5分钟内快速上手，并开始构建自己专属的 AI 助手。 ZipAgent 基于 Python 3.10+ 版本，支持异步编程，并提供了包括流式输出、上下文自动管理、以及对模型上下文协议（MCP）的原生支持等现代化功能。 项目拥有超过120个测试用例，保证了代码的高质量和稳定性，适合用于构建聊天机器人、智能助手、工作流自动化等多种应用场景。
Function List
- 简洁API: 采用极简设计理念，开发者只需几行代码就能构建出一个基本的 AI Agent。
- tooling system: 提供强大的
@function_tool装饰器，可以轻松地将普通 Python 函数转换为 AI Agent 可调用的工具，从而扩展其能力。 - streaming output: 全面支持流式响应处理，能够实现类似打字机效果的实时交互体验，提升了用户感受。
- context management (computing): 能够自动管理和维护多轮对话的历史记录与状态，让开发者无需手动处理复杂的对话逻辑。
- MCP Integration: 原生支持模型上下文协议（Model Context Protocol），可以方便地与外部工具（如高德地图等）进行集成。
- 现代化架构: 项目基于 Python 3.10+，全面拥抱异步编程，保证了高性能和高并发处理能力。
- High quality code: 项目包含超过120个测试用例，代码覆盖率达到78%，确保了框架的稳定性和可靠性。
Using Help
ZipAgent 的设计目标是让开发者能够快速上手，下面将详细介绍其安装和使用流程。
1. Environment preparation and installation
在开始之前，请确保你的开发环境中已经安装了 Python 3.10 或更高版本。
然后，通过 pip 命令即可完成 ZipAgent 的安装：
pip install zipagent
2. 5分钟快速上手
安装完成后，你只需要三个步骤就可以创建一个可以对话的 AI 助手。
步骤一：定义工具
工具是 Agent 可以使用的能力。ZipAgent 使用一个简单的装饰器 @function_tool 就可以将任何 Python 函数变成一个工具。
例如，我们定义一个计算数学表达式的工具：
from zipagent import function_tool
@function_tool
def calculate(expression: str) -> str:
"""这个工具用于计算一个数学表达式的值。"""
# 注意：eval函数有安全风险，这里仅为演示目的
return str(eval(expression))
函数中的文档字符串（docstring）非常重要，Agent会根据这个描述来判断何时应该使用该工具。
步骤二：创建 Agent
接下来，创建一个 Agent 实例，并告诉它它的身份、任务指令以及它能使用的工具。
from zipagent import Agent
agent = Agent(
name="MathAssistant",
instructions="你是一个非常厉害的数学助手，你需要使用工具来回答用户的数学问题。",
tools=[calculate] # 将刚才定义的工具列表传给Agent
)
步骤三：运行 Agent 并开始对话
最后，使用 Runner 来执行 Agent 并获取结果。
from zipagent import Runner
# 向Agent提问
result = Runner.run(agent, "请帮我计算一下 (100 + 200) * 3 等于多少？")
# 打印Agent的回答
print(result.content)
运行后，你将看到输出结果：
(100 + 200) * 3 的计算结果是900
至此，一个简单的 AI Agent 就构建完成了。
3. Operation of core functions
A. 实现流式输出（打字机效果）
为了提升交互体验，你可以使用 run_stream 方法来获取实时的流式响应。
from zipagent import Runner, StreamEventType
# 使用run_stream方法
stream = Runner.run_stream(agent, "简单解释一下什么是人工智能？")
# 遍历事件流
for event in stream:
if event.type == StreamEventType.ANSWER_DELTA:
# ANSWER_DELTA事件表示模型正在生成回答内容
print(event.content, end="", flush=True)
elif event.type == StreamEventType.TOOL_CALL:
# TOOL_CALL事件表示Agent正在调用工具
print(f"\n🔧 正在调用工具: {event.tool_name}...")
这段代码会逐字打印出模型的回答，当 Agent 调用工具时，也会有相应的提示。
B. 管理多轮对话上下文
在实际应用中，用户通常会和 Agent 进行多轮对话。ZipAgent 通过 Context 对象自动管理对话历史。
from zipagent import Context, Runner
# 创建一个上下文对象
context = Context()
# 第一轮对话
Runner.run(agent, "记住，我的名字叫小明。", context=context)
# 第二轮对话
result = Runner.run(agent, "现在，请问我叫什么名字？", context=context)
print(result.content) # 输出: "你叫小明"
# 你还可以查看对话的统计信息
print(f"当前对话轮数: {context.turn_count}")
print(f"累计使用的Token数量: {context.usage}")
你只需要将同一个 context 对象传入 run 方法，Agent 就能记住之前的对话内容。
C. 集成外部工具（MCP）
ZipAgent 支持通过 MCP 协议连接并使用外部发布的工具服务，这让工具扩展变得非常灵活。
import asyncio
from zipagent import MCPTool, Agent, Runner
async def main():
# 假设有一个高德地图的MCP服务在运行
# 这里使用npx启动一个示例服务
amap_tools = await MCPTool.connect(
command="npx",
args=["-y", "@amap/amap-maps-mcp-server"],
env={"AMAP_MAPS_API_KEY": "填写你的高德API密钥"}
)
# 将MCP工具和本地工具混合使用
map_agent = Agent(
name="MapAssistant",
instructions="你是一个地图和天气查询助手。",
tools=[amap_tools] # MCP工具的接口与本地工具完全一样
)
result = Runner.run(map_agent, "查询一下中国北京市今天的天气怎么样？")
print(result.content)
# 运行异步函数
asyncio.run(main())```
### **4. 高级功能**
**A. 自定义模型配置**
默认情况下，ZipAgent 使用 OpenAI 的模型。你也可以轻松更换成其他模型或自定义配置。
```python
from zipagent import OpenAIModel
# 自定义模型，例如使用gpt-4，并指定API地址
custom_model = OpenAIModel(
model="gpt-4",
api_key="你的API Key",
base_url="你的代理API地址或官方地址"
)
# 在创建Agent时传入自定义模型
custom_agent = Agent(
name="CustomAgent",
instructions="...",
tools=[],
model=custom_model
)
B. 异常处理
在与 Agent 交互时，可能会出现工具执行失败或对话陷入死循环等问题。ZipAgent 提供了明确的异常类型用于处理这些情况。
from zipagent import ToolExecutionError, MaxTurnsError
try:
# 设定最大对话轮数为3，防止无限循环
result = Runner.run(agent, "计算 10 / 0", max_turns=3)
except ToolExecutionError as e:
# 捕获工具执行失败的异常
print(f"工具 '{e.details['tool_name']}' 执行失败: {e}")
except MaxTurnsError as e:
# 捕获超出最大轮次的异常
print(f"对话已达到最大轮次 {e.details['max_turns']}，已自动终止。")
application scenario
- Intelligent Customer Service
可以构建一个能够自动回答用户常见问题、查询订单状态、处理售后申请的智能客服机器人。通过集成公司的内部API作为工具，Agent可以完成更复杂的业务操作。 - 代码开发助手
为开发者提供一个编码伙伴，可以帮助生成代码片段、审查代码质量、修复常见的Bug，或者根据需求文档自动生成测试用例。 - Automated data analysis
将数据查询、处理和可视化的脚本封装成工具，让 Agent 可以根据用户的自然语言指令，自动完成数据分析任务并生成分析报告。 - Workflow automation
设计一个能够调度多个工具和服务的 Agent，用于自动化处理复杂的多步骤任务，例如：从邮件中提取附件，读取内容，进行分析，最后将结果汇总到指定的在线文档中。 - 企业知识库问答
连接企业内部的知识库或数据库，创建一个智能问答系统。员工可以用自然语言提问，Agent 负责检索相关信息并给出精准的回答。
QA
- ZipAgent 是什么？
ZipAgent 是一个使用 Python 语言编写的轻量级 AI Agent（智能体）框架。它的特点是代码简洁、易于扩展，可以帮助开发者在几分钟内快速构建出具备工具调用、对话管理等功能的专属 AI 助手。 - 使用 ZipAgent 需要付费吗？
ZipAgent 框架本身是开源免费的，它使用 MIT 许可证，你可以自由地使用、修改和分发。 但请注意，Agent 内部需要调用大语言模型（如 OpenAI 的 GPT 系列），使用这些模型服务通常需要支付相应的 API 调用费用。 - 我需要什么样的技术背景才能使用它？
你需要具备基本的 Python 编程知识。了解函数、类和装饰器的概念会非常有帮助。如果你想进行更高级的开发，例如集成外部工具，那么对异步编程（async/await）有所了解会更好。 - 它支持哪些大语言模型？
ZipAgent 内置了对 OpenAI 模型的支持。同时，它的模型层是抽象的，你可以通过自定义模型类来接入任何其他的大语言模型，例如 Google Gemini、Anthropic Claude 等。
English 
简体中文 
日本語 
Deutsch 
Português do Brasil