Delegate to Another Agent
Let a lead agent hand a question to another Fruxon agent and use its answer, with a worked CLI example
A lead agent can hand a question to another agent in your workspace and get its answer back. An incident responder can ask a log-analyst agent what the logs show and a code-investigator agent where the bug is, then write the incident summary from both answers.
The other agent is a peer. It stays its own agent, with its own prompts, tools, evaluations and revision history. The lead reaches it through the Agent Network: the peer is represented by an AI-agent participant, and that participant is bound to the lead.
Works in conversations only. Delegation runs end to end when the lead is answering a conversation: a message on a channel, a chat, or a sandbox session. On a run with no conversation behind it, such as an API :execute call, a schedule or a trigger fired with no conversation, ask doesn't reach the peer: it becomes a one-shot request that no agent answers, and the lead waits until it expires. This is still being changed.
How it works
- You create an AI-agent participant for the peer and bind it to the lead.
- Because the lead now has a peer, it gets two extra tools,
askanddelegate_to_participant, and a<consult_roster>block in its prompt that lists its peers. - The lead calls
askwith the peer's name and a question. - The peer runs its deployed revision in a session of its own, with the question as its only input.
- The peer's reply comes back to the lead as the result of
ask, and the lead carries on.
The peer's run is a child of the lead's run: it shows up in the lead's trace, its cost counts toward the lead's run, and the lead's action-type ceiling caps the tools the peer may use.
Set it up from the CLI
You need two agents, both created and deployed: the lead, and the peer. The peer always runs its deployed revision, so a peer with nothing deployed can't answer.
1. Create a participant for the peer and bind it to the lead
Write the participant as JSON. relatedAgentId is the peer agent; agentIds binds the participant to the lead in the same call:
{
"kind": "AI_AGENT",
"displayName": "Log analyst",
"relatedAgentId": "log-analyst",
"agentIds": ["incident-responder"],
"description": "Reads application logs and reports what failed, when, and how often.",
"expertise": ["logs", "error rates"]
}fruxon participants create -f log-analyst.jsonTo bind an existing participant instead, use fruxon participants bind <participant-id> <lead-agent-id>. Do the same for each peer: one participant per peer agent.
Write a clear displayName, description and expertise. They're what the lead's model reads in its roster when it decides whom to ask.
2. Check the lead's roster
fruxon agents roster incident-responderEach peer is listed with its participantId, its kind (AI_AGENT) and its display name. If the list is empty, the lead won't get the delegation tools.
3. Tell the lead when to ask
The tools appear on their own, but the lead's prompt should say when to use them, for example:
When an incident comes in,
askthe Log analyst what the logs show for the affected service, andaskthe Code investigator which recent change most likely caused it. Write the incident summary from their answers.
You don't need to change definition.network. The tools are added because the lead has a peer bound, whatever network.enabled says.
The tools the lead gets
ask: ask and wait for the answer
The lead's run pauses and resumes with the peer's reply as the tool's result. Use it when the lead needs the answer to carry on.
| Parameter | Required | What it is |
|---|---|---|
to | Yes | Whom to ask: the peer's display name, a role, or its participant_id from the roster |
question | Yes | The question. It's the only thing the peer sees, so make it self-contained |
urgency | No | low, normal, high or emergency. An AI peer accepts up to normal |
expecting | No | answer (default) or decision |
fallback | No | refuse (default) or pick_any, for when nobody matches to |
ttl_hours | No | How long to wait, 1 to 336 hours. Defaults to 24 |
The result has an outcome and the peer's answer in summary. If the peer fails or replies with nothing, the outcome is no_answer, and the lead may not ask the same peer again in that run.
delegate_to_participant: hand off and keep talking
The call returns at once, without the answer, and the lead keeps going. When the peer answers, its reply arrives later as a new message in the lead's conversation. Use it when the lead should acknowledge the user now and follow up later. It takes to, question, urgency and fallback, plus context_for_advisor.
delegate_to_participant works only inside a conversation. A delegated peer can't delegate further, and a conversation can have at most 3 delegations waiting at once.
What the peer sees and does
- Only the question. The peer runs in a new session of its own. It doesn't see the lead's conversation, the user, or earlier answers, so put everything it needs in
question. - Its deployed revision. Deploying a new revision of the peer changes what the lead gets from then on.
- Its own tools, capped by the lead's action-type ceiling.
- No waiting tools of its own. In production the peer runs inline, so a tool that waits (its own
ask,spawn_subtask, a tool behind an approval gate) fails with "Async tools can only run from a queued agent task". A chain of agents, A asks B and B asks C, doesn't work today.
Two peers in one turn
The lead can call ask twice in one turn, once per peer. It resumes when both have answered. The peers run one after the other, not in parallel, so the lead waits for the sum of both runs. Each request is also picked up on a 15-second cycle, so expect at least about 15 seconds before a peer starts. For work that should run in parallel, use parallel sub-tasks.
Test it in the sandbox
A sandbox session is a conversation, so delegation runs end to end there. You send a turn as a person participant, for example yourself from the Directory:
SESSION=$(fruxon agents sandbox open incident-responder -o id)
fruxon agents sandbox turn "$SESSION" \
--as <your-participant-id> \
--text "checkout-api error rate jumped to 8% at 14:05 UTC. What happened?" \
--await --wait--awaitmakesaskpause the run instead of running in the background.- The peer's deployed revision runs in sandbox mode: real sends are blocked and its connections follow sandbox routing. Add
--draftto run the lead's unpublished draft; the peer still runs its deployed revision. - Fruxon runs the peer and resolves the
askon its own, usually within 15 seconds plus the peer's run time. Nothing has to be answered by hand.
While the lead waits, the stream shows a pending_consult frame with advisorIsAgent: true and an operationId. To resolve it yourself instead of waiting:
# Run the peer now, as a nested sandbox run
fruxon agents sandbox answer "$SESSION" <operationId> --run-advisor --yes
# Or answer as the peer, to test how the lead handles a given reply
fruxon agents sandbox answer "$SESSION" <operationId> --text "No errors in the logs before 14:03." --yesThe first answer wins; a later one changes nothing.
Limits
| Limit | Value |
|---|---|
ask wait | 24 hours by default, 1 to 336 |
delegate_to_participant wait | 24 hours |
| Delegations waiting at once, per conversation | 3 |
| Delegation depth | 1: a delegated peer can't delegate |
| Unanswered asks to the same peer, per run | 1 |
| Urgency to an AI peer | Up to normal |
| Peers in a roster | No limit |
What doesn't work yet
These are known gaps, and they're still being changed:
- Runs with no conversation.
askfrom an API call, a schedule or a trigger run with no conversation doesn't run the peer. - Chains. A peer can't use
askor another waiting tool, so it can't consult a third agent. - Per-peer roster settings.
fruxon participants roster(roles,maxUrgency,responsePolicy) has no effect on an AI-agent participant. Point the lead at a peer by name, byparticipant_id, or through the participant'sexpertise. expecting: "decision"to an AI peer isn't tested; use the defaultanswer.- No checks on
relatedAgentId. Creating the participant doesn't check that the agent exists or is deployed. A wrong id shows up only asno_answerat run time. network.enabledis ignored.fruxon agents checkand the CLI's build guide still treat it as the switch for delegation, but the tools follow the bound peers.
Related
- Combining Agents: parallel sub-tasks and when to split work
- Agent Network: participants, bindings and conversations
- Observability: the peer's run nests in the lead's trace
- Sandbox Mode: how connections are routed in a sandbox run