Master Agents — Client
master-agents-client is the public client wheel for Master Agents, a
vendor-agnostic agent orchestration framework with a designed pipeline,
deterministic traces, and cost gating built into every model call.
pip install master-agents-client
Requires Python 3.11+.
For developers building agent pipelines
Master Agents is opinionated about three things most frameworks treat as afterthoughts:
1. Cost awareness, not just reporting
Every agent's system prompt carries a <runtime_limits> block at runtime
listing its own per-turn caps: output budget (tokens), max steps, max
total steps, and the wall-clock timeout per local-tool call. Agents read
those caps and plan within them — when a brief exceeds capacity, the
agent refuses upfront and proposes splitting it, instead of producing
truncated work that hits the cap mid-thought.
Layered on top:
estimate_tokenstool — agents can probe a path's token cost before reading. Results classify into a tier ladder (tier_1 ≤ 100k silent; tier_2 100–200k asks the user; tier_3 > 200k auto-rejected, agent must narrow scope).- Per-spec
cost_budget— opt-in YAML field on agent specs. When set, the runtime enforces hard per-step pre-call abort when cumulative spend would breach the cap. Pick the spec that matches your risk tolerance. - Byte-stable prefixes by design — agent system prompts are kept byte-identical across turns within a session, so the model layer's prefix caching maximises cache hits on repeat runs (second runs of the same pipeline cost a fraction of the first).
Show the cap. Plan within it.
2. Trace is truth
Every session emits a structured JSONL trace — every tool call, every model response, every cost event. CI can diff traces across runs to detect regressions; post-mortems use the trace as the single source of truth instead of stitching logs together from multiple places.
Don't log. Trace.
3. Agents should be auditable, not magical
The pipeline DAG (kind: graph) is declared in code and inspectable end to
end: brainstorm → architect → plan → code → review → aggregate. No hidden
subagents, no emergent topology, no "the LLM figured it out." You can
render the graph before running it.
Show the graph. Hide the magic.
What the client gives you
- A CLI (
mao-client) to drive a hosted Master Agents service from a workstation: one-shot runs, interactive chat, login/logout, detach + resume. - Tool inversion: file / git / bash / RAG operations execute on your machine under explicit path allowlists declared at login. Source files never leave the local environment — only tool output text travels to the service.
- Trace streaming over WebSocket; persistent server-side sessions that survive laptop close, network blips, and cross-machine resume.
The client itself ships no orchestration logic, no prompts, no agent specs — those live on the service. Upgrades happen server-side; the client stays a stable terminal.
First chat (60 seconds)
# 1. Save server URL + token (paste at the prompt or via --token).
mao-client remote login --server https://your-master-agents-service.example
# 2. Start an interactive session.
mao-client remote chat
# 3. Or run a one-shot prompt against a specific master agent.
mao-client remote run -m brainstormer "What should I prototype this week?"
Inside chat, /help lists all slash commands (tier selection, cost caps,
session controls, etc.).
Why not LangChain / LangGraph / CrewAI / AutoGen / OpenAI Assistants / Claude Agent SDK?
Three concrete reasons that don't depend on framework taste:
| Concern | What other frameworks give you | What Master Agents gives you |
|---|---|---|
| Cost awareness | Cost callbacks / monitoring — usage reported after the model returns | Per-turn caps visible to the agent in its system prompt (output tokens, steps, tool wall-clock). Agent plans within them and refuses upfront when a brief overshoots. Optional per-spec cost_budget adds a hard pre-call abort. |
| Reproducibility | Re-run and hope the model samples the same way | Structured JSONL trace per session — diff across runs to catch regressions; the trace is the single source of truth for post-mortems instead of stitching logs together |
| Topology | Emergent agent-to-agent conversations decided at runtime | DAG declared upfront; render the graph before running it |
Sessions, detach, resume
Sessions are first-class identities, not keepalive. Detach a long-running pipeline mid-flight, reconnect from a different machine an hour later, continue from the exact server-side state:
mao-client remote run --detach -m parallel_coder "<long-running brief>"
# ... close laptop, commute, etc.
mao-client remote chat --resume # picks up the most recent session
mao-client remote chat --pick # interactive list of detached sessions
What runs where
| Where it runs | |
|---|---|
| Chat REPL, slash commands | Your machine (this client) |
| File reads / writes / edits, bash, git | Your machine (this client) |
| Agent reasoning, model calls, retrieval, DAG execution | The service |
The client never uploads your source files. Only the tool output text the agent asked for travels to the service.
Configuration
Server URL + token live in ~/.master_agents/remote.yaml after login.
Override per-call with --config <path>. Env-var override:
MASTER_AGENTS_REMOTE_CONFIG=/path/to/remote.yaml.
Self-host (the orchestration server)
The hosted service is master-agents (a separate package, deliberately not
on PyPI — it carries the agent specs, framework internals, RAG configs, and
prompts). Self-host via authenticated git access:
pip install "git+ssh://git@github.com/<owner>/master_agents_os.git#subdirectory=packages/py"
mao-server serve --http --host 0.0.0.0 --port 8000
That gates per-person on repo access — the right authorisation model for IP-bearing code, not anonymous PyPI.
Links
- Slash command + troubleshooting reference:
USER_GUIDE.md - Architecture overview:
docs/MASTER_ARCHITECTURE.md(upstream repo) - Versioning policy:
docs/policy/VERSIONING.md(upstream repo) - Release runbook:
docs/RELEASE.md(upstream repo)
License
MIT. The server-side master-agents package is proprietary; this client
wheel is permissively licensed so anyone can integrate against a hosted
service.
1 maintainer
Release files for master-agents-client 4.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| master_agents_client-4.9.1.tar.gz | 355.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| master_agents_client-4.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 737.3 kB
Release files / master_agents_client-4.9.1.tar.gz
| Download URL | master_agents_client-4.9.1.tar.gz |
|---|---|
| Size | 355.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
56bb333a6b6050b6e31fe927bebdcc38a77f4bbdc07e849b880926890f16d9af
|
|
BLAKE2b-256 checksum How to use checksums |
18539542ad681e8fb7d9fe499f8282ac7aeb98d7e4df41c423595895cc7f7693
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Release files / master_agents_client-4.9.1-py3-none-any.whl
| Download URL | master_agents_client-4.9.1-py3-none-any.whl |
|---|---|
| Size | 381.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
30a18228b1990c068d63cb9d87631afab8732bf3d0eb089e2c53bd3d30b73681
|
|
BLAKE2b-256 checksum How to use checksums |
bfe59cfb4be2f8b9fb96f70c9ccd21aaa0b81308646599a98bcec6b19861e302
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
