Runtime Overview

The LeafMesh runtime manages your platform lifecycle, event processing, and request handling so you can focus on agent configuration.

Lifecycle

LeafMesh.from_store()                 # 1. The agency, from its store
    │
await leafmesh.start()                # 2. Initialize the platform
    │
await leafmesh.mesh_call(...)         # 3. Process requests
    │
await leafmesh.stop()                 # 4. Graceful shutdown

from_store() starts from the agency's configuration, kept and versioned in its store (named by LEAFMESH_AGENCY_NAME in .env). start() brings the platform online — connections, agent registration, event handlers, schedulers, and observability all activate automatically. stop() performs a graceful shutdown.

Request Execution Pipeline

When leafmesh.mesh_call() is called:

Session: Create or resume the session
Pre-compose: Run context, input, and others processors (if configured)
Prompt assembly: Construct structured messages with yields schema
LLM call: Send to the configured provider
Tool execution: Process any tool calls from the LLM (loop until done or max reached)
Yields parsing: Parse LLM response against the agent's yields schema
Condition evaluation: Evaluate can_call rules against parsed yields
Intelligence function: Run the auto-discovered intelligence function (if registered)
Mesh routing: Execute downstream agent calls (if conditions match)
Storage: Persist yields, mesh calls, and conversation automatically

Public API

LeafMesh exposes a focused public API. Everything underneath — sessions, events, routing, persistence — is managed automatically:

leafmesh = LeafMesh.from_store()
await leafmesh.start()

# Execute agent workflows
result = await leafmesh.mesh_call("entry_point", input_data={...}, session_id="...")

# Analytics
stats = Studio's Dashboard (HTTP)    # Event statistics
cache = Studio's Dashboard (HTTP)    # LLM cache metrics
agents = leafmesh.get_agent_stats()       # Per-agent metrics

# Discover mesh topology
leafmesh.discover()

await leafmesh.stop()

For runtime introspection — session data, agent listings, and the event stream — use Studio. The local server exposes GET /health for liveness checks:

curl http://localhost:18820/health

Lazy Initialization

Network connections, event subscriptions, and background workers come up during leafmesh.start().

Graceful Shutdown

leafmesh.stop() shuts down cleanly — in-flight work is allowed to drain, background tasks are stopped in a safe order, and connections are closed last. This prevents events from being dropped on shutdown.

Next Steps

Context Engineering — Context window management
Runtime Optimization — Performance tuning
Configuration — Configuration system

LeafMesh — Runtime execution environment