master-agents-client 1.4.0

Thin client for the Master Agents service. Talks to a hosted server; bundles no orchestration logic, prompts, or agent specs.

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_tokens tool — 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://[e-mail]/<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.