Hubloom

# Hubloom **Hubloom —— Agentic Runtime: Make large models truly "advance" in business systems, upgrading existing APIs and data assets into intelligent, operable, interactive, automatable, and auditable operational capabilities.** > Hubloom is an Agentic Runtime: It integrates OpenAPI/Swagger and business data, enabling intelligent agents to complete tasks on real systems by "understanding → calling tools → presenting results." It uses Markdown for explanations and A2UI for operations; extensions are achieved through **configuration and Skills**, while business logic remains within proprietary systems. > > As an Agent foundation, it connects tool calls, context and sessions, result presentation, authentication transmission, and process observability into a runnable chain: connected to real REST via MCP, delivering results through Markdown/A2UI dual channels, and providing extension points for upper-layer capabilities—optional memory, RAG, and A2A cross-Agent collaboration. On this basis, it evolves from conversational loops to event-triggered tasks, Agent proactive push, IM multi-endpoint reach, automation, autonomous operation, and multi-Agent collaboration. On the protocol stack: **MCP** connects business APIs and data, **A2A** supports cross-Agent delegation, **A2UI** generates interfaces and **AG-UI** standard interaction events (outbound SSE + form return) are ready; further exploration of **ANP** open interconnection. ## Features - **Embedded intelligence, not a bypass assistant**: Intelligent agents operate on process and data planes, directly accessing enterprise APIs, with verifiable results and retraced processes. - **Contract equals capability**: OpenAPI/Swagger dynamically maps tool surfaces; switching business domains mainly involves configuration changes, quickly reusing existing digital assets. - **Cognition-decision-presentation integration**: Think → Present → Respond orchestration loop; complex goals can be disassembled, adjustable tools, and adaptive interaction forms. - **Dual-channel experience**: Markdown carries insights and conclusions, A2UI generates forms/lists/confirmation operation interfaces on the fly (`auto | markdown | a2ui`). - **AG-UI round interaction**: `/v1/chat` outbound aligns with AG-UI events; form waiting uses `run_id` / `toolCallId`, submission uses structured `action` (not idle chat). - **From suggestion to closed loop**: Through MCP meta-tool calls real REST, turning "being able to talk" into "being able to complete tasks". - **Evolvable operational intelligence**: Configuration + Skill solidifies domain Know-how; memory and RAG precipitate context; A2A supports multi-Agent collaboration and automation closed loops. - **Event-driven inbound**: Business Webhook (`POST /v1/events`) injects `skills/events` sub-volume procedures, then actively runs Agent, with results written to session history. - **Process auditable**: Trajectory, tool chain, and SSE contracts can be displayed and retraced, meeting transparency and controllability requirements for landing. ## Interface Preview One sentence, multiple tasks: create a community first, then complete a key cabinet—dialogue explanation + right-side A2UI interaction panel.  After creation, use a table to verify system status (tool call can be expanded for viewing).  ## Architecture Documentation The example station (`examples/chat`) is responsible for out-of-the-box demonstration; Runtime (`HubloomRuntime` / `/v1/chat`) is responsible for embedding into portals and proprietary applications. For hierarchical and protocol boundaries, see [docs/](./docs/): | Document | Description | | ----------------------------------------- | ----------------------------------------------------- | | [Product Positioning](./docs/Hubloom产品定位.md) | What it is / what it's not, delivery form, and main path | | [Architecture Boundary](./docs/Hubloom架构边界.md) | MCP / A2A / A2UI / AG-UI convergence principles and package boundaries | | [Overall Architecture Diagram](./docs/Hubloom总体架构图.md) | System hierarchy and main link roadshow | | [SSE Contract](./docs/Hubloom-SSE契约.md) | `/v1/chat` AG-UI outbound events (`data.type`) | | [Round Interaction Contract](./docs/Hubloom-回合交互契约.md) | `run_id`, form waiting, and structured action return | | [Event-driven](./docs/Hubloom-事件驱动.md) | Webhook inbound, `skills/events` sub-volume, idempotence, and type discovery | | [MCP Adaptation](./docs/Hubloom-MCP适配.md) | OpenAPI pipeline, meta-tool, Token transmission | | [A2A Interconnection](./docs/Hubloom-A2A互联.md) | Bidirectional A2A, remote process display | | [Tool Layer](./docs/Hubloom-工具层.md) | ToolRegistry, ToolRunner, and built-in tools | | [Memory System](./docs/Hubloom-记忆系统.md) | Session / long-term memory | | [RAG Knowledge Base](./docs/Hubloom-RAG知识库.md) | Document entry and retrieval | | [ADP Orchestration](./docs/Hubloom-ADP编排.md) | Historical dual-path description (documents to be aligned with Think/Present/Respond) | ## Quick Start ### Environment Requirements - Python 3.12+ - [uv](https://github.com/astral-sh/uv) (recommended) or pip - Node.js (only required for running example station frontend) ### 1. Install Dependencies ```bash uv sync ``` or using pip: ```bash pip install -r requirements.txt ``` ### 2. Configuration ```bash cp config/env.example.yaml config/env.yaml ``` Fill in `config/env.yaml` with LLM and MCP (OpenAPI specifications, business API addresses, etc.). Business tokens are passed from the frontend session; do not write them into the configuration file. ### 3. Start Example Station ```bash # Backend API (default: 8010) PYTHONPATH=src:. uv run python main.py # Frontend (open another terminal) cd examples/chat/web && npm install && npm run dev ``` - **Web dialogue page**: http://127.0.0.1:5173/ (Vite proxy `/v1` → `:8010`) - **API documentation**: http://127.0.0.1:8010/docs Adjust using `CORTEX_API_HOST`, `CORTEX_API_PORT`, `HUBLOOM_CONFIG`. **Health Check** ```bash curl http://127.0.0.1:8010/health ``` **Call Dialogue Interface** ```bash curl -s http://127.0.0.1:8010/v1/chat \ -H "Content-Type: application/json" \ -H "X-Session-Id: demo-session" \ -H "X-MCP-Token: your-business-token" \ -d '{"message":"Hello, what can you do?","stream":false}' ``` Default SSE (`"stream": true`). History: `GET /v1/chat/history?session_id=demo-session`. Presentation mode can be requested or selected from the sidebar: `auto` / `markdown` / `a2ui`. **Event Inbound (requires `events.enable: true`)** Contract and Skill sub-volume agreements see **[Event-driven](./docs/Hubloom-事件驱动.md)**. Supported `type` scanned by [`skills/events/`](./skills/events/); `GET /v1/events/types` available. Idempotence key is `event_id` (not `session_id`). ```bash # View supported event types curl -s http://127.0.0.1:8010/v1/events/types \ -H "X-Event-Secret: change-me" # Push event (replace with real deviceId / Token; or use scripts) export HUBLOOM_BEARER_TOKEN='your-business-token' export HUBLOOM_SESSION_ID='demo-session' ./examples/chat/scripts/post_locker_created.sh ``` Results are written to the `session_id` history (refresh dialogue page to see "event" mark). New event types: add a sub-volume md with `event:` in `skills/events/` and restart. ## Roadmap ### Current Version (after refactoring) - [x] OpenAPI → MCP tool surface (catalog + meta-tool `list_api` / `call_api`) - [x] **Think → Present → Respond** unified orchestration loop - [x] **Dual presentation**: Markdown + A2UI (including `present_mode=auto`) - [x] **[AG-UI](https://docs.ag-ui.com/)** outbound SSE (`RUN_*` / `TEXT_MESSAGE_*` / `TOOL_CALL_*` / `CUSTOM` etc.) and official `ag-ui-protocol` encoding - [x] **Form round trip**: `run_id` waiting state, client `hubloom.a2ui_action`, structured `action` return (see [Round Interaction Contract](./docs/Hubloom-回合交互契约.md)) - [x] Web dialogue page: interaction panel, this round A2UI lifecycle, AG-UI event consumption - [x] Multi-turn conversation and tool chain sensing history clipping - [x] Optional long-term memory and RAG knowledge base - [x] **A2A bidirectional MVP**: inbound Server, outbound `list_agents` / `delegate_task`, remote process display - [x] **Event-driven Webhook MVP**: `POST /v1/events`, `skills/events` sub-volume injection, idempotence, and type discovery (see [Event-driven](./docs/Hubloom-事件驱动.md)) ### Next Steps - [ ] **Event-driven enhancement**: message queue / timing alarm inbound, result callback improvement, active push screen when opening conversation (not just refreshing history) - [ ] **IM / multi-endpoint reach**: access enterprise WeChat, DingTalk, Feishu, Slack, and other IM and notification channels, extending dialogue, approval, and push to daily work entries - [ ] **Automation operation enhancement**: on the basis of configuration + Skill, strengthen process orchestration and unattended execution, moving towards autonomous operation and multi-Agent collaboration - [ ] **Document alignment**: overall architecture diagram / ADP orchestration document alignment with Think–Present–Respond, meta-tool single-track expression - [ ] **A2A enhancement**: chained delegation, dynamic discovery, formal credential Provider - [ ] **AG-UI enhancement**: more complete official event surface (e.g., independent THINKING event family), verification with third-party AG-UI clients - [ ] **Observability and maintenance**: more complete outbound indicators and deployment conventions ### Protocol Stack Evolution | Protocol | Role | Status | | --------- | ---------------------------------- | ------------------------------------ | | **MCP** | Agent ↔ enterprise API / data | Landed | | **A2A** | Agent ↔ Agent delegation | Bidirectional MVP | | **A2UI** | Declarative generative UI (forms, etc.) | Landed (via AG-UI CUSTOM / panel) | | **AG-UI** | Standard interaction event protocol for Agent ↔ user applications | Landed (outbound SSE + form action return) | | **ANP** | More open Agent interconnection | Exploring | > **A2UI ≠ AG-UI**: A2UI describes "what interface to draw"; AG-UI describes "how Agent and frontend use standard events to dialogue". They are complementary and can be used together. ## License This project is released under the [Apache License 2.0](LICENSE).