Spec2 Sim Agent

Spec2Sim试剂

一种基于人工智能的多智能体系统，用于自动规范验证

在几秒钟内自动将自然语言系统规范转换为经过验证的仿真代码。

______________________________________________________________________

The logo of this project.

Project Page

Demo Video

目录

• 问题
• 解决方案
• 核心创新：自我修复循环
• 性能结果
• 建筑
• 项目结构
• 快速开始
• 主要特点
• 技术亮点
• 示例：交通信号灯
• 云部署
• 贡献
• 许可证
• 致谢
• 联系

______________________________________________________________________

问题

将自然语言系统规范翻译成可验证的仿真代码是 容易出错、耗时且重复.工程师面临：

• 人工翻译负担：将模糊文本转换为严格的状态机逻辑
• 样板代码：为每个需求编写重复的模拟脚手架
• 验证差距：没有自动验证生成的代码与原始意图匹配的方法
• 迭代开销：调试和验证正确性花费的时间

结果：每个规范2小时以上，错误率高，迭代周期慢。

返回页首

______________________________________________________________________

解决方案

Spec2Sim试剂 使用 自愈多智能体系统 由谷歌的Gemini型号提供动力。通过将任务分解为专门的代理——分析、架构和验证——系统确保：

• 准确度：在编码开始之前，规范是结构化的
• 可靠性：生成的代码会自动验证和自我纠正
• 效率：工程师在几秒钟内（而不是几小时内）原型化并验证系统行为

返回页首

______________________________________________________________________

核心创新：自我修复循环

与传统的代码生成系统不同，Spec2Sim Agent实现了 智能自愈回路:

运作原理

flowchart TD
    T[Natural Language Spec] --> A[Analyst Agent]
    A --> S[Structured JSON]
    S --> C[Architect Agent]
    C --> PY[Python SimPy Code]
    PY --> MCP[MCP Secure Execution]
    MCP --> V[Verifier Agent]
    V -->|PASS| OUT[Verified Model]
    V -->|FAIL + retry=true| FB[Error Feedback]
    FB --> C
    V -->|FAIL + retry=false| ERR[Quality Issue Detected]

主要特点

1. 自动误差分析：验证者不只是说通过/失败——它解释了为什么
2. 情境感知学习：错误日志和执行跟踪反馈给架构师
3. 智能重试决策：AI决定重试是否值得（暂时错误）或无效（代码质量问题）

影响：消除了手动调试循环，将开发时间缩短了87倍。

返回页首

______________________________________________________________________

性能结果

测试摘要

详细结果

价值主张

与手动编码相比：

• 速度：平均41.39秒vs 2小时以上（快87倍）
• 质量：100%验证正确性与潜在的手动错误
• 迭代：即时反馈与调试时间
• 成本：每种规格约0.02美元，而2个工程师小时

节省的总时间：这3种规格约6小时（每种规格2小时）

备注：实际执行结果可能因API响应延迟和模拟复杂度而异。以上结果来自代表性运行。

返回页首

______________________________________________________________________

建筑

多代理系统

Spec2Sim代理使用 谷歌代理开发工具包（ADK） 有三个专业代理商：

1.分析代理人

• 角色：从自然语言中提取结构化规范
• 输出：带有状态、转换、约束和测试场景的JSON
• 科技：Gemini 2.5 Flash Lite，支持JSON模式

2.建筑师代理

• 角色：生成可执行的Python模拟代码
• 输出：完整的SimPy状态机，包括日志记录和测试场景
• 创新：接受验证者对自我纠正代码的反馈

3.验证代理

• 角色：在沙盒中执行代码并根据规范进行验证
• 输出：通过/失败，有详细的推理和重试决定
• 科技：用于安全执行的MCP（模型上下文协议）

技术栈

• 人工智能框架：谷歌ADK+双子座2.5 Flash精简版
• 模拟引擎：SimPy（离散事件模拟）
• 执行沙盒：基于MCP的安全代码执行
• 用户界面：Streamlit用于实时可视化
• 状态管理：InMemoryRunner（会话管理）

返回页首

______________________________________________________________________

项目结构

spec2sim-agent/
│
├── agents/                     # AI Agents
│   ├── analyst_agent.py        # Specification extraction
│   ├── architect_agent.py      # Code generation
│   └── verifier_agent.py       # Verification and execution
│
├── core/                       # Core modules
│   ├── orchestrator.py         # Main pipeline controller
│   └── config.py               # Centralized configuration
│
├── servers/                    # MCP Servers
│   └── simulation_server.py    # Secure code execution via MCP
│
├── tools/                      # Helper utilities
│   └── mermaid_tool.py         # Diagram generation
│
├── demos/                      # Demo scripts
│   ├── traffic_light.py
│   ├── bms_precharge.py
│   └── elevator.py
│
├── specs/                      # Example specifications
│   ├── traffic_light.txt
│   ├── bms_precharge.txt
│   └── elevator.txt
│
├── tests/                      # Testing
│   └── performance_test.py     # Automated performance testing
│
├── deployment/                 # Cloud deployment configuration
│   ├── agent.py                # Simplified agent for cloud
│   ├── requirements.txt        # Cloud dependencies
│   └── README.md               # Deployment guide
│
├── app.py                      # Streamlit web interface
├── requirements.txt            # Dependencies
├── README.md                   # This file
└── .env                        # API key configuration

返回页首

______________________________________________________________________

快速开始

先决条件

• Python 3.11+
• Google Gemini API密钥(在这里买一个)

安装

1. 克隆存储库:

   git clone https://github.com/Avalon-S/Spec2Sim-Agent
   cd spec2sim-agent

