ZipAgent: ein leichtgewichtiges Python-Framework zur Erstellung exklusiver KI-Assistenten in 5 Minuten

ZipAgent ist ein modernes Python-Framework für KI-Agenten, das sich auf die Bereitstellung einer sauberen, effizienten und leicht erweiterbaren Entwicklungserfahrung konzentriert. Das Framework wurde mit dem Gedanken an "Leichtgewichtigkeit" entwickelt und implementiert ein voll funktionsfähiges System von Intelligenzen, einschließlich einer Agenten-Engine, eines Tooling-Systems und einer Dialogverwaltung, in etwa 700 Zeilen Kerncode. Dies ermöglicht es Entwicklern, in nur 5 Minuten mit der Entwicklung eigener KI-Assistenten zu beginnen. ZipAgent basiert auf Python Version 3.10+, unterstützt asynchrone Programmierung und bietet moderne Funktionen wie Streaming Output, automatisches Kontextmanagement und native Unterstützung für das Model Context Protocol (MCP). Das Projekt verfügt über mehr als 120 Testfälle, um eine hohe Qualität und Stabilität des Codes zu gewährleisten, wodurch es sich für die Entwicklung von Chatbots, intelligenten Assistenten, Workflow-Automatisierung und viele andere Anwendungsszenarien eignet.

Funktionsliste

• Einfache APIMit einer minimalistischen Designphilosophie können Entwickler mit nur wenigen Zeilen Code einen einfachen KI-Agenten erstellen.
• Werkzeugsystem: Bietet leistungsstarke @function_tool Dekoratoren, die es einfach machen, die Fähigkeiten gewöhnlicher Python-Funktionen zu erweitern, indem sie sie in Tools umwandeln, die von einem KI-Agenten aufgerufen werden können.
• Streaming-AusgangVollständige Unterstützung für Streaming Responsive Processing ermöglicht ein interaktives Erlebnis in Echtzeit, das dem Effekt einer Schreibmaschine ähnelt und das Nutzererlebnis verbessert.
• Kontextmanagement (Computertechnik)Die Fähigkeit, die Historie und den Status mehrerer Dialogrunden automatisch zu verwalten und zu pflegen, erspart den Entwicklern die manuelle Bearbeitung komplexer Dialoglogiken.
• MCP-IntegrationNative Unterstützung für das Model Context Protocol ermöglicht eine einfache Integration mit externen Tools (z.B. Goldmap, etc.).
• ModernisierungDas Projekt basiert auf Python 3.10+ und setzt vollständig auf asynchrone Programmierung, um hohe Leistung und gleichzeitige Verarbeitung zu gewährleisten.
• Hochwertiger CodeDas Projekt enthält über 120 Testfälle mit einer Codeabdeckung von 78%, wodurch die Stabilität und Zuverlässigkeit des Frameworks gewährleistet wird.

Hilfe verwenden

ZipAgent ist so konzipiert, dass Entwickler schnell damit arbeiten können. Der Installations- und Nutzungsprozess wird im Folgenden ausführlich beschrieben.

1. ökologische Vorbereitung und Installation

Bevor Sie beginnen, stellen Sie sicher, dass Sie Python 3.10 oder höher in Ihrer Entwicklungsumgebung installiert haben.

Dann, durch pip wird die Installation von ZipAgent abgeschlossen:

pip install zipagent

2. 5-minütiger Schnellstart

Nach der Installation können Sie in nur drei Schritten einen KI-Assistenten für Konversationen erstellen.

Schritt 1: Definieren Sie das Werkzeug
Tools sind Fähigkeiten, die der Agent nutzen kann. ZipAgent verwendet einen einfachen Dekorator @function_tool Sie können jede Python-Funktion in ein Werkzeug verwandeln.

Wir definieren zum Beispiel ein Werkzeug, um einen mathematischen Ausdruck zu berechnen:

from zipagent import function_tool
@function_tool
def calculate(expression: str) -> str:
"""这个工具用于计算一个数学表达式的值。"""
# 注意：eval函数有安全风险，这里仅为演示目的
return str(eval(expression))

Der Dokumentationsstring (docstring) in der Funktion ist sehr wichtig, und der Agent verwendet diese Beschreibung, um zu bestimmen, wann das Tool verwendet werden soll.

Schritt 2: Agent erstellen
Als Nächstes erstellen Sie eine Agenteninstanz und teilen ihr mit, wer sie ist, welche Aufgaben sie hat und welche Werkzeuge sie verwenden kann.

from zipagent import Agent
agent = Agent(
name="MathAssistant",
instructions="你是一个非常厉害的数学助手，你需要使用工具来回答用户的数学问题。",
tools=[calculate] # 将刚才定义的工具列表传给Agent
)

Schritt 3: Führen Sie den Agenten aus und starten Sie den Dialog
Schließlich ist die Verwendung von Runner um den Agenten auszuführen und die Ergebnisse zu erhalten.

from zipagent import Runner
# 向Agent提问
result = Runner.run(agent, "请帮我计算一下 (100 + 200) * 3 等于多少？")
# 打印Agent的回答
print(result.content)

Nach der Ausführung sehen Sie die Ausgabe:

(100 + 200) * 3 的计算结果是900

