Planned Feature — Coming Soon

🚧 This feature is not yet released. The documentation below describes planned behavior and may change before launch.

Multi-Agent Handoffs

Build systems of specialized agents that delegate tasks to each other. A coordinator agent routes work to specialists optimized for specific domains — research, analysis, code, data processing.

Why Handoffs?

A single agent can do a lot, but specialized agents are better at specific tasks:

Approach	Pros	Cons
Single agent	Simple, one config	Jack-of-all-trades, slower for complex tasks
Multi-agent	Each agent is optimized, parallel execution, modular	More setup, coordination logic

Architecture

                    ┌─────────────────┐
       Input ──────▶│   Coordinator   │
                    │   (fast model)  │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
     ┌────────────┐  ┌────────────┐  ┌────────────┐
     │ Researcher  │  │  Analyst   │  │   Writer   │
     │ (reasoning) │  │ (code_int) │  │  (default) │
     └──────┬─────┘  └──────┬─────┘  └──────┬─────┘
            │               │               │
            └───────────────┼───────────────┘
                            ▼
                    ┌────────────────┐
                    │  Final Output  │
                    └────────────────┘

Building a Multi-Agent System

Step 1: Create Specialist Agents

Python
JavaScript

from flymyai import AgentClient

client = AgentClient(api_key="fly-***")

# Specialist 1: Deep web researcher
researcher = client.agents.create(
    name="Deep Researcher",
    goal="""Thoroughly research {{ query }}.
    Find at least 5 authoritative sources.
    Verify claims across multiple sources.
    Return raw findings with source URLs.""",
    tools=["web_search", "browse_website", "news_search"],
    model="anthropic/reasoning",
    input_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Research query"}
        },
        "required": ["query"]
    },
    output_schema={
        "type": "object",
        "properties": {
            "findings": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "fact": {"type": "string"},
                        "source": {"type": "string"},
                        "confidence": {"type": "string", "enum": ["high", "medium", "low"]}
                    }
                }
            }
        }
    }
)

# Specialist 2: Data analyst
analyst = client.agents.create(
    name="Data Analyst",
    goal="""Analyze the provided data about {{ subject }}.
    Compute key metrics, identify trends, create visualizations if helpful.
    Return structured analysis with numbers.""",
    tools=["code_interpreter"],
    model="anthropic/default",
    input_schema={
        "type": "object",
        "properties": {
            "subject": {"type": "string"},
            "data": {"type": "string", "format": "textarea", "description": "Raw data to analyze"}
        },
        "required": ["subject", "data"]
    }
)

# Specialist 3: Report writer
writer = client.agents.create(
    name="Report Writer",
    goal="""Write a polished {{ report_type }} report based on the provided research and analysis.
    Target audience: {{ audience }}.
    Include executive summary, key findings, and recommendations.""",
    tools=["web_search"],
    model="anthropic/default",
    input_schema={
        "type": "object",
        "properties": {
            "report_type": {"type": "string"},
            "audience": {"type": "string"},
            "research_data": {"type": "string", "format": "textarea"},
            "analysis_data": {"type": "string", "format": "textarea"}
        },
        "required": ["report_type", "research_data"]
    }
)

import { AgentClient } from "flymyai-js-client";

const client = new AgentClient({ apiKey: "fly-***" });

const researcher = await client.agents.create({
    name: "Deep Researcher",
    goal: "Thoroughly research {{ query }}. Find 5+ sources. Return raw findings.",
    tools: ["web_search", "browse_website", "news_search"],
    model: "anthropic/reasoning",
    inputSchema: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"]
    }
});

const analyst = await client.agents.create({
    name: "Data Analyst",
    goal: "Analyze data about {{ subject }}. Compute metrics, identify trends.",
    tools: ["code_interpreter"],
    inputSchema: {
        type: "object",
        properties: {
            subject: { type: "string" },
            data: { type: "string" }
        },
        required: ["subject", "data"]
    }
});

const writer = await client.agents.create({
    name: "Report Writer",
    goal: "Write a polished {{ report_type }} report from research and analysis.",
    tools: ["web_search"],
    inputSchema: {
        type: "object",
        properties: {
            report_type: { type: "string" },
            research_data: { type: "string" },
            analysis_data: { type: "string" }
        },
        required: ["report_type", "research_data"]
    }
});

Step 2: Create the Coordinator

The coordinator uses specialist agents as tools:

Python
JavaScript

coordinator = client.agents.create(
    name="Market Intelligence Report",
    goal="""Produce a comprehensive market intelligence report for {{ company }} in {{ industry }}.

    Steps:
    1. Use deep_research to gather information about the company and its market
    2. Use deep_research again for competitor analysis
    3. Use data_analysis to process and analyze the findings
    4. Use report_writer to produce the final polished report

    {{#if specific_questions}}
    Also address these specific questions:
    {{#each specific_questions}}
    - {{ this }}
    {{/each}}
    {{/if}}""",

    tools=[
        "web_search",
        {"type": "agent", "agent_id": researcher.id, "name": "deep_research"},
        {"type": "agent", "agent_id": analyst.id, "name": "data_analysis"},
        {"type": "agent", "agent_id": writer.id, "name": "report_writer"}
    ],

    model="anthropic/default",  # coordinator can be fast; specialists handle heavy lifting

    input_schema={
        "type": "object",
        "properties": {
            "company": {"type": "string", "description": "Company to analyze"},
            "industry": {"type": "string", "description": "Industry sector"},
            "specific_questions": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Specific questions to address in the report"
            }
        },
        "required": ["company", "industry"]
    },

    output_schema={
        "type": "object",
        "properties": {
            "executive_summary": {"type": "string"},
            "market_overview": {"type": "string"},
            "company_analysis": {"type": "string"},
            "competitive_landscape": {"type": "string"},
            "recommendations": {"type": "array", "items": {"type": "string"}},
            "sources": {"type": "array", "items": {"type": "string"}}
        }
    },

    visibility="public",
    pricing={"per_run": 3.00}
)

