Agent-Wiz：分析AI智能体工作流程和安全风险

综合介绍

Agent-Wiz 是一个开源的Python命令行工具，专为开发者、研究人员和安全团队设计。它能从LangGraph、CrewAI、AutoGen等主流AI智能体框架中提取复杂的工作流程，生成直观的可视化图表，并通过MAESTRO威胁建模框架自动分析潜在安全风险。Agent-Wiz让用户清晰了解智能体、工具和数据流之间的交互逻辑，适用于调试代码、优化设计或评估系统安全性。

功能列表

• 提取AI智能体的工作流程，生成详细的节点和连接数据。
• 生成交互式可视化图表，展示智能体、工具和数据流的动态关系。
• 基于MAESTRO框架进行威胁建模，输出安全风险报告。
• 支持多种AI框架，包括AutoGen、CrewAI、LangGraph、LlamaIndex等。
• 提供简洁的命令行界面，支持JSON格式输出，便于开发者集成。
• 允许用户自定义解析器，扩展对新框架的支持。

使用帮助

Agent-Wiz 是一个轻量级的命令行工具，基于Python开发，安装简单，功能强大。以下是详细的安装和使用指南，帮助用户快速上手并充分利用其功能。

安装流程

Agent-Wiz 需要Python 3.8或更高版本，并依赖OpenAI API进行部分功能。以下是安装步骤：

1. 安装Agent-Wiz
   打开终端，运行以下命令直接通过pip安装：

   pip install repello-agent-wiz
   

   这会自动安装Agent-Wiz及其依赖库，如Click、Graphviz等。

2. 设置OpenAI API密钥
   部分功能（如威胁建模）需要OpenAI API支持。运行以下命令设置环境变量：
   • macOS/Linux：

     export OPENAI_API_KEY=sk-...
     

   • Windows：

     set OPENAI_API_KEY=sk-...
     

   为持久化设置，可将上述命令添加到.bashrc、.zshrc或环境变量配置文件中。

3. 验证安装
   安装完成后，运行以下命令检查是否成功：

   agent-wiz --help
   

   如果显示命令帮助信息，说明安装无误。

使用方法

Agent-Wiz 提供三个核心命令：extract（提取工作流程）、visualize（生成可视化图表）和analyze（进行威胁建模）。以下是详细操作说明。

1. 提取工作流程

此功能通过静态解析代码，提取智能体的工作流程。假设你有一个基于CrewAI的项目，运行以下命令：

agent-wiz extract --framework crewai --directory ./my_project --output workflow.json

• --framework：指定框架，支持autogen、crewai、langgraph、llamaindex、n8n、swarm等。
• --directory：指定项目文件夹路径，Agent-Wiz会分析代码结构。
• --output：指定输出文件路径，生成JSON格式的工作流程数据。
  输出的JSON文件包含节点（智能体、工具等）和边（交互关系），结构如下：

{
"nodes": [{"id": "agent1", "type": "agent"}, ...],
"edges": [{"from": "agent1", "to": "tool1"}, ...],
"metadata": {"framework": "crewai"}
}

2. 生成可视化图表

可视化功能将工作流程转换为交互式图表，展示智能体之间的连接。运行以下命令：

agent-wiz visualize --input workflow.json --open

• --input：指定提取的JSON文件。
• --open：可选，自动在默认浏览器中打开生成的HTML图表。
  图表基于D3.js，显示智能体、工具和数据流的动态关系，用户可缩放和拖动查看细节。

3. 进行威胁建模

威胁建模功能基于MAESTRO框架，分析工作流程中的安全风险。运行以下命令：

agent-wiz analyze --input workflow.json

• --input：使用提取的JSON文件。
  运行后，工具会生成一个Markdown格式的报告（如crewai_report.md），内容包括：
• 系统目标和资产清单。
• 攻击入口和潜在威胁。
• 风险评估和安全建议。
  MAESTRO框架具体分析以下方面：
• 任务目标：明确系统功能和安全需求。
• 资产：列出智能体、工具和数据流。
• 入口：识别可能的攻击点。
• 控制措施：评估现有防御机制。
• 威胁：列出漏洞和攻击场景。
• 风险：计算影响和可能性。
• 运营：检查运行时的安全问题。

4. 查看帮助信息

如需了解更多命令详情，运行：

agent-wiz --help

这会列出所有可用命令及其参数，帮助用户探索功能。

支持的框架

Agent-Wiz 支持以下主流AI智能体框架，每种框架都有专门的AST解析器，确保提取准确：

• AutoGen：支持核心功能和AgentChat模块。
• CrewAI：解析团队协作智能体。
• LangGraph：处理复杂的有向图工作流。
• LlamaIndex：支持数据索引和查询智能体。
• n8n：解析自动化工作流。
• OpenAI Agents：兼容OpenAI的智能体API。
• Pydantic-AI：支持基于Pydantic的智能体。
• Swarm：处理多智能体协作。

进阶使用

• 批量分析：编写脚本循环调用extract和visualize，处理多个项目。
• 自定义输出：调整图表样式，参考项目文档中的D3.js配置。
• 扩展框架：开发者可基于SDK编写新解析器，扩展对其他框架的支持。
• 安全报告优化：结合人工审查，完善威胁建模报告。

注意事项

• 确保项目代码包含清晰的结构和注释，便于解析。
• OpenAI API密钥需有效，否则威胁建模功能不可用。
• 如果遇到依赖问题，运行以下命令升级pip：

  pip install --upgrade pip
  

• 可视化图表建议在现代浏览器（如Chrome）中查看，以获得最佳体验。

通过以上步骤，用户可以轻松安装Agent-Wiz，提取工作流程、生成图表并分析安全风险。

应用场景

1. 开发者优化智能体系统
   在开发LangGraph智能体时，开发者可能难以理清复杂的交互逻辑。Agent-Wiz提取工作流程并生成图表，帮助快速定位问题，提升系统效率。
2. 安全团队识别潜在威胁
   安全专家需要评估AutoGen智能体是否存在漏洞。Agent-Wiz的MAESTRO威胁建模功能生成详细报告，列出攻击入口和改进建议。
3. 技术培训展示AI框架
   培训讲师使用Agent-Wiz生成CrewAI工作流的交互式图表，向学生直观展示多智能体协作原理，降低学习门槛。
4. 研究人员分析新框架
   研究人员探索新兴框架如Swarm时，可用Agent-Wiz提取其工作流程，比较不同框架的优劣，辅助学术研究。

QA

1. Agent-Wiz是否需要OpenAI API？
   威胁建模功能需要OpenAI API密钥，提取和可视化功能无需API。
2. 支持哪些威胁建模框架？
   目前支持MAESTRO，STRIDE、PASTA等框架正在开发中。
3. 可以处理大型项目吗？
   可以，但建议项目代码结构清晰，解析效率更高。
4. 输出的图表能否导出其他格式？
   目前支持HTML和JSON，未来可能支持PNG或SVG。