An diesem Punkt wird ein einfacher KI-Agent erstellt.

3. der Betrieb der Kernfunktionen

A. Erzielen von Streaming-Ausgaben (Schreibmaschineneffekt)

Um das interaktive Erlebnis zu verbessern, können Sie die run_stream Methode, um eine Echtzeit-Streaming-Antwort zu erhalten.

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

Dieser Code gibt die Antworten des Modells wortwörtlich aus und fordert den Agenten auf, das Tool aufzurufen.

B. Management des Kontextes mehrerer Dialogrunden

In der Praxis haben die Benutzer in der Regel mehrere Dialogrunden mit einem Agenten. Context Das Objekt verwaltet automatisch die Dialoghistorie.

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

Sie müssen nur die gleichen context Objekt übergeben in run Methode kann sich der Agent an den Inhalt des vorherigen Dialogs erinnern.

C. Integration von externen Tools (MCP)

ZipAgent unterstützt die Verwendung des MCP Protokoll, um sich mit extern veröffentlichten Werkzeugdiensten zu verbinden und diese zu nutzen, was Werkzeugerweiterungen sehr flexibel macht.

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. Behandlung von Ausnahmen
Bei der Interaktion mit einem Agenten kann es zu Problemen kommen, z. B. wenn das Tool nicht ausgeführt wird oder der Dialog in einer toten Schleife stecken bleibt usw. ZipAgent bietet explizite Ausnahmetypen, um diese Situationen zu behandeln.

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']}，已自动终止。")

Anwendungsszenario

1. Intelligente Kundenbetreuung
   Es ist möglich, einen intelligenten Kundendienstroboter zu entwickeln, der automatisch die häufig gestellten Fragen der Benutzer beantwortet, den Status von Bestellungen überprüft und After-Sales-Anwendungen bearbeitet. Durch die Integration der internen API des Unternehmens als Werkzeug kann der Agent komplexere Geschäftsvorgänge durchführen.
2. Assistentin für Code-Entwicklung
   Stellen Sie Entwicklern einen Coding-Partner zur Seite, der bei der Erstellung von Codeschnipseln, der Überprüfung der Codequalität, der Behebung häufiger Fehler oder der automatischen Erstellung von Testfällen auf der Grundlage der Anforderungsdokumentation helfen kann.
3. Automatisierte Datenanalyse
   Skripte für die Datenabfrage, -verarbeitung und -visualisierung sind in Tools gekapselt, die es dem Agenten ermöglichen, Datenanalyseaufgaben zu automatisieren und Analyseberichte auf der Grundlage der natürlichsprachlichen Befehle des Benutzers zu erstellen.
4. Automatisierung von Arbeitsabläufen
   Entwicklung eines Agenten, der in der Lage ist, mehrere Tools und Dienste zu planen, um komplexe, mehrstufige Aufgaben zu automatisieren, wie z. B. das Extrahieren von Anhängen aus E-Mails, das Lesen des Inhalts, die Analyse des Inhalts und schließlich die Zusammenfassung der Ergebnisse in einem bestimmten Online-Dokument.
5. Wissensdatenbank für Unternehmen Q&A
   Stellen Sie eine Verbindung zu einer internen Wissensdatenbank her, um ein intelligentes Q&A-System zu erstellen. Mitarbeiter können Fragen in natürlicher Sprache stellen, und der Agent ist dafür verantwortlich, relevante Informationen abzurufen und präzise Antworten zu geben.

QA

1. Was ist ZipAgent?
   ZipAgent ist ein leichtgewichtiges, in Python geschriebenes KI-Agenten-Framework. Es zeichnet sich durch einfachen Code aus, ist leicht zu erweitern und kann Entwicklern helfen, in wenigen Minuten einen eigenen KI-Assistenten mit Werkzeugaufruf, Dialogmanagement und anderen Funktionen zu erstellen.
2. Muss ich für die Nutzung von ZipAgent bezahlen?
   Das ZipAgent-Framework selbst ist quelloffen und steht unter der MIT-Lizenz, so dass Sie es frei verwenden, verändern und weitergeben können. Beachten Sie jedoch, dass der Agent intern Aufrufe zu großen Sprachmodellen (z. B. der GPT-Familie von OpenAI) benötigt und die Nutzung dieser Modelldienste in der Regel eine entsprechende API-Aufrufgebühr erfordert.
3. Welche technischen Vorkenntnisse brauche ich, um das Programm zu nutzen?
   Sie sollten Grundkenntnisse in der Python-Programmierung haben. Das Verstehen der Konzepte von Funktionen, Klassen und Dekoratoren ist sehr hilfreich. Wenn Sie fortgeschrittenere Entwicklungen durchführen wollen, wie z. B. die Integration externer Tools, dann wäre ein Verständnis der asynchronen Programmierung (async/await) besser.
4. Welche großen Sprachmodelle werden unterstützt?
   ZipAgent verfügt über integrierte Unterstützung für OpenAI-Modelle. Gleichzeitig ist seine Modellschicht abstrakt, und Sie können auf jedes andere große Sprachmodell zugreifen, indem Sie die Modellklasse anpassen, z. B. Google Gemini, Anthropic Claude usw.