minmo · reference

VoiceAgent

The core class. One instance holds a prompt, a provider, and the tools registered on it.

VoiceAgent(prompt, api_key, name="minmo-agent", llm=None, provider=None, provider_options=None, log_path=None, on_session_end=None)

prompt: str, required. The agent's system prompt.
api_key: str, required. Must be non-empty, or it raises ValueError.
name: str, default "minmo-agent". Sent to the provider as the agent's name.
llm: dict, optional. {"base_url", "model", "api_key"}, all three required if given (ValueError if any is missing). Needed for simulate(). ElevenLabs ignores it entirely (it picks a model by name via provider_options["llm"] instead); Hume reads only llm.model, ignoring base_url/api_key.
provider: optional. A VoiceProvider instance, defaulting to AssemblyAIProvider().
provider_options: dict, optional. Passed through to the provider as-is; see Providers for what each one reads.
log_path: str, optional. Directory log_session() writes JSON session logs into.
on_session_end: callable, optional. Called with the log record right after log_session() writes it.

@agent.tool

Registers a Python function as a tool. Works bare (@agent.tool) or called with a transport (@agent.tool(transport="client")).

agent.tool(func=None, *, transport="http")

transport: "http" (default): minmo hosts the function behind a URL the provider calls. "client": no server; the caller's own live session handles the call.

The tool's JSON-Schema is inferred from the function:

The docstring is required: its first line becomes the tool's description. Missing docstring raises MinmoSchemaError.
Every parameter needs a type hint, one of str, int, float, bool, list[str], or Optional[...] of those. A missing or unsupported hint raises MinmoSchemaError.
Optional[T] makes the parameter non-required in the generated schema; everything else is required.

deploy() · mint_token() · log_session()

agent.deploy(local=False, host_url=None) -> dict

local: bool, default False. If any registered tool uses transport="http": True starts a local tool server and tunnels it publicly via ngrok; False requires host_url or the MINMO_HOST_URL env var, or raises MinmoDeployError.
host_url: str, optional. Your already-deployed tool server's public URL, used when local=False.

Validates tools against the provider first, snapshots the prompt and tool schemas to .minmo/history/, then calls the provider's deploy(). Returns the provider's raw record, always including an "info" string explaining what just happened and how to connect.

agent.mint_token() -> str

Requires a prior successful deploy(), or it raises MinmoDeployError. Delegates to the provider; what the returned string actually is differs per provider (client token, signed WebSocket URL, OAuth access token, client secret; see Providers).

agent.log_session(session_id, transcript, tool_calls) -> dict | None

No-op, returns None, if log_path wasn't set on the agent. Otherwise writes a JSON record to {log_path}/{session_id}.json and calls on_session_end(record) if configured.

Errors

Error	Raised when
`MinmoError`	Base class for every minmo exception.
`MinmoSchemaError`	A `@agent.tool` function can't be turned into a JSON-Schema tool (missing docstring, missing or unsupported type hint, invalid transport).
`MinmoDeployError`	Deploying fails: missing required config, a provider rejecting an unsupported tool set, or the provider's API returning an error.
`MinmoAuthError`	The provider's API key (or Hume's secret key) is missing, empty, or rejected (HTTP 401).

Providers

Pass a different provider via VoiceAgent(provider=..., provider_options=...). Each provider's required provider_options are documented in its own module under minmo/providers/.

Provider	Hosted?	Tool transports	provider_options	mint_token() returns
`AssemblyAIProvider` (default)	Yes, persistent agent record	http, client	`voice_id` (optional, default `"alba"`)	A short-lived client token
`ElevenLabsProvider`	Yes, persistent agent record	http (webhook), client	`voice_id`, `llm` (both optional, default Rachel / `gemini-2.5-flash`)	A signed WebSocket URL
`HumeProvider`	Yes, versioned config resource	client only	`secret_key` (required), `voice` (optional)	An OAuth access token

CLI

minmo init

Scaffolds main.py, .env.example, and requirements.txt in the current directory.

minmo deploy [--local | --remote]

Imports main.py, finds the first VoiceAgent instance defined in it, and calls .deploy(); --local is the default. Prints the returned record as JSON.

minmo logs

Imports main.py's VoiceAgent and prints its most recent session log from agent.log_path. Requires log_path to be set and at least one logged session.

minmo.testing.simulate

simulate(agent, transcript: list[str]) -> dict

Requires agent.llm to be set, or it raises MinmoError; there's no way to call a provider's managed model directly outside a live voice session. Calls that llm (any OpenAI-compatible endpoint) directly with each line of transcript as a user message, running tool calls against your local Python functions in a loop until the model stops calling tools. Returns {"conversation": [...], "tool_calls": [...]}.

minmo.server.create_tool_server

create_tool_server(tools: dict[str, Tool]) -> FastAPI

Builds a FastAPI app with one POST /tools/{name} route per transport="http" tool. Each route validates its JSON body against the tool's parameter schema, calls the tool function, and returns {"result": ...} or {"error": str(exc)}. This is exactly what deploy(local=True) runs for you locally, and it's reusable directly if you want to host it yourself behind a real domain instead.

← Back to the cookbook

Every signature, one place.