Agent Classes

API reference for the agent types in LeafMesh.

LLM Agent

The default agent type. Sends requests to an LLM provider and produces structured output.

Configuration

agents:
  my_agent:
    name: "my_agent"                    # Required
    model: "gpt-4o"                     # LLM model
    prompt: "Your instructions here"    # Required for LLM agents
    temperature: 0.1                    # Default: 0.1
    max_tokens: 2000                    # Max response tokens
    yields:                             # Expected output schema
      field: "type"
    can_call:                           # Routing rules
      - agent: "target"
        condition: "field == 'value'"
        call_immediately: false
    tools: ["calculator"]               # Granted tools
    tool_choice: "auto"                 # auto | required | none
    max_tool_calls_per_message: 5        # Default: 5, range 0-20
    communication_type: "dual"          # dual | chain | execute
    optimization_strategy: "performance" # Adaptive executor strategy

Execution Pipeline

Pre-compose → Prompt assembly → LLM Call → Tool Loop → Yields Parse → Conditions → Intelligence → Mesh

Programmatic Agent

Pure Python execution without LLM calls. Set agent_type: "programmatic".

Configuration

agents:
  validator:
    name: "validator"
    agent_type: "programmatic"
    yields:
      is_valid: "boolean"
      errors: "string"
    can_call:
      - agent: "next_step"
        condition: "is_valid == true"

Implementation

async def validator(llm_response, input_data, context):
    # input_data contains upstream yields
    # Perform pure Python validation
    errors = []
    if not input_data.get("email"):
        errors.append("Email required")
    return {
        "is_valid": len(errors) == 0,
        "errors": ", ".join(errors) if errors else "none"
    }

Human Agent

Routes execution to a human reviewer. Set agent_type: "human".

Configuration

agents:
  reviewer:
    name: "reviewer"
    agent_type: "human"
    timeout: 300                        # Seconds (default: 300)
    webhook_config:
      connection: "review-webhook"   # Outbound webhook record (Infrastructure → Add custom)
    yields:
      approved: "boolean"
      notes: "string"
    can_call:
      - agent: "executor"
        condition: "approved == true"

Custom Handler

# Alternative to webhook: custom Python handler
async def custom_handler(context, session_id, timeout):
    # Implement custom review logic
    # (Slack, email, in-app, etc.)
    return {"approved": True, "notes": "Looks good"}

Human-in-the-Loop Events

These events are emitted automatically and visible in Studio's Activity tab:

Event	When
`human.input.requested`	Webhook/handler invoked
`human.input.received`	Human responds
`human.input.timeout`	Timeout exceeded
`workflow.paused`	Workflow paused for human input
`workflow.resumed`	Workflow resumed after human responds

Scheduled Agent

Any agent with wake_up becomes scheduled. Uses APScheduler.

Configuration

agents:
  monitor:
    name: "monitor"
    wake_up: "0 9 * * *"              # Cron: daily at 9 AM
    # wake_up: "30s"                  # Interval (s/m/h/d)
    # wake_up: "@hourly"              # Keyword (leading @ required)

Schedule Formats

Format	Example	Description
Cron	`"0 9 * * *"`	Five-field cron expression
Interval	`"5m"`	Number + unit: `s`, `m`, `h`, `d`
Keyword	`"@daily"`	Predefined schedules (leading `@`)

Keywords: "@daily" (midnight), "@hourly" (top of hour), "@weekly" (Sunday midnight), "@monthly" (first of the month). The leading @ is required.

Runtime Management

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": {"monitor": {"wake_up": "5m"}}}   # null to stop it waking

External Agent

Integrates with external frameworks (LangChain, CrewAI, etc.). Set agent_type: "external".

Configuration

agents:
  external_agent:
    name: "external_agent"
    agent_type: "external"
    framework: "langchain"
    connector_config:
      connection: "my-connector"   # Infrastructure → External agents: holds the address and credentials
    yields:
      result: "string"
      status: "string"
    can_call:
      - agent: "processor"
        condition: "status == 'success'"

External agents delegate execution to an outside system while still participating in the mesh with yields, can_call, and condition evaluation.

Listing Agents

List registered agents from Python:

agents = leafmesh.list_agents()

Or browse them in Studio's Agents tab.

Next Steps

LeafMesh Class — LeafMesh class reference
Configuration API — Full config reference
Agent Development — Building agents

LeafMesh — Agent class reference