Skip to content

Commit 0b87e4c

Browse files
RichardTang-AdenRichardTang-Aden
authored
Merge pull request #5245 from TimothyZhang7/main
doc(architecture): update documents
2 parents 9c781ed + 9c7e846 commit 0b87e4c

File tree

4 files changed

+525
-271
lines changed

4 files changed

+525
-271
lines changed

‎README.md‎

Lines changed: 121 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ Use Hive when you need:
8787
8888
### Installation
8989

90-
>**Note**
90+
> **Note**
9191
> Hive uses a `uv` workspace layout and is not installed with `pip install`.
9292
> Running `pip install -e .` from the repository root will create a placeholder package and Hive will not function correctly.
9393
> Please use the quickstart script below to set up the environment.
@@ -124,26 +124,31 @@ hive tui
124124
# Or run directly
125125
hive run exports/your_agent_name --input '{"key": "value"}'
126126
```
127-
## Coding Agent Support
127+
128+
## Coding Agent Support
129+
128130
### Codex CLI
131+
129132
Hive includes native support for [OpenAI Codex CLI](https://github.com/openai/codex) (v0.101.0+).
130133

131134
1. **Config:** `.codex/config.toml` with `agent-builder` MCP server (tracked in git)
132135
2. **Skills:** `.agents/skills/` symlinks to Hive skills (tracked in git)
133136
3. **Launch:** Run `codex` in the repo root, then type `use hive`
134137

135138
Example:
139+
136140
```
137141
codex> use hive
138142
```
139143

140-
### Opencode
144+
### Opencode
145+
141146
Hive includes native support for [Opencode](https://github.com/opencode-ai/opencode).
142147

143-
1. **Setup:** Run the quickstart script
148+
1. **Setup:** Run the quickstart script
144149
2. **Launch:** Open Opencode in the project root.
145150
3. **Activate:** Type `/hive` in the chat to switch to the Hive Agent.
146-
4. **Verify:** Ask the agent *"List your tools"* to confirm the connection.
151+
4. **Verify:** Ask the agent _"List your tools"_ to confirm the connection.
147152

148153
The agent has access to all Hive skills and can scaffold agents, add tools, and debug workflows directly from the chat.
149154

@@ -180,7 +185,6 @@ Hive is built to be model-agnostic and system-agnostic.
180185
- **LLM flexibility** - Hive Framework is designed to support various types of LLMs, including hosted and local models through LiteLLM-compatible providers.
181186
- **Business system connectivity** - Hive Framework is designed to connect to all kinds of business systems as tools, such as CRM, support, messaging, data, file, and internal APIs via MCP.
182187

183-
184188
## Why Aden
185189

186190
Hive focuses on generating agents that run real business processes rather than generic agents. Instead of requiring you to manually design workflows, define agent interactions, and handle failures reactively, Hive flips the paradigm: **you describe outcomes, and the system builds itself**—delivering an outcome-driven, adaptive experience with an easy-to-use set of tools and integrations.
@@ -273,93 +277,124 @@ See [environment-setup.md](docs/environment-setup.md) for complete setup instruc
273277
Aden Hive Agent Framework aims to help developers build outcome-oriented, self-adaptive agents. See [roadmap.md](docs/roadmap.md) for details.
274278

275279
```mermaid
276-
flowchart TD
277-
subgraph Foundation
278-
direction LR
279-
subgraph arch["Architecture"]
280-
a1["Node-Based Architecture"]:::done
281-
a2["Python SDK"]:::done
282-
a3["LLM Integration"]:::done
283-
a4["Communication Protocol"]:::done
284-
end
285-
subgraph ca["Coding Agent"]
286-
b1["Goal Creation Session"]:::done
287-
b2["Worker Agent Creation"]
288-
b3["MCP Tools"]:::done
289-
end
290-
subgraph wa["Worker Agent"]
291-
c1["Human-in-the-Loop"]:::done
292-
c2["Callback Handlers"]:::done
293-
c3["Intervention Points"]:::done
294-
c4["Streaming Interface"]
295-
end
296-
subgraph cred["Credentials"]
297-
d1["Setup Process"]:::done
298-
d2["Pluggable Sources"]:::done
299-
d3["Enterprise Secrets"]
300-
d4["Integration Tools"]:::done
280+
flowchart TB
281+
%% Main Entity
282+
User([User])
283+
284+
%% =========================================
285+
%% EXTERNAL EVENT SOURCES
286+
%% =========================================
287+
subgraph ExtEventSource [External Event Source]
288+
E_Sch["Schedulers"]
289+
E_WH["Webhook"]
290+
E_SSE["SSE"]
301291
end
302-
subgraph tools["Tools"]
303-
e1["File Use"]:::done
304-
e2["Memory STM/LTM"]:::done
305-
e3["Web Search/Scraper"]:::done
306-
e4["CSV/PDF"]:::done
307-
e5["Excel/Email"]
308-
end
309-
subgraph core["Core"]
310-
f1["Eval System"]
311-
f2["Pydantic Validation"]:::done
312-
f3["Documentation"]:::done
313-
f4["Adaptiveness"]
314-
f5["Sample Agents"]
315-
end
316-
end
317-
318-
subgraph Expansion
319-
direction LR
320-
subgraph intel["Intelligence"]
321-
g1["Guardrails"]
322-
g2["Streaming Mode"]
323-
g3["Image Generation"]
324-
g4["Semantic Search"]
325-
end
326-
subgraph mem["Memory Iteration"]
327-
h1["Message Model & Sessions"]
328-
h2["Storage Migration"]
329-
h3["Context Building"]
330-
h4["Proactive Compaction"]
331-
h5["Token Tracking"]
332-
end
333-
subgraph evt["Event System"]
334-
i1["Event Bus for Nodes"]
292+
293+
%% =========================================
294+
%% SYSTEM NODES
295+
%% =========================================
296+
subgraph WorkerBees [Worker Bees]
297+
WB_C["Conversation"]
298+
WB_SP["System prompt"]
299+
300+
subgraph Graph [Graph]
301+
direction TB
302+
N1["Node"] --> N2["Node"] --> N3["Node"]
303+
N1 -.-> AN["Active Node"]
304+
N2 -.-> AN
305+
N3 -.-> AN
306+
307+
%% Nested Event Loop Node
308+
subgraph EventLoopNode [Event Loop Node]
309+
ELN_L["listener"]
310+
ELN_SP["System Prompt<br/>(Task)"]
311+
ELN_EL["Event loop"]
312+
ELN_C["Conversation"]
313+
end
314+
end
335315
end
336-
subgraph cas["Coding Agent Support"]
337-
j1["Claude Code"]
338-
j2["Cursor"]
339-
j3["Opencode"]
340-
j4["Antigravity"]
341-
j5["Codex CLI"]
316+
317+
subgraph JudgeNode [Judge]
318+
J_C["Criteria"]
319+
J_P["Principles"]
320+
J_EL["Event loop"] <--> J_S["Scheduler"]
342321
end
343-
subgraph plat["Platform"]
344-
k1["JavaScript/TypeScript SDK"]
345-
k2["Custom Tool Integrator"]
346-
k3["Windows Support"]
322+
323+
subgraph QueenBee [Queen Bee]
324+
QB_SP["System prompt"]
325+
QB_EL["Event loop"]
326+
QB_C["Conversation"]
347327
end
348-
subgraph dep["Deployment"]
349-
l1["Self-Hosted"]
350-
l2["Cloud Services"]
351-
l3["CI/CD Pipeline"]
328+
329+
subgraph Infra [Infra]
330+
SA["Sub Agent"]
331+
TR["Tool Registry"]
332+
WTM["Write through Conversation Memory<br/>(Logs/RAM/Harddrive)"]
333+
SM["Shared Memory<br/>(State/Harddrive)"]
334+
EB["Event Bus<br/>(RAM)"]
335+
CS["Credential Store<br/>(Harddrive/Cloud)"]
352336
end
353-
subgraph tmpl["Templates"]
354-
m1["Sales Agent"]
355-
m2["Marketing Agent"]
356-
m3["Analytics Agent"]
357-
m4["Training Agent"]
358-
m5["Smart Form Agent"]
337+
338+
subgraph PC [PC]
339+
B["Browser"]
340+
CB["Codebase<br/>v 0.0.x ... v n.n.n"]
359341
end
360-
end
361342
362-
classDef done fill:#9e9e9e,color:#fff,stroke:#757575
343+
%% =========================================
344+
%% CONNECTIONS & DATA FLOW
345+
%% =========================================
346+
347+
%% External Event Routing
348+
E_Sch --> ELN_L
349+
E_WH --> ELN_L
350+
E_SSE --> ELN_L
351+
ELN_L -->|"triggers"| ELN_EL
352+
353+
%% User Interactions
354+
User -->|"Talk"| WB_C
355+
User -->|"Talk"| QB_C
356+
User -->|"Read/Write Access"| CS
357+
358+
%% Inter-System Logic
359+
ELN_C <-->|"Mirror"| WB_C
360+
WB_C -->|"Focus"| AN
361+
362+
WorkerBees -->|"Inquire"| JudgeNode
363+
JudgeNode -->|"Approve"| WorkerBees
364+
365+
%% Judge Alignments
366+
J_C <-.->|"aligns"| WB_SP
367+
J_P <-.->|"aligns"| QB_SP
368+
369+
%% Escalate path
370+
J_EL -->|"Report (Escalate)"| QB_EL
371+
372+
%% Pub/Sub Logic
373+
AN -->|"publish"| EB
374+
EB -->|"subscribe"| QB_C
375+
376+
%% Infra and Process Spawning
377+
ELN_EL -->|"Spawn"| SA
378+
SA -->|"Inform"| ELN_EL
379+
SA -->|"Starts"| B
380+
B -->|"Report"| ELN_EL
381+
TR -->|"Assigned"| EventLoopNode
382+
CB -->|"Modify Worker Bee"| WorkerBees
383+
384+
%% =========================================
385+
%% SHARED MEMORY & LOGS ACCESS
386+
%% =========================================
387+
388+
%% Worker Bees Access
389+
Graph <-->|"Read/Write"| WTM
390+
Graph <-->|"Read/Write"| SM
391+
392+
%% Queen Bee Access
393+
QB_C <-->|"Read/Write"| WTM
394+
QB_EL <-->|"Read/Write"| SM
395+
396+
%% Credentials Access
397+
CS -->|"Read Access"| QB_C
363398
```
364399

365400
## Contributing

0 commit comments

Comments
 (0)