How intelligent-internet/ii-agent works
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)