[Question]: How to call rag in the agent

[likaiyuan00]

Question Validation

• I have searched both the documentation and discord for an answer.

Question

How to call rag in the agent
Using this has no effect
budget_tool = QueryEngineTool.from_defaults(
query_engine=query_engine,
name="rag",
description="rag",
)
workflow = AgentWorkflow.from_tools_or_functions(
[budget_tool, weather],
llm=llm,
system_prompt="For unknown questions, the rag tool must be used to answer them",
verbose=True
)
reference https://github.com/run-llama/python-agents-tutorial/blob/main/1_basic_agent.py
I need help

[dosubot]

To get RAG (your QueryEngineTool) to be called in an agent workflow, make sure of these key points:

• The LLM you use must support function/tool calling (e.g., OpenAI GPT-3.5/4 function-calling models). If not, the agent won't invoke tools even if you register them and set a system prompt.
• The tool's name and especially its description must be clear and specific about when to use it. Generic names/descriptions like "rag" or "rag" are often ignored by the agent. Try something like:

  budget_tool = QueryEngineTool.from_defaults(
      query_engine=query_engine,
      name="budget_lookup",
      description="Use this tool to answer any question that requires searching the budget database or when you don't know the answer."
  )

• The system prompt should explicitly instruct the agent to use the tool for unknown or data-backed questions, but the LLM still decides when to call it. Prompt engineering helps, but can't force tool usage.
• Lower the LLM temperature (e.g., temperature=0.0) to make the agent more likely to follow instructions and use tools.
• Use verbose=True to debug and see if the agent is even considering the tool.
• Make sure you are on the latest LlamaIndex version. There were bugs in older versions where QueryEngineTool wouldn't work in AgentWorkflow—upgrade if you see odd errors or no tool calls at all (see here).
• If using AzureOpenAI, disable streaming, as it's not supported and can break tool invocation (see here).

Example pattern:

from llama_index.core.tools import QueryEngineTool
from llama_index.core.agent.workflow import AgentWorkflow

budget_tool = QueryEngineTool.from_defaults(
    query_engine=query_engine,
    name="budget_lookup",
    description="Use this tool to answer any question that requires searching the budget database or when you don't know the answer."
)
workflow = AgentWorkflow.from_tools_or_functions(
    [budget_tool, weather],
    llm=llm,
    system_prompt="If you don't know the answer, always use the budget_lookup tool to search the budget database.",
    verbose=True
)
response = await workflow.run(user_msg="What was the travel budget last year?")

If the agent still doesn't call the tool, try making the tool description even more explicit, lower the temperature, and check the logs for tool call attempts. The agent framework waits for the LLM to emit a tool call; it won't force it just because of the prompt (details).

For more, see the official tutorial and this Hugging Face guide.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[likaiyuan00]

@dosu
I have referred to your instance, but found that when calling the tool, it does not retrieve the knowledge base. Using query_degine. query() alone is effective,

要在代理工作流中调用 RAG（您的 QueryEngineTool），请确保以下几个关键点：

• 您使用的LLM必须支持函数/工具调用（例如，OpenAI GPT-3.5/4函数调用模型）。否则，即使您注册了工具并设置了系统提示符，智能体也不会调用这些工具。
• 工具的名称，尤其是其描述，必须清晰明确地说明何时使用。诸如“工具”"rag"或“工具”之类的通用名称/描述"rag"通常会被代理忽略。尝试使用类似这样的名称/描述：
  budget_tool = QueryEngineTool.from_defaults(
  query_engine=query_engine,
  name="budget_lookup",
  description="Use this tool to answer any question that requires searching the budget database or when you don't know the answer."
  )
• 系统提示应明确指示客服人员在遇到未知问题或需要数据支持的问题时使用该工具，但最终调用该工具的决策权仍然掌握在语言学习模型（LLM）手中。提示设计有所帮助，但无法强制客服人员使用该工具。
• 降低 LLM 温度（例如，temperature=0.0），使智能体更有可能遵循指示和使用工具。
• 用于verbose=True调试并查看代理是否正在考虑使用该工具。
• 请确保您使用的是最新版本的 LlamaIndex。旧版本存在一些错误，导致 QueryEngineTool 在 AgentWorkflow 中无法正常工作——如果您看到奇怪的错误或完全没有工具调用，请升级（参见此处）。
• 如果使用 AzureOpenAI，请禁用流式传输，因为它不受支持，并且可能会破坏工具调用（请参阅此处）。

