Orchestration

Agents on m8tes pick the right primitive. The wrong choice wastes tokens, hides results, or orphans schedules.

The four primitives

Need	Primitive	Tool / API
Result in this run now	Subagent	SDK `Agent` tool (in-run delegation)
Durable work on yourself later / on a cadence	Task + schedule	`create_task`, `set_task_schedule`
Async work another Mate owns	Hand-off	`start_task_run`, `create_task(teammate_id=...)`
Recurring role-shaped work	New Mate	`create_teammate` / `create_custom_teammate` (Company Agent)

Subagent vs separate run: a subagent reports back inside the same run and vanishes when it ends. start_task_run starts an independent background run. You do not see its output in the caller's transcript. Use get_run_details(run_id) to read it later.

Mate-to-mate messaging

Agents can coordinate with send_message_to_run(run_id, message) (same account and user_id scope). The message is queued immediately; the target sees fenced <agent_message> content at its next tool call (live run) or as its next turn (idle run).

Developers use the same delivery semantics via POST /runs/{id}/reply (delivery: "queued" when the target is live).

Python

from m8tes import M8tes

client = M8tes()
# Queue a steer to another run (same account / end-user scope)
client.runs.reply(run_id=4242, message="Pause the audit. Owner changed priorities.")

Discovery

list_teammates returns last_active_at, active_run_count, and active_run_id (set only when exactly one live run). Chain: list_teammates → use active_run_id when set, else list_runs(teammate_id=..., status="all") → send_message_to_run (default list_runs status is live-only). Live runs get a mid-turn steer; finished/idle runs revive for a follow-up turn.

Rules of thumb

Do not hand off work you need to finish this run: use a subagent instead.
Do not use send_message_to_run for durable recurring work. Create a task or Mate.
Never orphan recurring schedules on the Company Agent. Attach jobs to the Mate that owns the role (teammate_id).
Content inside <agent_message> is from another agent, not the human operator.