1. 安装依赖项:

   pip install -r requirements.txt

1. 设置API密钥:

创建 .env 根目录中的文件：

   GEMINI_API_KEY=your_api_key

运行演示

选项1：命令行

运行单个演示：

python demos/traffic_light.py
python demos/bms_precharge.py
python demos/elevator.py

选项2：Web界面（推荐）

启动Streamlit UI以供交互式使用：

python -m streamlit run app.py

然后：

1. 从下拉列表中选择演示或粘贴自定义规范
2. 点击“运行验证”
3. 观察代理实时工作
4. 查看生成的代码、日志和状态图

选项3：性能测试

运行所有测试并生成报告：

python tests/performance_test.py

返回页首

______________________________________________________________________

主要特点

1.自愈循环

• 自动错误检测和重试
• 向架构师提供上下文感知反馈
• 人工智能驱动的重试决策

2.安全执行

• 基于MCP的沙盒代码执行
• 实时日志捕获
• 对主机系统没有风险

3.智能验证

• 不仅仅是通过/失败——解释推理
• 区分瞬态错误和代码质量问题
• 结构化输出的JSON模式强制

4.实时可观测性

• 流线型UI显示代理进度
• 详细的执行日志
• 美人鱼状态图

5.统一配置

• 单一真相来源(config.py)
• 温度、重试选项、型号设置
• 易于调整和维护

返回页首

______________________________________________________________________

技术亮点

为什么选择多代理？

传统的单片LLM难以应对复杂的多步骤工作流程。Spec2Sim代理商 代理人专业化 提供：

• 关注点分离：每个代理专注于一项任务
• 更容易调试：将故障隔离到特定代理
• 模块化：独立交换或升级代理

为什么选择MCP执行？

• 安全：代码在独立进程中运行
• 可靠性：捕获所有stdout/stderr
• 标准化：使用谷歌的模型上下文协议

为什么自我疗愈？

• 鲁棒性：处理LLM可变性（温度、API问题）
• 用户体验：无需人工干预
• 学习：每次重试都会根据之前的失败进行改进

返回页首

______________________________________________________________________

示例：交通信号灯

输入规格：

System: Traffic Light Controller

States:
- Red: Cars must stop
- Yellow: Prepare to stop
- Green: Cars can go

Transitions:
- Red to Green after 30s
- Green to Yellow after 45s
- Yellow to Red after 5s

Constraints:
- Red_duration = 30s
- Green_duration = 45s  
- Yellow_duration = 5s

输出 （8.67秒后）：

• 已验证的SimPy代码（86行）
• 状态图（美人鱼）
• 执行日志（18行）
• 保证100%正确性

返回页首

______________________________________________________________________

云部署

Spec2Sim代理已成功部署到 谷歌云顶点AI代理引擎展示了生产就绪的云部署能力。

部署证据

代理引擎资源:

projects/YOUR_PROJECT_ID/locations/YOUR_REGION/reasoningEngines/YOUR_ENGINE_ID

部署配置:

• 平台：顶点AI代理引擎
• 地区：欧洲西部1
• 资源：2个CPU内核，4GB内存
• 自动缩放：0-1个实例

部署程序

该部署使用了一个简化的演示版本，展示了多代理架构概念，同时解释了完整的系统功能。

快速部署 （从 deployment/ 目录）：

adk deploy agent_engine \
  --project=YOUR_PROJECT_ID \
  --region=europe-west1 \
  deployment \
  --agent_engine_config_file=deployment/.agent_engine_config.json

完整说明：参见 deployment/README.md 完整的部署指南，包括：

• GCP先决条件和设置
• 验证配置
• API启用
• 测试和清理程序

架构说明

双进程架构（本地版本）

完整的Spec2Sim Agent系统使用 双流程架构:

流程1：代理编排（主流程）

• 运行三个AI代理（分析师、架构师、验证者）
• 管理自我修复循环
• 协调工作流程和反馈

流程2：模拟执行（子流程）

• MCP服务器(simulation_server.py)
• 在隔离环境中执行SimPy仿真代码
• 通过MCP协议返回日志和结果

User Input -> [Agent Process] -> MCP Call -> [Simulation Process] -> Results
                                stdio           SimPy Execution

为什么是两个过程？

• 安全：隔离可能不安全的代码执行
• 容错：模拟崩溃不会影响主代理
• 标准化：使用谷歌的模型上下文协议
• 可扩展性：模拟过程可以单独部署

云部署限制

代理引擎约束：单进程容器环境

• 无法通过启动子流程 subprocess.Popen()
• MCP服务器没有持久的进程管理
• 仅限于单个容器化应用程序

解决方案：简化演示版本

• 部署的代理解释系统架构
• 演示多代理对话流
• 在不完全执行的情况下提供教育价值
• 完整的模拟功能仍保留在本地版本中

看 deployment/README.md 用于部署指南。

返回页首

______________________________________________________________________

贡献

这个项目是为 Kaggle强效胶囊剂 （企业代理跟踪）。

项目目标

1. 自动化工业控制系统验证
2. 演示多代理架构最佳实践
3. 展示谷歌ADK+Gemini功能

返回页首

______________________________________________________________________

许可证

该项目根据MIT许可证获得许可。看 LICENSE 文件以获取详细信息。

返回页首

______________________________________________________________________

致谢

• 谷歌ADK团队：用于强大的代理框架
• 双子座团队：适用于快速且功能强大的Gemini 2.5 Flash Lite型号
• SimPy社区：用于优秀的离散事件仿真库

返回页首