mashpy 0.5.3

SDK for building hosted multi-agent Mash applications.

Mash

A Python SDK and host runtime for building self-hosted multi-agent applications.

Mash gives you a Python AgentSpec contract for defining agents, a HostBuilder for composing them into a multi-agent host, a FastAPI server for deployment, and a CLI/REPL for interacting with a running host.

Install

pip install mashpy

Requires Python >= 3.10. Set your LLM provider key:

export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY or GEMINI_API_KEY

What Mash Provides

• Multi-agent composition — define a primary agent, add specialized subagents, and compose workflows behind a single host. Agents delegate to each other without a separate coordination layer.
• Durable harness — requests execute through a durable engine and are recorded as replayable runtime events. Retries, restarts, and long-running work just work.
• Human-in-the-loop — agents can pause for approval or ask users questions mid-execution. Interactions survive host restarts.
• Workflows — ordered task sequences with structured output, defined in code or published dynamically at runtime.
• Observability — span trees, trace analysis, telemetry API, built-in dashboard, and CLI trace inspection. No external APM needed.
• Self-hosted interfaces — HTTP API with streaming, CLI, and interactive REPL. Deploy locally, in Docker, or on any cloud.

                  ┌─────────────────────────────────────────┐
                  │          Durable Request                │
                  │                                         │
                  │   ┌─ context ─── memory ──┐             │
                  │   │                       │             │
request ────────► │   │     Agent Loop        │ ──► signals │
(cli/api)         │   │ think → act → observe │      │      │
                  │   │                       │      ▼      │
                  │   └─ tools ───── skills ──┘  structured │
workflow ───────► │        ▲                      output    │
(schedule/trigger)│        │ user interaction               │
                  │        ▼ (approval / ask-user)          │
                  │                                         │
                  │       resumable · replayable            │
                  └─────────────────────────────────────────┘

See Mash under the hood for a deeper look at each capability, and the product brief for the pitch.

Quick Start

1. Define an agent

# my_agent/spec.py
from mash.core.config import AgentConfig
from mash.core.llm import AnthropicProvider
from mash.runtime import AgentMetadata, AgentSpec, HostBuilder
from mash.skills import SkillRegistry
from mash.tools import ToolRegistry


class AssistantAgent(AgentSpec):
    def get_agent_id(self) -> str:
        return "assistant"

    def build_tools(self) -> ToolRegistry:
        return ToolRegistry()

    def build_skills(self) -> SkillRegistry:
        return SkillRegistry()

    def build_llm(self):
        return AnthropicProvider(app_id="assistant")

    def build_agent_config(self) -> AgentConfig:
        return AgentConfig(
            app_id="assistant",
            system_prompt="You are a helpful assistant.",
        )


def build_pool():
    return (
        HostBuilder()
        .agent(
            AssistantAgent(),
            metadata=AgentMetadata(
                display_name="Assistant",
                description="General-purpose assistant.",
                capabilities=["conversation"],
                usage_guidance="Default agent for user requests.",
            ),
        )
        .build()
    )

2. Serve it

mash host serve --host-app my_agent.spec:build_pool --port 8000

3. Connect

mash connect --api-base-url http://127.0.0.1:8000 --api-key secret --agent assistant
mash repl

Key Concepts

Concept	What it is
AgentSpec	Abstract contract defining one agent (id, tools, skills, LLM, config)
HostBuilder	Fluent builder that composes agents, workflows, and hosts into an AgentPool
AgentPool	The deployed pool of role-less agents the API server runs
Host	A composition over the pool (primary + subagents + workflows), defined in code or dynamically over the API
ToolRegistry	Register callable tools; built-ins include Bash, AskUser, InvokeSubagent
SkillRegistry	Markdown instruction bundles loaded on demand via a meta-tool
LLMProvider	Adapters for Anthropic, OpenAI, and Gemini
WorkflowSpec	Ordered task chains with structured output, orchestrated by DBOS

Example: Mash Pilot

Mash Pilot is a full example host app built on the Mash SDK. It demonstrates multi-agent composition, custom REPL commands, workflows, and deployment. Use it as a reference when building your own host.

Build with a Coding Agent

This repo includes CLAUDE.md so coding agents like Claude Code, Codex, and Cursor can scaffold a Mash-powered agent from a natural language prompt. Copy it into your project or point your agent at this repo to get started. The Pilot agent also includes a build-mash-agent skill for interactive agent scaffolding.

Documentation

• Product brief — the pitch: why the application-to-agent seam needs a standard
• Mash under the hood — what Mash offers and where it fits
• Deployment guide — Docker, cloud, horizontal scaling
• Building agent CLIs — custom CLI development
• CLAUDE.md — full SDK reference for coding agents
• Package overview — subsystem boundaries and module guides
• Contributing — development setup, tests, repo structure