JaatoRuntime

Shared runtime environment for the jaato framework. JaatoRuntime manages resources that are shared across the main agent and any subagents, including provider configuration, plugin registry, permissions, and token accounting.

Module	shared.jaato_runtime
Relationship	Parent of JaatoSession
Used by	JaatoClient (facade wrapper)

When to Use JaatoRuntime

Most users should use JaatoClient which wraps the runtime automatically. Access the runtime directly when you need to:

• Create subagent sessions with different models or tool subsets
• Share resources across multiple independent sessions
• Register additional providers for cross-provider subagents
• Access telemetry configuration

from jaato import JaatoClient

# JaatoClient creates runtime internally
client = JaatoClient()
client.connect()  # Reads JAATO_PROVIDER and MODEL_NAME from env
client.configure_tools(registry)

# Access runtime for subagent creation
runtime = client.get_runtime()
sub_session = runtime.create_session(
    model="claude-sonnet-4-20250514",
    tools=["cli", "web_search"],
    system_instructions="You are a researcher."
)
sub_response = sub_session.send_message("Research...")

from jaato import PluginRegistry
from shared import JaatoRuntime

# Create runtime directly
runtime = JaatoRuntime(provider_name="anthropic")
runtime.connect()  # Reads provider config from env

# Configure plugins
registry = PluginRegistry()
registry.discover()
registry.expose_tool("cli")
runtime.configure_plugins(registry)

# Create sessions
main = runtime.create_session(model="claude-sonnet-4-20250514")
helper = runtime.create_session(
    model="claude-sonnet-4-20250514",
    tools=["web_search"],
    system_instructions="Search assistant"
)

Constructor

__init__

Creates a new JaatoRuntime instance with the specified provider.

• provider_name str optional
  Name of the model provider to use. Supported providers: google_genai, anthropic, github_models, claude_cli, antigravity, ollama.
  Default: "google_genai"

# Explicit provider
runtime = JaatoRuntime(provider_name="anthropic")

# Or Google GenAI
runtime = JaatoRuntime(provider_name="google_genai")

# Cross-provider support
runtime = JaatoRuntime(provider_name="anthropic")
runtime.register_provider("google_genai")  # For subagents

Connection

connect

Establishes the provider configuration. For some providers (Google), project and location are required. For others (Anthropic), they can be None.

• project str required
  Cloud project ID (required for Vertex AI, optional for others)
• location str required
  Provider region (e.g., us-central1, global)

is_connected property

Returns True if runtime is connected.

provider_name property

Returns the model provider name.

verify_auth

Verify authentication before loading tools. For providers with OAuth support, this can trigger interactive login.

# Recommended: reads config from env
runtime = JaatoRuntime()  # Uses JAATO_PROVIDER env var
runtime.connect()

# Or with explicit provider
runtime = JaatoRuntime(provider_name="anthropic")
runtime.connect()

# Google GenAI (Vertex AI) with explicit project/location
runtime = JaatoRuntime(provider_name="google_genai")
runtime.connect(
    project="my-gcp-project",
    location="us-central1"
)

# Verify auth with interactive login
if not runtime.verify_auth(allow_interactive=True):
    print("Authentication failed")
    return

Plugin Configuration

configure_plugins

Configure plugins for the runtime. Sets up the shared plugin registry, permission plugin, and ledger that will be available to all sessions.

• registry PluginRegistry required
  Registry with exposed plugins
• permission_plugin PermissionPlugin optional
  Permission plugin for access control
• ledger TokenLedger optional
  Token ledger for accounting

registry property

Get the plugin registry.

permission_plugin property

Get the permission plugin.

ledger property

Get the token ledger.

refresh_tool_cache

Refresh the cached tool configuration after enabling/disabling tools.

from jaato import PluginRegistry
from shared import (
    JaatoRuntime,
    PermissionPlugin,
    TokenLedger
)

runtime = JaatoRuntime()
runtime.connect()  # Reads provider config from env

# Setup registry
registry = PluginRegistry()
registry.discover()
registry.expose_tool("cli")
registry.expose_tool("file_edit")
registry.expose_tool("web_search")

# Optional: permission control
perm = PermissionPlugin()
perm.initialize({"config_path": "perms.json"})

# Optional: token accounting
ledger = TokenLedger()

# Configure
runtime.configure_plugins(
    registry,
    permission_plugin=perm,
    ledger=ledger
)

# Access shared resources
print(f"Registry: {runtime.registry}")
print(f"Ledger: {runtime.ledger}")

Session Creation

create_session

Create a new session from this runtime. Sessions share the runtime's resources but have their own conversation history and can use different models or tool subsets.

