api reference

Every parameter, in one place.

Everything minmo exposes: classes, methods, every parameter with its default, every provider option, every error it can raise. Generated by reading the source directly — if it's not here, it's not public API.

VoiceAgent
@agent.tool
Tool
Supported type hints
minmo.testing.simulate
minmo.server.create_tool_server
Providers
Errors
CLI
Environment variables

VoiceAgent

from minmo import VoiceAgent — the only class you construct directly.

VoiceAgent(...)

Parameter	Type	Default	Description
`prompt` required	str	—	The system prompt / instructions for the agent.
`api_key` required	str	—	Provider API key. Raises `ValueError` if empty.
`name`	str	`"minmo-agent"`	Agent/resource name sent to the provider.
`llm`	dict or None	`None`	Custom LLM config: `{"base_url", "model", "api_key"}`, all three required if given. Needed for `simulate()`; per-provider handling of this differs (see Providers). Raises `ValueError` if any key is missing.
`provider`	VoiceProvider or None	`AssemblyAIProvider()`	Which backend to deploy to. Pass `HumeProvider()`, `OpenAIRealtimeProvider()`, or `ElevenLabsProvider()` to switch.
`provider_options`	dict or None	`{}`	Provider-specific options — shape depends on `provider`, see Providers below.
`log_path`	str or None	`None`	Directory to write session logs to via `log_session()`. Without it, `log_session()` is a no-op.
`on_session_end`	callable or None	`None`	Called with the session record dict every time `log_session()` writes one.

.deploy(local=False, host_url=None) → dict

Parameter	Type	Default	Description
`local`	bool	`False`	If `True`, starts a local FastAPI tool server on a free port and tunnels it via ngrok. Only used if at least one tool is `transport="http"`.
`host_url`	str or None	`None`	Public URL of an already-running tool server, used when `local=False`. Falls back to the `MINMO_HOST_URL` env var. Raises `MinmoDeployError` if neither is set and an http tool is registered.

Also writes a JSON snapshot of the prompt + tool schemas to .minmo/history/<timestamp>.json on every call, before deploying. Sets self.agent_id from the returned record's "id".

.mint_token() → str

Mints a short-lived client/session token via the active provider. Raises MinmoDeployError if called before a successful deploy().

.log_session(session_id, transcript, tool_calls) → dict or None

Parameter	Type	Description
`session_id`	str	Used as the log filename: `<log_path>/<session_id>.json`.
`transcript`	list	Whatever you want recorded — stored as-is.
`tool_calls`	list	Whatever you want recorded — stored as-is.

Returns None if log_path wasn't set on the agent. Otherwise writes {"session_id", "transcript", "tool_calls", "ended_at"} and calls on_session_end(record) if configured.

@agent.tool

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

Parameter	Type	Default	Description
`transport`	`"http"` \| `"client"`	`"http"`	`"http"`: minmo hosts the function behind a URL the provider calls. `"client"`: no server, no tunnel — your own live-session code answers `tool.call`. Raises `MinmoSchemaError` for any other value.

Works both as @agent.tool and @agent.tool(transport="client"). Every registered function must have:

a docstring (its first line becomes the tool's description) — missing one raises MinmoSchemaError,
a type hint on every parameter — missing one raises MinmoSchemaError,
only supported type hints.

Tool

minmo.agent.Tool — the internal record created by @agent.tool, exposed as-is to providers and stored in agent.tools (a dict[str, Tool] keyed by function name).

Field	Type	Description
`name`	str	The function's `__name__`.
`description`	str	First line of the docstring.
`parameters`	dict	JSON Schema object built from the function's type hints.
`func`	callable	The original Python function.
`transport`	str	`"http"` or `"client"`.

Supported type hints

What @agent.tool can turn into JSON Schema, from minmo/schema.py:

Python hint	JSON Schema	Required?
`str`	`{"type": "string"}`	yes
`int`	`{"type": "integer"}`	yes
`float`	`{"type": "number"}`	yes
`bool`	`{"type": "boolean"}`	yes
`list[str]`	`{"type": "array", "items": {"type": "string"}}`	yes
`Optional[T]` (T from above)	same as T	no

Any other hint (e.g. list[int], a custom class, an untyped param, a multi-type Union) raises MinmoSchemaError at registration time.

minmo.testing.simulate

simulate(agent, transcript) → dict

Parameter	Type	Description
`agent`	VoiceAgent	Must have been constructed with `llm={...}` — raises `MinmoError` otherwise.
`transcript`	list[str]	User utterances, sent one at a time as chat turns.

Returns {"conversation": [...], "tool_calls": [{"name", "input", "output"}, ...]}. Calls agent.llm's OpenAI-compatible endpoint directly and executes matched tools locally — no live session with any provider.

minmo.server.create_tool_server

create_tool_server(tools) → FastAPI

Builds a FastAPI app with one POST /tools/<name> route per transport="http" tool (client-side tools are skipped). Each route validates the request body against the tool's JSON Schema, calls the function, and returns {"result": ...} or {"error": str(exc)} on failure. Used internally by deploy(local=True); reusable if you want to host it yourself (see the Cookbook's production deploy recipe).

