The LeafMesh ADK

LeafMesh Class

The LeafMesh class is the entry point for all LeafMesh operations. It loads the agency's configuration, initializes components, and provides methods for processing requests, calling agents, and managing the system lifecycle.

Quick Start

from leafmesh import LeafMesh # Start the agency named by LEAFMESH_AGENCY_NAME from the store set in .env leafmesh = LeafMesh.from_store() # Optionally add business logic (function name = agent name) async def solver(llm_response, input_data, context): return llm_response # Start, process, stop await leafmesh.start() result = await leafmesh.mesh_call( "solver", input_data={"problem": "What is 2 + 3?"}, session_id="demo" ) await leafmesh.stop()

Construction

From 2.4.481 new projects start with LeafMesh.from_store(). The agency's configuration lives in its store; from_store() starts the agency named by LEAFMESH_AGENCY_NAME from the store set in .env. An existing config.yaml is imported into the store once, then not read (the boot log says so).

# From the agency's store (recommended) leafmesh = LeafMesh.from_store() # From a YAML file leafmesh = LeafMesh.from_yaml("config.yaml") # From Python dictionary leafmesh = LeafMesh.from_dict({ "name": "my_swarm", "architecture": "managed_mesh", "agents": { "solver": { "name": "solver", "model": "gpt-4o-mini", "prompt": "You solve math problems.", "yields": {"answer": "number"} } } })

Both methods validate the configuration before returning.

Lifecycle

await leafmesh.start() # Initialize the platform and register agents # ... process requests ... await leafmesh.stop() # Shut down cleanly, completing in-flight requests

start() brings the platform online — connections, agent registration, scheduling. stop() shuts it down cleanly, completing in-flight requests before closing connections.

Core Methods

mesh_call()

The primary entry point. Sends data through the full agent pipeline.

result = await leafmesh.mesh_call( "triage", # Target agent or entry point input_data={"message": "..."}, # Data passed to the agent session_id="user_123" # Session for state continuity )

The pipeline: load session → pre-compose → prompt assembly → LLM call → yields parsing → intelligence function → auto-store → can_call evaluation → downstream agents.

mesh_call() — Agent-to-Agent

Direct agent-to-agent communication from within intelligence functions.

async def coordinator(llm_response, input_data, context): result = await leafmesh.mesh_call( from_agent="coordinator", to_agent="verifier", data={"claim": llm_response.get("claim")}, session_id=context.get("session_id", "default") ) return {"verified": result.get("is_valid", False)}

Intelligence Functions

Register a Python function to enhance or replace an agent's LLM response. The function name must match the agent name in YAML:

async def checker(llm_response, input_data, context): # llm_response: parsed LLM output (empty dict for programmatic agents) # input_data: data from the caller or upstream agent # context: {"session_id": "...", "agent_name": "..."} return {"is_correct": True, "explanation": "Verified."}

State & Events

State (sessions, yields, mesh communications) is managed automatically. Browse it through Studio's Sessions and Activity tabs.

Scheduling

Schedule agents for periodic execution, or manage schedules at runtime:

# In YAML agents: collector: name: "collector" wake_up: "*/5 * * * *" # Every 5 minutes

Schedules are declared on the agent. To change one, patch its wake_up through the config API or Agent Studio — the schedule is rebuilt in place:

PATCH /api/yaml/config {"agents": {"collector": {"wake_up": "1m"}}} # null to stop it waking

Auto-Discovery

Find and register intelligence functions from files:

count = leafmesh.discover("./agency/", "*_agent.py") # Imports each matching file and registers functions by name

Analytics

# Aggregated usage statistics analytics = await Studio's Dashboard (HTTP) # LLM cache performance cache_stats = await Studio's Dashboard (HTTP) # Swarm status status = leafmesh.get_status() # Agent list agents = leafmesh.list_agents()

Error Handling

from leafmesh import LeafMeshError, ConfigError, AgentError try: leafmesh = LeafMesh.from_store() await leafmesh.start() result = await leafmesh.mesh_call( "solver", input_data={"message": "Hello"}, session_id="s1" ) except ConfigError as e: print(f"Bad configuration: {e}") except AgentError as e: print(f"Agent error: {e}") except LeafMeshError as e: print(f"LeafMesh error: {e}") finally: await leafmesh.stop()

Next Steps


LeafMesh — One class, full orchestration

Last updated: 11/21/2026