# intelligent-internet/ii-agent architecture

> Architecture diagram of the GitHub repository intelligent-internet/ii-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/intelligent-internet/ii-agent
- Repository: https://github.com/intelligent-internet/ii-agent

## Overview

##### Project Type and Purpose
- This is a full-stack intelligent assistant framework ("II-Agent") combining:
- A Python-based core (CLI + WebSocket server + agent logic + tool orchestration)
- A React/Next.js frontend (real-time WebSocket UI)
- Integration with external LLM providers (Anthropic Claude, OpenAI, Google Vertex AI)
- Persistent storage (SQLite or similar via `src/ii_agent/db`) and file-based context archives

##### File Structure Analysis
- Top level
- `cli.py` – command-line interface entry point
- `ws_server.py` – WebSocket server powering frontend interactions
- `src/ii_agent/` – core agent code (agents, LLM adapters, tools, browser automation, context managers, DB models)
- `frontend/` – Next.js app (API routes under `app/api`, React components, CSS, utilities)
- `assets/`, `tests/`, `pyproject.toml`, `run_gaia.py` (benchmark harness)
- Patterns and layers
- Separation of concerns: CLI vs WS API vs tooling vs core reasoning vs context management vs persistence
- Modular agent architecture: each tool and LLM client is pluggable under `src/ii_agent/tools` and `llm`

##### Important README Insights
- Dual interaction modes: CLI and WebSocket
- Real-time streaming events for responsive UX
- Context management strategies: token counting, file-based archival
- Execution capabilities: shell commands, browser automation, file ops, search, multimedia processing

a. Main Components
- Frontend (Next.js React UI)
- WebSocket Server API (Python)
- CLI Interface (Python)
- Core Agent Engine
– Event & message manager
– Context manager (in-memory + file)
– Tool manager (shell, browser, search, PDF, image, etc.)
– LLM clients (Anthropic, OpenAI, Vertex via Google SDK)
- Persistence Layer
– Database manager & models (`src/ii_agent/db`)
– File system workspace for state & archives
- External Services
– Anthropic API
– Google Vertex AI
– SerpAPI / Tavily / other search APIs
– Static file host for frontend assets

b. Relationships & Data Flows
- Frontend ↔ WebSocket server (bidirectional streams of events & messages)
- CLI → Core Agent → LLM / Tools → Core Agent → CLI (synchronous command execution)
- Core Agent → Database (read/write interaction history, config)
- Core Agent → File System (workspace files, context archives)
- Core Agent → External LLM APIs & third-party services via HTTP/SDK

c. Architectural Patterns & Principles
- Layered Architecture: Presentation (CLI/WS), API, Core Logic, Persistence, External Integration
- Modular / Plug-in approach: Tools and LLM adapters conform to base interfaces for easy extension
- Real-time Event Streaming: WebSocket for low-latency UI updates
- Context Management: strategic truncation, file-based archiving to handle large interactions

d. Key Technologies & Frameworks
- Python 3.10+: FastAPI or websockets library (for `ws_server.py`), Pydantic models, SQLAlchemy or similar
- Node.js 18+, Next.js 13+, TypeScript, React Components, CSS modules
- Google Cloud Vertex AI SDK, Anthropic Python client
- WebSocket protocol for frontend communication
- CLI parsing (e.g., argparse)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    CLIInterface["CLI Interface"]:::backend
    WSAPI["WebSocket Server API"]:::backend

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        FrontendUI["Next.js React UI"]:::frontend
    end

    %% Backend Service
    subgraph "Backend Service"
        direction TB
        subgraph "Core Agent Engine"
            direction TB
            EventManager["Event & Message Manager"]:::backend
            subgraph "Context Manager"
                direction TB
                ContextInMemory["In-Memory Context"]:::backend
                ContextFile["File-Based Context"]:::backend
            end
            subgraph "Tool Manager"
                direction TB
                ToolManagerCore["Tool Manager Core"]:::backend
                ShellTool["Shell Tool"]:::backend
                BrowserTools["Browser Automation Tools"]:::backend
                AdvancedTools["Advanced Tools"]:::backend
            end
            subgraph "LLM Clients"
                direction TB
                LLMBase["LLM Base Interface"]:::backend
                AnthropicClient["Anthropic Client"]:::backend
                OpenAIClient["OpenAI Client"]:::backend
            end
        end
        subgraph "Persistence Layer"
            direction TB
            DBManager["Database Manager"]:::persistence
            DBModels["Database Models"]:::persistence
            Workspace["File-Based Workspace & Archives"]:::persistence
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AnthropicAPI["Anthropic API"]:::external
        OpenAIAPI["OpenAI API"]:::external
        VertexAPI["Google Vertex AI"]:::external
        SearchAPIs["Search & Media Services"]:::external
    end

    %% Data Flows
    CLIInterface -->|synch call| EventManager
    EventManager -->|manages| ContextInMemory
    EventManager -->|manages| ContextFile
    EventManager -->|orchestrates| ToolManagerCore
    ToolManagerCore -->|calls| ShellTool
    ToolManagerCore -->|calls| BrowserTools
    ToolManagerCore -->|calls| AdvancedTools
    EventManager -->|routes| LLMBase
    LLMBase -->|implements| AnthropicClient
    LLMBase -->|implements| OpenAIClient
    AnthropicClient -->|HTTP/SDK| AnthropicAPI
    OpenAIClient -->|HTTP/SDK| OpenAIAPI
    AnthropicClient -->|HTTP/SDK| VertexAPI
    EventManager -->|read/write| DBManager
    DBManager -->|uses| DBModels
    EventManager -->|save/read| Workspace

    FrontendUI -.->|WebSocket async| WSAPI
    WSAPI -->|synch call| EventManager
    WSAPI -->|streaming events| FrontendUI

    %% Persistence to External
    ToolManagerCore -->|calls| SearchAPIs

    %% Click Events
    click CLIInterface "https://github.com/intelligent-internet/ii-agent/blob/main/cli.py"
    click WSAPI "https://github.com/intelligent-internet/ii-agent/blob/main/ws_server.py"
    click FrontendUI "https://github.com/intelligent-internet/ii-agent/tree/main/frontend/"
    click EventManager "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/core/event.py"
    click ContextInMemory "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/llm/context_manager/standard.py"
    click ContextFile "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/llm/context_manager/file_based.py"
    click ToolManagerCore "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/tools/tool_manager.py"
    click ShellTool "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/tools/bash_tool.py"
    click BrowserTools "https://github.com/intelligent-internet/ii-agent/tree/main/src/ii_agent/tools/browser_tools/"
    click AdvancedTools "https://github.com/intelligent-internet/ii-agent/tree/main/src/ii_agent/tools/advanced_tools/"
    click LLMBase "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/llm/base.py"
    click AnthropicClient "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/llm/anthropic.py"
    click OpenAIClient "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/llm/openai.py"
    click DBManager "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/db/manager.py"
    click DBModels "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/db/models.py"
    click Workspace "https://github.com/intelligent-internet/ii-agent/blob/main/src/ii_agent/utils/workspace_manager.py"

    %% Styles
    classDef backend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef frontend fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef persistence fill:#fff9c4,stroke:#fdd835,color:#f57f17
    classDef external fill:#ffcdd2,stroke:#e53935,color:#b71c1c
```
