Building Multi-Agent Systems

Overview

Multi-agent systems involve multiple agents working together to solve complex problems. While other frameworks require you to find contrived ways to have agents spawn agents, the Agentica SDK makes this trivial: pass an agentic function or an agent to another agentic function or agent. That’s it. No special orchestration layers, no graphs, no composition primitives or DSL, no message-passing protocols, no global state management. It’s just code.

When to Use Multi-Agent Systems

Multi-agent systems shine when:

Tasks can be parallelized: Multiple independent sub-tasks may be worked on simultaneously
Specialization helps: Different agents with different capabilities or contexts tackle different aspects
Complex workflows: The problem naturally breaks down into distinct phases or responsibilities
Iterative refinement: One agent’s output becomes another agent’s input

The Core Concept

Because the Agentica SDK allows you to pass any runtime value into scope — functions, objects, classes, SDKs — this naturally includes:

The spawn() function itself
Existing agents
Agentic functions
Custom orchestration logic

When you pass these to an agent or agentic function, they can use them just like anything else in scope. No schemas, no special handling. It’s just code.

Pattern: Basic Composition

Let’s start with the simplest possible multi-agent pattern: calling one agentic function from another.

from agentica import agentic
from dataclasses import dataclass

@dataclass
class CodeAnalysis:
    bugs: list[str]
    style_issues: list[str]
    performance_issues: list[str]

# Two separate agentic functions, each specialized
@agentic()
async def analyze_code(code: str) -> CodeAnalysis:
    """Analyze code for bugs, style issues, and performance problems."""
    ...

@agentic()
async def fix_code(code: str, analysis: CodeAnalysis) -> str:
    """Fix the code based on the analysis."""
    ...

# Compose them together
analysis = await analyze_code(code)
fixed = await fix_code(code, analysis)

import { agentic } from '@symbolica/agentica';

interface CodeAnalysis {
  bugs: string[];
  styleIssues: string[];
  performanceIssues: string[];
}

// Two separate agentic functions, each specialized
async function analyzeCode(code: string): Promise<CodeAnalysis> {
  return await agentic('Analyze code for bugs and performance issues', { code });
}

async function fixCode(code: string, analysis: CodeAnalysis): Promise<string> {
  return await agentic('Fix the code based on the analysis', { code, analysis });
}

// Compose them together
const analysis = await analyzeCode(code);
const fixed = await fixCode(code, analysis);

This is a multi-agent system: two separate agent invocations, each specialized for its task, composed together. However the “workflow” here is very boring — it’s entirely serial, with no conditionality. Let’s take a look at what introducing control flow is like.

Pattern: External Control Flow

In this pattern, you orchestrate the agents from your code. You decide when to call agents, what tasks to give them, and how to combine their results. You write the control flow: loops, conditionals, error handling — all the logic that coordinates the agents. This is useful when:

The workflow involves iteration, conditionals, or complex branching
You want explicit control over execution order and conditions
You need to inject custom logic between agent calls
You’re building a specific, repeatable process with clear control flow

Example: Parallelization, Iteration, and Conditional Logic

from agentica import agentic

... # other logic and classes

@agentic()
async def evaluate_candidate(cand: Candidate) -> EvaluationResult:
    """Evaluate if candidate meets our technical and cultural requirements."""
    ...

@agentic()
async def create_interview_plan(cand: Candidate, eval: EvaluationResult) -> InterviewPlan:
    """Create a tailored interview plan focusing on the candidate's strengths and gaps."""
    ...

@agentic()
async def create_rejection_letter(cand: Candidate, eval: EvaluationResult) -> RejectionLetter:
    """Generate a polite rejection letter with constructive feedback."""
    ...

async def pipeline(candidates: list[Candidate]):
    # Evaluate all candidates in parallel
    evaluations = await asyncio.gather(*[evaluate_candidate(c) for c in candidates])

    to_be_interviewed: dict[Candidate, InterviewPlan] = dict()
    to_be_rejected: dict[Candidate, RejectionLetter] = dict()

    # Branch based on results
    async def pick_candidate(candidate: Candidate, evaluation: EvaluationResult):
        if evaluation.is_qualified:
            to_be_interviewed[candidate] = await create_interview_plan(candidate, evaluation)
        else:
            to_be_rejected[candidate] = await create_rejection_letter(candidate, evaluation)

    async with asyncio.TaskGroup() as tg:
        for candidate, evaluation in zip(candidates, evaluations):
            tg.create_task(pick_candidate(candidate, evaluation))

    # Do something with the data
    ...

import { agentic } from '@symbolica/agentica';

... // other logic and classes

