Agent Studio

Agent Studio refers to the development environment and tools for building, testing, and iterating on LeafMesh agent configurations.

Development Setup

Project Structure

my_project/
├── .env                      # Agency name, store, keys (the configuration lives in the store)
├── app.py                  # Application entry point
├── intelligence/           # Intelligence functions
│   ├── __init__.py
│   ├── triage.py
│   └── specialist.py
├── tools/                  # Custom tools
│   ├── __init__.py
│   └── database.py
├── processors/             # Pre-compose processors
│   ├── __init__.py
│   └── context.py
└── tests/                  # Test files
    ├── test_agents.py
    └── test_tools.py

Minimal Entry Point

import asyncio
from leafmesh import LeafMesh

leafmesh = LeafMesh.from_store()

# Register intelligence functions
from intelligence.triage import triage_handler
from intelligence.specialist import specialist_handler

# Register custom tools
from tools.database import register_tools
register_tools()

async def main():
    await leafmesh.start()

    result = await leafmesh.mesh_call(
        "triage_agent",
        input_data={"user_message": "Test request"},
        session_id="dev_session"
    )
    print(result)
    await leafmesh.stop()

asyncio.run(main())

Playground Service

LeafMesh includes an interactive playground for testing:

from leafmesh import LeafMesh

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

# The playground_service provides endpoints for:
# - Testing agent configurations
# - Validating can_call chains
# - Testing pre-compose pipelines
# - Experimenting with different inputs

Access via the API server (default port: 18820).

What the Playground can tune

The Playground edits and runs everything that changes a single agent's behavior — and every edit genuinely applies to the run (overrides merge into the agent's config for that execution):

model, prompt, temperature, tokens, context parts, reasoning/thinking (thinking's tools are text only — code runs in the sandbox), prompt caching
tools, tool choice, per-turn tool-call limits, parallel tool calls, strict schemas
memory, knowledge, skills (with per-skill eager/lazy delivery)
super-agent — enable plus the full tuning surface (budgets, step/synthesis caps, concurrency)
playbook — edit intent responsibilities and re-run in seconds
self-scheduling toggle and output modality

Declared-block tools (playbook, MCP, Zapier / Composio / n8n) register at execute time, so ad-hoc agents and edited blocks work in the Playground before anything is committed to YAML. What the Playground deliberately does not touch: identity, mesh wiring (can_call, wait_for, listen events, schedules) and monthly budgets — those are Studio's job, because the Playground tests one agent, never the mesh around it, and a test surface must not bypass spend caps.

A person's seat (a human agent) can be tried too: from 2.4.508, plain text you type is taken as the message.

A Playground run also stays out of the mesh's records: it never touches the shared board (no board tools, no ticket taken or recorded), the Manager never grades it, and it cannot widen an agent's sandbox limits.

Studio config editors

Studio edits the agency's configuration, which lives in its store, with structured forms — no raw JSON: the Manager's analysis fields and yields, escalation targets as typed cards (human agent / webhook / channel), coordination rules, mesh chain limits, and the per-agent tool picker that offers exactly what an agent may be given (config-activated, block-configured and system tools are filtered out). The store itself is set only in .env; Infrastructure → Datastores shows whether it is reachable, its latency, the server, the settings in force and which .env names set them — never the address or password. Credentials and addresses are records on the Infrastructure page, named in the configuration with connection: <name>.

Tools, tool blocks, the playbook, follow-ups, image output, eager skills and the sandbox are offered on LLM agents only. The agent settings that guard what an agent may do are grouped in Studio's Safety section (called Governance in earlier versions); the config keys are unchanged.

Saving writes only what you set. A map field you clear is saved empty, and a mesh setting you clear returns to its default; values the SDK works out for itself are not written into the configuration. A new agent keeps its name when saved, and a renamed or retyped agent is saved as it is running, without settings its new type cannot use.

Studio builds its forms from the contract the mesh publishes at GET /api/schema/contract — every field with its real type, default and choices — so the forms match the SDK you run.

YAML Configuration Iteration

Every Studio save is a new version of the agency's configuration. Studio's versions page lists each save with a diff, and make default restores one. A saved change applies live on every pod within about 15 seconds; settings that still need a reload make the agency reload itself in place, and only evolution_api's host, port and enabled need a process restart.

The yaml_service also offers validation and loading over HTTP:

# Validate a new configuration without deploying
# POST /yaml/validate with YAML body

# Load a new configuration at runtime
# POST /yaml/load with YAML body

This allows iterating on agent prompts, yields schemas, and routing rules without restarting the system.

Auto-Discovery

For larger projects, use auto-discovery to automatically register intelligence functions:

leafmesh = LeafMesh.from_store()

# Auto-discover intelligence functions whose names match YAML agent names
# in the specified module path
leafmesh.discover("intelligence")

Interactive Testing

Test individual agents interactively:

async def test_agent():
    await leafmesh.start()

    # Test with different inputs
    test_cases = [
        {"user_message": "Simple question"},
        {"user_message": "Complex technical issue with database"},
        {"user_message": "Billing dispute for $5000"},
    ]

    for case in test_cases:
        result = await leafmesh.mesh_call(
            "triage_agent",
            input_data=case,
            session_id=f"test_{hash(str(case))}"
        )
        print(f"Input: {case['user_message'][:50]}")
        print(f"Output: {result}")
        print("---")

    await leafmesh.stop()

Connect the Hosted Studio to a Locally-Running Mesh

You can drive a mesh running on your own machine from the hosted Studio console — no deployment required. Run your mesh locally (the API server listens on 127.0.0.1), then authorize your Studio origin so the browser is allowed to call your local API:

api:
  cors_origins:
    - "https://platform.leafcraft.ai"   # your hosted Studio origin

cors_origins is appended to the SDK's built-in allowlist, so this just adds your Studio origin. With it set, start your mesh locally and the hosted console can connect to it and drive sessions, inspect activity, and iterate on config against your live local process. This is ideal for developing against real data on your machine while using the full hosted UI.

Next Steps

Testing Framework — Automated testing
Debugging Tools — Debugging techniques
Agent Chat UI — Interactive chat interface

LeafMesh — Development environment for agent building