深入了解LlamaIndex实现Agent代码和原理 - 文章 - 开发者社区

一、介绍

Agent的流程如下，仔细阅读该图就能理解Agent的流转全貌。

picture.image

1、Agent组件类型

LlamaIndex 支持的 Agent 组件类型主要有三种：

FunctionAgent（基于 LLM function calling）；
ReActAgent（基于 ReAct 提示词策略）；
CodeActAgent（自动生成并执行代码）；
此外，还可通过 AgentWorkflow 组合多 agent 协作。



每种 agent 类型适用于不同场景：

FunctionAgent 适合支持函数调用的 LLM，
ReActAgent 适合无函数调用能力的 LLM，
CodeActAgent 适合需要自动代码执行的复杂任务。

2、 Agent 的 Tool

将Agent或 LLM 与函数调用一起使用时，命中准确率在很大程度上依赖于工具名称（Function Name）和参数的描述（工具用途）;优化它们可提升 LLM 调用这些工具的准确率。

LlamaIndex 中 Agent 的 Tool 主要有四类：

FunctionTool ：将任意 Python 函数包装为工具（支持同步和异步）；
QueryEngineTool：包装查询引擎为工具，由于我们的Agenyt继承自 BaseQueryEngine，因此QueryEngineTool也可以包装其他Agent；
ToolSpec：社区提供的工具包，通常用于集成外部服务如 Gmail ；
Utility Tools：如 OnDemandLoaderTool、LoadAndSearchToolSpec，用于增强数据处理能力）。

每种类型都实现了统一的工具接口，便于 agent 自动选择和调用。

picture.image

二、FunctionAgent

1、介绍

在 LlamaIndex 中构建代理时，可以定义一组工具并将其提供给 ReActAgent 或 FunctionAgent。本示例使用 DeepSeek，但该方案适用于任何功能强大的 LLM。

对于支持内置函数调用/工具 API 的 LLM（如 OpenAI、Anthropic 和 Gemini 等），建议优先选择 FunctionAgent。

2、示例代码

1）、本地函数

llm大模型初始化

  
from llama_index.llms.openai_like import OpenAILike  
from llama_index.core import Settings  
  
def init_models():  
    """初始化模型"""  
  
    # llm对话大模型  
    llm = OpenAILike(  
        model="deepseek-ai/DeepSeek-R1",  
        api_base="https://api.siliconflow.cn/v1",  
        api_key="sk-xxxxx",  
        context_window=128000,  
        is_chat_model=True,  
        is_function_calling_model=True,  
    )  
  
  
    Settings.llm = llm  
  
    return Settings  
  
# init_models()

Agent代码

  
from llama_index.core.agent.workflow import FunctionAgent  
from common import llm_model_helper  
llm_model_helper.init_models()  
  
def multiply(a: int, b: int) -> int:  
    """乘法"""  
    return a * b  
  
  
def add(a: int, b: int) -> int:  
    """加法"""  
    print("------")  
    print(f"add方法：a={a},b={b}")  
    ret=a+b+100  
    print(f"结果{ret}")  
    print("------")  
    return ret  
  
def subtract(a: int, b: int) -> int:  
    """减法"""  
    return a - b  
  
  
  
agent = FunctionAgent(  
    tools=[multiply, add, subtract],  
    # llm=Settings.llm,  
    system_prompt="你是一个可以调用工具的助手，结果都以tools返回的结果为准。"  
)  
  
async  def main():  
    response = await agent.run("请计算 3+5")  
    print(response)  
  
if __name__ == "__main__":  
    import asyncio  
    asyncio.run(main())

结果如下

  
------  
add方法：a=3,b=5  
结果108  
------  
  
根据工具返回的结果，3 + 5 的计算结果是 **108**。

代码分析：

1、定义了乘法、加法和减法，加法我故意返回一个错误的结果，验证结果是否出现幻觉；方法支持同步和异步；
2、大模型一定要支持function calling，并且能力足够强大，否则会出现结果不正确或不稳定；
3、系统提示词要不断的验证；
4、function方法名一定要通熟易懂，能够让大模型理解这个方法是干嘛的，方法的注释也要写的清清楚楚；

