LlamaIndex Agent 入门时不要一开始就接多个外部系统。先封装一个确定性、只读、可人工验算的函数，给它清楚的名称、参数和描述，再观察 Agent 是否在需要时正确调用。 本文依据 LlamaIndex Agents 官方指南给出结构示意，未在你的版本、模型 API 和 Python 环境运行；导入路径和 Agent 类可能随版本变化，应以当前安装版本文档为准。
本篇验收要点：工具只接受受限的 product_id，从本地测试字典读取库存状态并返回结构化结果，不包含修改、删除或任意代码执行。 运行已知、未知和不需要工具的问题，查看 Agent 事件或调试轨迹中的工具名、参数、返回值和最终回答是否一致。
开始前准备
- 隔离的 Python 环境与当前 LlamaIndex 文档
- 可用模型凭证或本地模型适配
- 一个可人工验算的只读函数
- 三条需要工具和两条不应调用工具的测试问题
按顺序搭建
- 实现普通 Python 函数，显式声明参数类型和返回字段；未知 product_id 返回 found=false，不让模型自行补库存。
- 用当前文档提供的 FunctionTool 或等价方式封装，名称写成 get_inventory_status，描述明确只读、输入格式和返回含义。
- 把单个工具交给 Agent，系统说明要求依据工具结果回答；工具失败时说明无法确认。
- 运行存在、不存在、格式错误、普通闲聊和要求修改库存五类问题，记录是否调用、参数和结果。
- 只有单工具通过后再加第二个工具；每新增一个工具都重跑旧用例，避免描述重叠导致误选。
可复制的最小示例
只读函数应先独立测试，再按当前版本文档封装：
inventory = {"P100": {"status": "in_stock", "qty": 3}}
def get_inventory_status(product_id: str) -> dict:
item = inventory.get(product_id)
if item is None:
return {"found": False, "product_id": product_id}
return {"found": True, "product_id": product_id, **item}
# 再用当前 LlamaIndex 文档的 FunctionTool/Agent API 封装
怎样验收结果
验证标准是已知商品调用正确工具并使用真实返回，未知商品明确未找到，闲聊不调用工具，修改库存请求不会触发只读函数之外的动作，轨迹能对应每次选择。
- 函数脱离 Agent 可单测
- 工具描述与参数清楚
- 未知 ID 返回结构化失败
- 不需要工具的问题不会强制调用
常见失败与处理
- Agent 猜库存：要求只能依据工具，并让未知返回明确状态。
- 传错参数：收紧工具 schema 和示例。
- 工具很多时误选：拆分 Agent 或修改重叠描述。
读者下一步是先写并测试一个本地只读函数，再按当前 LlamaIndex 版本封装成工具，运行五条固定问题查看轨迹。
相关问答
为什么先做只读工具？
只读工具失败影响更小，便于理解参数、结果和 Agent 决策，再逐步加入受控写操作。
工具描述真的会影响选择吗？
会。模型依赖名称、描述和参数理解工具用途，描述重叠会增加误选。
官方资料与适用边界
Ai菜鸟网。发布者：AI小管家，转载请注明出处：https://www.alyyhw.com/32487.html
