HackCrib-AI

align="center"> <h1>🏆 HackCrib AI</h1> <p><strong>一个由 Google Agent Development Kit (ADK) 构建的 AI 驱动的多智能体黑客马拉松导师</strong></p> <p><em>从空白创意到完整的、已批准的项目计划 — 在 2 分钟的对话内。</em></p> <br/> [](https://www.python.org/) [](https://adk.dev/) [](https://aistudio.google.com/) [](https://fastapi.tiangolo.com/) [](https://modelcontextprotocol.io/) [](https://a2a-protocol.org/) [](LICENSE) <br/> <p align="center"> <img src="https://github.com/user-/590e0b1b-6549a-bb5a-cd8d0035e" alt="HackCrib AI Banner width="100%"> </p> </div> --- 📖 目录 - [概述](#-overview) - [功能](#-features) - [技术栈](#-tech-stack) - [架构](#-architecture) - [多智能体工作流](#-multi-agent-workflow) - [人工审批流程](#-human-approval-flow) - [快速开始](#-quick-start) - [用法](#-usage) - [项目结构](#-project-structure) - [API 参考](#-api-reference) - [部署](#-deployment) - [使用的 ADK 功能](#-adk-features-used) - [未来改进](#-future-improvements) - [黑客马拉松](#-hackathon) - [贡献者](#-contributors) - [许可证](#-license) --- ## 🎯 概述 **HackCrib AI** 是一个智能的黑客马拉松规划系统，作为学生的个人 AI 导师。通过自然对话，学生描述他们的黑客马拉松 — 问题陈述、团队组成、时间限制和技术偏好。然后，由六个专门的 AI 智能体组成的管道协同工作，生成结构化、可行的项目计划。 在计划被锁定之前，**人工审批步骤（HITL）**赋予学生完全的控制权：审查 AI 生成的草稿，请求有针对性的批准以生成交付成果。 > **完全基于 [Google Agent Development Kit (ADK).x](https://adk.dev/) 构建 在单个生产级应用程序中演示 10 个 ADK 原语。 --- ## | 功能 | 描述 | |:---|:---| 🤖 **6 个专门的 AI 智能体**客马拉松智能、技术栈顾问、计划器、文档、编排器导师 | | 👤 **人工审批（H）** |确定之前，审查和批准（或请求改进）计划 | | 🔄 **无限改进循环** | 用普通英语描述更改排器重新规划，直到您满意为止 | | 🛡️ **默认安全** | 每次输入都进行 擦除、凭证）和提示注入检测 | | 🔧 **MCP 工具集成** | 通过本地 MCP 服务器进行技术文档搜索、API 发现和依赖项验证 | | 📊 **结构化输出** | 计划根据 `ProjectPlanOutput`antic 模式验证 —觉字段 🔌 **A2A 协议支持** | 与其他 ADK 智能体完全支持 [Agent-to-Agent 协议](https://a2a-protocol.org/)，实现互操作性 | | ⚡ **限制器** | 免费层 Gemini API 设计安全 — 修补全局速率限制器，间隔至少 | | 🐳 **云就绪**容器 + Google Cloud Agent Runtime 部署即用 | | 💬 **持久化学生档案 在对话回合并保留学生的技能和偏好## 🛠️| 层 | 技术 | |:---|: **AI 框架 [Google Agent DevelopmentADK) 2.x](https://ad/) | | ** | [Gem2.5 Flash / Flash Lite](https://a.google.com/) 通过 Google AI Studio | | **Web 服务器** | [FastAPI](https://fastolo.com/) + [Uvicorn](www.uvicorn.org/) | | **智能体协议** | [A2A 协议](https://a2a-protocol.org/) (`a2a-sdk`) | | **工具协议** | [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) (`mcp`) | | **数据验证** | [Pydantic v2](https://docs.pydantic.dev/) | | **包管理器** | [uv](https://docs.astral.sh/uv/) | | **容器** | [Docker](https://www.docker.com/) | | **部署** | [Google Cloud Run](https://cloud.google.com/run) / [Agent Runtime](https://cloud.google.com) | | **可观察性** | [OpenTelemetry](httpsentelemetry.io/) + Cloud Logging](cloud.google.com/logging)## 🏗架构 HackC结构化**两层系统收集上下文的智能体和一个执行的多智能体工作流。 <p align="center"> <img src="https://github.com/user-attachments/assets/d0d0d693-bec48b5-bac6-3811a54998e6" alt="HackCrib AI 架构" width="</p> ─────────────────────────────────────────────────────────────────────┐ │ 用户 (ADK Playground / A2A 客户端 / REST API) │ └──────────────────────────┬──────────────────────────────────────────┘ │ / HTTP ┌──────────────────────────▼──────────────────────────────────────────┐ │ FastAPI 服务器 (fast_api_app.py) ├── AD路由 (/run, /run, /apps/...) ├── A2A (/a2a/app/...) │ │ └── /feedback │ └──────────────────────────┬──────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────┐ │ student_mentor_agent (LlmAgent, mode=chat) │ │ ├── before_model_callback → security_checkpoint (PII + 注入) │ │ ├── after_model_callback → 轻量级日志记录 │ │ ├── state_schema: HackCribState │ │ └── tool: start_project_planning() │ └──────────────────────────┬──────────────────────────────────────────┘ │ ctx(hackcrib_workflow) ┌──────────────────────────▼──────────────────────────────────────────┐ │ hackcrib_workflow (ADK 工作流) │ │ ├── security_checkpoint ──unsafe──▶ security_error_node │ │ │ │ 安全 │ │ ├── orchestrator (output_schemaPlanOutput) │ │ │ ├── hackathon_intelligence_agent (AgentTool) │ │ │ ├── tech_stack_advisor_agent (AgentTool + MCP) │ │ │ └── MCP_tech_docs, discover_apis │ │ │ ├── project_agent (Agent) │ │ │ │: validate_dependencies│ │ └── documentation_agent (AgentTool) │ │ ├── human_approval_node Input → HITL) │ │ ├── "approve" ──▶ final_output │ │ │ └── <> ──▶_agent │ │ └── final_output (产生富 Markdown 事件) │ └─────────────────────────────────────────────────────────────────────┘ ``` 📐 完整架构详情：[`docs/ARCHITECTUREdocs/ARCHITECTURE.md) --- 🔀 多智能体工作流 <p align="center"> <img src="https://github.comattachments/assets/b3d416-0ca9-44d7-9271-96fe9131ba39" alt="HackCrib AI 工作流" width="95%"> </p> ```mermaid flowchart TD A([用户消息]) --> B[student_mentor_agent\nLlmAgent · mode B -->|"上下文"| C[start_project_planning\ntool 调用] C -->security_checkpoint\nP除 · 注入检测] D -->|不安全|_error_node\n提醒] D安全| Festrator_agent\n 模式] --> G[hackathon_intelligence_agent\n分析标准和评分] H[techvisor_agent\nMCP: search_techMCP: discover] F[project_planningMCP: validate F -->documentation_agent\nREADME 清单] G & H & I & J --> K[human_approval_node\n请求输入 · HITL 暂停] K -->|"批准"| L[final_output\n格式化 Markdown 计划] K -->|改进文本| F L --> M([✅ 批准的计划已交付]) A fill:#1a2e,color:#fff,stroke5F4 style B fill:#4285F4,color:#stroke:#4285 style C fill:#2d5:#fff:#34A853 D fill:#7b2d00,stroke:#EA4335 fill:#3d,color:#ff6b6b,stroke4335 style F fill:#1a3a6b,color:#fff,stroke:#F4 fill:#0d3349,color:#fff:#00BCD4 style H fill:#0d3349,color:#fff,stroke:#00 style I0d,color:#fff,stroke:#00BCD4 style J fill:#0d3349,color:#stroke:#00BCD style K4a206:#fff,strokeC27B style L fillb4332,color:#fff,stroke:#34 style M fill:#34A853fff,stroke:#34A853 ``` --- ## ✅ 人工审批流程 ```msequenceDiagram participant as student_mentor_agent participant 工作流 as hackcrib_workflow participant 审批 as human_approval_node participant 最终 as 学生导师: 描述马拉松 + 团队 导>导师:（多轮） 导师工作流: startanning() 工作流->>工作流: security_checkpoint → orchestrator → 4 个智能体 工作流审批: 草稿Output 已就绪 审批-->>学生: 📋 草稿计划 + "批准？" 学生->>审批: "批准" 审批->>最终: 路径 = "批准" 最终-->>学生: 🎉 最终 Markdown 计划 else 学生请求改进 学生->>审批: "将数据库更改为 PostgreSQL" 审批->>工作流: 路径 = "改进" + 状态中的反馈 工作>工作流:器重新规划 工作流->>审批: 修订后的草稿 -->>学生📋 更新的计划 + "批准或改进 end ``` --- 🚀 快速 前置条件 | 需求 | | |:---|:---|:---| | Python | ≥ 3.11 | [python.org](https://www.python/) | | uv | `pip install uv` | | Google AI Studio API 密钥免费 | [aistudio.google.com/ap://aist.com/apikey) | ### 安装 ```bash # 1. 克隆仓库 git clone https://github.com/SeshankTangudu/HackCrib-AI cd HackCrib-AI # 2. 复制并配置环境 cp .env.example .env # 打开 .env 并设置 GOOGLE_API_KEY # 3. 安装所有依赖 uv sync # 4. 启动 ADK Playground make playground ``` 打开 **[http://localhost](http://localhost:18081)** → 选择 **`app`** 智能体 → 开始聊天。 ### 用法 ### 步骤 1 — 描述你的黑客马拉松 ``` 我想参加一个名为“EduTech Innovation Challenge”的为期 36 小时的黑客马拉松。 问题是：远程学生团队在小组项目时遇到困难团队有 1 名 FastAPI 开发 2 名 React 开发人员喜欢 WebSockets。 ``` ### 步骤 2 — 启动规划 ``` 是切准备就绪。请现在生成计划。 ``` 系统会顺序运行 6 个智能体（约 60-90 秒免费层）。您将实时看到每个智能体的贡献流入 Playground。 ### 步骤 3 — 审查和批准 草稿计划出现，包含项目名称、主要想法、选定的架构、技术栈和冲刺里程碑。 ``` 批准 ``` 或请求改进： ``` 请将 Vue 替换为 React，并在最后 6添加 WebRTC 里程``` ### 步骤 4 — 接收最终计划 ``` 🎉 黑客马拉松项目计划已批准！ 💡 评估想法 ⚙️ 选定的实施细节 🛠️ 推荐的技术栈 📅 开发路线图 🏆 冲刺检查点 👥 团队任务分配--- ## 📁 项目结构 ``` HackCrib-AI/ ├── app/ │ ├── agent.py # 所有智能体、工作流、节点、工具、回调、速率限制器 │ ├── config.py # 模型和环境配置 │ ├── mcp_server.py # 本地 MCP 服务器（search_tech_docs、discover_apis、validate_dependencies） │ ├── fast_api_app.py # FastAPI 服务器 — ADK路由2A 协议路由 ├── __init__.py │ └── app_utils/ │ ├── a2a.py # A2A 协议适配器 │ ├── services.py # 会话和运行服务 │ ├── telemetry.py OpenTelemetry 集成 │ ├── typing.py # 共享类型定义 │ └── reasoning_engine_adapter.py ├── tests ├── unit/ │ │ └── test_dummy.py # 单元测试占位符 │ ├── integration/ │ │ _agent.py │ │ ├── test_server_e2e.py │ │ test_e2e_workflow.py # 完整端到端工作流测试 │ └──│ ├── eval_config.yaml │ └── datasets/ │ └── basic-dataset.json ├── docs/ │ ├── ARCHITECTURE.md # 系统设计、组件图、数据流 │ ├── DEPLOYMENT.md # 本地、Docker、Cloud Run、Agent│ ├── API.md 端点、SSE 模式、A2A 协议 │ O.md # 逐步演示脚本，供评委使用 │ ├── PRESENTATION.md # 推介幻灯片要点 │ └── SUBMISSION.md # 黑客马拉松 ├── assets/ │ ├── # 缩略图规范 │ ├── architecture_flow.md架构 Mermaid 源代码 │ └── workflow_flow.md # 工作流 Mermaid 源代码 ├── deployment/ │ └── terraform/ # 基础设施即代码（单项目） env.example # 环境变量复制 → .env） ├── .gitignore 排除 .envvenv、日志、__pycache__ ├── Dockerfile # 容器 Cloud Run ├── Makefile # 开发者便利命令 ├── pyproject.toml # 项目元数据和依赖项 ├── agents-cli-manifest.yaml # agents-cli 部署配置 └── GEMINI.md # AI 编码智能体针对该项目的指南 ``` --- ## 📡 API 参考 | 端点 | 方法 | 描述 | |:---|:|:---| | `/run_sse` | POST | 运行智能体并流式传输事件（Server-Sent | | `/run` | POST | 运行智能体，返回所有事件的 JSON 数组 | | `/apps/{app}/users/{uid}/sessions` | 创建新会话 | | `/app}/users/{uid}/sessions` | GET | 列出会话 | apps/{app}/users/{uid}/sessions/{sid}` | GET | 获取会话及其完整事件历史记录 | | `/apps/{app}/users/{sessions/{sid}/feedback` | POST | 提交会话反馈 | | `/a/app/.well-known/agent-card.json` | GET | A2A 智能体卡片 | | `/a2a/app` | POST | A2A 任务端点 | 完整 API 文档，包括 `curl` 示例和 SSE 事件模式：[`docs/API.md/API.md) --- ## 🚢### 本地（开发） ```bash make playground # ADK Playground 在 :18081 make run # 原始 FastAPI 服务器在 :8000 ``` ### Docker ```bash docker build -t hackcrib-ai . docker run -p 8080:8080 \ -e GOOGLE_API_KEY=your-key \ -e GOOGLE_GENAI_USE_VERTEXAI=False \ -e GEMINI_MODEL=gemini-2.5-flash-lite \ hackcrib``` ### Google Cloud Run gcloud config set_PROJECT_ID agents ``` 完整部署指南、Cloud Run 和 Agent Runtime 指令：[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) --- ## ⚙️ 使用的 ADK 功能 该项目在单个应用程序中练习了 **10 ADK 原语**： | # | ADK 功能 | | |:---:|:---|: 1 | 具有 `mode"` 的 `LlmAgent` | `student_mentor_agent`轮对话 | | 2 | `before_model_callback` | 安全 PII 擦除 + 注入检测 | | 3 | `after_model | 轻量级回合 | | 4 | 具有条件路由的 ADK `Workflow `hackcrib_workflow` — 4 个工作流边 | | 5 | 自定义同步/异步工作流节点 | `security_checkpointhuman_approval_node`、`final_output` | | 6 | `RequestInput` — 人工参与环路 | `human_approval_node` — 批准/改进暂停 | | 7 | `AgentTool` —体调用智能体 | `ator_agent` → 4智能体 | | 8output_schema` — 结构化 Pydantic 输出 | `orchestr` → `ProjectPlanOutput` | | 9 | `Mset` — MCP 工具集成 | `tech_stack_advisor_agentproject_planning_agent` | | 10 | `ctx.run_node()` — 工具中的嵌套工作流 | `start_project_planning()` 调用 `hackcrib_workflow` | --- ## 🔮 未来改进 - 🌐 **多语言支持** — 非英语黑客马拉松描述和计划 - 📊 **历史分析** — 跟踪过去获奖黑客马拉松提交的模式 - 🔗 **直接集成** — 自动创建 GitHub 仓库、Jira 看板、F模板（在批准时） - 🏫 **导师仪表板** — 机构级视图，供导师跟踪多个学生团队 - 🔊输入** — 使用 Gemini Live API 通过语音描述你的黑客马拉松 - 🌍 **远程 MCP 传输** — 交换 `ConnectionParams` 以进行水平扩展的 HTTP MCP - 💾化会话** — Cloud Firestore SQL 会话服务，用于有 - 📱 **侣** — 轻量，用于在黑客马拉松期间随时访问导师 --- 🏆 黑客马拉松 本项目是为 **Google ADK马拉松 2026** 构建的。 | 字段详情 | |:---|:---| | **黑客马拉松 Google Agent Development Kit () 黑客马拉松 2026 | | **类别** | 开发者工具 / 教育 / 多智能体 AI | | **框架** | Google Agent Development Kit (ADK) 2.x | | **提交** | [`docs/SUBMISSION.md`](docs/SUBMISSION.md) | | **演示脚本** | [`docs/DEMO.md`](docs/DEMO.md) | | **架构** | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) | ** |录制并在最终提交前添加)* | --- ## 贡献者 | 姓名 | |:---|:---| | **[Seshank Tangudu](https://github.com/SeshankTangudu)** | 项目负责人 · AI 工作流设计 · 后端开发 · 多智能体架构 · 测试 · 部署 | --- ## 📄 许可证 该项目根据 **Apache License 2.0** 许可。 详见 [LICENSE](LICENSE) 文件。 ``` Copyright 2026 Seshank Tangudu Lic Apache License, Version 2.0 (the "License may not use this file except in compliance with the License. ``` --- ="center"> **使用 [Google ADK](https://ad/) · [Gemini](https://aistudio.google.com/)FastAPI](https://fastapi.com/) ·CP](https://modelcontext/) 构建 💕** HackCrib AI 帮助了你的黑客马拉松给这个仓库点赞！ [🐛 报告 Bug](github.com/Seshank/HackCrib-AI [💡 请求功能](https://github.com/Seshudu/HackCrib-AI/issues) · [📖 阅读docs/ARCHITECTURE.md) </div>