aios-cerebrum

AIOS & Cerebrum: Agent Operating System

Overview

AIOS (AI Agent Operating System) is a user-space agent kernel that provides syscall-like abstractions for AI agents. Cerebrum is the SDK that enables developers to build and deploy agents on AIOS.

Together, they form an agent substrate layer in the FlexStack architecture, complementing AGiXT for orchestration and LocalAI for inference.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                          AGENT STACK                                     │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                   │
│  │  Your Agent  │  │  Your Agent  │  │  Your Agent  │   <- Cerebrum SDK │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘                   │
│         │                 │                 │                           │
│  ┌──────┴─────────────────┴─────────────────┴───────┐                   │
│  │              AIOS Kernel (Port 8000)             │   <- Agent Syscalls│
│  │   Scheduler | Memory | Storage | Tools | LLM    │                    │
│  └──────────────────────┬───────────────────────────┘                   │
│                         │                                               │
│  ┌──────────────────────┴───────────────────────────┐                   │
│  │              LocalAI (Port 8080)                 │   <- LLM Inference │
│  │   OpenAI-compatible API | Local Models          │                    │
│  └──────────────────────────────────────────────────┘                   │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────┐                   │
│  │              AGiXT (Port 7437)                   │   <- Orchestration │
│  │   Chains | Extensions | Memory | Multi-Agent    │                    │
│  └──────────────────────────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

# Enter full development shell
nom develop .#full

# Or use direnv
direnv allow

Installation

# Install AIOS Kernel
aios install

# Install Cerebrum SDK (in AIOS pixi environment)
pixi run -e aios pip install aios-agent-sdk

# Verify installation
pixi run -e aios python -c "import cerebrum; print('Cerebrum SDK ready')"

Starting Services

# 1. Start LocalAI (inference backend)
localai start

# 2. Start AIOS Kernel (agent syscalls)
aios start

# 3. (Optional) Start AGiXT (orchestration)
agixt up

Running Your First Agent

# List available agents
pixi run -e aios list-agenthub-agents

# Run an agent from AgentHub
pixi run -e aios run-agent \
  --mode remote \
  --agent_author example \
  --agent_name test_agent \
  --task "What is the capital of France?"

# Run a local agent
pixi run -e aios run-agent \
  --mode local \
  --agent_path ./my_agent \
  --task "Your task here"

AIOS Kernel Management

Commands

Command	Description
aios install	Clone AIOS repository and setup
aios start	Start AIOS Kernel server (port 8000)
aios stop	Stop AIOS Kernel server
aios status	Check if AIOS is running
aios config	Show AIOS configuration

Environment Variables

Variable	Default	Description
AIOS_DIR	~/.local/share/aios	Installation directory
AIOS_PORT	8000	Kernel server port
AIOS_URL	http://localhost:8000	Kernel API URL
AIOS_VECTOR_DB	chroma	Vector database (chroma/qdrant)

Configuration

Edit ~/.local/share/aios/AIOS/aios/config/config.yaml:

api_keys:
  openai: "sk-..."        # OpenAI API key
  anthropic: "sk-..."     # Claude API key
  gemini: "..."           # Google Gemini key
  groq: "..."             # Groq fast inference
  huggingface_token: ""   # HuggingFace access

llm_models:
  - name: "gpt-4"
    backend: "openai"
  - name: "claude-3-opus"
    backend: "anthropic"
  - name: "local-model"
    backend: "ollama"     # For LocalAI models

storage:
  vector_db:
    type: "chroma"        # or "qdrant"

server:
  host: "localhost"
  port: 8000

Cerebrum SDK

Agent Structure

my_agent/
├── entry.py              # Main agent implementation
├── config.json           # Agent metadata
└── meta_requirements.txt # Additional dependencies (optional)

Agent Configuration (config.json)

{
  "name": "ros2_controller",
  "description": [
    "ROS2-aware agent that can control robot systems"
  ],
  "tools": [
    "my_org/ros2_topic_tool",
    "my_org/ros2_service_tool"
  ],
  "meta": {
    "author": "my_org",
    "version": "0.0.1",
    "license": "MIT"
  },
  "build": {
    "entry": "entry.py",
    "module": "ROS2ControllerAgent"
  }
}

Basic Agent Implementation

# entry.py
from cerebrum.llm.apis import llm_chat
from cerebrum.memory.apis import memory_read, memory_write
from cerebrum.storage.apis import storage_read, storage_write
from cerebrum.tool.apis import tool_call

class ROS2ControllerAgent:
    def __init__(self):
        self.name = "ROS2 Controller"

    def run(self, task: str) -> str:
        # Use LLM to understand the task
        response = llm_chat(
            messages=[
                {"role": "system", "content": "You are a ROS2 robot controller."},
                {"role": "user", "content": task}
            ],
            model="gpt-4"
        )

        # Use tools to interact with ROS2
        if "topic" in task.lower():
            result = tool_call("ros2_topic_tool", {"action": "list"})

        # Store context in memory
        memory_write("last_task", task)

        return response

