ZipAgent: uma estrutura Python leve para criar assistentes de IA exclusivos em 5 minutos

O ZipAgent é uma estrutura moderna de agente de IA em Python focada em fornecer uma experiência de desenvolvimento limpa, eficiente e facilmente extensível. Projetada com a "leveza" em mente, a estrutura implementa um sistema completo de inteligências, incluindo um mecanismo de agente, sistema de ferramentas e gerenciamento de diálogo, em cerca de 700 linhas de código principal. Isso permite que os desenvolvedores comecem a criar seus próprios assistentes de IA em apenas 5 minutos. O ZipAgent é baseado na versão 3.10+ do Python, suporta programação assíncrona e oferece recursos modernos, incluindo saída de streaming, gerenciamento automático de contexto e suporte nativo para o protocolo de contexto de modelo (MCP). O projeto tem mais de 120 casos de teste para garantir a alta qualidade e a estabilidade do código, tornando-o adequado para a criação de chatbots, assistentes inteligentes, automação de fluxo de trabalho e muitos outros cenários de aplicativos.

Lista de funções

• API simplesCom uma filosofia de design minimalista, os desenvolvedores podem criar um agente de IA básico com apenas algumas linhas de código.
• sistema de ferramentasFornece um poderoso @function_tool Decoradores que facilitam a ampliação dos recursos das funções comuns do Python, convertendo-as em ferramentas que podem ser chamadas por um agente de IA.
• saída de streamingSuporte total para processamento responsivo de streaming: permite uma experiência interativa em tempo real semelhante ao efeito de uma máquina de escrever, aprimorando a experiência do usuário.
• gerenciamento de contexto (computação)Capacidade de gerenciar e manter automaticamente o histórico e o status de várias rodadas de diálogo, eliminando a necessidade de os desenvolvedores manipularem manualmente a lógica complexa do diálogo.
• Integração de MCPSuporte nativo ao protocolo de contexto de modelo: permite fácil integração com ferramentas externas (por exemplo, Goldmap, etc.).
• modernizaçãoO projeto é baseado no Python 3.10+ e adota totalmente a programação assíncrona, garantindo alto desempenho e processamento simultâneo.
• Código de alta qualidadeO projeto contém mais de 120 casos de teste com cobertura de código de 78%, garantindo a estabilidade e a confiabilidade da estrutura.

Usando a Ajuda

O ZipAgent foi projetado para que os desenvolvedores possam começar a trabalhar rapidamente, e o processo de instalação e uso é descrito em detalhes a seguir.

1. preparação e instalação do ambiente

Antes de começar, certifique-se de ter o Python 3.10 ou posterior instalado em seu ambiente de desenvolvimento.

Então, por pip concluirá a instalação do ZipAgent:

pip install zipagent

2. Início rápido de 5 minutos

Depois de instalado, você pode criar um assistente de IA conversacional em apenas três etapas.

Etapa 1: Definir a ferramenta
Ferramentas são recursos que o agente pode usar. O ZipAgent usa um decorador simples @function_tool Você pode transformar qualquer função Python em uma ferramenta.

Por exemplo, definimos uma ferramenta para calcular uma expressão matemática:

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

A string de documentação (docstring) na função é muito importante, e o Agente usa essa descrição para determinar quando a ferramenta deve ser usada.

Etapa 2: Criar agente
Em seguida, crie uma instância de agente e informe quem ele é, suas instruções de tarefa e as ferramentas que pode usar.

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

Etapa 3: Execute o agente e inicie o diálogo
Por fim, o uso de Runner para executar o agente e obter os resultados.

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

Depois de executá-lo, você verá o resultado:

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

Nesse ponto, um agente de IA simples é criado.

3. operação de funções essenciais

A. Obtenção de saída de streaming (efeito máquina de escrever)

Para aprimorar a experiência interativa, você pode usar o run_stream para obter uma resposta de streaming em tempo real.

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