• model str required
  Model name to use for this session
• tools List[str] optional
  List of plugin names to expose. If None, uses all exposed plugins.
• system_instructions str optional
  Additional system instructions to prepend to base instructions.
• plugin_configs Dict[str, Dict] optional
  Per-plugin configuration overrides.
• provider_name str optional
  Provider override for cross-provider subagents. If specified, uses a different AI provider than the runtime default.

# Main agent session (all tools)
main = runtime.create_session(
    model="claude-sonnet-4-20250514"
)

# Research subagent (specific tools)
researcher = runtime.create_session(
    model="claude-sonnet-4-20250514",
    tools=["web_search", "web_fetch"],
    system_instructions="You are a research assistant."
)

# Code review subagent
reviewer = runtime.create_session(
    model="claude-sonnet-4-20250514",
    tools=["file_edit", "cli"],
    system_instructions="You are a code reviewer."
)

# Send messages to each
main_response = main.send_message("Hello", on_output)
research = researcher.send_message("Find info on...", on_output)
review = reviewer.send_message("Review this code...", on_output)

# Main agent uses Anthropic
runtime = JaatoRuntime(provider_name="anthropic")
runtime.connect()
runtime.configure_plugins(registry)

# Register Google GenAI for subagents
runtime.register_provider("google_genai")

# Create session with different provider
gemini_session = runtime.create_session(
    model="gemini-2.5-flash",
    provider_name="google_genai",
    tools=["cli"],
    system_instructions="You are a research assistant."
)

Multi-Provider Support

register_provider

Register an additional provider for cross-provider subagent support. Allows subagents to use different AI providers than the parent agent.

• provider_name str required
  Name of the provider (e.g., 'anthropic', 'google_genai').
• config ProviderConfig optional
  Optional ProviderConfig. If None, creates a default config. Providers will use environment variables for auth.

create_provider

Create a new provider instance for a session. Each session gets its own provider instance to maintain independent conversation state.

list_available_models

List available models from a provider, optionally filtered by prefix.

from shared import JaatoRuntime
from shared.plugins.model_provider.base import ProviderConfig

# Create runtime with primary provider
runtime = JaatoRuntime(provider_name="anthropic")
runtime.connect()

# Register additional providers
runtime.register_provider("google_genai")
runtime.register_provider("ollama")

# List models from each provider
claude_models = runtime.list_available_models(
    prefix="claude",
    provider_name="anthropic"
)
gemini_models = runtime.list_available_models(
    prefix="gemini",
    provider_name="google_genai"
)
local_models = runtime.list_available_models(
    provider_name="ollama"
)

print(f"Claude: {claude_models}")
print(f"Gemini: {gemini_models}")
print(f"Local: {local_models}")

# Register with custom config
runtime.register_provider("google_genai", ProviderConfig(
    project="different-project",
    location="europe-west1"
))

Tool Access

get_tool_schemas

Get tool schemas, optionally filtered by plugin names.

get_executors

Get executors, optionally filtered by plugin names.

get_system_instructions

Get system instructions. Assembles from base instructions (.jaato/system_instructions.md), additional instructions, and plugin instructions.

deferred_tools_enabled property

Check if deferred tool loading is enabled. When True, only 'core' tools are loaded into the initial model context. Controlled by JAATO_DEFERRED_TOOLS environment variable.

# Get all tool schemas
schemas = runtime.get_tool_schemas()
for schema in schemas:
    print(f"{schema.name}: {schema.description}")

# Get specific plugin tools
cli_schemas = runtime.get_tool_schemas(plugin_names=["cli"])

# Get executors
executors = runtime.get_executors()
print(f"Available tools: {list(executors.keys())}")

# Get system instructions
instructions = runtime.get_system_instructions(
    additional="Focus on code quality."
)

# Check deferred loading
if runtime.deferred_tools_enabled:
    print("Only core tools in initial context")

Telemetry

telemetry property

Get the telemetry plugin.

set_telemetry_plugin

Set a custom telemetry plugin for OpenTelemetry tracing. The plugin should be initialized before setting.

from shared.plugins.telemetry import create_otel_plugin

# Create and configure telemetry plugin
telemetry = create_otel_plugin()
telemetry.initialize({
    "enabled": True,
    "exporter": "otlp",
    "endpoint": "http://localhost:4317",
    "service_name": "my-jaato-app",
})

# Set on runtime
runtime.set_telemetry_plugin(telemetry)

# Telemetry will now trace:
# - jaato.turn spans
# - jaato.tool spans
# - jaato.permission spans