run-llama/llama_index · error · ValueError

Handoff prompt must contain {agent_info}

Error message

Handoff prompt must contain {agent_info}

What it means

When handoff_prompt is supplied as a plain string, AgentWorkflow wraps it in a PromptTemplate and validates that it contains the {agent_info} placeholder. That placeholder is where the list of available agents (name + description) is rendered so the LLM knows its handoff targets; without it the prompt cannot inform routing.

Source

Thrown at llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:159

        self.agents = {cfg.name: cfg for cfg in agents}
        if len(agents) == 1:
            root_agent = agents[0].name
        elif root_agent is None:
            raise ValueError("Exactly one root agent must be provided")
        else:
            root_agent = root_agent

        if root_agent not in self.agents:
            raise ValueError(f"Root agent {root_agent} not found in provided agents")

        self.root_agent = root_agent
        self.initial_state = initial_state or {}

        handoff_prompt = handoff_prompt or DEFAULT_HANDOFF_PROMPT
        if isinstance(handoff_prompt, str):
            handoff_prompt = PromptTemplate(handoff_prompt)
            if "{agent_info}" not in handoff_prompt.get_template():
                raise ValueError("Handoff prompt must contain {agent_info}")
        self.handoff_prompt = handoff_prompt

        handoff_output_prompt = handoff_output_prompt or DEFAULT_HANDOFF_OUTPUT_PROMPT
        if isinstance(handoff_output_prompt, str):
            handoff_output_prompt = PromptTemplate(handoff_output_prompt)
            if (
                "{to_agent}" not in handoff_output_prompt.get_template()
                or "{reason}" not in handoff_output_prompt.get_template()
            ):
                raise ValueError(
                    "Handoff output prompt must contain {to_agent} and {reason}"
                )
        self.handoff_output_prompt = handoff_output_prompt

        state_prompt = state_prompt or DEFAULT_STATE_PROMPT
        if isinstance(state_prompt, str):
            state_prompt = PromptTemplate(state_prompt)
            if (

View on GitHub (pinned to afd0fef371)

Solutions

1. Add {agent_info} to your custom string, e.g. handoff_prompt="You have access to these agents:\n{agent_info}\nHand off when appropriate."
2. Or omit handoff_prompt entirely to use DEFAULT_HANDOFF_PROMPT.
3. Check handoff_prompt.get_template() contains the exact token '{agent_info}' — double braces or renamed placeholders fail.

Example fix

# before
wf = AgentWorkflow(
    agents=[...], root_agent="researcher",
    handoff_prompt="Pass the task to a better agent.",  # ValueError
)

# after
wf = AgentWorkflow(
    agents=[...], root_agent="researcher",
    handoff_prompt=(
        "You can hand off to these agents:\n{agent_info}\n"
        "Use handoff when another agent is better suited."
    ),
)

def check_handoff_prompt(tpl: str):
    if "{agent_info}" not in tpl:
        raise ValueError("handoff_prompt must contain {agent_info}")
    return tpl

When it happens

Trigger: AgentWorkflow(agents=[...], handoff_prompt="Hand off to another agent if needed.") — any string template missing the literal {agent_info} token. Only string prompts are validated; pre-built PromptTemplate objects are accepted as-is.

Common situations: Customizing the handoff prompt for tone/language and dropping the placeholder; copying a prompt from an older version with different placeholders; escaping braces so the template no longer matches.

Related errors

• Handoff output prompt must contain {to_agent} and {reason}
• State prompt must contain {state} and {msg}
• All agents must have a name in a multi-agent workflow
• All agents must have a description in a multi-agent workflow
• Initial state is not supported per-agent in AgentWorkflow

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/d5c31840caa87481. Report an issue: GitHub.