Multi-Agent Workflows

Purpose and Scope

A multi-agent workflow is an application design where more than one agent participates in solving a user request. In LlamaIndex terminology, an agent is a specific system that uses an LLM, memory, and tools to handle inputs from outside users. The broader word agentic applies to systems that contain LLM decision-making even when they are not packaged as a single agent. This distinction matters because a multi-agent system can be composed from several ordinary agents, workflow steps, tool calls, and deployment boundaries rather than from a single monolithic prompt.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx

This page focuses on the workflow-level decisions developers make when coordinating agents: how tools are exposed, how memory is scoped, how control moves from one agent to another, and where trust gates belong. The supplied repository docs show agents as workflow-compatible objects such as FunctionAgent, with examples that run asynchronously and loop through tool selection, tool execution, history updates, and another LLM invocation. Multi-agent designs extend that same loop by deciding which agent owns the next step and which tools or external connections it may use.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx, docs/src/content/docs/framework/workflows/_meta.yml

Relevant Source Files

• docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx - Defines the reader-facing agent model, the FunctionAgent starter example, the tool-call loop, memory customization, tool configuration terminology, multimodal message support, and the streaming caveat.
• docs/src/content/docs/framework/module_guides/mcp/llamaindex_mcp.md - Documents how MCP servers are converted into LlamaIndex tools with BasicMCPClient and McpToolSpec, then passed into agents.
• docs/src/content/docs/framework/workflows/_meta.yml - Places Workflows as a first-class documentation area, which is important because multi-agent systems are usually orchestration problems, not only agent-constructor problems.
• docs/src/content/docs/framework/module_guides/_meta.yml - Places the component guides in the framework documentation structure, showing that agents, tools, deployment, and MCP live alongside other reusable framework components.
• docs/src/content/docs/framework/module_guides/deploying/_meta.yml - Groups deployment topics, including deployable agent interfaces, under the Deploying section.
• docs/src/content/docs/framework/module_guides/deploying/agents/_meta.yml - Establishes Agents as a deployment guide subsection for operationalizing agent systems.

Core Primitives

The smallest useful unit in these docs is FunctionAgent, an agent class that uses an LLM provider's function or tool-calling capability. Its constructor receives a list of tools, an LLM instance such as OpenAI(model="gpt-4o-mini"), and a system_prompt that defines the agent's role. The same page contrasts FunctionAgent with ReActAgent and CodeActAgent, which use different prompting strategies for tool execution. In a multi-agent workflow, these are not mutually exclusive choices; one agent might use function calling for reliable API execution while another uses ReAct-style reasoning or code execution patterns.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx

Tools are the main contract between an agent and the outside world. The deployment guide says tools can be plain Python functions, customized with classes such as FunctionTool and QueryEngineTool, or bundled in pre-defined Tool Specs for common APIs. That gives a multi-agent workflow a practical boundary: each agent should receive the smallest set of tools needed for its responsibility. A planner agent might choose a route, a retrieval agent might wrap a query engine tool, and an action agent might call an external API tool, with each role encoded through tool availability and prompt instructions.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx

Memory is the other core primitive. The agent guide states that LlamaIndex agents use ChatMemoryBuffer by default and shows creating a custom memory with ChatMemoryBuffer.from_defaults(token_limit=40000) before passing it into agent.run(..., memory=memory). For multi-agent systems, this forces an explicit state design. Shared memory can help agents maintain a common conversation, but isolated memory can prevent accidental leakage of private intermediate reasoning, tool outputs, or user-specific state between specialized agents.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx

Execution Flow

The single-agent execution loop is the foundation for multi-agent orchestration. The documented flow starts when the agent receives the latest message plus chat history. Tool schemas and chat history are sent to the model API. The model either returns a direct response or selects one or more tool calls. Each tool call is executed, the results are added to chat history, and the agent is invoked again with the updated history until it responds directly or chooses more tools. Multi-agent orchestration repeats this pattern across agent boundaries rather than only within one agent.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx

A useful mental model is to treat each agent handoff like a controlled tool result. One agent finishes a step by producing a message, structured output, or tool result that the workflow passes to another agent. The receiving agent sees only the context the workflow provides, plus whatever memory object is supplied. This is where trust-gated workflows fit naturally: before passing a result to a downstream agent that can take action, the workflow can require human approval, policy validation, or another agent's review. The repository snippets do not define a dedicated approval API here, but the documented execution loop shows the places where gates can be inserted: before tool execution, after tool results, or before the next agent invocation.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx, docs/src/content/docs/framework/workflows/_meta.yml

