Function Tooling 配置指南

FunctionToolConfig 允许 Agent 节点调用仓库中的 Python 函数。相关代码位于 entity/configs/tooling.py、utils/function_catalog.py 以及 functions/function_calling/。

1. 配置字段

字段	说明
`tools`	列表，元素为 `FunctionToolEntryConfig`。每个条目至少包含 `name`。
`timeout`	单次工具执行的超时时间（秒）。

FunctionToolEntryConfig 字段：

name：函数名，来自 functions/function_calling/ 文件的顶级函数。

函数列表展示与 `module_name:All`

UI 下拉列表会将每个函数展示为 module_name:function_name。module_name 等于函数文件相对于 functions/function_calling/ 的路径（去掉 .py，子目录使用 / 连接），便于快速定位语义相关模块。
每个模块顶部都会自动插入 module_name:All 选项，并且所有模块的 All 条目按照字典序排在列表最前。选择该项时会在解析阶段展开为该模块下的所有函数，顺序同样遵循字典序。
module_name:All 只能批量引入函数，禁止同时填写 description、parameters 或 auto_fill 等覆盖字段；若需要自定义，请展开后针对具体函数单独配置。
函数与模块都采用全局字典序排列，使长列表更易检索；YAML 中仍然以真实函数名落盘，module_name:All 仅作为输入辅助。

2. 函数目录要求

路径：functions/function_calling/（可通过 MAC_FUNCTIONS_DIR 覆盖）。
每个函数：
- 必须位于模块顶层。
- 使用 Python 类型注解；若需枚举或描述，可使用 typing.Annotated[..., ParamMeta(...)]。
- 不允许以 _ 开头的参数暴露给 Agent；*_args、**kwargs 会被过滤。
- 可以通过 docstring 的首段提供描述（自动截断为 600 字符）。
utils/function_catalog.py 会在启动时生成 JSON Schema，并向前端/CLI 暴露。

3. 上下文注入

执行器会对被调用的函数提供 _context 关键字参数，包含：

键	值
`attachment_store`	`utils.attachments.AttachmentStore` 实例，可查询/注册附件。
`python_workspace_root`	当前 Session 的 `code_workspace/`。
`graph_directory`	Session 根目录，可推导相对路径。
`human_prompt`	`utils.human_prompt.HumanPromptService`，可调用 `request()` 触发人工反馈。
其他	视运行环境扩展，例如 `session_id`、`node_id`。

函数可声明 _context: dict | None = None 并自行解析（参考 functions/function_calling/file.py 中的 FileToolContext，还可参考 functions/function_calling/user.py）。

4. 示例：文件读取工具

from typing import Annotated
from utils.function_catalog import ParamMeta


def read_text_file(
    path: Annotated[str, ParamMeta(description="workspace 相对路径")],
    *,
    encoding: str = "utf-8",
    _context: dict | None = None,
) -> str:
    ctx = FileToolContext(_context)
    target = ctx.resolve_under_workspace(path)
    return target.read_text(encoding=encoding)

在 YAML 中引用：

nodes:
  - id: summarize
    type: agent
    config:
      tooling:
        type: function
        config:
          tools:
            - name: describe_available_files
            - name: read_text_file

5. 扩展流程

在 functions/function_calling/ 新建模块或函数。
使用类型注解 + ParamMeta 描述参数；如需禁止自动 Schema，可设置 auto_fill: false 并提供手写 parameters。
若函数依赖额外第三方库，可在仓库 requirements.txt/pyproject.toml 中声明，或在函数内调用 install_python_packages（同目录提供）动态安装。
运行 python -m tools.export_design_template ... 以刷新前端枚举。

6. 调试与排错

若前端/CLI 报告 “function 'xxx' not found”，检查函数名称与文件是否位于 MAC_FUNCTIONS_DIR（默认 functions/function_calling/）。
function_catalog 加载失败时，FunctionToolEntryConfig.field_specs() 会在描述中提示错误，请先修复函数语法或依赖。
工具运行超时会向 Agent 返回异常文本；可通过 timeout 扩大限额，或在函数内部自行捕获并返回友好错误。

4.2 KiB Executable File Raw Blame History Unescape Escape