Tool Development

# tools/ros2_topic_tool/entry.py
class ROS2TopicTool:
    def __init__(self):
        self.name = "ros2_topic_tool"

    def run(self, params: dict) -> str:
        action = params.get("action", "list")
        topic = params.get("topic", "")

        if action == "list":
            import subprocess
            result = subprocess.run(
                ["ros2", "topic", "list"],
                capture_output=True,
                text=True
            )
            return result.stdout
        elif action == "echo":
            # Echo topic messages
            pass

        return "Unknown action"

    def get_tool_call_format(self):
        return {
            "type": "function",
            "function": {
                "name": "ros2_topic_tool",
                "description": "Interact with ROS2 topics",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "action": {
                            "type": "string",
                            "enum": ["list", "echo", "pub"],
                            "description": "Action to perform"
                        },
                        "topic": {
                            "type": "string",
                            "description": "Topic name"
                        }
                    },
                    "required": ["action"]
                }
            }
        }

CLI Commands

Agent Management

# List available agents
pixi run -e aios list-agenthub-agents
pixi run -e aios list-local-agents

# Download agent from AgentHub
pixi run -e aios download-agent \
  --agent_author example \
  --agent_name demo_agent \
  --agent_version 0.0.1

# Upload agent to AgentHub
pixi run -e aios upload-agents \
  --agent_path ./my_agent \
  --agenthub_url https://app.aios.foundation

Tool Management

# List available tools
pixi run -e aios list-toolhub-tools
pixi run -e aios list-local-tools

# Download tool
pixi run -e aios download-tool \
  --tool_author example \
  --tool_name arxiv \
  --tool_version 0.0.1

LLM Management

# List available LLMs
pixi run -e aios list-available-llms

Integration with FlexStack

LocalAI Integration

AIOS uses LocalAI as an inference backend through the ollama provider:

# In AIOS config.yaml
llm_models:
  - name: "gemma-3n-E2B"
    backend: "ollama"
  - name: "phi-4-mini"
    backend: "ollama"

LocalAI provides OpenAI-compatible endpoints on port 8080.

AGiXT Integration

AIOS and AGiXT can work together:

• AGiXT: High-level orchestration, chains, extensions, multi-agent coordination
• AIOS: Low-level agent kernel, syscalls, resource management

# Use AGiXT for orchestration
import requests

# Use AIOS for agent execution
from cerebrum.client import Cerebrum

# Example: AGiXT triggers AIOS agent
agixt_response = requests.post(
    "http://localhost:7437/api/v1/run_chain",
    json={"chain_name": "ros2_task", "input": "Navigate to waypoint"}
)

# AIOS handles the actual agent execution
cerebrum = Cerebrum()
result = cerebrum.run_agent("ros2_controller", "Move to position (1, 2, 0)")

ROS2 Integration

Build ROS2-aware agents using Cerebrum:

# ros2_agent/entry.py
import rclpy
from rclpy.node import Node
from cerebrum.tool.apis import tool_call

class ROS2AgentNode(Node):
    def __init__(self):
        super().__init__('aios_agent')
        # ROS2 node with AIOS agent capabilities

    def process_task(self, task: str):
        # Use AIOS tools within ROS2 context
        result = tool_call("llm_reasoning", {"prompt": task})
        return result

Pixi Environments

Default Environment

# Standard ROS2 development (no AIOS)
pixi run python your_script.py

AIOS Environment

# AIOS with strict dependency pins
pixi run -e aios python your_script.py

# Run AIOS agent
pixi run -e aios run-agent --mode local --agent_path ./my_agent --task "Hello"

AIOS + CUDA Environment

# AIOS with GPU support (vLLM backend)
pixi run -e aios-cuda python your_script.py

Troubleshooting

AIOS Kernel Not Starting

# Check if port 8000 is in use
lsof -i :8000

# Check AIOS installation
ls -la ~/.local/share/aios/AIOS

# Reinstall if needed
rm -rf ~/.local/share/aios/AIOS
aios install

Dependency Conflicts

AIOS requires strict dependency versions. Use the dedicated pixi environment:

# Wrong: mixing environments
pip install aios-agent-sdk  # May conflict with ROS2

# Correct: use AIOS environment
pixi run -e aios pip install aios-agent-sdk

LLM Connection Issues

# Check LocalAI is running
localai status

# Verify API endpoint
curl http://localhost:8080/v1/models

# Check AIOS config points to LocalAI
cat ~/.local/share/aios/AIOS/aios/config/config.yaml | grep -A5 "ollama"

Resources

• AIOS GitHub: agiresearch/AIOS
• Cerebrum GitHub: agiresearch/Cerebrum
• AIOS Documentation: docs.aios.foundation
• AgentHub: app.aios.foundation
• PyPI: aios-agent-sdk

Related Skills

• AI Assistants - LocalAI, AGiXT, aichat, aider
• Rust Tooling - AGiXT Rust SDK
• Distributed Systems - NATS, Temporal
• ROS2 Development - ROS2 integration patterns