async function evaluateCandidate(cand: Candidate): Promise<EvaluationResult> {
  return agentic('Evaluate if candidate meets our technical and cultural requirements', { cand });
}

async function createInterviewPlan(cand: Candidate, eval: EvaluationResult): Promise<InterviewPlan> {
  return agentic("Create a tailored interview plan focusing on the candidate's strengths and gaps", { cand, eval });
}

async function createRejectionLetter(cand: Candidate, eval: EvaluationResult): Promise<RejectionLetter> {
  return agentic('Generate a polite rejection letter with constructive feedback', { cand, eval });
}

async function pipeline(candidates: Candidate[]) {
  // Evaluate all candidates in parallel
  const evaluations = await Promise.all(candidates.map(c => evaluateCandidate(c)));

  const toBeInterviewed: Map<Candidate, InterviewPlan> = new Map();
  const toBeRejected: Map<Candidate, RejectionLetter> = new Map();

  // Process qualified and unqualified candidates concurrently
  await Promise.all(
    candidates.map(async (candidate, i) => {
      const evaluation = evaluations[i];

      if (evaluation.isQualified) {
        const plan = await createInterviewPlan(candidate, evaluation);
        toBeInterviewed.set(candidate, plan);
      } else {
        const letter = await createRejectionLetter(candidate, evaluation);
        toBeRejected.set(candidate, letter);
      }
    })
  );

  // Do something with the data
  ...
}

Notice how you write the parallelization, the conditional branching, the iteration logic. Agents are just functions you call — the control flow is yours. This is just regular programming with agents as building blocks.

Pattern: Coordinator + Workers

Now here’s where the Agentica SDK’s design truly shines. Instead of you controlling the flow, let an agent control it. A coordinator agent manages multiple worker agents, each handling independent sub-tasks. This is useful when:

The number of sub-tasks isn’t known in advance
The workflow needs to adapt based on intermediate results
You want agents to decide how to parallelize work
Sub-tasks benefit from specialization
The problem is too complex for fixed orchestration logic

Most Constrained: Passing Specific Agent Objects

Let’s start with the most constrained approach: pass pre-configured agent objects with specific capabilities.

from agentica import spawn

# Create specialized agents with permanent tool access
data_analyst = await spawn(
    premise="You are a data analyst",
    scope={"query_database": query_database}    # ← Functions at spawn time
)
market_analyst = await spawn(
    premise="You are a market analyst",
    scope={"get_market_data": get_market_data}  # ← Functions at spawn time
)

coordinator = await spawn(premise="You are a research coordinator")

report = await coordinator.call(
    ComprehensiveReport,             # ← The rigid class defining the report type
    f"Research {topic} using the data analyst and market analyst",
    data_analyst=data_analyst,       # ← Pass agent objects
    market_analyst=market_analyst    # ← Just like anything else
)

import { spawn } from '@symbolica/agentica';

// Create specialized agents with permanent tool access
await using dataAnalyst = await spawn(
  { premise: "You are a data analyst" },
  { queryDatabase }    // ← Functions at spawn time
);
await using marketAnalyst = await spawn(
  { premise: "You are a market analyst" },
  { getMarketData }    // ← Functions at spawn time
);

await using coordinator = await spawn({ premise: "You are a research coordinator" });

const report = await coordinator.call<ComprehensiveReport>(  // ← The rigid type defining the report structure
  `Research ${topic} using the data analyst and market analyst`,
  {
    dataAnalyst,    // ← Pass agent objects
    marketAnalyst   // ← Just like anything else
  }
);

The coordinator can now invoke the specialist agents, pass data between them, and decide when to use which one — all dynamically based on the task.

Least Constrained: Passing `spawn` Itself

For maximum flexibility, pass spawn itself so the coordinator can create any agents it needs:

from agentica import spawn

... # other logic and classes

async def web_search(query: str) -> list[SearchResult]: ...

# Create a coordinator with the ability to spawn
coordinator = await spawn(premise="You are a research coordinator who can spawn sub-agents")

# Give it spawn and tools - it decides how many sub-agents it needs
report = await coordinator.call(
    ResearchReport,       # ← The rigid return type defining the report
    f"Research '{topic}' thoroughly using sub-agents for different aspects",
    spawn=spawn,          # ← The interesting part happens here
    web_search=web_search # ← A function that may be passed to sub-agents
)

import { spawn } from '@symbolica/agentica';

... // other logic and classes

async function webSearch(query: string): Promise<SearchResult[]> { ... }

await using coordinator = await spawn({ premise: 'You are a research coordinator who can spawn sub-agents'});

