ZipAgent 是一个现代化的 Python AI Agent 框架，它专注于提供简洁、高效和易于扩展的开发体验。 该框架的核心设计思想是“轻量”，仅用大约700行核心代码就实现了一个功能完整的智能体系统，包括 Agent 引擎、工具系统和对话管理。 这使得开发者可以在短短5分钟内快速上手，并开始构建自己专属的 AI 助手。 ZipAgent 基于 Python 3.10+ 版本，支持异步编程，并提供了包括流式输出、上下文自动管理、以及对模型上下文协议（MCP）的原生支持等现代化功能。 项目拥有超过120个测试用例，保证了代码的高质量和稳定性，适合用于构建聊天机器人、智能助手、工作流自动化等多种应用场景。
Lista de funções
- 简洁API: 采用极简设计理念，开发者只需几行代码就能构建出一个基本的 AI Agent。
- sistema de ferramentas: 提供强大的
@function_tool装饰器，可以轻松地将普通 Python 函数转换为 AI Agent 可调用的工具，从而扩展其能力。 - saída de streaming: 全面支持流式响应处理，能够实现类似打字机效果的实时交互体验，提升了用户感受。
- gerenciamento de contexto (computação): 能够自动管理和维护多轮对话的历史记录与状态，让开发者无需手动处理复杂的对话逻辑。
- Integração de MCP: 原生支持模型上下文协议（Model Context Protocol），可以方便地与外部工具（如高德地图等）进行集成。
- 现代化架构: 项目基于 Python 3.10+，全面拥抱异步编程，保证了高性能和高并发处理能力。
- Código de alta qualidade: 项目包含超过120个测试用例，代码覆盖率达到78%，确保了框架的稳定性和可靠性。
Usando a Ajuda
ZipAgent 的设计目标是让开发者能够快速上手，下面将详细介绍其安装和使用流程。
1. preparação e instalação do ambiente
在开始之前，请确保你的开发环境中已经安装了 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 并开始对话
Por fim, o uso de 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. operação de funções essenciais
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']}，已自动终止。")
cenário do aplicativo
- Atendimento inteligente ao cliente
可以构建一个能够自动回答用户常见问题、查询订单状态、处理售后申请的智能客服机器人。通过集成公司的内部API作为工具，Agent可以完成更复杂的业务操作。 - 代码开发助手
为开发者提供一个编码伙伴，可以帮助生成代码片段、审查代码质量、修复常见的Bug，或者根据需求文档自动生成测试用例。 - Análise automatizada de dados
将数据查询、处理和可视化的脚本封装成工具，让 Agent 可以根据用户的自然语言指令，自动完成数据分析任务并生成分析报告。 - Automação do fluxo de trabalho
设计一个能够调度多个工具和服务的 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 等。
Português do Brasil 
简体中文 
English 
日本語 
Deutsch