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 byLEAFMESH_AGENCY_NAMEfrom the store set in.env. An existingconfig.yamlis 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 requestsstart() 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 minutesSchedules 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 wakingAuto-Discovery
Find and register intelligence functions from files:
count = leafmesh.discover("./agency/", "*_agent.py")
# Imports each matching file and registers functions by nameAnalytics
# 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
- Core API Reference — Full method signatures and parameter details
- Architecture — Control plane internals
- Agent Types — LLM, programmatic, human, external agents
- Quick Start — Build your first system in 5 minutes
LeafMesh — One class, full orchestration