企业官网建设流程全解析

ChatDev 2.0 如何编写自定义 Function Tooling 函数供 Agent 节点调用？

【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev

在 ChatDev 2.0 的工作流中，Agent 节点通过tooling配置获得可调用的工具。如果你已经内置的函数（如 functions/function_calling/ 下的天气、文件、代码执行工具）不能满足任务，就需要自己编写一个 Python 函数，让它出现在 Agent 的工具列表里被模型调用。完整路径是：在函数目录新建顶层函数 → 用类型注解和ParamMeta描述参数 → 在 Agent 节点的tooling配置中按函数名引用 → 用配置加载报错、前端下拉列表和模板导出命令验证结果。

函数从哪里加载：目录结构与命名规则

ChatDev 的 Function Tooling 由三部分协作完成：

• entity/configs/node/tooling.py：FunctionToolConfig负责解析 YAML 中的工具配置并做校验；
• utils/function_catalog.py：在启动时扫描函数目录、生成 JSON Schema，向前端和 CLI 暴露；
• utils/function_manager.py：按文件动态导入函数，运行时执行模型发起的调用。

必须遵守的目录与命名约束（来自 docs/user_guide/zh/modules/tooling/function.md）：

• 函数目录默认为functions/function_calling/，可通过环境变量MAC_FUNCTIONS_DIR覆盖为自定义目录；
• 函数必须位于模块顶层：文件名以_开头、__init__.py以及__pycache__会被跳过，以_开头的函数也不会被注册；
• 参数必须使用 Python 类型注解，否则无法生成 Schema；需要补充描述或枚举时，使用typing.Annotated[..., ParamMeta(...)]；
• 以_开头的参数不会暴露给 Agent，*_args、**kwargs会被过滤；
• docstring 的首段会作为工具描述，自动截断为 600 字符。

前端/UI 的下拉列表按module_name:function_name展示每个函数，其中module_name是函数文件相对functions/function_calling/的路径（去掉.py，子目录用/连接）。每个模块顶部还有一个module_name:All选项，表示批量引入该模块的全部函数。

第一步：编写一个带类型注解的顶层函数

以新增一个天气查询函数为例。新建或编辑functions/function_calling/下的文件，按下面的模式写顶层函数（示例代码基于 docs/user_guide/zh/modules/tooling/function.md 中的官方示例；city与返回字符串由你按业务替换）：

from typing import Annotated from utils.function_catalog import ParamMeta def get_weather( city: Annotated[str, ParamMeta(description="城市名称")], ) -> str: """查询指定城市的实时温度。""" # 在这里实现你的逻辑，例如请求一个天气 API return f"{city}: 20C"

各部分的作用：

• city: Annotated[str, ParamMeta(description="城市名称")]：类型注解决定 Schema 中的类型，ParamMeta的description写入该参数的描述；ParamMeta还支持enum字段提供枚举值（见 utils/function_catalog.py 中ParamMeta的定义）；
• """查询指定城市的实时温度。"""：docstring 首段成为工具描述，是模型决定是否调用该工具的关键信息；
• 函数没有默认值的参数会进入 Schema 的required列表，有默认值的会写入default。

如果函数需要访问运行时环境（附件存储、工作区目录等），可以声明_context关键字参数。执行器会自动向声明了_context的函数注入上下文，包含attachment_store（附件存储实例）、python_workspace_root（当前 Session 的code_workspace/）、graph_directory（Session 根目录）、human_prompt（可调用request()触发人工反馈）等键。仓库中的现成写法可以参考 functions/function_calling/file.py 里的FileToolContext和 functions/function_calling/user.py。以_开头的参数不会暴露给 Agent，因此_context不会被模型填写，只能由执行器注入。

第二步：在 Agent 节点的 tooling 配置中引用函数

仓库示例 yaml_instance/demo_function_call.yaml 展示了真实的引用方式：

