Skip to main content
Version: Next

Runtime

The Runtime is the global orchestrator that manages all agents, sessions, and execution across Agent Kernel. You can skip this section if you are not planning to contribute to Aent Kernel.

Overview​

What is the Runtime?​

The Runtime:

  • Maintains global agent registry
  • Manages sessions across requests
  • Provides centralized configuration
  • Coordinates execution across modes (CLI, API, Lambda)
  • Enables service integration (MCP, A2A)

Singleton Pattern​

The Runtime uses a singleton pattern - there's only one instance:

from agentkernel.core import Runtime

# Always returns the same instance
runtime1 = Runtime.get()
runtime2 = Runtime.get()

assert runtime1 is runtime2  # True

Accessing Agents​

Get Agent by Name​

from agentkernel.core import Runtime

runtime = Runtime.get()
agent = runtime.get_agent("assistant")

Get All Agents​

runtime = Runtime.get()
all_agents = runtime.get_all_agents()

for name, agent in all_agents.items():
    print(f"Agent: {name}")

Check Agent Existence​

runtime = Runtime.get()

if runtime.has_agent("assistant"):
    agent = runtime.get_agent("assistant")
else:
    print("Agent not found")

Session Management​

The Runtime manages sessions through a SessionManager:

from agentkernel.core import Runtime

runtime = Runtime.get()

# Get or create session
session = runtime.get_session("user-123")

# Session is automatically persisted based on configuration

Configuration​

The Runtime provides access to global configuration:

from agentkernel.core import Runtime, AKConfig

runtime = Runtime.get()
config = runtime.config

# Or access directly
config = AKConfig.get()

print(config.log_level)
print(config.session_storage)

Execution Modes​

The Runtime supports multiple execution modes:

CLI Mode​

from agentkernel.cli import CLI

# CLI uses Runtime to discover and execute agents
CLI.main()

REST API Mode​

from agentkernel.api import RESTAPI

# API server uses Runtime to route requests
RESTAPI.run()

AWS Lambda Mode​

from agentkernel.aws import Lambda

# Lambda handler uses Runtime to process events
handler = Lambda.handler

MCP Server Mode​

from agentkernel.mcp import MCP

# MCP server exposes agents via Runtime
server = MCP.get()

Runtime Lifecycle​

Advanced Usage​

Custom Agent Registration​

Manually register agents (advanced):

from agentkernel.core import Runtime

runtime = Runtime.get()

# Manually register an agent
runtime.register_agent(custom_agent)

Integration Points​

MCP Integration​

# when MCP server is enabled
# AK_MCP_ENABLED=true

A2A Integration​

# for all registered agents
# AK_A2A_ENABLED=true

REST API Integration​

# GET /agents - list all agents
# POST /chat - execute agent

Best Practices​

Single Runtime Instance​

Always use Runtime.get():

# Correct
runtime = Runtime.get()

# Don't try to instantiate
# runtime = Runtime()  # Won't work

Configuration Before Execution​

Set environment variables before importing:

import os
os.environ["AK_SESSION_STORAGE"] = "redis"
os.environ["AK_REDIS_URL"] = "redis://localhost:6379"

# Now import and use
from agentkernel.core import Runtime
runtime = Runtime.get()

Summary​

  • Runtime is the global orchestrator
  • Maintains agent registry
  • Manages sessions
  • Provides centralized configuration
  • Supports multiple execution modes
  • Singleton pattern - use Runtime.get()

Next Steps​