Skip to content

Commit fbfda19

Browse files
kashifpkkashifpk
committed
Replace ASCII diagrams with SVG images, add Open Graph meta tags
- Replace ASCII diagrams in docs with SVG references - Add tool-rag-flow.svg diagram - Add og:image and twitter:image meta tags for social sharing - Add forge-architecture-og.png for Open Graph preview
1 parent 7140b96 commit fbfda19

8 files changed

Lines changed: 145 additions & 184 deletions

File tree

‎.vitepress/config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ export default defineConfig({
1414
['meta', { property: 'og:type', content: 'website' }],
1515
['meta', { property: 'og:title', content: 'Agentic Forge' }],
1616
['meta', { property: 'og:description', content: 'Build more efficient AI agents with smart tool management' }],
17+
['meta', { property: 'og:image', content: 'https://agentic-forge.github.io/forge-architecture-og.png' }],
18+
['meta', { property: 'og:url', content: 'https://agentic-forge.github.io' }],
19+
['meta', { name: 'twitter:card', content: 'summary_large_image' }],
20+
['meta', { name: 'twitter:image', content: 'https://agentic-forge.github.io/forge-architecture-og.png' }],
1721
// Umami Analytics
1822
['script', {
1923
defer: '',

‎docs/armory.md‎

Lines changed: 8 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -22,41 +22,16 @@ Just as a forge creates tools and an armory stores them, the Armory is where you
2222

2323
Armory exposes multiple MCP endpoints, giving clients flexibility:
2424

25-
<div class="architecture-diagram">
26-
<pre>
27-
┌─────────────────────────────────────────────────────────────────────────────┐
28-
│ ARMORY │
29-
├─────────────────────────────────────────────────────────────────────────────┤
30-
│ │
31-
│ Endpoints (all valid MCP - path is flexible per spec): │
32-
│ ├── /mcp → Aggregated (all tools with prefixes) │
33-
│ ├── /mcp/weather → Direct access to weather server │
34-
│ ├── /mcp/search → Direct access to search server │
35-
│ ├── /mcp/notes → Direct access to notes server │
36-
│ └── /.well-known/mcp.json → Discovery metadata │
37-
│ │
38-
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
39-
│ │ Tool │ │ Tool RAG │ │ Protocol │ │ Result │ │
40-
│ │ Registry │ │ (optional) │ │ Adapters │ │ Transformer │ │
41-
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
42-
│ │
43-
└──────────────────────────────────────┬───────────────────────────────────────┘
44-
│
45-
┌──────────────────────────────┼──────────────────────────────┐
46-
│ │ │
47-
▼ ▼ ▼
48-
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
49-
│ CUSTOM │ │ EXISTING │ │ REMOTE │
50-
│ (FastMCP) │ │ (npm/local) │ │ (hosted) │
51-
├───────────────┤ ├───────────────┤ ├───────────────┤
52-
│ weather │ │ brave-search │ │ github │
53-
│ (Open-Meteo) │ │ fetch │ │ (GitHub host) │
54-
│ uptime │ │ filesystem │ │ │
55-
│ notes │ │ time │ │ │
56-
└───────────────┘ └───────────────┘ └───────────────┘
57-
</pre>
25+
<div class="diagram-container">
26+
<img src="/diagrams/armory-tool-call-flow.svg" alt="Armory Tool Call Flow" style="max-width: 100%; height: auto;" />
5827
</div>
5928

29+
**Endpoints:**
30+
- `/mcp` → Aggregated (all tools with prefixes)
31+
- `/mcp/weather` → Direct access to weather server
32+
- `/mcp/search` → Direct access to search server
33+
- `/.well-known/mcp.json` → Discovery metadata
34+
6035
**Why hybrid?** Clients wanting simplicity connect to `/mcp` (one connection, all tools). Clients wanting isolation connect to `/mcp/{server}` (specific server only).
6136

6237
## Key Features

‎docs/index.md‎

Lines changed: 4 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -2,51 +2,8 @@
22

33
Agentic Forge is built from modular components that work together to create efficient, interoperable AI agents with smart tool management.
44

5-
<div class="architecture-diagram">
6-
<pre>
7-
┌─────────────────────────────────────────────────────────────────────────────────┐
8-
│ AGENTIC FORGE │
9-
│ │
10-
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
11-
│ │ ORCHESTRATOR │ │
12-
│ │ Standalone component managing the LLM conversation loop │ │
13-
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
14-
│ │ │ Conversation │ │ Model │ │ Tool │ │ Execution │ │ │
15-
│ │ │ Manager │ │ Router │ │ Router │ │ Engine │ │ │
16-
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │
17-
│ └─────────────────────────────────────────┬──────────────────────────────────┘ │
18-
│ │ │
19-
│ MCP Protocol │ │
20-
│ ▼ │
21-
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
22-
│ │ ARMORY │ │
23-
│ │ Protocol Gateway exposing unified MCP interface │ │
24-
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
25-
│ │ │ MCP │ │ Tool │ │ Protocol │ │ Result │ │ │
26-
│ │ │ Server │ │ Registry │ │ Adapters │ │ Transformer │ │ │
27-
│ │ │ Interface │ │ │ │ │ │ (JSON→TOON) │ │ │
28-
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │
29-
│ │ │ │ │
30-
│ │ ▼ │ │
31-
│ │ ┌──────────────┐ │ │
32-
│ │ │ TOOL RAG │ │ │
33-
│ │ │ (optional) │ │ │
34-
│ │ └──────────────┘ │ │
35-
│ └─────────────────────────────────────────┬──────────────────────────────────┘ │
36-
│ │ │
37-
│ Protocol Translation │ │
38-
│ ▼ │
39-
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
40-
│ │ BACKENDS │ │
41-
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
42-
│ │ │ MCP Servers │ │ REST APIs │ │ Local │ │ OpenAI FC │ │ │
43-
│ │ │ (filesystem, │ │ (weather, │ │ Functions │ │ Services │ │ │
44-
│ │ │ brave, etc) │ │ etc) │ │ │ │ │ │ │
45-
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │
46-
│ └────────────────────────────────────────────────────────────────────────────┘ │
47-
│ │
48-
└─────────────────────────────────────────────────────────────────────────────────┘
49-
</pre>
5+
<div class="diagram-container">
6+
<img src="/diagrams/forge-architecture.svg" alt="Agentic Forge Architecture" style="max-width: 100%; height: auto;" />
507
</div>
518

529
## Components
@@ -75,36 +32,8 @@ Instead of loading all tools into context, Tool RAG uses semantic search to dyna
7532

7633
## Data Flow
7734

78-
<div class="architecture-diagram">
79-
<pre>
80-
USER QUERY
81-
│
82-
▼
83-
┌─────────────────────────────────────────────────────────────┐
84-
│ ORCHESTRATOR │
85-
│ ├── Model Router: selects appropriate LLM │
86-
│ ├── Sends to LLM with tool definitions │
87-
│ └── LLM returns: tool_call("search", {...}) │
88-
└──────────────────────────┬──────────────────────────────────┘
89-
│
90-
▼
91-
┌─────────────────────────────────────────────────────────────┐
92-
│ ARMORY (receives tool call via MCP) │
93-
│ ├── Tool RAG: confirms tool is relevant │
94-
│ ├── Protocol Adapter: routes to backend │
95-
│ └── Backend executes, returns JSON │
96-
└──────────────────────────┬──────────────────────────────────┘
97-
│
98-
▼
99-
┌─────────────────────────────────────────────────────────────┐
100-
│ RESULT TRANSFORMER │
101-
│ ├── Detects tabular data │
102-
│ └── Converts JSON → TOON (saves ~40% tokens) │
103-
└──────────────────────────┬──────────────────────────────────┘
104-
│
105-
▼
106-
FINAL RESPONSE TO USER
107-
</pre>
35+
<div class="diagram-container">
36+
<img src="/diagrams/armory-tool-call-flow.svg" alt="Tool Call Data Flow" style="max-width: 100%; height: auto;" />
10837
</div>
10938

11039
## Technology Stack

‎docs/interfaces.md‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -35,22 +35,20 @@ REST's request-response model doesn't fit LLM agents well:
3535
| Stateful conversations | Resend full context | Session maintained |
3636
| Cancel/feedback | Can't interrupt | Bi-directional messages |
3737

38-
## Recommended: WebSocket + REST Hybrid
38+
## Recommended: SSE + REST Hybrid
3939

40-
<div class="architecture-diagram">
41-
<pre>
42-
WebSocket /ws/chat REST /api/v1/*
43-
───────────────── ─────────────────
44-
• Conversations (streaming) • Health check
45-
• Token streaming • List conversations
46-
• Tool call progress • Get conversation history
47-
• Cancel requests • Configuration
48-
• User feedback mid-stream • Model/tool management
49-
50-
Best for: Real-time chat Best for: Management, CRUD
51-
</pre>
40+
<div class="diagram-container">
41+
<img src="/diagrams/sse-event-flow.svg" alt="SSE Event Flow" style="max-width: 100%; height: auto;" />
5242
</div>
5343

44+
| SSE `/conversations/{id}/stream` | REST `/api/v1/*` |
45+
|----------------------------------|------------------|
46+
| Token streaming | Health check |
47+
| Tool call progress | List conversations |
48+
| Thinking events | Get conversation history |
49+
| Completion events | Configuration |
50+
| Heartbeat pings | Model/tool management |
51+
5452
## WebSocket Protocol
5553

5654
### Client → Server

‎docs/orchestrator.md‎

Lines changed: 2 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -14,33 +14,8 @@ While Pydantic AI provides built-in orchestration, a standalone orchestrator off
1414

1515
## Architecture
1616

17-
<div class="architecture-diagram">
18-
<pre>
19-
┌─────────────────────────────────────────────────────────────────────────────┐
20-
│ ORCHESTRATOR │
21-
├─────────────────────────────────────────────────────────────────────────────┤
22-
│ │
23-
│ ┌────────────────────────────────────────────────────────────────────────┐ │
24-
│ │ PUBLIC API │ │
25-
│ │ - run(prompt) → Response │ │
26-
│ │ - run_stream(prompt) → AsyncIterator[Event] │ │
27-
│ │ - step() → manually advance one loop iteration │ │
28-
│ └────────────────────────────────────────────────────────────────────────┘ │
29-
│ │ │
30-
│ ▼ │
31-
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
32-
│ │ Conversation │ │ Model │ │ Tool │ │ Execution │ │
33-
│ │ Manager │ │ Router │ │ Router │ │ Engine │ │
34-
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
35-
│ │ │
36-
│ ▼ │
37-
│ ┌────────────────────────────────────────────────────────────────────────┐ │
38-
│ │ HOOKS / MIDDLEWARE │ │
39-
│ │ on_model_request, on_model_response, on_tool_call, on_complete │ │
40-
│ └────────────────────────────────────────────────────────────────────────┘ │
41-
│ │
42-
└─────────────────────────────────────────────────────────────────────────────┘
43-
</pre>
17+
<div class="diagram-container">
18+
<img src="/diagrams/orchestrator-architecture.svg" alt="Orchestrator Architecture" style="max-width: 100%; height: auto;" />
4419
</div>
4520

4621
## Sub-components

0 commit comments

Comments
 (0)