工具

工具是可由代理调用以执行任务的函数。它们被组织到工具组中，并注册到特定的提供者。每个工具组代表来自同一提供者的一组相关工具。它们被组织成组以便状态可以外部化：这组工具通常在同一状态下运行。一个例子是“db_access”工具组，它包含用于与数据库交互的工具。“list_tables”、“query_table”、“insert_row”可以作为该组中的工具示例。

工具在 llama stack 中被视为与模型等其他资源一样。您可以注册它们，为它们设置提供者等。

实例化代理时，您可以为其提供一个它可以访问的工具组列表。代理获取指定工具组对应的工具定义，并将其传递给模型。

请参阅构建 AI 应用笔记本，了解更多如何使用工具的示例。

工具组提供者类型

Llama Stack 支持三种类型的工具组提供者。

内置提供者
模型上下文协议 (MCP) 提供者
客户端提供的工具

内置提供者

内置提供者与 Llama Stack 一起打包。这些提供者提供常见功能，如网页搜索、代码解释和计算能力。

网页搜索提供者

Llama Stack 支持三种网页搜索提供者。

Brave Search
Bing Search
Tavily Search

注册由 brave-search 提供的“websearch”工具组的客户端 SDK 调用示例。

# Register Brave Search tool group
client.toolgroups.register(
    toolgroup_id="builtin::websearch",
    provider_id="brave-search",
    args={"max_results": 5},
)

该工具需要一个 API 密钥，可以在配置中提供，也可以通过请求头 X-LlamaStack-Provider-Data 提供。请求头的格式是 {"<provider_name>_api_key": <your api key>}。

注意：使用 Tavily Search 和 Bing Search 时，推理输出仍会显示“Brave Search”。这是因为 Llama 模型已将 Brave Search 作为内置工具进行训练。Tavily 和 Bing 只是替代 Brave Search 使用。

WolframAlpha

WolframAlpha 工具通过 WolframAlpha API 提供计算知识的访问。

# Register WolframAlpha tool group
client.toolgroups.register(
    toolgroup_id="builtin::wolfram_alpha", provider_id="wolfram-alpha"
)

使用示例

result = client.tool_runtime.invoke_tool(
    tool_name="wolfram_alpha", args={"query": "solve x^2 + 2x + 1 = 0"}
)

RAG

RAG 工具能够从各种类型的记忆库（向量、键值、关键词和图）中检索上下文。

# Register Memory tool group
client.toolgroups.register(
    toolgroup_id="builtin::rag",
    provider_id="faiss",
    args={"max_chunks": 5, "max_tokens_in_context": 4096},
)

功能

支持多种记忆库类型
可配置的查询生成
带有 token 限制的上下文检索

注意：默认情况下，llama stack 的 run.yaml 文件定义了用于网页搜索、Wolfram Alpha 和 RAG 的工具组，这些工具组由 tavily-search、wolfram-alpha 和 rag 提供者提供。

模型上下文协议 (MCP) 工具

MCP 工具是可以通过模型上下文协议与 llama stack 交互的特殊工具。这些工具从 MCP 端点动态发现，可用于扩展代理的功能。

请参阅 https://github.com/modelcontextprotocol/servers 查看可用的 MCP 服务器。

# start your MCP server
mkdir /tmp/content
touch /tmp/content/foo
touch /tmp/content/bar
npx -y supergateway --port 8000 --stdio 'npx -y @modelcontextprotocol/server-filesystem /tmp/content'

然后将 MCP 服务器注册为一个工具组，

client.toolgroups.register(
    toolgroup_id="mcp::filesystem",
    provider_id="model-context-protocol",
    mcp_endpoint=URL(uri="https://:8000/sse"),
)

MCP 工具需要

一个有效的 MCP 端点 URL
该端点必须实现模型上下文协议
工具从端点动态发现

添加自定义工具

当您想使用内置工具之外的工具时，只需实现一个带有 docstring 的 python 函数即可。docstring 的内容将用于描述该工具及其参数，并传递给生成模型。

# Example tool definition
def my_tool(input: int) -> int:
    """
    Runs my awesome tool.

    :param input: some int parameter
    """
    return input * 2

注意：我们使用 python docstring 来描述工具和参数。文档化工具和参数非常重要，以便模型能够正确使用该工具。建议尝试不同的 docstring，看看它们如何影响模型的行为。

定义后，只需将工具传递给代理配置即可。Agent 将处理其余部分（使用工具定义调用模型，执行工具，并将结果返回给模型进行下一次迭代）。

# Example agent config with client provided tools
agent = Agent(client, ..., tools=[my_tool])

请参阅 llama-stack-apps，了解如何使用客户端提供的工具的示例。

工具调用

可以使用 invoke_tool 方法调用工具

result = client.tool_runtime.invoke_tool(
    tool_name="web_search", kwargs={"query": "What is the capital of France?"}
)

结果包含

content: 工具的输出
error_message: 可选的错误消息，如果工具失败
error_code: 可选的错误代码，如果工具失败

列出可用工具

您可以列出所有可用工具，或按工具组过滤

# List all tools
all_tools = client.tools.list_tools()

# List tools in a specific group
group_tools = client.tools.list_tools(toolgroup_id="search_tools")

简单示例 2: 将代理与网页搜索工具一起使用

首先在 Tavily 注册一个 Tavily API 密钥。
[可选] 直接将 API 密钥提供给 Llama Stack 服务器

export TAVILY_SEARCH_API_KEY="your key"

--env TAVILY_SEARCH_API_KEY=${TAVILY_SEARCH_API_KEY}

运行以下脚本。

from llama_stack_client.lib.agents.agent import Agent
from llama_stack_client.types.agent_create_params import AgentConfig
from llama_stack_client.lib.agents.event_logger import EventLogger
from llama_stack_client import LlamaStackClient

client = LlamaStackClient(
    base_url=f"https://:8321",
    provider_data={
        "tavily_search_api_key": "your_TAVILY_SEARCH_API_KEY"
    },  # Set this from the client side. No need to provide it if it has already been configured on the Llama Stack server.
)

agent = Agent(
    client,
    model="meta-llama/Llama-3.2-3B-Instruct",
    instructions=(
        "You are a web search assistant, must use websearch tool to look up the most current and precise information available. "
    ),
    tools=["builtin::websearch"],
)

session_id = agent.create_session("websearch-session")

response = agent.create_turn(
    messages=[
        {"role": "user", "content": "How did the USA perform in the last Olympics?"}
    ],
    session_id=session_id,
)
for log in EventLogger().log(response):
    log.print()

简单示例 3: 将代理与 WolframAlpha 工具一起使用

首先在 WolframAlpha Developer Portal 注册一个 WolframAlpha API 密钥。

在启动 Llama Stack 服务器时提供 API 密钥

--env WOLFRAM_ALPHA_API_KEY=${WOLFRAM_ALPHA_API_KEY}

或从客户端提供

client = LlamaStackClient(
    base_url="https://:8321",
    provider_data={"wolfram_alpha_api_key": wolfram_api_key},
)

通过设置 tools=["builtin::wolfram_alpha"] 在代理中配置工具。

用户查询示例

response = agent.create_turn(
    messages=[{"role": "user", "content": "Solve x^2 + 2x + 1 = 0 using WolframAlpha"}],
    session_id=session_id,
)