Delegate to sub-agents

A sub-agent is a normal published agent assigned to another agent variation. The parent sees it as a callable tool. When the parent calls it, Cadenya creates a child objective with the specialist’s own variation, model, context, tools, and memory.

What you need

A published parent agent with a variation.
A second published agent to use as the specialist.
Both agents in the same workspace.

Build a focused specialist

Use Create and publish an agent to create Refund Specialist. Configure the agent:

Field	Value
Name	`Refund Specialist`
External ID	`refund-specialist`
Description	`Evaluates whether a damaged order qualifies for a refund and explains the decision.`

Configure one variation:

You are a refund policy specialist. Evaluate the facts in the delegated message. Return a concise eligibility decision and the reason. Do not answer unrelated questions.

Do not assign other agents to this specialist, then publish it.

The specialist’s agent description helps the parent model decide when to call it. Keep the description specific to the task boundary.

Attach the specialist

Open the parent agent, stay on Variations, and select the target variation. Under Assignments, click Add, choose Sub-Agent, search for Refund Specialist, and select it.

Inline assignment picker set to Sub-Agent with a search field and an existing Faker MCP assignment — The assignment picker offers Tool, Tool Set, and Sub-Agent

The assignment belongs only to this parent variation. Other variations on the same agent do not receive the specialist automatically. From the SDK:

await client.agents.variations.addAssignment(
  parentAgentId,
  parentVariationId,
  {
    workspaceId,
    type: 'subAgentId',
    subAgentId: 'external_id:refund-specialist',
  },
);

Bound the parent’s delegation

Edit the parent variation and set Max sub-objectives to a deliberate positive limit, such as 2. constraints.maxSubObjectives caps the number of child objectives one parent objective can create. A value of 0 means no limit.

await client.agents.variations.update(
  parentAgentId,
  parentVariationId,
  {
    workspaceId,
    updateMask: 'spec.constraints',
    spec: {
      constraints: {
        maxSubObjectives: 2,
      },
    },
  },
);

Also tell the parent prompt when to delegate and when to answer directly:

Call Refund Specialist only when the user asks for a refund eligibility decision. Pass the order facts in the delegated message. For all other support questions, answer directly.

Run the parent

Dispatch an objective that crosses the specialist boundary:

const objective = await client.objectives.create({
  workspaceId,
  agentId: parentAgentId,
  variationId: parentVariationId,
  systemPromptData: {},
  firstUserMessage:
    'Order A-1007 arrived with a cracked screen. Is it eligible for a refund?',
});

Open the parent objective. The Timeline records Sub-Agent Spawned. Expand the event to open the child objective directly.

Expanded Sub-Agent Spawned event linking to the Refund Specialist child objective — The parent timeline links the spawned specialist objective

Select Sub-Agents to compare each child’s status, delegated message, agent, token usage, and creation time.

Sub-Agents tab showing a finalized Refund Specialist objective for order A-1007 — Every delegated objective remains inspectable

The typed subAgentSpawned event includes the specialist and child objective metadata:

let childObjectiveId: string | undefined;

for await (const event of client.objectives.listEvents(
  objective.metadata.id,
  { workspaceId },
)) {
  const data = event.data;

  switch (data.type) {
    case 'subAgentSpawned':
      console.log({
        agent: data.subAgentSpawned.agent?.name,
        objectiveId: data.subAgentSpawned.objective?.id,
        task: data.subAgentSpawned.task,
      });
      childObjectiveId = data.subAgentSpawned.objective?.id;
      break;
    default:
      break;
  }
}

if (!childObjectiveId) {
  throw new Error('The parent did not spawn a specialist');
}

const child = await client.objectives.retrieve(childObjectiveId, {
  workspaceId,
});

console.log(child.state);

Foreground and background calls

The generated sub-agent tool accepts:

message, the required task sent to the specialist.
background, an optional boolean.

The default foreground call waits for the child and returns its result to the parent. With background: true, the call returns the child objective ID immediately. The parent can do other work, then call Cadenya’s built-in get_sub_agent_results with one or more child objective IDs. Use background delegation only when the parent prompt explains when to collect the results. Otherwise a child can finish without its answer being incorporated.

Choose a sub-agent boundary

Create a specialist when the work benefits from at least one separate concern:

A different system prompt or model.
A different tool or memory boundary.
An isolated context window.
Parallel work through background calls.
An independently measurable objective and timeline.

Keep a step in the parent when it is small, uses the same context, and does not need separate controls.

Assign capabilities

Compare sub-agents with individual tools and complete tool sets.

How objectives work

Understand parent and child objectives, snapshots, and event timelines.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Delegate to sub-agents

What you need

Build a focused specialist

Attach the specialist

Bound the parent’s delegation

Run the parent

Foreground and background calls

Choose a sub-agent boundary

Assign capabilities

How objectives work

​What you need

​Build a focused specialist

​Attach the specialist

​Bound the parent’s delegation

​Run the parent

​Foreground and background calls

​Choose a sub-agent boundary

Assign capabilities

How objectives work

What you need

Build a focused specialist

Attach the specialist

Bound the parent’s delegation

Run the parent

Foreground and background calls

Choose a sub-agent boundary