- id: A type: agent config: provider: openai base_url: ${BASE_URL} api_key: ${API_KEY} name: gpt-4o role: '你是一个天气查询助手，负责调用工具获取指定城市的实时温度。' tooling: - type: function config: auto_load: true tools: - name: get_weather

FunctionToolConfig的字段（见 docs/user_guide/zh/modules/tooling/function.md 与 entity/configs/node/tooling.py）：

• tools：必填列表，每个条目至少包含name，即functions/function_calling/文件中的顶级函数名；
• auto_fill：默认true，表示描述和参数 Schema 自动从函数签名解析；设为false时可自行提供手写的description和parameters覆盖自动结果；
• timeout：单次工具执行的超时时间（秒），可选；
• 同一条tools里还可以写module_name:All批量引入整个模块的函数，但此时不能同时填写description、parameters或auto_fill等覆盖字段；需要自定义就展开为具体函数逐条配置。

配置加载时会做严格校验：tools不能为空；每个条目必须有非空name；函数必须能在函数目录中找到，重复声明同一函数、或给module_name:All附带覆盖字段，都会直接报ConfigError并指出具体位置（tools[i].name）。

第三步：验证函数被正确加载

有三个由文档和代码明确给出的验证点，建议按顺序检查：

1. 配置期报错定位。如果前端/CLI 报告function 'xxx' not found，先检查函数名是否与functions/function_calling/内（或MAC_FUNCTIONS_DIR指向目录）的实际函数名完全一致、函数是否位于文件顶层。这是配置加载失败最常见的原因。
2. 前端/CLI 下拉列表。function_catalog在启动时扫描目录生成 Schema 并暴露给前端/CLI，新函数应出现在module_name:function_name列表中，列表项的描述即 docstring 首段。如果function_catalog加载失败，FunctionToolEntryConfig.field_specs()会在字段描述中显示loading failed: <错误>提示——此时要先修复函数的语法错误或依赖缺失，而不是继续配置。
3. 刷新前端枚举模板。新增函数后，运行仓库提供的导出命令刷新 DesignConfig 模板（输出路径按你本地约定替换，仓库内既有模板位于 yaml_template/design.yaml）：

python -m tools.export_design_template --output <输出路径.yaml>

该命令会从类型化 Schema 重新生成 YAML 模板，可选--version固定模板版本、--mirror同时写入其他路径（见 tools/export_design_template.py）。

运行时验证则依赖 Agent 实际执行：模型按生成的 Schema 发起工具调用，执行器从函数目录取出函数执行。工具运行超时时会向 Agent 返回异常文本，处理方式文档给出两条：调大timeout限额，或在函数内部捕获异常并返回友好错误信息。

函数依赖第三方库怎么办

文档给出两条路径：

• 在仓库的requirements.txt/pyproject.toml中声明依赖，随项目环境安装；
• 使用函数目录内现成的install_python_packages（位于 functions/function_calling/uv_related.py）在运行时安装。它实际执行的是uv add，且工作目录是当前 Session 的 workspace（从注入的python_workspace_root解析），因此只影响该 Session 的工作区环境；需要uv命令在 PATH 中可用。

边界与限制

• 只有模块顶层函数会被注册：放进类里或以下划线开头的函数都不会出现；
• _context是执行器专用通道：模型看不到它，函数内使用它做路径解析时（如FileToolContext.resolve_under_workspace）会把越出 workspace 的路径判为错误；
• module_name:All只是输入辅助，YAML 落盘时仍是真实函数名，且禁止搭配覆盖字段；
• 函数名冲突、覆盖字段误用等错误都在配置加载阶段以ConfigError形式暴露并带路径定位，运行前就能发现，不需要等到工作流执行。

完成以上步骤后，新函数会经过“目录扫描 → Schema 生成 → 配置校验 → 运行时调用”这条链路进入 Agent 节点的工具列表；出现找不到函数或加载失败的提示时，按第三步的三个检查点逐项定位即可。

【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev