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="client")

transport: "client" (the only supported transport): 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() -> dict

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	client	`voice_id` (optional, default `"alba"`)	A short-lived client token
`ElevenLabsProvider`	Yes, persistent agent record	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

Imports main.py, finds the first VoiceAgent instance defined in it, calls .deploy(), and 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": [...]}.

← Back to the cookbook

Every signature, one place.