LocalAGI Documentation

For managing multiple agents simultaneously, use the state.NewAgentPool system. An AgentPool allows you to define default models, API credentials, and global configurations for actions, connectors, dynamic prompts, and job filters.

Once a pool is initialized, you can create specific agents within it using an AgentConfig and control the entire group using StartAll(), Stop(), or Remove().

Key capabilities of the AgentPool include:

• Bulk Management: Start, stop, or remove agents by name.
• Global Configuration: Define shared actions, connectors, and prompts.
• Status Tracking: Retrieve status history for specific agents.
• Custom Logic: Implement custom job filtering and dynamic prompt templates.

import (
    "github.com/mudler/LocalAGI/core/state"
    "github.com/mudler/LocalAGI/core/types"
)

// Create a new agent pool
pool, err := state.NewAgentPool(
    "default-model",           // default model name
    "default-multimodal-model", // default multimodal model
    "transcription-model",     // default transcription model
    "en",                     // default transcription language
    "tts-model",              // default TTS model
    "http://localhost:8080",  // API URL
    "your-api-key",           // API key
    "./state",                // state directory
    func(config *AgentConfig) func(ctx context.Context, pool *AgentPool) []types.Action {
        // Define available actions for agents
        return func(ctx context.Context, pool *AgentPool) []types.Action {
            return []types.Action{
                // Add your custom actions here
            }
        }
    },
    func(config *AgentConfig) []Connector {
        // Define connectors for agents
        return []Connector{
            // Add your custom connectors here
        }
    },
    func(config *AgentConfig) []DynamicPrompt {
        // Define dynamic prompts for agents
        return []DynamicPrompt{
            // Add your custom prompts for agents
        }
    },
    func(config *AgentConfig) types.JobFilters {
        // Define job filters for agents
        return types.JobFilters{
            // Add your custom filters here
        }
    },
    "10m",  // timeout
    true,   // enable conversation logs
    nil,    // skills service (optional),
)

// Create a new agent in the pool
agentConfig := &AgentConfig{
    Name: "my-agent",
    Model: "gpt-4",
    SystemPrompt: "You are a helpful assistant.",
    EnableKnowledgeBase: true,
    EnableReasoning: true,
    // Add more configuration options as needed
}

err = pool.CreateAgent("my-agent", agentConfig)

// Start all agents
err = pool.StartAll()

// Get agent status
status := pool.GetStatusHistory("my-agent")

// Stop an agent
pool.Stop("my-agent")

// Remove an agent
err = pool.Remove("my-agent")

Skills are reusable instructions and resources (like scripts or assets) that agents can leverage.

Enabling Skills

To allow an agent to use skills, you must enable them in the agent's Advanced Settings by toggling Enable Skills. Once enabled, the agent can use built-in skill tools (list, read, search, resources) via a specialized skills MCP.

Managing Skills via Web UI

• Open Skills in the sidebar.
• Skills are stored in the STATE_DIR/skills directory.
• You can create, edit, search, import, and export skills.
• You can sync skills by adding Git repositories.

Storage and Persistence

In Docker environments, skills are persisted in the /pool directory. To use a host folder for skills, mount it to /pool/skills in your Docker configuration.

Docker Mount Example:

volumes:
  - ./my-skills:/pool/skills

Compatibility

Skills use the same format as skillserver (e.g., containing a SKILL.md file). Skills exported from LocalAGI are compatible with the standalone skillserver.

LocalAGI supports the Model Context Protocol (MCP) to connect agents to external tools and data sources. You can use both local and remote servers.

Local MCP Servers

Local servers run as processes spawned by LocalAGI via STDIO. A common pattern is running MCP servers inside Docker containers.

Example Configuration (GitHub MCP Server):

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Remote MCP Servers

Remote servers are accessed via HTTP URLs. You can add these URLs directly in the LocalAGI Web UI or via the API configuration.

Configuration Methods

• Web UI: Use the MCP Settings section during agent creation.
• API: Include the mcpServers configuration object in your agent's JSON configuration.

To develop LocalAGI, you need to run the Go backend and the React/Vite frontend. The frontend requires a build directory to exist before the backend can start.

1. Frontend Setup (React + Vite)

Navigate to the webui/react-ui directory to install dependencies and build the assets.

cd webui/react-ui

# Install dependencies using bun
bun i

# Compile frontend
bun run build

# Start frontend development server
bun run dev

2. Backend Setup (Go)

In a separate terminal, set the required environment variables and run the Go server.

cd LocalAGI

# Create state directory
mkdir pool

# Set required environment variables
export LOCALAGI_MODEL=gemma-3-4b-it-qat
export LOCALAGI_MULTIMODAL_MODEL=moondream2-20250414
export LOCALAGI_IMAGE_MODEL=sd-1.5-ggml
export LOCALAGI_LLM_API_URL=http://localai:8080
export LOCALAGI_STATE_DIR=./pool
export LOCALAGI_TIMEOUT=5m
export LOCALAGI_ENABLE_CONVERSATIONS_LOGGING=false
export LOCALAGI_SSHBOX_URL=root:root@sshbox:22

# Start development server
go run main.go

Note: Check webui/react-ui/.vite.config.js for additional environment variables used to configure the backend URL connection.

LocalAGI allows you to extend agent functionality by defining custom actions in Go. These actions can be defined inline within the Web UI when creating an agent or loaded automatically from a directory.

Automatic Loading via Environment Variable

You can configure LocalAGI to automatically load all .go files from a specific directory by setting the LOCALAGI_CUSTOM_ACTIONS_DIR environment variable.

Environment Variable:

• LOCALAGI_CUSTOM_ACTIONS_DIR: Path to a directory containing .go files.

Example Setup (Docker Compose):

environment:
  - LOCALAGI_CUSTOM_ACTIONS_DIR=/app/custom-actions

Custom Action Requirements

Every custom action must implement three specific functions:

1. Run(config map[string]interface{}) (string, map[string]interface{}, error): The core logic. It receives configuration parameters and returns a result string, a map of additional data, and an error.
2. Definition() map[string][]string: Defines the parameters the action accepts. The map key is the parameter name, and the value is a slice containing the type (e.g., "string") and a description.
3. RequiredFields() []string: A list of parameter names that must be provided for the action to execute.

Note: You may only use standard Go libraries; additional external modules are not supported.

You can customize the models used by LocalAGI by setting specific environment variables when running docker compose. If no models are specified, the system uses the following defaults:

• Text model: gemma-3-4b-it-qat
• Multimodal model: moondream2-20250414
• Image model: sd-1.5-ggml

Available environment variables:

• MODEL_NAME: The text model to use.
• MULTIMODAL_MODEL: The multimodal model to use.
• IMAGE_MODEL: The image generation model to use.
• LOCALAI_SINGLE_ACTIVE_BACKEND: Set to true to enable single active backend mode.

# CPU with custom model
MODEL_NAME=gemma-3-12b-it docker compose up

# NVIDIA GPU with custom models
MODEL_NAME=gemma-3-12b-it \
MULTIMODAL_MODEL=moondream2-20250414 \
IMAGE_MODEL=flux.1-dev-ggml \
docker compose -f docker-compose.nvidia.yaml up

# Intel GPU with custom models
MODEL_NAME=gemma-3-12b-it \
MULTIMODAL_MODEL=sd-1.5-ggml \
docker compose -f docker-compose.intel.yaml up