How to Use Agent

To pipeline of how to use agents in AIOS is shown as the following figure.

AIOS Agent Integration Flow

AIOS first checks cache for the agent (typically the source code of the agent will be stored in ~/.cache/cerebrum/) and then installs the agent if it is not available.

To use agents, you can follow the steps as below to run a demo agent.

Step 1: Initialize Your Client

First, let's create your client instance:

from cerebrum import config
from cerebrum.client import Cerebrum

aios_kernel_url = "http://localhost:8000"

client = Cerebrum(base_url = aios_kernel_url)
config.global_client = client

Step 2: Add Functionality Layers

The AIOS kernel offers five core modules that export APIs for users to customize

• LLM

• Memory

• Storage

• Tools

• Scheduler

Here's how to add these layers to your client:

from cerebrum.llm.layer import LLMLayer
from cerebrum.memory.layer import MemoryLayer
from cerebrum.overrides.layer import OverridesLayer
from cerebrum.storage.layer import StorageLayer
from cerebrum.tool.layer import ToolLayer

client.add_llm_layer(
    LLMLayer(llm_name="gpt-4o-mini", llm_backend="openai")  # Configure your LLM
).add_storage_layer(
    StorageLayer(root_dir="root")  # Set storage directory
).add_memory_layer(
    MemoryLayer(memory_limit=104857600)  # Set memory per agent
).add_tool_layer(
    ToolLayer()  # Add tool capabilities
).override_scheduler(
    OverridesLayer(max_workers=32)  # Configure scheduling
)

Step 3: Run Your Agent

Now you can run agents and get their results:

try:
    # Connect to the client
    client.connect()
    
    # Execute your agent
    agent_path = "demo_author/demo_agent"  # Your agent's name or path
    task = "Tell me what is core idea of AIOS"       # Your task description
    result = client.execute(agent_path, {"task": task})
    
    # Get the results
    final_result = client.poll_agent(
        result["execution_id"],
        timeout=300
    )
    print("📋 Task result:", final_result)
    print("✅ Task completed")

except TimeoutError:
    print("❌ Task timed out")
except Exception as e:
    print(f"❌ Failed to execute task: {str(e)}")
finally:
    client.cleanup()

You can find all the available agents in the example agents folder. If you would like to customize and develop your new agents, you can check out the guides on How to Develop Agents.