DOCSEARCHbyAlgolia
Submit Docs

ii-agent Documentation

repository·main·Indexed 25 days ago

https://github.com/intelligent-internet/ii-agent

An Intelligent Agent platform (v0.1.0) featuring tools and MCP support. The system consists of a Tauri-based desktop frontend built with React, TypeScript, and Tailwind CSS, and a domain-driven backend powered by FastAPI, Socket.IO, and PostgreSQL with SQLAlchemy 2.0. It includes features for session management, LLM configuration, sandbox integration via E2B, and a PubSub event system for real-time agent communication.

Tokens
133.3K
Snippets
301
Records
554
Agent score
86%

What's inside ii-agent

  1. Overview of II-Agent Database Schema

    main

    The II-Agent database is built on PostgreSQL 15+ and consists of approximately 30 models and 38 tables. The schema is organized into several functional domains including Users & Auth, Sessions, Tasks & Agent Runs, Chat, Files, Billing, Projects, Content, and Settings.

    Key architectural patterns include:

    • Soft Deletes: Used in the sessions table via is_deleted.
    • Optimistic Locking: Implemented via version columns in tables like sessions, run_tasks, agent_run_messages, chat_provider_vector_stores, and credit_balances.
    • Self-Referencing Trees: Used for message hierarchies (chat_messages), versioning (slide_versions, storybooks), and summaries (chat_summaries).
    • Event Logging: The application_events table is designed without foreign keys to ensure event logs do not block the deletion of parent entities.

  2. Understand II-Agent Interaction Modes

    main

    II-Agent operates in two distinct modes depending on the complexity of the task and the required transport layer:

    1. Agent Mode (app_kind: "agent"):

      • Use Case: Multi-step tasks involving tools, sandboxes, and deployments (e.g., full-stack development).
      • Transport: Socket.IO (provides real-time streaming).
      • Billing: Charged per-call within the agent loop.

    2. Chat Mode (app_kind: "chat"):

      • Use Case: Single-turn conversations across multiple LLM providers (e.g., quick questions, slide creation).
      • Transport: REST + SSE (Server-Sent Events).
      • Billing: Charged per-call via LLMExecutionService.

  4. Use the ii-app skill for local app lifecycle management

    main

    The ii-app skill uses a bundled Rust CLI to manage local web and mobile app projects. Use this skill instead of calling MCP tools when you need to scaffold, restart, or inspect local development servers.

    Key Capabilities:

    • Web Projects: Scaffold templates, restart tmux-backed servers, view logs, take screenshots, check status, and create git checkpoints.
    • Mobile Projects: Scaffold Expo apps, restart Expo dev servers, and view logs.
    • Stripe Integration: Register webhooks and automatically write STRIPE_WEBHOOK_SECRET to the project .env file.

  6. Understand the II Agent System Architecture

    main

    The II Agent platform is a domain-driven architecture built on FastAPI and Socket.IO. It uses a centralized ApplicationContainer (singleton) for dependency injection and follows a strict domain-driven design (DDD) pattern for all modules.

    Core Components

    • app/: FastAPI factory, router registration, and lifespan management.
    • core/: Centralized configuration, database (SQLAlchemy 2.0), Redis, storage abstractions, and the ApplicationContainer.
    • realtime/: Socket.IO management, command handlers, and pubsub.
    • agents/: Agent execution logic, toolsets, skills, and sandbox integration.
    • tasks/: The canonical domain implementation for tracking run lifecycles.

  7. Design System: Academic & Technical Domain

    main
    The Academic & Technical domain provides a clean, structured, and evidence-based design system optimized for research papers, technical documentation, and scholarly content. The primary goal is to prioritize readability and support deep, focused reading through high-contrast text, generous leading, and optimal line lengths.

  8. Manage UI and Game State

    main

    Follow these patterns for organizing your game's interface and data:

    • Layer Separation: Keep the game canvas or entity layer strictly separate from the overlay UI.
    • State Management: Use zustand or a similar lightweight store for score and game state rather than scattering state across components.
    • UI Transitions: Use Reanimated for menu and overlay transitions to keep them outside the main game loop.
    • Game Flow: Implement explicit states for pause, resume, restart, failure, and success.

  9. Command Chaining in agent-browser

    main

    You can chain commands using && in a single shell invocation. Because the browser persists via a background daemon, chaining is efficient and maintains state.

    Best Practices:

    • Use && when you do not need to parse the output of an intermediate command (e.g., open followed by wait).
    • Run commands separately when you need to read output to decide the next step (e.g., running snapshot to discover element IDs before interacting).
    # Chain open + wait + snapshot
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# Chain multiple interactions
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3

  10. Create tracked changes in docx

    main

    When editing documents, only mark text that actually changes using <w:del> (deletion) and <w:ins> (insertion) tags. To maintain document integrity, copy original <w:r> elements with their existing attributes when preserving unchanged text.

    Method Selection Guide:

    • Regular text changes: Use replace_node() with <w:del>/<w:ins> tags, or suggest_deletion() for removing entire <w:r> or <w:p> elements.
    • Modify another author's change: Use replace_node() to nest your changes inside their existing <w:ins>/<w:del>.
    • Reject an insertion: Use revert_insertion() on the <w:ins> element.
    • Reject a deletion: Use revert_deletion() on the <w:del> element to restore content.

    Note on Attributes: The Document class automatically injects attributes like w:id, w:date, w:rsidR, w:rsidDel, w16du:dateUtc, and xml:space into new elements.

    # Minimal edit - change one word: "The report is monthly" → "The report is quarterly"
node = doc["word/document.xml"].get_node(tag="w:r", contains="The report is monthly")
rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else ""
replacement = f'<w:r w:rsidR="00AB12CD">{rpr}<w:t>The report is </w:t></w:r><w:del><w:r>{rpr}<w:delText>monthly</w:delText></w:r></w:del><w:ins><w:r>{rpr}<w:t>quarterly</w:t></w:r></w:ins>'
doc["word/document.xml"].replace_node(node, replacement)

# Delete entire paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph to delete")
doc["word/document.xml"].suggest_deletion(para)

  11. Ensure Data Credibility and Trust Signals

    main

    To establish data credibility in your UI, always include the following trust signals:

    1. Source citations: Attribute all data sources.
    2. Dates: Explicitly show when data was collected.
    3. Methodology notes: Provide brief explanations of how data was derived where relevant.
    4. Clear labels: Avoid ambiguous abbreviations.
    5. Professional presentation: Avoid 'chartjunk' and maintain clean typography.

  12. Bootstrap mobile apps with `ii-app mobile init`

    main

    The ii-app mobile init command allows you to bootstrap Expo-based mobile projects using two different methods:

    1. Using Expo templates: Use the --template flag with one of the following values:

      • tabs (default)
      • blank
      • blank-typescript

    2. Using Expo examples: Use the --example flag followed by an <expo-example-name> (e.g., --example with-reanimated).

    Runtime Behavior:

    • The command uses bunx create-expo-app@latest to create the project.
    • It automatically installs Expo web/tunnel support packages.
    • It installs NativeWind-related packages by default unless you provide the --no-tailwind flag.
    • It attempts to start Expo in tunnel mode first, falling back to LAN mode if necessary.
    • Session metadata (web URL, tunnel URL, QR code, and tmux session) is stored in the mobile cache.