示例模式：

from llama_index.core.tools import QueryEngineTool
from llama_index.core.agent.workflow import AgentWorkflow

budget_tool = QueryEngineTool.from_defaults(
query_engine=query_engine,
name="budget_lookup",
description="Use this tool to answer any question that requires searching the budget database or when you don't know the answer."
)
workflow = AgentWorkflow.from_tools_or_functions(
[budget_tool, weather],
llm=llm,
system_prompt="If you don't know the answer, always use the budget_lookup tool to search the budget database.",
verbose=True
)
response = await workflow.run(user_msg="What was the travel budget last year?")
如果代理仍然没有调用工具，请尝试更详细地描述工具，降低温度，并检查日志中是否有工具调用尝试。代理框架会等待 LLM 发出工具调用；它不会仅仅因为提示（详情）就强制调用。

更多详情，请参阅官方教程和这篇拥抱脸指南。

回复时只需提及@dosu即可。

我做得怎么样？好|无关|错误|冗长|幻觉|举报 🐛 |其他

   

[dosubot]

你的问题很常见，通常和以下几点有关：

1. LlamaIndex 版本：请确认你用的是 llama-index 和 llama-index-core >= 0.12.28。老版本有 bug，导致 QueryEngineTool 在 AgentWorkflow 里无法被正常调用，升级后问题已解决。参考

2. LLM 支持：确保你用的 LLM（如 OpenAI GPT-3.5/4）支持函数/工具调用。如果用的是开源模型或不支持 function calling 的 LLM，Agent 无法自动调用工具。参考

3. 工具名称和描述：工具名和描述要非常具体，不能用 "rag" 这种通用词。比如：

   rag_tool = QueryEngineTool.from_defaults(
       query_engine=query_engine,
       name="knowledge_search",
       description="Use this tool to answer any question that requires searching the knowledge base or when you don't know the answer."
   )

   工具描述越具体，LLM 越容易调用。参考

4. system_prompt：system_prompt 也要和工具描述一致，明确告诉 Agent 什么时候用工具。

5. AzureOpenAI 用户：如果你用 AzureOpenAI，必须关闭 streaming（stream=False），否则工具调用会失败。参考

6. 调试：设置 verbose=True，观察日志里 Agent 是否尝试调用工具。如果没有调用，通常是 LLM 理解不到工具用途，或者 prompt/tool schema 不匹配。参考

7. 直接 query_engine.query() 有效但 Agent 不调用：说明知识库和 QueryEngine 没问题，是 Agent 没有触发工具调用。重点检查上面几点。

如果你确认以上都没问题，建议贴出你的完整代码片段（包括工具注册、AgentWorkflow 配置、system_prompt、LLM 配置等），我可以帮你进一步定位问题。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[likaiyuan00]

你的问题很常见，通常和以下几点有关：

1. LlamaIndex 版本：请确认你用的是 llama-index 和 llama-index-core >= 0.12.28。老版本有 bug，导致 QueryEngineTool 在 AgentWorkflow 里无法被正常调用，升级后问题已解决。参考

2. LLM 支持：确保你用的 LLM（如 OpenAI GPT-3.5/4）支持函数/工具调用。如果用的是开源模型或不支持 function calling 的 LLM，Agent 无法自动调用工具。参考

3. 工具名称和描述：工具名和描述要非常具体，不能用 "rag" 这种通用词。比如：
   rag_tool = QueryEngineTool.from_defaults(
   query_engine=query_engine,
   name="knowledge_search",
   description="Use this tool to answer any question that requires searching the knowledge base or when you don't know the answer."
   )

   工具描述越具体，LLM 越容易调用。参考

4. system_prompt：system_prompt 也要和工具描述一致，明确告诉 Agent 什么时候用工具。

5. AzureOpenAI 用户：如果你用 AzureOpenAI，必须关闭 streaming（stream=False），否则工具调用会失败。参考

6. 调试：设置 verbose=True，观察日志里 Agent 是否尝试调用工具。如果没有调用，通常是 LLM 理解不到工具用途，或者 prompt/tool schema 不匹配。参考

7. 直接 query_engine.query() 有效但 Agent 不调用：说明知识库和 QueryEngine 没问题，是 Agent 没有触发工具调用。重点检查上面几点。

如果你确认以上都没问题，建议贴出你的完整代码片段（包括工具注册、AgentWorkflow 配置、system_prompt、LLM 配置等），我可以帮你进一步定位问题。

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

   

