pip install minion-ai
Build agents you can
actually see inside
Minion is a small Python framework for agents that think, call tools, and delegate to sub-agents. Turn on tracing and every run, turn, tool call, token and dollar lands in a local dashboard you own.
pip install minion-ai - 1 Let me see what is in the reports directory…
list_files4ms
- 2 Twelve files — I will split these across sub-agents.
_spawn_sub_minion1,204ms_spawn_sub_minion1,180ms_spawn_sub_minion1,246ms
- 3 I have every summary; let me write the final answer.
_finish0ms
An agent is a function and a few tools
Pass plain Python functions. Minion reads the signature and the docstring to build the tool schema, so the thing the model sees and the thing that runs can never drift apart.
Read the quickstart →import minions
def get_weather(city: str) -> str:
"""Get the current weather for a city.
Args:
city: Name of the city.
"""
return f"{city}: 22°C, clear"
minions.init(tracing=True, project="demo")
agent = minions.Minion(
model="openai/gpt-4o",
tools=[get_weather],
)
print(agent("Should I take a jacket in Oslo today?"))Delegate without losing the thread
Give a minion allow_sub_agents=True and it splits
large jobs across generic workers — optionally on a cheaper
secondary_model. Or hand it named specialists and it
routes to them by name. Sub-agent traces nest under the parent
run, so the tree stays readable.
researcher = minions.Minion(
model="openai/gpt-4o",
tools=[search_web],
name="researcher",
description="Finds and summarises sources on a topic.",
)
lead = minions.Minion(
model="openai/gpt-4o",
tools=[write_file],
sub_minions=[researcher],
parallel_tools=True,
)Observability that costs one line
tracing=True writes to SQLite in your home directory.
Tag runs with metadata and filter on it later. Tracing never
raises — if the trace store is unreachable, the push is skipped
and your agent keeps running.
minions.init(
tracing=True,
project="support-bot",
)
agent(
"Refund order 8812",
metadata={"ticket_id": "T-4471", "tier": "pro"},
)What you get
Tools are just functions
A docstring and type hints are the schema. No decorators, no registry, no JSON to hand-write.
Sub-agents that stay cheap
Delegate big jobs to generic workers on a smaller model, or to named specialists you compose yourself.
Parallel tool calls
Run a turn's independent calls concurrently. Each one is timed on its own, so latency stays honest.
Traces, locally, by default
One flag records every run, turn and tool call to SQLite. No account, no vendor, no egress.
Know what it cost
Per-turn and per-run cost from a built-in price table for 145 models, plus your own per-project overrides.
A dashboard you run
`minion serve` — filter, drill into any turn, and roll spend up by day or by model.
Honest about models
Minion asks the model for a strict JSON envelope every turn, so it works with any model whose provider supports native JSON-schema structured output — and not with the ones that don't. Three tiers, stated plainly:
OpenAI, Anthropic, Gemini. Developed against and tested before every release.
Any other LiteLLM model with native schema output — Groq's gpt-oss-120b, Azure, vLLM.
Models without schema output. They fail on turn one; it isn't a degraded mode.
Start with one file
pip install minion-ai