---
title: "Multi-agent overview"
---

This document explains how to define, coordinate, and run multiple Agents within one system. The core of multi-agent system design lies in **role division** and **communication mechanisms**.

With sensible collaboration strategies, you can decompose a complex task into controllable subtasks, improving overall stability and scalability.

## Building a Multi-Agent System

A multi-agent system usually consists of several Agents with independent responsibilities. Common types of the main Agent include:

- **Autonomous Agent**: A general-purpose Agent based on a large language model, supporting natural-language understanding, reasoning, and generation, and configurable with tools, memory, knowledge base, etc.
- **Workflow Agent**: An Agent optimized for a specific execution pattern, including sequential, parallel, and loop execution modes, suited to different task-orchestration scenarios.

### Autonomous Agent

**Definition**: The autonomous Agent is VeADK's core Agent. Built on a large language model, it supports full intelligent conversation, tool calling, and memory management. Based on its configuration, it can **automatically invoke sub-agents or tools** to complete complex tasks.

**Example**: The following life-advice Agent demonstrates the main interaction patterns of an autonomous Agent. The main Agent receives user input, while the sub-agents respectively fetch the weather and give clothing suggestions. The call diagram below shows that, based on the user's prompt, the main Agent first calls the weather Agent to get the weather, then calls the clothing-suggestion Agent to give advice.

```mermaid
graph LR
    A["User asks: clothing advice for Beijing"] --> B["Life-advice assistant (main Agent)"]
    B --> C{"Analyze need, decide which sub-agent to call"}
    C -->|"Needs weather"| D["Weather Agent (sub-agent)"]
    C -->|"Needs clothing advice"| E["Suggester Agent (sub-agent)"]
    D --> F["Return: Beijing weather"]
    E --> G["Return: clothing advice"]
    F --> H["Combine results"]
    G --> H
    H --> I["Final answer: clothing advice based on weather"]
```

Before running, provide your model API key via an environment variable (VeADK reads `MODEL_AGENT_API_KEY` by default):

```bash
export MODEL_AGENT_API_KEY="<your Ark API key>"
```

```python title="llm_agent.py"
import asyncio

from veadk import Agent, Runner
from veadk.tools.demo_tools import get_city_weather

weather_reporter = Agent(
    name="weather_reporter",
    description="A weather reporter agent to report the weather.",
    tools=[get_city_weather],
)

suggester = Agent(
    name="suggester",
    description="A suggester agent that can give some clothing suggestions according to a city's weather.",
    instruction=(
        "Provide clothing suggestions based on weather temperature: "
        "wear a coat when below 15°C, long sleeves when 15-25°C, "
        "short sleeves when above 25°C."
    ),
)

root_agent = Agent(
    name="planner",
    description="A planner that can generate a suggestion according to a city's weather.",
    instruction=(
        "Invoke weather reporter agent first to get the weather, "
        "then invoke suggester agent to get the suggestion. "
        "Return the final response to user."
    ),
    sub_agents=[weather_reporter, suggester],
)

if __name__ == "__main__":
    runner = Runner(root_agent)
    response = asyncio.run(runner.run("Clothing advice for Beijing"))
    print(response)
```

Result:

![Result](/assets/images/agents/llm_agent.png)

### Workflow Agent

**Definition**: A Workflow Agent is a control Agent responsible for scheduling, invoking, and integrating results. It has no language-model capability of its own; instead, through a **user-defined sub-agent workflow category**, it invokes underlying sub-Agents to accomplish the overall task. In VeADK, workflow Agents fall into three categories:

- Sequential Agent: a flow that executes multiple Agents serially, one after another.
- Loop Agent: a flow that executes multiple Agents in a loop until a specific exit condition is met.
- Parallel Agent: a flow that executes multiple Agents in parallel.

The following sections explain how to build each of these three types of multi-agent flow.

#### Sequential Agent

**Example**: The following copywriting Agent demonstrates the execution flow of a Sequential Agent. We implement 3 Agents to run a "greet–farewell" workflow. As shown in the call diagram, the SequentialAgent invokes greeting_agent and goodbye_agent in the user-defined order; after each sub-agent finishes its task, it passes the result to the next Agent.

```mermaid
graph LR
    A["User input: Hi"] --> B["SequentialAgent (sequential)"]
    B --> C{"Call sub-agents in order"}
    C -->|"Step 1"| D["greeting_agent (sub-agent)"]
    D --> E["Return: warm greeting"]
    E -->|"Step 2"| F["goodbye_agent (sub-agent)"]
    F --> G["Return: polite goodbye"]
    G --> H["Final output: greeting + goodbye"]
```

```python title="examples/agent/agents/seq_agent.py"
import asyncio

from veadk import Agent, Runner
from veadk.agents.sequential_agent import SequentialAgent

greeting_agent = Agent(
    name="greeting_agent",
    description="A friendly agent that greets the user.",
    instruction="Greet the user warmly.",
)

goodbye_agent = Agent(
    name="goodbye_agent",
    description="A polite agent that says goodbye to the user.",
    instruction="Say goodbye to the user politely.",
)

root_agent = SequentialAgent(sub_agents=[greeting_agent, goodbye_agent])

if __name__ == "__main__":
    runner = Runner(root_agent)
    response = asyncio.run(runner.run("Hi"))
    print(response)
```

Result:

![Result](/assets/images/agents/seq_agent.png)

#### Loop Agent

**Definition**: A Loop Agent repeatedly executes its sub-Agents until a specific condition is met to exit the loop. It is suited to complex tasks that require iterative refinement, multi-turn dialogue, or conditional judgment.