@dosu My current version is 0.14.12
Is outputting logs helpful，Is there a problem with the operation at my place

None of PyTorch, TensorFlow >= 2.0, or Flax have been found. Models won't be available and only tokenizers, configuration and file/data utilities can be used.
加载了 2 个文档
Parsing nodes: 100%|██████████| 2/2 [00:00<00:00, 8.76it/s]
Generating embeddings: 100%|██████████| 3/3 [00:00<00:00, 3.89it/s]
2026-01-29 09:13:55,885 - INFO - HTTP Request: POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions "HTTP/1.1 200 OK"
query_engine.query: 小明是上海大学计算机与信息工程学院计算机科学与技术专业的学生，今年20岁。
2026-01-29 09:13:57,793 - INFO - HTTP Request: POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions "HTTP/1.1 200 OK"
workflow.run: “小明”是一个常见的中文名字，通常用于举例或泛指某个人。如果你有更具体的背景信息或上下文，可以提供给我，我可以更好地帮助你！

[dosubot]

输出 logs（事件流）对排查 agent 是否调用 RAG 工具非常有帮助，尤其是在 LlamaIndex 0.14.x 版本。你可以用如下方式捕获详细的工具调用和 LLM 推理过程：

from llama_index.core.agent.workflow import ToolCall, ToolCallResult, AgentStream

handler = workflow.run(user_msg="你的问题")
async for event in handler.stream_events():
    if isinstance(event, ToolCall):
        print(f"ToolCall: {event.tool_name} with args: {event.tool_kwargs}")
    elif isinstance(event, ToolCallResult):
        print(f"ToolCallResult: {event.tool_output}")
    elif isinstance(event, AgentStream):
        print(event.delta, end="", flush=True)

这样可以实时看到 agent 是否尝试调用工具、传递了什么参数、工具返回了什么结果等，便于定位问题。参考

你的 setup 目前最大的问题很可能是 DashScope LLM 和 FunctionAgent 兼容性差。DashScope 返回的响应对象和 LlamaIndex 期望的格式不一致，导致 agent 无法正确识别和调用工具（即使工具注册和 prompt 没问题）。这是 DashScope 目前和 LlamaIndex agent 的已知兼容性 bug，推荐的解决方案是直接用 ReActAgent 替代 FunctionAgent：

from llama_index.core.agent import ReActAgent

agent = ReActAgent(
    tools=[your_query_engine_tool],
    llm=your_dashscope_llm,
    system_prompt="你是一个可以查知识库的助手，遇到不知道的问题请调用知识库工具。"
)

如果你必须用 FunctionAgent，可以尝试 patch 本地 llama-index-llms-dashscope，避免 assistant 消息带空的 tool_calls 字段（见这个修复建议），但最简单的办法还是用 ReActAgent。

建议你先用上面的事件流代码跑一遍，贴出完整的 agent 注册、system_prompt、LLM 配置和事件流输出，这样可以进一步定位 agent 是否有尝试调用工具、DashScope 返回了什么等细节。

PyTorch/TensorFlow/Flax 未安装的提示和本问题无关，只影响本地模型加载，不影响 DashScope 或远程 LLM。

如还有问题，欢迎贴出详细代码和日志。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[likaiyuan00]

输出 logs（事件流）对排查 agent 是否调用 RAG 工具非常有帮助，尤其是在 LlamaIndex 0.14.x 版本。你可以用如下方式捕获详细的工具调用和 LLM 推理过程：

from llama_index.core.agent.workflow import ToolCall, ToolCallResult, AgentStream

handler = workflow.run(user_msg="你的问题")
async for event in handler.stream_events():
if isinstance(event, ToolCall):
print(f"ToolCall: {event.tool_name} with args: {event.tool_kwargs}")
elif isinstance(event, ToolCallResult):
print(f"ToolCallResult: {event.tool_output}")
elif isinstance(event, AgentStream):
print(event.delta, end="", flush=True)
这样可以实时看到 agent 是否尝试调用工具、传递了什么参数、工具返回了什么结果等，便于定位问题。参考

你的 setup 目前最大的问题很可能是 DashScope LLM 和 FunctionAgent 兼容性差。DashScope 返回的响应对象和 LlamaIndex 期望的格式不一致，导致 agent 无法正确识别和调用工具（即使工具注册和 prompt 没问题）。这是 DashScope 目前和 LlamaIndex agent 的已知兼容性 bug，推荐的解决方案是直接用 ReActAgent 替代 FunctionAgent：