A minimal multi-agent structure can start from the same asynchronous form as the deployment guide. Instead of one FunctionAgent, create role-specific agents and call them from an orchestrating workflow or application function. Keep each agent's system_prompt narrow, pass only the tools it needs, and decide whether the call should use a shared ChatMemoryBuffer or a fresh role-local memory. When the workflow is meant to be deployed, keep the external interface stable: user input enters the coordinator, internal agents operate behind that boundary, and only approved final responses or actions leave the system.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx, docs/src/content/docs/framework/module_guides/deploying/agents/_meta.yml

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
 
research_agent = FunctionAgent(
    tools=[search_tool],
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt="Research the user's request and return concise evidence.",
)
 
action_agent = FunctionAgent(
    tools=[ticket_tool],
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt="Create tickets only from approved research summaries.",
)
 
research = await research_agent.run("Investigate the customer issue")
# Insert review, validation, or human approval before action.
result = await action_agent.run(str(research))

MCP, Connections, and Tool Boundaries

MCP support expands the tool boundary beyond local Python functions. The MCP guide documents installing llama-index-tools-mcp, connecting with BasicMCPClient, wrapping the client in McpToolSpec, and calling to_tool_list_async() to turn the server capabilities into LlamaIndex tool definitions. Once converted, the resulting tools list is passed directly into a FunctionAgent. That means a remote MCP server and a local Python function participate through the same agent-facing tool list, while connection details remain isolated in the MCP client setup.

Sources: docs/src/content/docs/framework/module_guides/mcp/llamaindex_mcp.md

The connection type changes the operational trust model. The MCP guide shows Server-Sent Events with an /sse URL, streamable HTTP with an /mcp URL, and a local process launched with a command plus args=["server.py"]. In a multi-agent workflow, those transports should be assigned intentionally. A research agent may safely consume read-only MCP tools over HTTP, while an action agent with write privileges should be placed behind review or policy checks. Local process MCP tools should be treated as part of the runtime environment, with deployment controls matching their filesystem and process access.

Sources: docs/src/content/docs/framework/module_guides/mcp/llamaindex_mcp.md

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
 
mcp_client = BasicMCPClient("http://127.0.0.1:8000/sse")
mcp_tool_spec = McpToolSpec(client=mcp_client)
tools = await mcp_tool_spec.to_tool_list_async()
 
agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-5-mini"),
    system_prompt="You are a helpful assistant.",
)

Deployment and Documentation Mapping

The documentation structure separates Workflows, Component Guides, Deploying, and Deploying Agents. That organization is a useful implementation cue. Workflows are where orchestration concepts belong; component guides explain reusable parts such as tools, MCP, and agent memory; deployment guides explain how an agent-facing system is exposed and operated. Multi-agent systems cross all of these areas. They are built from components, coordinated as workflows, and deployed as a stable agent application rather than as a collection of unrelated scripts.

Sources: docs/src/content/docs/framework/workflows/_meta.yml, docs/src/content/docs/framework/module_guides/_meta.yml, docs/src/content/docs/framework/module_guides/deploying/_meta.yml, docs/src/content/docs/framework/module_guides/deploying/agents/_meta.yml

The deployment guide also notes streaming behavior: streaming is enabled by default for FunctionAgent, but some models may not support streaming LLM output, and FunctionAgent(..., streaming=False) can disable it. For multi-agent systems, make this a coordinator-level decision. Streaming internal agent output can be useful for observability or debugging, but user-facing streams should avoid exposing unreviewed intermediate steps from specialist agents. A trust-gated workflow may buffer internal responses, run approval checks, and only stream the final approved answer or action status.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx

Multimodal inputs add another design dimension. The deployment guide shows chat messages built with content blocks such as TextBlock and ImageBlock, allowing an agent to reason over images and text when the selected LLM supports those modalities. In a multi-agent workflow, modality-aware routing can keep the system maintainable. A vision-capable agent can interpret an image, a retrieval agent can look up supporting text, and an action agent can use the resulting structured summary. The key is to route content blocks deliberately instead of assuming every agent and model can process every modality.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx

Compact Reference

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx, docs/src/content/docs/framework/module_guides/mcp/llamaindex_mcp.md

Next Steps

Start by building one reliable FunctionAgent with a narrow tool list and explicit memory behavior. Then split responsibilities only when a second role needs different tools, model capabilities, prompts, state, or approval rules. Add MCP tools when external servers should provide capabilities through a standard connection boundary, and treat each MCP transport as an operational decision. For production-facing systems, keep the deployed interface simple: one coordinator accepts user input, internal agents collaborate through workflow logic, and trust gates control which tool calls, handoffs, streams, and final actions are allowed to reach the outside world.

Sources: docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx, docs/src/content/docs/framework/module_guides/mcp/llamaindex_mcp.md, docs/src/content/docs/framework/module_guides/deploying/_meta.yml