const coordinator = await client.agents.create({
    name: "Market Intelligence Report",
    goal: `Produce a market intelligence report for {{ company }} in {{ industry }}.
    1. Use deep_research for company info
    2. Use deep_research for competitors
    3. Use data_analysis to process findings
    4. Use report_writer for final output`,
    tools: [
        "web_search",
        { type: "agent", agentId: researcher.id, name: "deep_research" },
        { type: "agent", agentId: analyst.id, name: "data_analysis" },
        { type: "agent", agentId: writer.id, name: "report_writer" }
    ],
    model: "anthropic/default",
    inputSchema: {
        type: "object",
        properties: {
            company: { type: "string", description: "Company to analyze" },
            industry: { type: "string", description: "Industry sector" }
        },
        required: ["company", "industry"]
    },
    visibility: "public",
    pricing: { perRun: 3.00 }
});

Step 3: Run the System

run = client.runs.create(
    agent_id=coordinator.id,
    input={
        "company": "Databricks",
        "industry": "Data & AI Infrastructure",
        "specific_questions": [
            "What is their pricing model?",
            "How do they compare to Snowflake?"
        ]
    }
)

# Watch the orchestration
for event in client.runs.stream_events(run.id):
    print(f"[{event.type}] {event.message}")

# [planning] Breaking task into research, analysis, and writing phases...
# [tool_call] deep_research({"query": "Databricks company overview 2025"})
# [tool_result] Research complete: 8 findings from 5 sources
# [tool_call] deep_research({"query": "Databricks vs Snowflake comparison"})
# [tool_result] Research complete: 12 findings from 7 sources
# [tool_call] data_analysis({"subject": "Databricks", "data": "..."})
# [tool_result] Analysis complete: market trends identified
# [tool_call] report_writer({"report_type": "market intelligence", ...})
# [tool_result] Report written: 2,500 words
# [completed] Final report ready

result = client.runs.get(run.id)
print(result.output["executive_summary"])

Patterns

Coordinator-Specialist

One coordinator routes to multiple specialists (shown above). Best for complex, multi-faceted tasks.

Pipeline

Each agent feeds into the next. Best for sequential processing:

# Stage 1 → Stage 2 → Stage 3
pipeline_agent = client.agents.create(
    name="Content Pipeline",
    goal="""Process content for {{ topic }}:
    1. Use researcher to gather raw data
    2. Use analyst to extract key insights
    3. Use writer to produce final content""",
    tools=[
        {"type": "agent", "agent_id": researcher.id, "name": "researcher"},
        {"type": "agent", "agent_id": analyst.id, "name": "analyst"},
        {"type": "agent", "agent_id": writer.id, "name": "writer"}
    ],
    input_schema={
        "type": "object",
        "properties": {"topic": {"type": "string"}},
        "required": ["topic"]
    }
)

Fan-Out

Coordinator runs multiple specialists in parallel, then merges results:

fan_out_agent = client.agents.create(
    name="Multi-Source Analyzer",
    goal="""Analyze {{ topic }} from multiple perspectives simultaneously:
    - Use tech_researcher for technology angle
    - Use market_researcher for market angle
    - Use regulatory_researcher for regulatory angle
    Then synthesize all findings into a unified report.""",
    tools=[
        {"type": "agent", "agent_id": tech_researcher.id, "name": "tech_researcher"},
        {"type": "agent", "agent_id": market_researcher.id, "name": "market_researcher"},
        {"type": "agent", "agent_id": reg_researcher.id, "name": "regulatory_researcher"}
    ],
    input_schema={
        "type": "object",
        "properties": {"topic": {"type": "string"}},
        "required": ["topic"]
    }
)

Best Practices

Fast coordinator, smart specialists — use a fast model (anthropic/default) for the coordinator; use reasoning models for specialists that need deep thinking
Clear delegation — name your agent-tools descriptively so the coordinator knows when to use each
Structured handoffs — define output schemas on specialists so the coordinator gets predictable data
Test individually first — make sure each specialist works well on its own before wiring them together
Monitor costs — multi-agent runs consume more credits; price marketplace agents accordingly

Next Steps

Custom Tools & MCP — connect agents to external services
Webhooks — get notified when multi-agent runs complete

Why Handoffs?​

Architecture​

Building a Multi-Agent System​

Step 1: Create Specialist Agents​

Step 2: Create the Coordinator​

Step 3: Run the System​

Patterns​

Coordinator-Specialist​

Pipeline​

Fan-Out​

Best Practices​

Next Steps​