Sub-agents

Any Fruxon agent can be called as a tool by any other agent in the same organization. That's a sub-agent. It's the primary way to build complex systems without ending up with one giant unreadable workflow.

When to reach for a sub-agent

Use a sub-agent when:

• A piece of behavior is reusable across multiple parents (e.g., a "draft email" agent used by sales, support, and ops).
• A piece of behavior is distinct enough to deserve its own evaluation set, prompts, and revision history (e.g., a classifier independent of the orchestrator that calls it).
• A workflow is getting too big to read on the canvas.
• A piece needs different guardrails — a stricter model, a tighter system prompt, sandboxed integrations.

If a piece of behavior is only ever called from one place and is small, leave it as steps. Don't pre-factor.

How a sub-agent call works

1. Parent agent reaches a sub-agent step.
2. Parent passes the sub-agent's parameters (mapped from the parent's inputs and prior step outputs).
3. Sub-agent runs as a normal agent — its own steps, tools, memory, knowledge.
4. Sub-agent's exit point produces a structured response.
5. Parent receives the response and continues, referencing fields like {{step.<sub_agent_step>.<field>}}.

The call is in-process and shows up as a nested trace inside the parent's trace — you can drill into the sub-agent's run without leaving the parent's view.

Adding a sub-agent step

1. In Studio, click + Add Node → Sub-agent.
2. Pick the agent to invoke.
3. (Optionally) pin to a specific revision — see pinning below.
4. Map the sub-agent's parameters from the parent's data.
5. Reference outputs in subsequent steps:

{{step.classify.category}}
{{step.draft_email.subject}}
{{step.draft_email.body}}

Composition patterns

Sequential

The straightforward chain — each sub-agent's output feeds the next.

extract_text → summarize → translate

Parallel

Run independent sub-agents at the same time. Steps with no shared dependencies run concurrently in Fruxon — there's no extra wiring needed.

              ┌─ sentiment_analyzer
input  ──────┼─ keyword_extractor    →  merge
              └─ language_detector

Router / dispatcher

A small orchestrator agent classifies the request and dispatches to the right specialist sub-agent.

input → classify (cheap model) →  branch
                                    ├─ technical_support
                                    ├─ billing_support
                                    └─ general_inquiry

This is the pattern for most multi-domain customer-facing agents — the router stays small and fast; specialists stay focused.

Map-reduce

Iterate a sub-agent over an array, then aggregate.

articles → for each → extract_facts → reduce → final_briefing

Human-in-the-loop

A draft sub-agent produces a candidate; an approval node pauses for a human; on approval, an action sub-agent commits the change.

Versioning

Sub-agent calls always invoke the deployed revision of the target. Improvements to a sub-agent automatically benefit every parent that calls it. Per-step pinning to a specific revision isn't supported today — if you need a stable target, deploy the sub-agent's exact revision and avoid changing it.

If you're calling a specific revision from your own code (for canary tests or regression replays), put it in the URL path:

POST /v1/{tenant}/agents/{agent}/{revision}:execute
X-API-KEY: ...
Content-Type: application/json

{
  "input": { ... }
}

The default :execute endpoint without the revision routes to the deployed revision.

Cost and latency

A sub-agent call is roughly the cost and latency of running that agent standalone — there's no platform overhead worth worrying about. The trace breaks costs down per nested run, so per-parent reporting stays accurate.

For latency-sensitive paths, prefer parallel composition over deep sequential chains. A 4-stage sequential chain costs the sum of the stages; a parallel fan-out costs the slowest stage.

Best practices

• One job per sub-agent. A sub-agent that does three things is harder to evaluate than three sub-agents that each do one.
• Stable exit shapes. Downstream parents depend on the field names. Don't rename without coordinating.
• Evaluate sub-agents independently. Each gets its own golden dataset; the orchestrator gets its own.
• Don't nest too deep. Three levels of sub-agents is fine. Six is a smell.

Next steps

• Agent Studio — the canvas in depth
• Versioning — revisions and rollback
• Evaluations — per-agent quality gating
• Use Cases — patterns built from sub-agents