Providers

AssemblyAIProvider (default)

provider_options key	Default	Notes
`voice_id`	`"alba"`	Passed as `{"voice_id": ...}`.

deploy() creates a persistent agent record at POST /v1/agents; mint_token() requests a client token good for 60 seconds (AssemblyAI allows 1–600, docs recommend 60–300).
401 from AssemblyAI → MinmoAuthError. Any other 4xx/5xx → MinmoDeployError.
Accepts both transport="http" and transport="client" tools.

HumeProvider

provider_options key	Required?	Default	Notes
`secret_key`	required	—	Hume issues this separately from `api_key`; needed for both `deploy()` and `mint_token()`. Missing → `MinmoDeployError`.
`voice`	optional	`{"name": "Ava Song", "provider": "HUME_AI"}`	EVI3 configs require a voice.

Only transport="client" tools are supported — any http tool raises MinmoDeployError at validate_tools(), before any network call.
Prompts, tools, and configs are name-unique versioned resources: redeploying with the same names adds a new version instead of creating a duplicate (409 avoided automatically).
If llm is set, only llm["model"] is used (as language_model.model_resource); base_url/api_key are ignored and a warning is returned in result["warnings"].
mint_token() does OAuth client-credentials with (api_key, secret_key) and requires a prior deploy() call on the same instance.

OpenAIRealtimeProvider

provider_options key	Required?	Default	Notes
`model`	required	none	No fallback — you must pick a realtime model. Missing → `MinmoDeployError`.
`voice`	required	none	No fallback. Missing → `MinmoDeployError`.

Only transport="client" tools are supported.
deploy() makes no network call — it stores the session config in memory on the provider instance, keyed by a locally generated id. That id is not a server-side resource: it isn't valid across processes or a different provider instance.
llm is ignored entirely (with a warning) — provider_options["model"] is the LLM.
mint_token() is the only real network call: POST /v1/realtime/client_secrets, sending the stored config and returning an ephemeral client token.

ElevenLabsProvider

provider_options key	Default	Notes
`llm`	`"gemini-2.5-flash"`	Model name string from ElevenLabs' own supported model list — not a `{base_url, model, api_key}` config.
`voice_id`	`"21m00Tcm4TlvDq8ikWAM"`	ElevenLabs' "Rachel" voice.

deploy() creates a persistent agent record at POST /v1/convai/agents/create; mint_token() calls GET /v1/convai/conversation/get-signed-url and returns a signed WebSocket URL.
401 from ElevenLabs → MinmoAuthError. Any other 4xx/5xx → MinmoDeployError.
Accepts both transport="http" tools (sent as type: "webhook", using tool_url() exactly like AssemblyAI) and transport="client" tools (sent as type: "client").
If llm is set, it's ignored entirely (with a warning) — provider_options["llm"] is the model.

Errors

from minmo import MinmoError, MinmoSchemaError, MinmoDeployError, MinmoAuthError

Exception	Raised when
`MinmoError`	Base class for all of the below. Also raised directly by `simulate()` when `agent.llm` isn't configured.
`MinmoSchemaError`	A `@agent.tool` function can't become a JSON-Schema tool (missing docstring, missing/unsupported type hint), or an invalid `transport` value.
`MinmoDeployError`	Deploy-time failures: missing config (`host_url`, provider-required options), a provider rejecting an unsupported tool, or a non-401 error response from the provider's API.
`MinmoAuthError`	A provider's API returns 401 — bad or missing API key/secret.

Plain ValueError is raised directly by VoiceAgent() for an empty api_key or an incomplete llm dict — before any provider is involved.

CLI

Command	Options	What it does
`minmo init`	—	Writes `main.py`, `.env.example`, `requirements.txt` into the current directory.
`minmo deploy`	`--local` / `--remote` (default: `--local`)	Imports `main.py`, finds the `VoiceAgent` instance, calls `.deploy(local=...)`, prints the resulting record as JSON.
`minmo logs`	—	Prints the most recently modified file in the agent's `log_path`. Errors if `main.py` is missing, has no `VoiceAgent`, has no `log_path`, or the log directory is empty.

Environment variables

Variable	Used by	Purpose
`MINMO_HOST_URL`	`deploy(local=False)`	Fallback for `host_url` when not passed explicitly.
`NGROK_AUTHTOKEN`	`deploy(local=True)`	Required by pyngrok to open a tunnel for the local tool server.
`ASSEMBLYAI_API_KEY`	your own `main.py`	Not read by minmo itself — just the variable name `minmo init` scaffolds into `.env.example` as a convention.