# vcky4/agent88 architecture

> Architecture diagram of the GitHub repository vcky4/agent88, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vcky4/agent88
- Repository: https://github.com/vcky4/agent88

## Overview

Agent88 is a TypeScript framework for building AI agents and composing them into multi-agent graphs. The main interaction is a user prompt entering an Agent, which loads optional memory, builds an execution context, and delegates to an engine that calls a model and may dispatch tools before returning a response. Agents also support direct text streaming. The graph API runs agents in topological order, passing each output to the next. The map includes documented middleware, tracing, provider adapters, and memory options; unsampled provider and Redis internals are not expanded.

Main entry points: [`src/core/Agent.ts`](https://github.com/vcky4/agent88/blob/main/src/core/Agent.ts) (Agent), [`src/core/execution/ExecutionEngine.ts`](https://github.com/vcky4/agent88/blob/main/src/core/execution/ExecutionEngine.ts) (Execution Engine), [`src/core/models/BaseModel.ts`](https://github.com/vcky4/agent88/blob/main/src/core/models/BaseModel.ts) (Model Interface), [`src/core/graph/AgentGraph.ts`](https://github.com/vcky4/agent88/blob/main/src/core/graph/AgentGraph.ts) (Agent Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_api["Agent API"]
  node_agent["Agent<br/>[Agent.ts]"]
end

subgraph group_execution["Execution"]
  node_context["Execution Context"]
  node_engine["Execution Engine<br/>[ExecutionEngine.ts]"]
  node_middleware["Middleware<br/>[Middleware.ts]"]
  node_trace["Trace<br/>[Trace.ts]"]
  node_tool_executor["Tool Executor<br/>[ToolExecutor.ts]"]
end

subgraph group_capabilities["Tools"]
  node_registry["Tool Registry<br/>[ToolRegistry.ts]"]
  node_tool["Tool<br/>[Tool.ts]"]
end

subgraph group_models["Model Adapters"]
  node_model_contract["Model Interface<br/>[BaseModel.ts]"]
  node_openai["OpenAI Adapter<br/>[OpenAIModel.ts]"]
  node_gemini["Gemini Adapter<br/>[GeminiModel.ts]"]
  node_ollama["Ollama Adapter<br/>[OllamaModel.ts]"]
  node_mock_model["Mock Adapter<br/>[MockModel.ts]"]
end

subgraph group_memory["Memory"]
  node_memory_contract["Memory Interface<br/>[index.ts]"]
  node_in_memory["In-Memory Adapter<br/>[InMemoryMemory.ts]"]
  node_redis_memory["Redis Adapter<br/>[RedisMemory.ts]"]
end

subgraph group_graphs["Agent Graphs"]
  node_graph_api["Agent Graph<br/>[AgentGraph.ts]"]
  node_graph_executor["Graph Executor<br/>[GraphExecutor.ts]"]
  node_graph_node["Graph Node<br/>[GraphNode.ts]"]
  node_graph_edge["Graph Edge<br/>[GraphEdge.ts]"]
end

node_user(("Developer / User"))

node_user -->|"submits prompt"| node_agent
node_agent -->|"loads / saves"| node_memory_contract
node_agent -->|"registers tools"| node_registry
node_registry -->|"stores tools"| node_tool
node_agent -->|"builds context"| node_context
node_agent -->|"delegates run"| node_engine
node_agent -->|"creates trace"| node_trace
node_agent -->|"streams directly"| node_model_contract
node_engine -->|"reads and updates"| node_context
node_engine -->|"dispatches through"| node_middleware
node_engine -->|"generates response"| node_model_contract
node_engine -->|"dispatches tool"| node_tool_executor
node_tool_executor -->|"executes"| node_tool
node_engine -->|"records timings"| node_trace
node_openai -->|"implements"| node_model_contract
node_gemini -->|"implements"| node_model_contract
node_ollama -->|"implements"| node_model_contract
node_mock_model -->|"implements"| node_model_contract
node_in_memory -->|"implements"| node_memory_contract
node_redis_memory -->|"implements"| node_memory_contract
node_user -->|"runs graph"| node_graph_api
node_graph_api -->|"delegates run"| node_graph_executor
node_graph_api -->|"registers agents"| node_graph_node
node_graph_api -->|"connects agents"| node_graph_edge
node_graph_executor -->|"runs agents"| node_agent
node_graph_executor -->|"orders by edges"| node_graph_edge

click node_agent "https://github.com/vcky4/agent88/blob/main/src/core/Agent.ts"
click node_context "https://github.com/vcky4/agent88/blob/main/src/core/execution/ExecutionContext.ts"
click node_engine "https://github.com/vcky4/agent88/blob/main/src/core/execution/ExecutionEngine.ts"
click node_middleware "https://github.com/vcky4/agent88/blob/main/src/core/execution/Middleware.ts"
click node_trace "https://github.com/vcky4/agent88/blob/main/src/core/execution/Trace.ts"
click node_registry "https://github.com/vcky4/agent88/blob/main/src/core/tools/ToolRegistry.ts"
click node_tool "https://github.com/vcky4/agent88/blob/main/src/core/tools/Tool.ts"
click node_tool_executor "https://github.com/vcky4/agent88/blob/main/src/core/execution/ToolExecutor.ts"
click node_model_contract "https://github.com/vcky4/agent88/blob/main/src/core/models/BaseModel.ts"
click node_openai "https://github.com/vcky4/agent88/blob/main/src/core/models/OpenAIModel.ts"
click node_gemini "https://github.com/vcky4/agent88/blob/main/src/core/models/GeminiModel.ts"
click node_ollama "https://github.com/vcky4/agent88/blob/main/src/core/models/OllamaModel.ts"
click node_mock_model "https://github.com/vcky4/agent88/blob/main/src/core/models/MockModel.ts"
click node_memory_contract "https://github.com/vcky4/agent88/blob/main/src/types/index.ts"
click node_in_memory "https://github.com/vcky4/agent88/blob/main/src/core/memory/InMemoryMemory.ts"
click node_redis_memory "https://github.com/vcky4/agent88/blob/main/src/core/memory/RedisMemory.ts"
click node_graph_api "https://github.com/vcky4/agent88/blob/main/src/core/graph/AgentGraph.ts"
click node_graph_executor "https://github.com/vcky4/agent88/blob/main/src/core/graph/GraphExecutor.ts"
click node_graph_node "https://github.com/vcky4/agent88/blob/main/src/core/graph/GraphNode.ts"
click node_graph_edge "https://github.com/vcky4/agent88/blob/main/src/core/graph/GraphEdge.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_user toneBlue
class node_context,node_engine,node_middleware,node_trace,node_tool_executor toneAmber
class node_registry,node_tool toneMint
class node_model_contract,node_openai,node_gemini,node_ollama,node_mock_model toneRose
class node_memory_contract,node_in_memory,node_redis_memory toneIndigo
class node_graph_api,node_graph_executor,node_graph_node,node_graph_edge toneTeal
```

## Components

### Agent API

- [Agent](https://github.com/vcky4/agent88/blob/main/src/core/Agent.ts): `src/core/Agent.ts`

### Execution

- [Execution Context](https://github.com/vcky4/agent88/blob/main/src/core/execution/ExecutionContext.ts): `src/core/execution/ExecutionContext.ts`
- [Execution Engine](https://github.com/vcky4/agent88/blob/main/src/core/execution/ExecutionEngine.ts): `src/core/execution/ExecutionEngine.ts`
- [Middleware](https://github.com/vcky4/agent88/blob/main/src/core/execution/Middleware.ts): `src/core/execution/Middleware.ts`
- [Trace](https://github.com/vcky4/agent88/blob/main/src/core/execution/Trace.ts): `src/core/execution/Trace.ts`
- [Tool Executor](https://github.com/vcky4/agent88/blob/main/src/core/execution/ToolExecutor.ts): `src/core/execution/ToolExecutor.ts`

### Tools

- [Tool Registry](https://github.com/vcky4/agent88/blob/main/src/core/tools/ToolRegistry.ts): `src/core/tools/ToolRegistry.ts`
- [Tool](https://github.com/vcky4/agent88/blob/main/src/core/tools/Tool.ts): `src/core/tools/Tool.ts`

### Model Adapters

- [Model Interface](https://github.com/vcky4/agent88/blob/main/src/core/models/BaseModel.ts): `src/core/models/BaseModel.ts`
- [OpenAI Adapter](https://github.com/vcky4/agent88/blob/main/src/core/models/OpenAIModel.ts): `src/core/models/OpenAIModel.ts`
- [Gemini Adapter](https://github.com/vcky4/agent88/blob/main/src/core/models/GeminiModel.ts): `src/core/models/GeminiModel.ts`
- [Ollama Adapter](https://github.com/vcky4/agent88/blob/main/src/core/models/OllamaModel.ts): `src/core/models/OllamaModel.ts`
- [Mock Adapter](https://github.com/vcky4/agent88/blob/main/src/core/models/MockModel.ts): `src/core/models/MockModel.ts`

### Memory

- [Memory Interface](https://github.com/vcky4/agent88/blob/main/src/types/index.ts): `src/types/index.ts`
- [In-Memory Adapter](https://github.com/vcky4/agent88/blob/main/src/core/memory/InMemoryMemory.ts): `src/core/memory/InMemoryMemory.ts`
- [Redis Adapter](https://github.com/vcky4/agent88/blob/main/src/core/memory/RedisMemory.ts): `src/core/memory/RedisMemory.ts`

### Agent Graphs

- [Agent Graph](https://github.com/vcky4/agent88/blob/main/src/core/graph/AgentGraph.ts): `src/core/graph/AgentGraph.ts`
- [Graph Executor](https://github.com/vcky4/agent88/blob/main/src/core/graph/GraphExecutor.ts): `src/core/graph/GraphExecutor.ts`
- [Graph Node](https://github.com/vcky4/agent88/blob/main/src/core/graph/GraphNode.ts): `src/core/graph/GraphNode.ts`
- [Graph Edge](https://github.com/vcky4/agent88/blob/main/src/core/graph/GraphEdge.ts): `src/core/graph/GraphEdge.ts`

### Other components

- **Developer / User**

## Connections

- Developer / User → Agent: submits prompt (evidence: `README.md`)
- Agent → Memory Interface: loads / saves (evidence: `src/core/Agent.ts`)
- Agent → Tool Registry: registers tools (evidence: `src/core/Agent.ts`)
- Tool Registry → Tool: stores tools (evidence: `src/core/tools/ToolRegistry.ts`)
- Agent → Execution Context: builds context (evidence: `src/core/Agent.ts`)
- Agent → Execution Engine: delegates run (evidence: `src/core/Agent.ts`)
- Agent → Trace: creates trace (evidence: `src/core/Agent.ts`)
- Agent → Model Interface: streams directly (evidence: `src/core/Agent.ts`)
- Execution Engine → Execution Context: reads and updates (evidence: `src/core/execution/ExecutionEngine.ts`)
- Execution Engine → Middleware: dispatches through (evidence: `src/core/execution/ExecutionEngine.ts`)
- Execution Engine → Model Interface: generates response (evidence: `src/core/execution/ExecutionEngine.ts`)
- Execution Engine → Tool Executor: dispatches tool (evidence: `src/core/execution/ExecutionEngine.ts`)
- Tool Executor → Tool: executes (evidence: `src/core/execution/ToolExecutor.ts`)
- Execution Engine → Trace: records timings (evidence: `src/core/execution/ExecutionEngine.ts`)
- OpenAI Adapter → Model Interface: implements (evidence: `src/core/models/OpenAIModel.ts`)
- Gemini Adapter → Model Interface: implements (evidence: `src/core/models/GeminiModel.ts`)
- Ollama Adapter → Model Interface: implements (evidence: `src/core/models/OllamaModel.ts`)
- Mock Adapter → Model Interface: implements (evidence: `src/core/models/MockModel.ts`)
- In-Memory Adapter → Memory Interface: implements (evidence: `src/core/memory/InMemoryMemory.ts`)
- Redis Adapter → Memory Interface: implements (evidence: `src/core/memory/RedisMemory.ts`)
- Developer / User → Agent Graph: runs graph (evidence: `README.md`)
- Agent Graph → Graph Executor: delegates run (evidence: `src/core/graph/AgentGraph.ts`)
- Agent Graph → Graph Node: registers agents (evidence: `src/core/graph/AgentGraph.ts`)
- Agent Graph → Graph Edge: connects agents (evidence: `src/core/graph/AgentGraph.ts`)
- Graph Executor → Agent: runs agents (evidence: `src/core/graph/GraphExecutor.ts`)
- Graph Executor → Graph Edge: orders by edges (evidence: `src/core/graph/GraphExecutor.ts`)
