LlamaIndex AgentWorkflow Report Swarm

What This Builds

This recipe implements a handoff-based agent swarm with LlamaIndex AgentWorkflow. You declare a set of specialist agents, name the root, and let the workflow manage hand-offs: each agent does its part and explicitly hands control to the next one until a final answer is returned. At any point an agent can also hand control back to the user.

The concrete use case is collaborative report generation with three FunctionAgents:

• ResearchAgent — searches the web and records notes, then hands off to the writer.
• WriteAgent — drafts a markdown report from the notes, then asks the reviewer for feedback (and can hand back to research).
• ReviewAgent — reviews the report and either approves or hands back to the writer for revisions.

Shared initial_state (research notes, report content, review) carries context across handoffs.

The Stack

• LlamaIndex AgentWorkflow — the built-in linear “swarm” pattern; agents declare can_handoff_to=[...] and the workflow streams events as control moves between them.
• LLM bindings — Claude (via the Anthropic Startup Program) or models through OpenRouter for the agents; you can mix a stronger model for review with cheaper models for research/writing.
• Qdrant (Cloud free tier) — back the research agent’s tools with a vector index so it can retrieve from your own corpus in addition to web search.

Step-by-Step Outline

1. Define specialist agents. Create research_agent, write_agent, and review_agent as FunctionAgents, each with a name, description, system prompt, tools, and a can_handoff_to list describing valid transitions.
2. Wire the workflow. Construct AgentWorkflow(agents=[...], root_agent="ResearchAgent", initial_state={...}) with the shared state keys the agents read and write.
3. Run and stream. Call await agent_workflow.run(user_msg=...) and stream events to keep the user informed as control hands off between agents.
4. Choose your control level. For more deterministic control, switch to the orchestrator pattern: expose each agent’s run as a tool on a top-level FunctionAgent so tools always return to the orchestrator. For maximum control, write a custom planner that emits an XML/JSON plan you parse and execute yourself.
5. Extend. Add a citation or fact-check agent to the handoff graph, or persist intermediate state so long runs survive restarts.

Why This Shape Works

AgentWorkflow gives you multi-agent behavior with almost no orchestration code — handoffs, streaming, and shared state come built in. The handoff approach saves an LLM call versus always routing through an orchestrator and reduces the chance an extra coordinator misinterprets the task. When you outgrow the default heuristics, the orchestrator and custom-planner patterns are drop-in upgrades along the same spectrum.

Source

LlamaIndex Developer Documentation, Multi-agent patterns in LlamaIndex (AgentWorkflow swarm, orchestrator, and custom-planner patterns, with code): https://developers.llamaindex.ai/python/framework/understanding/agent/multi_agent/

LlamaIndex blog, Introducing AgentWorkflow: https://www.llamaindex.ai/blog/introducing-agentworkflow-a-powerful-system-for-building-ai-agent-systems