// Give it spawn and tools - it decides how many sub-agents it needs
const report = await coordinator.call<ResearchReport>(  // ← The rigid return type defining the report
  `Research '${topic}' thoroughly using sub-agents for different aspects`,
  {
    spawn,    // ← The interesting part happens here
    webSearch // ← A function that may be passed to sub-agents
  }
);

What just happened? The coordinator agent can now:

Decide how many sub-agents it needs
Spawn them dynamically using spawn()
Assign them specific tasks
Wait for their results
Synthesize everything into a final report

You didn’t write any of that orchestration logic. The agent figured it out.

For a richer case of this pattern, see the Deep Research example.

Best Practices

1. Choose the Right Pattern

Basic composition: For simple sequential agentic operations
External control flow: For predictable processes with iteration and conditionals
Coordinator + workers: For dynamic, adaptive workflows where agents orchestrate other agents

2. Be Clear About Responsibilities

Give each agent a focused premise that defines its role:

researcher = await spawn(
    premise="You are a researcher who finds and verifies facts. Do not write content."
)

writer = await spawn(
    premise="You are a writer who creates engaging content from facts. Do not do research."
)

await using researcher = await spawn({
  premise: "You are a researcher who finds and verifies facts. Do not write content."
});

await using writer = await spawn({
  premise: "You are a writer who creates engaging content from facts. Do not do research."
});

3. Use Appropriate Scope

Only pass what each agent needs:

# Good: Focused scope
researcher = await spawn()
result = await researcher.call(ResearchReport, "Research X", web_search=web_search)

# Avoid: Too much scope
result = await researcher.call(
    ResearchReport,
    "Research X",
    web_search=web_search,
    database=db,
    api_client=client  # Researcher doesn't need these
)

// Good: Focused scope
await using researcher = await spawn();
const result = await researcher.call<ResearchReport>("Research X", { webSearch });

// Avoid: Too much scope
const result = await researcher.call<ResearchReport>(
  "Research X",
  {
    webSearch,
    database: db,
    apiClient: client  // Researcher doesn't need these
  }
);

Why This Works in the Agentica SDK

In traditional agent frameworks, multi-agent systems require:

Message-passing protocols
State management systems
Complex orchestration layers
Schema definitions for inter-agent communication

With the Agentica SDK, none of that is needed because:

Everything is just scope: Agents, functions, objects — they’re all just values you can pass around
Warp handles communication: The framework automatically manages calls between your runtime and the sandbox
Proxies enable references: Agents can pass complex objects without serialization
REPL enables agency: Agents can write actual code to orchestrate other agents, not just call predefined tools

The result: multi-agent systems that feel like regular programming, not framework wrangling.

Next Steps

Error Handling

Handle errors in multi-agent systems

Best Practices

Production-ready patterns

Human-in-the-Loop

Add human oversight to agents

Examples

See the Deep Research multi-agent example

Getting Started

Core Concepts

Guides

Integrations

Building Multi-Agent Systems

Overview

When to Use Multi-Agent Systems

The Core Concept

Pattern: Basic Composition

Pattern: External Control Flow

Example: Parallelization, Iteration, and Conditional Logic

Pattern: Coordinator + Workers

Most Constrained: Passing Specific Agent Objects

Least Constrained: Passing `spawn` Itself

Best Practices

1. Choose the Right Pattern

2. Be Clear About Responsibilities

3. Use Appropriate Scope

Why This Works in the Agentica SDK

Next Steps

Error Handling

Best Practices

Human-in-the-Loop

Examples

​Overview

​When to Use Multi-Agent Systems

​The Core Concept

​Pattern: Basic Composition

​Pattern: External Control Flow

​Example: Parallelization, Iteration, and Conditional Logic

​Pattern: Coordinator + Workers

​Most Constrained: Passing Specific Agent Objects

​Least Constrained: Passing spawn Itself

​Best Practices

​1. Choose the Right Pattern

​2. Be Clear About Responsibilities

​3. Use Appropriate Scope

​Why This Works in the Agentica SDK

​Next Steps

Error Handling

Best Practices

Human-in-the-Loop

Examples

Overview

When to Use Multi-Agent Systems

The Core Concept

Pattern: Basic Composition

Pattern: External Control Flow

Example: Parallelization, Iteration, and Conditional Logic

Pattern: Coordinator + Workers

Most Constrained: Passing Specific Agent Objects

Least Constrained: Passing `spawn` Itself

Best Practices

1. Choose the Right Pattern

2. Be Clear About Responsibilities

3. Use Appropriate Scope

Why This Works in the Agentica SDK

Next Steps