函数元数据#

本文档定义本框架中的函数必须携带哪些元数据（无论它是否调用 LLM）、这些元数据存放在何处，以及哪些组件会消费它们。

适用范围：所有用 @agentic_function 装饰的函数，以及任何传入 render_options 或决策菜单协议其他组件的普通 Python 可调用对象。（runtime.exec(tools=[...]) 不接受普通可调用对象——条目必须是 @agentic_function、{"spec", "execute"} 字典，或带有 .spec/.execute 的对象；其他任何形式都会抛出 TypeError。）

1. 为什么需要这份规范#

历史上，同一份信息曾散落在多个位置：

• 参数描述既可以写在 docstring 的 Args: 段落里，也可以写在 @agentic_function(input={...}) 中
• 决策菜单的调用方在调用处手写一份冗长的 available 注册字典，重复了函数上已有的信息
• 不同的消费方（tool_use spec、WebUI、决策菜单、meta 工具）遵循的读取顺序约定略有差异

结果是：新函数的作者不知道该把描述写在哪里，框架从不一致的来源读取元数据，而生成的代码也并不总能与其他消费方的预期一致。

本规范定义了单一可信来源，让每个消费方都按相同的规则读取元数据。

2. 谁会消费函数元数据#

3. 元数据字段及其规范位置#

每一份信息都恰好只有一个可信来源。下表即为规范：

核心原则：凡是可通过签名 / 注解表达的内容，就不在装饰器中重复；凡是可通过 input= 表达的内容，就不在 docstring 中重复。

装饰器还接受共享的工具注册 / 门控 kwargs（name、description、toolset、unsafe_in、requires_approval、available_if、defer 等），详见 docs/reference/design/function/calling-unification.md；cache / cache_ttl（按 name + args 记忆化结果）和 timeout（N 秒后强行终止函数体并返回一个错误结果）的行为与 @function 中一致。

一个裸 @agentic_function 的有效默认值#

由此可知：一个帧会自然地累积自身的工作。仅当需要在长循环中约束 prompt 体积时，才显式设置 subcalls=N。仅在（少见的）需要完全隔绝帧内节点时，才显式设置 subcalls=0。

4. docstring 与 content 各自的角色#

这两条通道可以携带相互重叠的信息，但它们承担不同的职责——彼此都无法替代对方：

一个函数可以有一段详尽的 docstring，说明“本函数通过询问 LLM 并对回复做归一化来分类情感”，但函数体仍然需要一个显式的 runtime.exec(content=[...])，其中包含真正发给 LLM 的指令 + 数据。docstring 中的文档不会传递进 LLM 调用——框架把 docstring 作为描述性上下文发送（以 metadata.doc 携带在 DAG 节点上，并渲染进内层调用的 situation prompt），而非作为权威指令。各 provider 的行为各异；codex CLI 尤其会忽略作为指令的 docstring。务必把每次调用的 prompt 放进 content。

docstring 撰写规则：

• 一行摘要（第一段）是必需的——这正是决策菜单和 tool_use spec 所读取的内容。
• 正文可以写到对代码读者有用的详细程度——包括描述每一次 LLM 调用做什么。
• 不要写填充性内容（“You are a helpful assistant”、“Complete the task”）。
• 详尽的 docstring 并不能免去在每次 exec 调用上写显式 content=[...] 文本的必要。

content 撰写规则：

• 每一项都是形如 {"type": "text", "text": ...} 或 {"type": "image", "path": ...} 的字典。
• 把这次 LLM 调用的指令与数据都嵌进去。示例：

  runtime.exec(content=[{"type": "text", "text": (
      f"Classify the sentiment of the following text. Reply with exactly one "
      f"word: positive, negative, or neutral.\n\nText:\n{text}"
  )}])
  

• 在行内定义确切的输出格式；不要指望 docstring 或外部上下文来传达它。

5. input= 与 docstring 的 Args: 段落#

历史上，同一份参数描述既可能出现在 docstring 的 Args: 段落，也可能出现在 @agentic_function(input={...}) 中。本规范将 input= 定为可信来源。

推荐写法（新代码必须采用）#

最小示例：

@agentic_function(input={
    "text":  {"description": "Text to polish."},
    "style": {"description": "Output style.", "options": ["academic", "casual"]},
})
def polish(text: str, style: str, runtime: Runtime) -> str:
    """Polish a text in the given style."""
    ...

更完整的示例，演练了更多元数据特性（placeholder、multiline、hidden、混合类型）：

@agentic_function(input={
    "essay": {
        "description": "Essay to review.",
        "placeholder": "Paste the essay text here...",
        "multiline": True,
    },
    "rubric_id": {
        "description": "Which rubric to apply.",
        "options": ["ielts_writing", "toefl_writing", "gre_argument"],
    },
    "max_score": {
        "description": "Upper bound for the numeric score.",
    },
    "show_rubric_internals": {
        "description": "Include rubric breakdown in the output.",
    },
    "session_id": {
        # 由系统提供；LLM 看不到它。
        "hidden": True,
    },
})
def review_essay(
    essay: str,
    rubric_id: str,
    max_score: int,
    show_rubric_internals: bool,
    session_id: str,           # 由 Python 通过上下文填充，而非 LLM
    runtime: Runtime,          # 自动注入
) -> dict:
    """Score an essay against a named rubric and return a structured report."""
    ...