**Example**: The following poetry-writing Agent demonstrates the execution flow of a Loop Agent. We implement 2 Agents to run a "plan–execute" loop workflow with a maximum of 3 iterations:

- Planner Agent: decides the next action plan based on the user's goal.
- Executor Agent: executes the plan and checks the result, calling the exit function once done.

As shown in the call diagram, the LoopAgent repeatedly invokes planner_agent and executor_agent until executor_agent detects that the task is complete and calls the exit function.

```mermaid
graph LR
    A["User input: write a 3-line autumn poem"] --> B["LoopAgent (loop)"]
    B --> C{"Loop starts"}
    C --> D["Step 1: planner_agent"]
    D --> E["Make a writing plan"]
    E --> F["Step 2: executor_agent"]
    F --> G{"Done?"}
    G -->|"Not done"| H["Execute plan / write poem"]
    H --> I{"Iterations < 3?"}
    I -->|"Yes"| D
    I -->|"No"| J["Force exit"]
    G -->|"Done"| K["Call exit_loop()"]
    K --> L["Loop ends"]
    L --> M["Return final poem"]
```

```python title="examples/agent/agents/loop_agent.py"
import asyncio

from google.adk.tools.tool_context import ToolContext
from veadk import Agent, Runner
from veadk.agents.loop_agent import LoopAgent


def exit_loop(tool_context: ToolContext):
    print(f"  [Tool Call] exit_loop triggered by {tool_context.agent_name}")
    tool_context.actions.escalate = True
    return {}


planner_agent = Agent(
    name="planner_agent",
    description="Decomposes a complex task into smaller actionable steps.",
    instruction=(
        "Given the user's goal and current progress, decide the NEXT step to take. You don't need to execute the step, just describe it clearly. "
        "If all steps are done, respond with 'TASK COMPLETE'."
    ),
)

executor_agent = Agent(
    name="executor_agent",
    description="Executes a given step and returns the result.",
    instruction="Execute the provided step and describe what was done or what result was obtained. If you received 'TASK COMPLETE', you must call the 'exit_loop' function. Do not output any text.",
    tools=[exit_loop],
)

root_agent = LoopAgent(
    sub_agents=[planner_agent, executor_agent],
    max_iterations=3,  # Limit the number of loops to prevent infinite loops
)

if __name__ == "__main__":
    runner = Runner(root_agent)
    response = asyncio.run(runner.run("Write me a three-line poem about autumn"))
    print(response)
```

Result:

![Result](/assets/images/agents/loop_agent.png)

#### Parallel Agent

**Definition**: A Parallel Agent executes multiple sub-Agents simultaneously. It is suited to tasks that can be processed independently, such as pros-and-cons analysis and multi-perspective evaluation, and can significantly improve processing efficiency.

**Example**: The following pros-and-cons analysis Agent demonstrates the execution flow of a Parallel Agent. We implement 2 Agents to analyze the "LLM-as-a-Judge evaluation pattern" in parallel:

- Pros Agent: identifies and explains the advantages of the pattern.
- Cons Agent: identifies and explains the disadvantages of the pattern.

As shown in the call diagram, the ParallelAgent invokes pros_agent and cons_agent at the same time; the two sub-agents run independently and the results are aggregated and returned at the end.

```mermaid
graph LR
    A["User input: analyze pros/cons of LLM-as-a-Judge"] --> B["ParallelAgent (parallel)"]
    B --> C{"Launch sub-agents simultaneously"}
    C --> D["pros_agent (advantages)"]
    C --> E["cons_agent (disadvantages)"]
    D --> F["List advantages"]
    E --> G["List disadvantages"]
    F --> H{"Wait for all results"}
    G --> H
    H --> I["Combine pros & cons"]
    I --> J["Return full analysis"]
```

```python title="examples/agent/agents/parallel_agent.py"
import asyncio

from veadk import Agent, Runner
from veadk.agents.parallel_agent import ParallelAgent

pros_agent = Agent(
    name="pros_agent",
    description="An expert that identifies the advantages of a topic.",
    instruction="List and explain the positive aspects or advantages of the given topic.",
)

cons_agent = Agent(
    name="cons_agent",
    description="An expert that identifies the disadvantages of a topic.",
    instruction="List and explain the negative aspects or disadvantages of the given topic.",
)

root_agent = ParallelAgent(sub_agents=[pros_agent, cons_agent])

if __name__ == "__main__":
    runner = Runner(root_agent)
    response = asyncio.run(runner.run("Analyze the pros and cons of the LLM-as-a-Judge evaluation pattern"))
    print(response)
```

Result:

![Result](/assets/images/agents/parallel_agent.png)

## FAQ

<Accordions>
<Accordion title="Common multi-agent issues and solutions">

**Sub-agent returns no result after being invoked**

- Symptom: After the main Agent invokes a sub-agent, there is no response for a long time or it returns an empty value.
- Solution: Try the Agent-as-a-Tool pattern, invoking the sub-agent as a tool. See [Custom function tools](/en/docs/framework/tools/custom-function).

**Sub-agent is invoked inaccurately or misunderstands the task**

- Symptom: The sub-agent does not correctly understand the task and returns irrelevant content.
- Solution: Switch to a model with stronger comprehension, such as a thinking or reasoning model.

**Data transfer between sub-agents fails**

- Symptom: The output of the previous Agent cannot be correctly received by the next Agent.
- Solution: Check that the data formats are consistent, and ensure the output format matches the next Agent's input requirements.

**Loop invocation causes deadlock**

- Symptom: Agents invoke each other, forming an infinite loop.
- Solution: Set a maximum invocation-depth limit, or use a timeout mechanism.

</Accordion>
</Accordions>