from llama_index.core.agent import ReActAgent

agent = ReActAgent(
tools=[your_query_engine_tool],
llm=your_dashscope_llm,
system_prompt="你是一个可以查知识库的助手，遇到不知道的问题请调用知识库工具。"
)
如果你必须用 FunctionAgent，可以尝试 patch 本地 llama-index-llms-dashscope，避免 assistant 消息带空的 tool_calls 字段（见这个修复建议），但最简单的办法还是用 ReActAgent。

建议你先用上面的事件流代码跑一遍，贴出完整的 agent 注册、system_prompt、LLM 配置和事件流输出，这样可以进一步定位 agent 是否有尝试调用工具、DashScope 返回了什么等细节。

PyTorch/TensorFlow/Flax 未安装的提示和本问题无关，只影响本地模型加载，不影响 DashScope 或远程 LLM。

如还有问题，欢迎贴出详细代码和日志。

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

   

@dosu
It seems that I haven't used the tool yet. How can I ensure that I can use a certain tool as a backup

Parsing nodes: 100%|██████████| 2/2 [00:00<00:00, 8.45it/s]
Generating embeddings: 100%|██████████| 3/3 [00:00<00:00, 4.38it/s]
2026-01-29 09:56:54,008 - INFO - HTTP Request: POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions "HTTP/1.1 200 OK"
query_engine.query: 小明是上海大学计算机与信息工程学院计算机科学与技术专业的学生，今年20岁。
2026-01-29 09:56:55,522 - INFO - HTTP Request: POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions "HTTP/1.1 200 OK"
2026-01-29 09:56:57,963 - INFO - HTTP Request: POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions "HTTP/1.1 200 OK"
Thought: 我无法通过提供的工具来确定“小明”是谁，因为这可能是一个常见的名字，没有具体的上下文信息。
Answer: “小明”是一个常见的中文名字，通常用作示例或代称。如果你有更多上下文信息，可以提供更具体的细节，我可以帮助你进一步解答！workflow.run: “小明”是一个常见的中文名字，通常用于举例或泛指某个人。如果你有更多上下文或具体信息，我可以更好地帮助你！

[dosubot]

LlamaIndex 的 Agent（无论是 FunctionAgent 还是 ReActAgent）都不能 100% 保证“遇到不会的问题就一定调用某个工具”，因为工具调用的决策权在 LLM（大模型）本身，系统提示和工具描述只能“强烈建议”而不能强制执行。尤其是 DashScope 这类非 OpenAI LLM，function calling 支持和兼容性有限，FunctionAgent 经常无法正确触发工具调用，推荐直接用 ReActAgent 以获得更好的兼容性和工具调用率 参考1 参考2。

最佳实践：

• 工具名和描述要非常具体（如“knowledge_search”，“Use this tool to answer any question that requires searching the knowledge base or when you don't know the answer.”），不能用“rag”这种泛泛的名字。
• system_prompt 要和工具描述一致，明确告诉 Agent“遇到不知道的问题必须用 knowledge_search 工具”。
• LLM temperature 设为 0.0，减少 LLM 自作主张直接回答的概率。
• 用事件流（ToolCall/ToolCallResult/AgentStream）实时观察 agent 是否尝试调用工具。

但即使如此，LLM 还是可能直接输出答案而不走工具。想要“兜底”强制用工具，推荐如下方案：

1. 先跑一遍 agent，判断输出是否为工具调用结果。
2. 如果不是（比如输出是泛泛的 LLM 回答），你可以手动再用 query_engine.query() 兜底补充答案。

示例代码（伪代码，需根据你的实际 agent 封装调整）：

# 1. 运行 agent
response = await agent.run(user_msg="你的问题")
# 2. 检查 response 是否为工具调用结果
if not response.tool_calls:
    # 3. 如果不是，手动调用 query_engine 兜底
    kb_result = query_engine.query("你的问题")
    print("兜底知识库答案：", kb_result)
else:
    print("Agent 工具调用结果：", response)

总结：

• 没有内置“强制兜底”机制，必须用后处理逻辑手动补救 参考。
• 推荐用 ReActAgent + 明确 prompt + 明确工具描述 + 低温度 + 事件流调试，最大化工具调用概率。
• 兜底逻辑建议如上，先跑 agent，再判断是否需要手动 query_engine.query()。

如需进一步定位问题，欢迎贴出你的 agent 注册、工具定义、system_prompt 代码片段和事件流日志。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}