Workflows

Purpose and Scope

Workflows are the orchestration layer for building multi-step LlamaIndex applications. In the first-party documentation, workflows are presented as event-driven software that can combine agents, data connectors, and tools to complete a task. That framing matters because many LlamaIndex systems are not a single retrieval call: they may load data, route a user request, call an LLM, invoke tools, update memory, and return intermediate or final outputs. This page explains how the repository documentation positions workflows, how agent workflows fit into deployment guidance, and how tool integrations such as MCP become workflow inputs rather than isolated utilities.

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/agents/index.mdx

A workflow should be read as a runtime pattern, not just a documentation category. The navigation metadata gives Workflows their own first-class section, while the component guides and deploying guides place agents inside a broader framework of modules and production concerns. That structure signals a common reader journey: learn core components, assemble them into an agentic or RAG process, then deploy the resulting interface. In practical terms, a workflow is the place where LLM decisions, tool execution, memory, chat history, and external connections are ordered into a repeatable application behavior.

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

Relevant Source Files

• docs/src/content/docs/framework/workflows/_meta.yml — Defines the Workflows section label and marks it as a collapsible first-class documentation area.
• docs/src/content/docs/framework/module_guides/_meta.yml — Places Component Guides in the framework navigation, which is the parent learning path for workflow-adjacent modules.
• docs/src/content/docs/framework/module_guides/deploying/_meta.yml — Defines the Deploying section that contains runtime guidance for production-facing components.
• docs/src/content/docs/framework/module_guides/deploying/agents/_meta.yml — Defines the Agents subsection under Deploying, connecting agent runtime guidance to the deployment path.
• docs/src/content/docs/framework/module_guides/deploying/agents/index.mdx — Provides the concrete FunctionAgent example, agent loop description, memory customization, tools guidance, multimodal messaging, and streaming note.
• docs/src/content/docs/framework/module_guides/mcp/llamaindex_mcp.md — Shows how MCP servers are converted into LlamaIndex tools and then passed into an agent workflow.

Core Primitives

The most important primitive shown in the supplied deployment guide is FunctionAgent from llama_index.core.agent.workflow. It is created with a list of tools, an LLM such as OpenAI(model="gpt-4o-mini"), and a system_prompt. Although the example is documented under deployed agents, the imported module name makes the workflow relationship explicit: an agent is not only a model wrapper, but a workflow-compatible runtime that can receive input, inspect chat history, decide whether to answer or call tools, and repeat until the task is complete.

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

Tools are the next primitive. The deployment guide starts with a plain Python function, multiply(a: float, b: float) -> float, and passes it directly into FunctionAgent(tools=[multiply], ...). It also explains that tools can be customized with FunctionTool and QueryEngineTool, and that Tool Specs provide predefined collections for common APIs. In a workflow, tools are the action surface: they are the operations an LLM can choose when natural-language reasoning must turn into a concrete calculation, query, API call, or data access step.

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

Memory and messages are also workflow primitives because they carry state across turns and steps. The agent deployment guide says LlamaIndex agents use ChatMemoryBuffer by default and shows how to pass a custom memory object created with ChatMemoryBuffer.from_defaults(token_limit=40000) into agent.run(..., memory=memory). The same page introduces multimodal chat messages through ChatMessage, TextBlock, and ImageBlock, which means a workflow can be stateful and modality-aware rather than limited to stateless text prompts.

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

Execution Flow

A typical workflow begins when client code calls await agent.run(...). The documented agent loop then gathers the latest user message and chat history, sends tool schemas and history to the model API, and waits for the model to choose either a direct response or one or more tool calls. When tool calls are returned, the runtime executes each call, appends the results to chat history, and invokes the agent again with the updated context. This loop is the core orchestration behavior: the workflow repeatedly moves between reasoning, action, observation, and final response.

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

