mhl-agents

mhl agents

Assumes the mhl-language skill. An agent is a one-shot call: a CLI subprocess (cli/*) or an Ollama request (ollama/*) that takes a prompt and returns a string. It cannot call a tool mid-generation on mhl's behalf. So the program does the deterministic work around the model: it fetches the data, builds the prompt, and validates the answer.

Declaring an agent

The runtime reads exactly: engine, command, args, stdin, endpoint, temperature, log, trace, retry, cache, rate_limit, fallback, skills, system_prompt, before, after, description. Anything else is a lint error, including timeout (use a step's timeout clause) and api_key (let the CLI read its own environment).

agent Claude {
    engine: "cli/claude-code"
    command: env("MODEL_CMD", "claude")     // swappable per environment
    args: ["-p", "${prompt}", "--output-format", "text"]

    retry: {
        max_attempts: 3
        delay: 2s
        retry_on: [500, 503, "timeout", "rate_limit"]
    }
    cache: { ttl: 10m, storage: "disk" }
    rate_limit: { requests_per_minute: 20, concurrency: 2 }
}

agent Local {
    engine: "ollama/qwen2.5-coder"
    endpoint: "http://localhost:11434"
    temperature: 0.1
    fallback: [Claude]
}

Placeholders. "${prompt}" and "${schema}" are recognized only as a whole args: element. "pre ${prompt}" is a lint error. Without either placeholder, the prompt is appended as the last argument. An args: element may also be an expression (env("FLAG", "x")).

Large prompts go through stdin: instead of args:, where placeholders are substituted anywhere in the string. Whole documents in argv hit the ~32 KB command-line limit on Windows. Some CLIs treat piped text that reads like an instruction as prompt injection, so keep stdin content phrased as data and the instruction in args:.

agent Summarizer {
    command: "sh"
    args: ["-c", "cat"]              // stands in for: claude -p "Summarize stdin"
    stdin: "${prompt}"
}

test summarizer {
    describe prompt_arrives_on_stdin {
        are_equal(Summarizer.run(prompt: "a long document"), "a long document")
    }
}