Orchestration

Agents on m8tes pick the right primitive for the job. 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

Discovery

list_teammates returns last_active_at and active_run_count so orchestrators can see who is live before messaging or handing off.

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.