Llama Index AgentWorkflow调用工具函数时出现'toolUse' KeyError的问题求助

我照着官方示例写了一个最简单的Llama Index AgentWorkflow代码，用来调用自定义工具函数获取魔法数字，但一直报'toolUse'的KeyError，实在搞不懂原因，求大家帮忙看看！

我的代码 #

from llama_index.core.agent.workflow import AgentWorkflow
import asyncio

async def magic_number():
    """Get the magic number."""
    print("Here")
    await asyncio.sleep(1)
    return 42

workflow = AgentWorkflow.from_tools_or_functions(
    [magic_number],
    verbose=True,
    llm=llm # <--- Need to define llm for this to run
)

async def main():
    result = await workflow.run(user_msg="Get the magic number")
    print(result)


if __name__ == "__main__":
    asyncio.run(main(), debug=True)

运行后出现的错误 #

Running step init_run
Step init_run produced event AgentInput
Executing <Task pending name='init_run' coro=<Workflow._start.<locals>._task() running at tasks.py:410> took 0.135 seconds
Running step setup_agent
Step setup_agent produced event AgentSetup
Running step run_agent_step
Executing <Task pending name='run_agent_step' coro=<Workflow._start.<locals>._task() running at tasks.py:410> took 0.706 seconds
Exception in callback Dispatcher.span.<locals>.wrapper.<locals>.handle_future_result(span_id='Workflow.run...-e79838aa3b7a', bound_args=<BoundArgumen...mory': None})>, instance=<llama_index....00203B74F7620>, context=<__contextvars...00203B6D93440>)(<WorkflowHand...handler.py:20>) at dispatcher.py:274
handle: <Handle Dispatcher.span.<locals>.wrapper.<locals>.handle_future_result(span_id='Workflow.run...-e79838aa3b7a', bound_args=<BoundArgumen...mory': None})>, instance=<llama_index....00203B74F7620>, context=<__contextvars...00203B6D93440>)(<WorkflowHand...handler.py:20>) at workflow.py:553>
source_traceback: Object created at (most recent call last):
  File "test.py", line 36, in <module>
    asyncio.run(main(), debug=True)
  File "runners.py", line 194, in run
    return runner.run(main)
  File "runners.py", line 118, in run
    return self._loop.run_until_complete(task)
  File "base_events.py", line 708, in run_until_complete
    self.run_forever()
  File "base_events.py", line 679, in run_forever
    self._run_once()
  File "base_events.py", line 2019, in _run_once
    handle._run()
  File "events.py", line 89, in _run
    self._context.run(self._callback, *self._args)
  File "workflow.py", line 553, in _run_workflow
    result.set_exception(e)
Traceback (most recent call last):
  File "workflow.py", line 304, in _task
    new_ev = await instrumented_step(**kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "dispatcher.py", line 368, in async_wrapper
    result = await func(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "multi_agent_workflow.py", line 329, in run_agent_step
    agent_output = await agent.take_step(
                   ^^^^^^^^^^^^^^^^^^^^^^
    ...<4 lines>...
    )
    ^
  File "function_agent.py", line 48, in take_step
    async for last_chat_response in response:
    ...<16 lines>...
        )
  File "callbacks.py", line 88, in wrapped_gen
    async for x in f_return_val:
    ...<8 lines>...
        last_response = x
  File "base.py", line 495, in gen
    tool_use = content_block_start["toolUse"]
               ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
KeyError: 'toolUse'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "events.py", line 89, in _run
    self._context.run(self._callback, *self._args)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "dispatcher.py", line 286, in handle_future_result
    raise exception
  File "workflow.py", line 542, in _run_workflow
    raise exception_raised
  File "workflow.py", line 311, in _task
    raise WorkflowRuntimeError(
        f"Error in step '{name}': {e!s}"
    ) from e
llama_index.core.workflow.errors.WorkflowRuntimeError: Error in step 'run_agent_step': 'toolUse'
Traceback (most recent call last):
  File "workflow.py", line 304, in _task
    new_ev = await instrumented_step(**kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "dispatcher.py", line 368, in async_wrapper
    result = await func(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "multi_agent_workflow.py", line 329, in run_agent_step
    agent_output = await agent.take_step(
                   ^^^^^^^^^^^^^^^^^^^^^^
    ...<4 lines>...
    )
    ^
  File "function_agent.py", line 48, in take_step
    async for last_chat_response in response:
    ...<16 lines>...
        )
  File "callbacks.py", line 88, in wrapped_gen
    async for x in f_return_val:
    ...<8 lines>...
        last_response = x
  File "base.py", line 495, in gen
    tool_use = content_block_start["toolUse"]
               ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
KeyError: 'toolUse'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "test.py", line 36, in <module>
    asyncio.run(main(), debug=True)
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "runners.py", line 194, in run
    return runner.run(main)
           ~~~~~~~~~~^^^^^^
  File "runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "base_events.py", line 721, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "test.py", line 31, in main
    result = await workflow.run(user_msg="Get the magic number")
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "workflow.py", line 542, in _run_workflow
    raise exception_raised
  File "workflow.py", line 311, in _task
    raise WorkflowRuntimeError(
        f"Error in step '{name}': {e!s}"
    ) from e
llama_index.core.workflow.errors.WorkflowRuntimeError: Error in step 'run_agent_step': 'toolUse'

我的运行环境 #

• Python 3.13
• llama-index 0.12.24.post1
• 使用的LLM：Anthropic Claude 3.5 Sonnet

问题分析与解决方案 #

这个KeyError: 'toolUse'本质是LLM返回的工具调用格式和AgentWorkflow期望的格式不匹配导致的。Claude系列模型的默认工具调用字段名（比如tool_calls）和Llama Index AgentWorkflow默认期望的toolUse字段不一致，加上版本适配问题就会触发这个错误。

1. 正确配置Anthropic LLM并适配格式

首先要确保LLM初始化正确，并且Llama Index能正确解析Claude的工具调用响应。修改后的完整代码如下：

from llama_index.core.agent.workflow import AgentWorkflow
from llama_index.llms.anthropic import Anthropic
import asyncio

async def magic_number():
    """Get the magic number."""
    print("Here")
    await asyncio.sleep(1)
    return 42

# 正确初始化Anthropic Claude LLM
llm = Anthropic(
    model="claude-3-5-sonnet-20240620",
    api_key="你的Anthropic API密钥"  # 替换为实际密钥
)

workflow = AgentWorkflow.from_tools_or_functions(
    [magic_number],
    verbose=True,
    llm=llm
)

async def main():
    result = await workflow.run(user_msg="Get the magic number")
    print(result)

if __name__ == "__main__":
    asyncio.run(main(), debug=True)

2. 尝试换用更轻量的FunctionCallingAgent测试

如果AgentWorkflow还是有问题，可以先测试基础的FunctionCallingAgent，它对工具调用的格式适配更直接：

from llama_index.core.agent import FunctionCallingAgent
from llama_index.llms.anthropic import Anthropic
import asyncio

async def magic_number():
    """Get the magic number."""
    print("Here")
    await asyncio.sleep(1)
    return 42

llm = Anthropic(model="claude-3-5-sonnet-20240620", api_key="你的Anthropic API密钥")
agent = FunctionCallingAgent.from_tools([magic_number], llm=llm, verbose=True)

async def main():
    result = await agent.chat("Get the magic number")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

3. 版本兼容性调整

如果上述方法无效，可能是llama-index版本和Claude 3.5的适配问题：

• 尝试升级llama-index到最新稳定版：pip install --upgrade llama-index llama-index-llms-anthropic
• 或者降级到已知兼容的版本（比如0.12.20左右）

4. 显式指定工具调用Prompt模板

如果还是有格式问题，可以手动指定针对Claude的工具调用Prompt，确保LLM输出包含toolUse字段：

from llama_index.core.prompts import PromptTemplate
from llama_index.core.agent.workflow import AgentWorkflow
from llama_index.llms.anthropic import Anthropic

# 自定义适配Claude的工具调用Prompt
tool_call_prompt = PromptTemplate(
    "你是一个工具调用专家，当需要调用工具时，请严格按照以下格式返回：\n"
    "{'toolUse': {'tool_name': '工具函数名', 'parameters': {}}}\n"
    "用户查询：{user_msg}"
)

# 初始化LLM和Workflow时指定模板
llm = Anthropic(model="claude-3-5-sonnet-20240620", api_key="你的API密钥")
workflow = AgentWorkflow.from_tools_or_functions(
    [magic_number],
    verbose=True,
    llm=llm,
    agent_prompt=tool_call_prompt
)

备注：内容来源于stack exchange，提问作者LMc