Multi-Machine Prompts

ask_agents is the agent-to-agent fan-out tool. One prompt → many machines → one aggregated answer. This guide shows how to drive it from chat and how to read the result.

The use case

Ask all my prod machines: do you see this error in the last hour?

One chat turn, many agents in parallel, one consolidated answer. The alternative — calling ask_agent N times sequentially — is slower and harder to compare across hosts.

What `ask_agents` does

For deeper mechanics see Concepts: agent communication. In short:

Per-host timeout — clamped to [1, 300] seconds, default 120 s.
Total deadline — clamped to [1, 600] seconds, default 240 s.
Dedup — repeated hostnames collapsed, original order preserved.
Result map — keyed by hostname, values are Response / RemoteError / Error / TimedOut.
Cancellation — drops in-flight workers; tagged in TimedOut.

Calling from chat

Just ask. The agent translates intent into a ask_agents tool call:

Ask prod-1, prod-2, and db-1 to each report uptime. Tell me which is busiest.

Behind the scenes the agent emits:


{
  "tool": "ask_agents",
  "args": {
    "hostnames": ["prod-1", "prod-2", "db-1"],
    "prompt": "Run `uptime` and report the load average.",
    "timeout_ms": 30000
  }
}

Reading the result

The tool returns a map keyed by hostname:


{
  "prod-1": {"type": "response", "text": "load average: 0.4 0.5 0.6"},
  "prod-2": {"type": "remote_error", "error": "uptime: command not found"},
  "db-1":   {"type": "error", "kind": "timeout", "ms": 30000}
}

Three buckets:

response — success; surface the text.
remote_error — the receiver agent reported failure (e.g. tool denied, command missing). Look at the receiver’s audit log.
error — our side failed (resolve, dial, offline, timeout).

TimedOut: ["db-1"] is the convenient list version for prompts that just want to know “who timed out”.

Common patterns

Health sweep


Ask all hosts tagged env=prod for `uptime` and CPU temperature. Group by load.

Log scan


Ask web-1, web-2, web-3 to grep `ERROR` in `/var/log/myapp.log` for the last 30 minutes.

Rolling deploy

For sequential operations with stop-on-fail, prefer ask_agent in a loop — ask_agents is parallel by design:


Ask prod-1 to deploy. If exit 0, ask prod-2 to deploy. Repeat for prod-3.

Limits and tuning

Default 120 s per host is generous. Tighten for interactive use:
```
...timeout_ms 15000  # 15 seconds per host
```
Total deadline (240 s default) caps the whole fan-out. The slowest host or the deadline — whichever fires first.
Fan-out is not transactional. Some hosts can succeed while others fail. Always check the per-host result map.

Permissions on the receivers

Each receiver enforces its own permissions.yaml. If one denies, the others still run. The deny lands in the result map as remote_error with the gate’s reason — debug per host, not workspace-wide.

Hostnames are deduped before fan-out. Don’t worry about repeating a machine in your prompt.

Fan-out is not transactional. Some hosts can succeed while others fail. Always check the per-host result map before drawing conclusions.