minmo

Boilerplate-free SDK for building voice agents, with a single API across AssemblyAI (default), Hume, and ElevenLabs.

Define a prompt, register Python functions as tools, deploy. minmo handles JSON-Schema generation and each provider's REST API, so you can configure a voice agent without translating provider-specific payloads.

• One decorator, real tools — @agent.tool turns a typed Python function into a JSON-Schema tool, inferred from its signature and docstring.
• Client tools — deployed tool schemas run through your live client session.
• Provider-agnostic — swap AssemblyAI, Hume, or ElevenLabs by changing one argument; minmo normalizes what each API needs.
• Test without burning session minutes — simulate() runs your tools against any OpenAI-compatible LLM, no live voice session required.

Install

pip install minmo

(Contributing or want an editable checkout instead? pip install -e ".[dev]" after cloning.)

Quickstart

from minmo import VoiceAgent

agent = VoiceAgent(
    prompt="You are a friendly voice assistant. Keep answers short.",
    api_key="YOUR_ASSEMBLYAI_API_KEY",
)


@agent.tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"It's sunny in {city}."


result = agent.deploy()
print(result)  # the created AssemblyAI agent record, including its id

deploy() registers get_weather as a client tool. Your live session handles its calls and returns results to the provider.

result always includes an "info" field — a plain-language paragraph telling you whether the agent is hosted on the provider's servers or only exists locally, and how to actually connect to it (usually via mint_token()). Worth printing after every deploy, especially since this differs per provider — see below.

Testing tool logic without burning session minutes

from minmo import VoiceAgent
from minmo.testing import simulate

agent = VoiceAgent(
    prompt="You are a friendly voice assistant.",
    api_key="YOUR_ASSEMBLYAI_API_KEY",
    llm={"base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key": "YOUR_OPENAI_KEY"},
)


@agent.tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"It's sunny in {city}."


result = simulate(agent, transcript=["What's the weather in Paris?"])
print(result["tool_calls"])

simulate() calls the llm you configured directly (any OpenAI-compatible endpoint) and runs tool calls against your local Python functions — no AssemblyAI session, no phone call.

Client-side tools

@agent.tool defaults to transport="client", declaring a client-side/function tool.

@agent.tool(transport="client")
def get_account_balance(account_id: str) -> str:
    """Look up an account's balance."""
    return "$42.00"

minmo only builds the correct agent config for this — declaring the tool as client-side. Running the actual session (the WebSocket connection that receives tool.call and sends back tool.result) is your own code's job: a browser app, a Twilio bridge, whatever already holds that live connection. minmo deploys client-tool schemas only. It does not host Python callbacks or run a tool-call server.

Providers

minmo supports AssemblyAI (default), Hume, and ElevenLabs. They don't all host your agent the same way:

Pass a different provider via VoiceAgent(provider=..., provider_options=...); see each provider's docstring in minmo/providers/ for required options.

CLI

minmo init     # scaffold main.py, .env.example, requirements.txt
minmo deploy   # import main.py, find the VoiceAgent, deploy it
minmo logs     # print the most recent session log

Development

pip install -e ".[dev]"
pytest -q

Pushes are auto-formatted with Black via GitHub Actions, and every push/PR runs the test suite across Python 3.10–3.12.

scripts/smoke_test.py is a live smoke test — it calls deploy() and mint_token() against real provider APIs (reading credentials from a gitignored .env) and skips any provider whose env vars aren't set. It makes real network calls, so it's run manually, not in CI:

python scripts/smoke_test.py

Contributing

Issues and PRs welcome. Keep changes small and covered by a test.

License

MIT © Anas Abuelhaag