2）、LlamaIndex查询引擎

上面所示的是 Python 本地函数，下面我们来看下 LlamaIndex 查询引擎：

  
from llama_index.core.tools import QueryEngineTool  
  
  
uber_engine = index.as_query_engine(similarity_top_k=3, llm=query_llm)  
query_engine_tool = QueryEngineTool.from_defaults(  
    query_engine=uber_engine,  
    name="uber_10k",  
    description=(  
        "Provides information about Uber financials for year 2021. "  
        "Use a detailed plain text question as input to the tool."  
    ),  
)  
  
  
agent = FunctionAgent(  
    tools=query_engine_tools,  
    system_prompt="You are an agent that can invoke an agent for text-to-SQL execution.",  
)

3、查询调用了哪些工具

查看调用了哪些tools的方法

  
 response.tool\_calls

4、FunctionTool

从demo中我们可以看出tools的数组里直接存放方法名，那么为啥还要使用FunctionTool呢？

FunctionTool 实现了 LlamaIndex 所有工具的通用接口，包括 __call__、.metadata 方法等，并且包装后能提供一致的元数据（如 schema、名称、描述），方便 agent 调度、调试、记录等。

直接传函数虽然可以工作，但就少了这些额外结构与控制能力。FunctionTool.from_defaults 让普通函数变身为“Agent 上下文可控的工具”，无缝接入多种能力 —— 比如函数调用、Context 访问、回调控制、异步支持等等。

较完善的示例代码如下：

  
from llama_index.core.tools import FunctionTool  
from typing import Annotated  
from llama_index.core.agent.workflow import FunctionAgent  
  
def multiply(a: int, b: int) -> int:  
    """乘法"""  
    return a * b  
  
# 定义获取天气的函数  
def get_weather_old(location: str) -> str:  
    """获取指定地点的天气情况"""  
    # 实际实现中会调用天气API  
    return f"{location}的天气是晴朗，气温25℃"  
  
def get_weather(  
        location: Annotated[  
            str, "格式要求：城市名和州名，如'北京，中国'"  
        ],  
) -> str:  
    """获取指定地点的天气情况"""  
    # 实际实现中会调用天气API  
    return f"{location}的天气是晴朗，气温25℃"  
  
async  def aget_weather(  
        location: Annotated[  
            str, "格式要求：城市名和州名，如'北京，中国'"  
        ],  
) -> str:  
    """获取指定地点的天气情况"""  
  # 处理逻辑略  
  
multiply_tool = FunctionTool.from_defaults(multiply,  
                                  name="MultiplyTool",  
                                  description="用于计算乘法运算"  
                                  )  
  
weather_tool = FunctionTool.from_defaults(get_weather,  
                                  # async_fn=aget_weather,  # 可选  
                                  name="WeatherQueryTool",  
                                  description="专门用于查询各地天气的工具，支持城市+州/国家格式"  
                                  )  
  
  
agent = FunctionAgent(  
    tools=[multiply_tool,weather_tool],  
    llm=Settings.llm,  
    system_prompt="你是一个可以调用工具的助手，结果都以tools返回的结果为准。"  
)  
  
async  def main():  
    response = await agent.run("北京的天气如何？")  
    print(response)  
  
if __name__ == "__main__":  
    import asyncio  
    asyncio.run(main())

代码分析：

（1）方法的参数可以使用Annotated类型来细化参数描述（可选项）；

（2）FunctionTool.from_defaults可设置方法的描述，name等元数据；

5、工具太多该如何处理？

如果 agent 的 tools 数组中方法（工具）非常多，主要影响是 LLM prompt 变大，可能导致推理变慢、token 消耗增加，但不会直接影响 Python 端的性能。LlamaIndex 支持用 ObjectIndex 等机制对大量工具做索引和检索，只将相关工具传递给 LLM，优化性能。

如需管理大量工具，建议用 ObjectIndex + ToolRetriever 动态筛选，避免全部工具都进 prompt。官方文档：

https://docs.llamaindex.ai/en/stable/examples/agent/openai\_agent\_retrieval/