post_task_auto
Automatically route each task to the least-loaded agent with all required capabilities. Queue if no agent is online, then auto-assign when a capable agent appears.
Instructions
Auto-route a task to the least-loaded capable agent (v2.0).
When to use: when you know the required capabilities but do not want to hard-code a specific assignee, load balances across the fleet. Prefer post_task when the assignee is intentional. Prefer broadcast for non-tracked notifications.
Behavior: picks the agent with the smallest accepted-task backlog whose capability set is a superset of required_capabilities. Tie-break: freshest last_seen. If no live agent qualifies, the task enters status='queued' and is auto-assigned the first time a capable agent calls register_agent (the assignment is included in that response's auto_assigned). By default the sender is excluded from routing, set allow_self_assign=true to opt in (v2.1).
Returns: { success: true, task_id, status: 'posted' | 'queued', assigned_to: string | null, routed: boolean, candidate_count, required_capabilities, note }. routed=true only when an agent matched at post time; routed=false with status='queued' is the no-match path that auto-resolves on next register.
Errors: AUTH_FAILED, PAYLOAD_TOO_LARGE, RATE_LIMITED.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| from | Yes | Requester agent name | |
| title | Yes | Short task title | |
| priority | No | Task priority | normal |
| agent_token | No | Your agent token (from register_agent response). Optional here — also resolvable from RELAY_AGENT_TOKEN env or X-Agent-Token header. | |
| description | Yes | Full task description (max 64KB by default) | |
| allow_self_assign | No | v2.1: opt-in flag to let the sender self-assign the task when they match the required capabilities. Default false — sender is excluded from routing so auto-routed work reaches peers. | |
| required_capabilities | Yes | Capabilities the assigned agent must have (ALL must match). Also used to auto-assign from the queue when a capable agent registers later. |