Documentation Index
Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt
Use this file to discover all available pages before exploring further.
工具是 LLM 可以调用的异步函数，它们是模型推理与真实操作之间的桥梁。
from SimpleLLMFunc import tool
@tool
async def get_weather(city: str, unit: str = "celsius") -> str:
"""
Get current weather for a city.
Args:
city: City name (e.g., "Tokyo", "New York").
unit: Temperature unit — "celsius" or "fahrenheit".
Returns:
Current weather description.
Best Practices:
- Use full city names, not abbreviations.
- Default to celsius unless the user specifies otherwise.
"""
# Your implementation here
return f"Sunny, 22°C in {city}"
核心规则
- 必须是异步函数 —
@tool 要求使用 async def，不支持同步函数。
- 文档字符串即规格说明 — 模型看到的工具描述就是你的文档字符串。
- 最佳实践很重要 —
Best Practices 部分会作为 <tool_best_practices> 注入到系统提示词中。用它来引导模型何时以及如何使用工具。
- 类型注解定义 schema — 参数类型会转换为工具的 JSON schema。
文档字符串结构
@tool
async def my_tool(param: str) -> str:
"""
One-line description of what the tool does.
Longer explanation if needed. This becomes the tool description
the model sees.
Args:
param: Description of this parameter.
Returns:
What the tool returns.
Best Practices:
- When to use this tool vs. alternatives.
- Common pitfalls to avoid.
- Expected input formats.
"""
组合工具集
将多个工具传递给智能体：
@llm_chat(llm_interface=llm, toolkit=[get_weather, search_docs, calculate])
async def agent(message: str, history: list | None = None):
"""Use available tools to answer questions."""
pass
内置工具集
具有过期写入保护的工作区级文件操作：
from SimpleLLMFunc.builtin import FileToolset
file_tools = FileToolset("/path/to/workspace")
@llm_chat(llm_interface=llm, toolkit=file_tools.toolset)
async def file_agent(message: str, history: list | None = None):
"""A file-aware assistant."""
pass
read_file、read_image、grep、sed、echo_into。
PyRepl
带运行时原语的持久化 Python REPL：
from SimpleLLMFunc.builtin import PyRepl
repl = PyRepl(working_directory="/path/to/workspace")
@llm_chat(llm_interface=llm, toolkit=repl.toolset)
async def code_agent(message: str, history: list | None = None):
"""Execute Python code to solve problems."""
pass
execute_code、reset_repl。
多模态返回
工具可以返回图片和混合内容：
from SimpleLLMFunc.type import ImgPath, ImgUrl
@tool
async def generate_chart(data: str) -> ImgPath:
"""Generate a chart from the data."""
# ... create chart, save to file ...
return ImgPath(path="/tmp/chart.png")
@tool
async def fetch_screenshot(url: str) -> ImgUrl:
"""Take a screenshot of a webpage."""
return ImgUrl(url="https://screenshot-api.example.com/capture?url=" + url)
元组返回（混合内容）
同时返回文本和图片：
@tool
async def analyze_image(image_path: str) -> tuple[str, ImgPath]:
"""Analyze an image and return description + annotated version."""
description = "A landscape photo..."
annotated = ImgPath(path="/tmp/annotated.png")
return description, annotated
长输出处理
对于产生超长输出的工具：
@tool(too_long_to_file=True)
async def read_large_file(path: str) -> str:
"""Read a potentially large file."""
with open(path) as f:
return f.read()
too_long_to_file=True 后，如果结果超过约 20,000 个 token，框架会：
- 将完整输出写入临时文件
- 向模型发送截断版本和文件路径
- 模型随后可以按需读取特定部分
动态创建工具
以编程方式创建工具：
from SimpleLLMFunc import Tool
def make_api_tool(endpoint: str, description: str) -> Tool:
async def call_api(params: str) -> str:
# ... call endpoint ...
return "result"
return Tool(
name=f"call_{endpoint}",
description=description,
func=call_api,
best_practices=["Use structured JSON for params"],
)
系统提示词注入
每个工具的 Best Practices 部分会被收集并作为 <tool_best_practices> 块注入到系统提示词的顶部。这是自动完成的——你无需在文档字符串中引用工具。
此外，工具可以通过 prompt_injection_builder 提供动态提示词注入：
@tool(prompt_injection_builder=lambda ctx: f"Current workspace: {ctx.get('workspace', '/')}")
async def list_files(path: str) -> str:
"""List files in a directory."""
...