docstring 只保留一行摘要——没有 Args: 段落，也没有 Returns: 段落。如果返回值字段的含义对下游 LLM 驱动的调用很重要，就用结构化返回类型（例如 TypedDict 或 dataclass）来编码它，以便消费方能够反射它；不要在 docstring 段落里重复这套 schema。

旧写法（仍受支持）#

@agentic_function
def polish(text: str, style: str, runtime: Runtime) -> str:
    """Polish a text in the given style.

    Args:
        text: Text to polish.
        style: Output style.
        runtime: LLM runtime.

    Returns:
        Polished text.
    """
    ...

旧函数仍然能运行，但 Args: 段落是死文本——框架中任何地方都不存在 docstring-Args: 解析器（见 §10）。_build_agentic_tool_spec 的回落顺序如下：

fn.input_meta[name]["description"]
    ↓ 未找到
fn.input_meta[name]["placeholder"]  (渲染为 "e.g. {placeholder}")
    ↓ 未找到
无描述；仅有参数名 + 类型

render_options 只从 input_meta 读取 description 和 options；缺少二者的参数只会得到 name + type。

6. 普通 Python 可调用对象（未装饰）#

决策菜单路径并不强制要求 @agentic_function：普通可调用对象可以传给 render_options（也可作为 decision.make / choices= 的选项），但它们携带的元数据更少。它们不能传给 runtime.exec(tools=[...])——对于任何既不是 @agentic_function、也不是 {"spec", "execute"} 字典、又不带 .spec/.execute 的对象，_adapt_tools 都会抛出 TypeError。

在以下场景使用普通可调用对象：参数很少的简单决策分支、不暴露 WebUI 界面、且不需要丰富的菜单提示。一旦你需要枚举值、隐藏参数或详细描述，就立刻升级到 @agentic_function。

7. 自动注入的参数#

下列参数名按约定保留：如果某函数的签名包含其中任何一个，框架会在调用时自动注入它们。LLM 看不到它们，也不需要填写。

这些名字存放在两个文件中的两个常量里：agentic_programming/function.py 中的 _RUNTIME_PARAMS（运行时注入 + 从 tool spec 中过滤）和 agentic_programming/decision.py 中的 _AUTO_PARAMS（从决策菜单中隐藏 + 派发）。要新增一个自动注入的名字，需同时改这两处。不要在单个调用处用 input={"x": {"hidden": True}} 来标记它们。

8. WebUI 渲染行为#

WebUI 不会反射运行中的 Python 对象：它对源文件（openprogram/webui/_functions.py）做 AST/正则解析。因此 input= 必须在装饰器调用中写成字面量字典，才能在表单中显示出来——动态构建的元数据（变量、辅助函数调用）对 WebUI 是不可见的。

WebUI 表单按下列规则渲染每个参数（实现见 web/components/chat/composer/modes/fn-form/fn-form.tsx 和 fn-form-fields.tsx）。在编写 @agentic_function(input={...}) 时，用下表来预判你的函数会生成哪种输入控件：

工作目录选择器单独渲染在参数行上方，由顶层的 workdir_mode 控制：

参数的 description 渲染为参数名旁的小标签；类型注解显示在同一行，非必填参数会带一个 “optional” 标记（没有 “required” 标记）。

9. 不在范围内（推迟到未来扩展）#

下列字段曾被讨论，但现在有意不引入，因为尚不存在任何消费方：

一旦出现真正的上游消费方，再重新审视本节。

10. 迁移路径（仅供参考）#

将既有代码迁移到本规范的推荐顺序；并非严格要求：

1. 在 agentic_programming/function.py 中添加一个共享辅助函数 _parse_docstring_args(fn) -> dict[name, description]
2. 让 _build_agentic_tool_spec 调用该辅助函数作为回落（目前 spec 完全不读取 docstring 的 Args:）
3. 让 render_options 调用同一个辅助函数作为同样的回落
4. 既有的 @agentic_function 函数无需立即改写；在你顺手触及它们时再随机迁移

11. 风格检查清单#

编写一个新的 @agentic_function 时：

• docstring 第一段是一行摘要（直接说明函数做什么 / 何时选用它）
• docstring 中没有 Args: 或 Returns: 段落（除非你确实出于调试 / 阅读目的想要它们）
• 每个对 LLM 可见的参数在 input= 中都有 description
• 枚举参数在 input= 中使用 options（而非埋在描述文本里）
• 由系统填充的参数（DB session、当前用户等）标记 hidden: True
• 框架自动注入的参数（runtime 等）无需注解；框架会自行检测它们
• 函数名清晰（fn.__name__ 就是 LLM 看到的动作名）
• docstring 中没有角色扮演、没有空洞指令、没有比喻

12. 参考资料#

• openprogram/agentic_programming/function.py —— @agentic_function 装饰器实现
• openprogram/agentic_programming/decision.py —— 选项菜单渲染、回复解析，以及下一步决策原语（decision.make、render_options、parse_args、DecisionError）
• docs/capabilities/agentic-programming/writing-functions/agentic-function.md —— 装饰器使用指南
• docs/reference/design/function/calling-unification.md —— 函数 / 工具调用框架
• docs/capabilities/agentic-programming/choosing-the-next-step/tool-calling.md —— 单轮原生 tool-use 循环机制