That loop explains why workflows are useful beyond simple question answering. A workflow can encode a RAG process, a function-calling assistant, a ReAct-style agent, a CodeAct agent, a text-to-SQL flow, or a multi-agent handoff pattern. The official examples index points readers from agent examples to agentic workflow examples such as Function Calling Agent from Scratch, Basic RAG, and Advanced Text-to-SQL. Those examples all share the same design idea: multiple steps are made explicit so the application can control how context, tools, model calls, and outputs are sequenced.

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

Streaming is an execution concern because workflow clients often need intermediate output or incremental model tokens. The agent deployment page notes that streaming is enabled by default for FunctionAgent, and that some models may not support streaming LLM output. The documented escape hatch is to construct the agent with streaming=False. In production workflows, this option is important because the same orchestration logic may be used with different model providers, and the workflow should preserve behavior even when a provider cannot stream responses.

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

Tools, MCP, and External Connections

MCP support expands workflow tooling from local Python functions to externally hosted capabilities. The MCP guide installs llama-index-tools-mcp, creates a BasicMCPClient, wraps it in McpToolSpec, and calls await mcp_tool_spec.to_tool_list_async() to convert a server into standard LlamaIndex tool definitions. Once converted, the tools are passed into FunctionAgent exactly like local tools. This is the key workflow boundary: external capabilities are normalized into the same tool contract that the agent loop already knows how to call.

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

MCP connections differ from local functions because the operation may live behind a transport rather than inside the Python process. The documented BasicMCPClient examples cover Server-Sent Events with an /sse endpoint, streamable HTTP with an /mcp endpoint, and a local process launched with a command such as python plus args=["server.py"]. For workflow authors, this means tool availability can come from a remote service, an HTTP endpoint, or a subprocess while still participating in the same agent run loop and chat-history update cycle.

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

pip install llama-index-tools-mcp

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()

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
 
agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-5-mini"),
    system_prompt="You are a helpful assistant.",
)
 
response = await agent.run("Your query here")

System-to-Code Mapping

The most direct code-level contract visible in these sources is the constructor-and-run pattern for FunctionAgent. A workflow author supplies tools, an LLM, and a system prompt, then awaits agent.run(...). The same guide shows customization through memory=memory at run time and streaming=False at construction time. These are small surface-area controls, but they determine the major runtime properties of the workflow: available actions, model provider, behavioral instructions, conversational state, and output delivery mode.

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

The documentation split also gives a practical architecture rule. Use component guides to understand building blocks, use workflows to compose those blocks into multi-step behavior, and use deploying guides when that behavior becomes a service-facing agent or chat interface. MCP belongs in this map as a connection mechanism that supplies tools to the workflow. It does not replace local tools; it broadens the source of callable capabilities while preserving the same agent-facing list of tool definitions.

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

Practical Workflow Checklist

Start with the task boundary: decide whether the workflow is a RAG answerer, a calculator-style function-calling assistant, a multimodal agent, or a tool-connected automation. Next, define the tools the model may call. If the tool is local, a documented Python function can be enough; if it comes from an MCP server, build a BasicMCPClient, convert it with McpToolSpec, and pass the resulting tool list to the agent. Then choose the LLM, write the system_prompt, and decide whether the default streaming behavior is compatible with the selected model provider.

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

For stateful workflows, make memory an explicit design decision instead of an afterthought. The default ChatMemoryBuffer is suitable for many agents, but the deployment guide shows that a custom token limit can be declared and passed into agent.run. For multimodal workflows, construct ChatMessage values with content blocks so the agent receives text and images in the same conversational structure. These choices affect not only quality, but also cost, latency, and reproducibility because the workflow loop sends history and schemas back to the model across iterations.

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

Next steps: read the Agents Overview for the broader agent model, Tools for local and packaged tool contracts, MCP Tools for external tool servers, Sessions for stateful runtime behavior, and Streaming for incremental outputs. If you are deploying an application, follow the deploying agents path after the workflow works locally, because production concerns such as model support, streaming compatibility, memory scope, and external tool connectivity are easiest to reason about once the orchestration loop is already clear.

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