Esse código imprime as respostas do modelo na íntegra e solicita ao Agente quando ele chama a ferramenta.

B. Gerenciar o contexto de várias rodadas de diálogo

Na prática, os usuários geralmente têm várias rodadas de diálogo com um Agente. Context O objeto gerencia automaticamente o histórico do diálogo.

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

Você só precisa colocar o mesmo context passado no objeto run o Agente poderá se lembrar do conteúdo do diálogo anterior.

C. Integração de ferramentas externas (MCP)

O ZipAgent oferece suporte ao uso do MCP para se conectar e usar serviços de ferramentas publicados externamente, o que torna as extensões de ferramentas muito flexíveis.

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. Tratamento de exceções
Ao interagir com um agente, pode haver problemas como a falha na execução da ferramenta ou o diálogo ficar preso em um loop morto etc. O ZipAgent fornece tipos de exceção explícitos para lidar com essas situações.

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

1. Atendimento inteligente ao cliente
   É possível criar um robô inteligente de atendimento ao cliente que possa responder automaticamente às perguntas frequentes dos usuários, verificar o status dos pedidos e lidar com aplicativos de pós-venda. Ao integrar a API interna da empresa como uma ferramenta, o agente pode executar operações comerciais mais complexas.
2. Assistente de desenvolvimento de código
   Forneça aos desenvolvedores um parceiro de codificação que possa ajudar a gerar trechos de código, revisar a qualidade do código, corrigir bugs comuns ou gerar automaticamente casos de teste com base na documentação de requisitos.
3. Análise automatizada de dados
   Os scripts para consulta, processamento e visualização de dados são encapsulados em ferramentas que permitem que o agente automatize as tarefas de análise de dados e gere relatórios de análise com base nos comandos de linguagem natural do usuário.
4. Automação do fluxo de trabalho
   Projete um agente capaz de programar várias ferramentas e serviços para automatizar tarefas complexas de várias etapas, como extrair anexos de e-mails, ler o conteúdo, analisá-lo e, por fim, resumir os resultados em um documento on-line especificado.
5. Perguntas e respostas da Base de Conhecimento Empresarial
   Conecte-se a uma base de conhecimento ou a um banco de dados interno para criar um sistema inteligente de perguntas e respostas. Os funcionários podem fazer perguntas em linguagem natural, e o agente é responsável por recuperar as informações relevantes e fornecer respostas precisas.

QA

1. O que é o ZipAgent?
   O ZipAgent é uma estrutura leve de agente de IA escrita em Python. Ele apresenta código simples, fácil de estender e pode ajudar os desenvolvedores a criar rapidamente um assistente de IA proprietário com invocação de ferramentas, gerenciamento de diálogos e outros recursos em poucos minutos.
2. Tenho que pagar para usar o ZipAgent?
   A estrutura do ZipAgent em si é de código aberto e gratuita sob a licença MIT, portanto, você está livre para usá-la, modificá-la e distribuí-la. Observe, no entanto, que o agente requer internamente chamadas para grandes modelos de linguagem (por exemplo, a família GPT da OpenAI), e o uso desses serviços de modelo geralmente requer uma taxa de chamada de API correspondente.
3. Que tipo de conhecimento técnico é necessário para usá-lo?
   Você precisa ter um conhecimento básico de programação em Python. Entender os conceitos de funções, classes e decoradores será muito útil. Se você quiser fazer um desenvolvimento mais avançado, como a integração de ferramentas externas, será melhor ter conhecimento de programação assíncrona (async/await).
4. Quais modelos de idiomas grandes são compatíveis?
   O ZipAgent tem suporte integrado para modelos OpenAI. Ao mesmo tempo, sua camada de modelo é abstrata, e você pode acessar qualquer outro modelo de linguagem grande personalizando a classe do modelo, por exemplo, Google Gemini, Anthropic Claude etc.