GigaAgent Modular Agent Framework

GigaAgent is a modular AI agent system consisting of a FastAPI backend, a LangGraph execution graph, and a built-in web interface. Running the giga_agent dev command starts a local server on port 9090, providing both the programmatic API and the web UI.

Core Components

GigaAgent is a universal AI agent built on the GigaChain framework. It uses sub-agents and a REPL environment to solve complex tasks.

Key Features:

• Model Agnostic: Works with GigaChat, ChatGPT, Anthropic, and any model available in LangChain.
• Code Execution: Uses a REPL environment (similar to Jupyter notebooks) to execute code.
• Extensibility: Connects to external services via MCP servers and a connector catalog (e.g., Yandex Mail, Calendar, Disk, VK, GitHub).
• Multimodal: Generates images via GigaChat, FusionBrain, or OpenAI.
• Interactive UI: Displays results using interactive widgets (emails, calendars, files) in the chat.
• RAG Support: Uses vector storage (Qdrant) to apply knowledge from your documents.
• Automation: Supports scheduled tasks and Telegram channel responses.

GigaAgent can be applied to various typical tasks including file analysis, data visualization, RAG (Retrieval-Augmented Generation), social media interaction (VK), image processing, and artifact manipulation.

Key use cases include:

• Data Analysis: Analyzing CSV/XLSX files, generating summaries, and creating charts.
• Social Listening: Clustering social media comments (e.g., VK) and generating user signal reports.
• Business Analytics: Analyzing routes, profits, delivery speeds, and generating recommendations from CSV data.
• Presentation Management: Analyzing and improving .pptx files using Python tools.
• Multimodal Analysis: Converting images to business frameworks (e.g., Photo $\rightarrow$ Lean Canvas).
• Security: Searching for signs of brute-force attacks in security logs.

A Module is the fundamental unit of extension for GigaAgent. Modules allow you to extend the agent's capabilities by adding various components, including:

• API Routes: New endpoints via FastAPI.
• Data Models & Migrations: Database schemas via SQLAlchemy.
• Tools: New capabilities for the agent to execute.
• System Instructions: Additional context for the agent's persona.
• Secrets: Requirements for sensitive credentials.
• Middleware: Intermediary processors for agent requests.
• Subgraphs: Entry points for LangGraph subgraphs.
• Startup Handlers: Logic to run when the agent starts.
• Task Extensions: Modifying user tasks before execution.

A subgraph is an independent LangGraph graph that can be called from the main agent as a tool.

Benefits of Subgraphs

• Isolate complex logic: Move multi-step processes into a separate graph.
• Reuse components: Use the same subgraph across different agents.
• State management: Each subgraph maintains its own isolated state.
• Streaming: Allows receiving intermediate execution results in real-time.

Decision Guide

The agent displays interactive cards (widgets) directly in its responses when tools return specific data types. These widgets allow users to view data and perform actions without extra chat messages.

Available widgets include:

• Incoming Emails: A list of Yandex Mail messages showing sender, subject, and date. Clicking an email loads the text immediately without a model call. Emails are rendered in an isolated frame (no scripts allowed) and links open in new tabs.
• Calendar Agenda: A list of upcoming events for the next few days.
• Month Grid: A monthly calendar view showing events by day.
• File Explorer: A view of Yandex Disk folder contents. Users can navigate folders directly within the widget and use buttons to publish or unpublish files via open links.

Projects can have their own RAG collection. The behavior during project creation depends on your configuration:

• If vector embeddings are configured: A project collection is created automatically.
• If vector embeddings are NOT configured: The project is saved without a knowledge base. You can add one later by configuring vector embeddings.

Note on File Uploads: To upload files to a project's knowledge base, you must have vector embeddings configured. Depending on the scenario, an isolated environment may also be required. If uploading is unavailable, the interface will indicate what needs to be configured.

For task management services (e.g., issue trackers), use the common layer provided in modules/integrations/tracker_base.py. This layer implements a normalized contract for tasks.

Key Components of the Tracker Contract:

• BaseTrackerModule: The base class providing standard server routes for status transitions.
• make_issue: A method to create a normalized task contract.
• Payloads: Standardized formats for boards and individual cards.
• emit_composed_board(): A generative composition method.

If a provider returns a normalized payload following this contract, the interface will automatically display ready-to-use widgets without additional UI modifications.

When sharing GigaAgent, follow these principles for user management:

• Individual Accounts: Create separate accounts for colleagues rather than sharing the admin password.
• Principle of Least Privilege: If you only need to show the chat interface, do not grant administrative rights.
• Resource Isolation: Ensure users only see the collections, files, and settings required for the demo.
• Connector Privacy: OAuth tokens for external services are stored per user; colleagues will not gain access to your personal email or files via your connections.
• Telegram Channels: Be cautious with Telegram channel bots, as the agent may act without call confirmations in those environments.

Giga Agent uses a dual-database strategy to support both local development and production environments via SQLAlchemy 2.0. The specific database driver is determined by the GIGA_AGENT_RUNTIME environment variable.

Local Development (Dev/Test)

• Environment Variable: GIGA_AGENT_RUNTIME=local (default)
• Database: SQLite (sqlite+aiosqlite)
• Behavior: Data is stored in a local file. JSON fields are stored as TEXT. Alembic migrations use render_as_batch mode.

Production / Docker

• Environment Variable: GIGA_AGENT_RUNTIME=production (or similar configuration)
• Database: PostgreSQL (postgresql+asyncpg)
• Behavior: Uses native JSONB for high performance and strict typing.