Function metadata#

This document defines what metadata a function in this framework must carry — whether or not it calls an LLM — where that metadata lives, and which components consume it.

Scope: every function decorated with @agentic_function, plus any plain Python callable passed into render_options or any other component of the decision-menu protocol. (runtime.exec(tools=[...]) does not accept plain callables — entries must be an @agentic_function, a {"spec", "execute"} dict, or an object with .spec/.execute; anything else raises TypeError.)

1. Why this spec exists#

Historically the same piece of information lived in multiple places:

• Parameter descriptions could be written in the docstring Args: section or in @agentic_function(input={...})
• Decision-menu callers hand-wrote a verbose available registry dict at the call site, repeating information already present on the function
• Different consumers (tool_use spec, WebUI, decision menu, meta tooling) followed slightly different read-order conventions

The result: authors of new functions didn't know where to put descriptions, the framework read metadata from inconsistent sources, and generated code didn't always match what other consumers expected.

This spec defines a single source-of-truth so every consumer reads metadata by the same rules.

2. Who consumes function metadata#

3. Metadata fields and their canonical locations#

Every piece of information has exactly one source-of-truth. This table is the spec:

Core principle: anything expressible in the signature / annotation is not repeated in the decorator; anything expressible in input= is not repeated in the docstring.

The decorator also accepts the shared tool-registration / gating kwargs (name, description, toolset, unsafe_in, requires_approval, available_if, defer, ...) documented in docs/reference/design/function/calling-unification.md; cache / cache_ttl (memoize results on name + args) and timeout (hard-kill the body after N seconds, returning an error result) behave as in @function.

Effective defaults for a bare @agentic_function#

Implication: a frame naturally accumulates its own work. Set subcalls=N explicitly only to bound prompt size in a long loop. Set subcalls=0 explicitly to fully wall off in-frame nodes (rare).

4. The role of the docstring vs content#

These two channels can carry overlapping information, but they have different responsibilities — neither replaces the other:

A function may have a rich docstring explaining "this function classifies sentiment by asking the LLM and normalizing the reply", but the body still needs an explicit runtime.exec(content=[...]) containing the actual instruction + data going to the LLM. Documentation in the docstring does not propagate into the LLM call — the framework sends the docstring as descriptive context (carried on the DAG node as metadata.doc and rendered into the inner call's situation prompt), not as authoritative instruction. Provider behavior varies; codex CLI in particular ignores docstring as instruction. Always put the per-call prompt in content.

Docstring writing rules:

• One-line summary (the first paragraph) is required — that's what decision menus and tool_use specs read.
• The body may be as detailed as is useful for code readers — including describing what each LLM call does.
• Do not write filler ("You are a helpful assistant", "Complete the task").
• A detailed docstring does NOT eliminate the need for explicit content=[...] text on each exec call.

content writing rules:

• Each item is a dict like {"type": "text", "text": ...} or {"type": "image", "path": ...}.
• Embed both the instruction and the data for this LLM call. Example:

  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}"
  )}])
  

• Define the exact output format inline; don't rely on the docstring or external context to convey it.

5. input= vs. docstring Args: section#

Historically the same parameter description could appear both in the docstring Args: section and in @agentic_function(input={...}). This spec makes input= the source-of-truth.

Recommended style (required for new code)#

Minimal example:

@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."""
    ...

Fuller example exercising more metadata features (placeholder, multiline, hidden, mixed types):

@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": {
        # System-supplied; LLM does not see this.
        "hidden": True,
    },
})
def review_essay(
    essay: str,
    rubric_id: str,
    max_score: int,
    show_rubric_internals: bool,
    session_id: str,           # filled by Python via context, not LLM
    runtime: Runtime,          # auto-injected
) -> dict:
    """Score an essay against a named rubric and return a structured report."""
    ...

The docstring keeps only the one-line summary — no Args: section and no Returns: section. If the meaning of return-value fields matters to downstream LLM-driven calls, encode it with a structured return type (e.g. TypedDict or a dataclass) so consumers can introspect it; do not duplicate the schema in a docstring paragraph.

Legacy style (still supported)#

@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.
    """
    ...

Legacy functions still run, but the Args: section is dead text — no docstring-Args: parser exists anywhere in the framework (see §10). _build_agentic_tool_spec falls back as follows:

fn.input_meta[name]["description"]
    ↓ not found
fn.input_meta[name]["placeholder"]  (rendered as "e.g. {placeholder}")
    ↓ not found
no description; only parameter name + type

render_options reads only description and options from input_meta; parameters without them get name + type only.

6. Plain Python callables (undecorated)#

@agentic_function is not required for the decision-menu path: plain callables can be passed to render_options (and as decision.make / choices= options), but they carry less metadata. They can not be passed to runtime.exec(tools=[...]) — _adapt_tools raises TypeError for anything that is not an @agentic_function, a {"spec", "execute"} dict, or an object with .spec/.execute.

Use plain callables for: simple decision branches with few parameters, no WebUI surface, and no need for rich menu hints. Upgrade to @agentic_function as soon as you need enums, hidden parameters, or detailed descriptions.

7. Auto-injected parameters#

The following parameter names are reserved by convention: if a function's signature includes any of them, the framework auto-injects them at call time. The LLM does not see them and does not need to fill them.

These names live in two constants in two files: _RUNTIME_PARAMS in agentic_programming/function.py (runtime injection + filtering from tool specs) and _AUTO_PARAMS in agentic_programming/decision.py (hiding from decision menus + dispatch). To add a new auto-injected name, edit both. Do not mark them per-callsite via input={"x": {"hidden": True}}.

8. WebUI rendering behavior#

The WebUI does not introspect live Python objects: it AST/regex-parses the source files (openprogram/webui/_functions.py). Consequently input= must be written as a literal dict in the decorator call to show up in the form — metadata built dynamically (variables, helper calls) is invisible to the WebUI.

The WebUI form renders each parameter by the following rules (implemented in web/components/chat/composer/modes/fn-form/fn-form.tsx and fn-form-fields.tsx). When authoring @agentic_function(input={...}), use this table to predict what kind of input control your function will produce:

The working-directory picker is rendered separately above the parameter rows, governed by the top-level workdir_mode:

Parameter description renders as a small label next to the parameter name; the type annotation is shown on the same row, and non-required parameters get an "optional" marker (there is no "required" marker).

9. Out of scope (deferred for future expansion)#

The following fields were discussed and are intentionally not introduced now, because no consumer exists yet:

Revisit this section once a real upstream consumer appears.

10. Migration path (informational)#

The recommended order for migrating existing code to this spec; not strictly required:

1. Add a shared helper _parse_docstring_args(fn) -> dict[name, description] in agentic_programming/function.py
2. _build_agentic_tool_spec calls this helper as a fallback (currently the spec does not read docstring Args: at all)
3. render_options calls the same helper for the same fallback
4. Existing @agentic_function functions do not need immediate rewriting; convert opportunistically when you touch them

11. Style checklist#

When writing a new @agentic_function:

• First paragraph of the docstring is a one-line summary (state what the function does / when to pick it, directly)
• No Args: or Returns: sections in the docstring (unless you specifically want them for debugging / reading)
• Every LLM-visible parameter has a description in input=
• Enum parameters use options in input= (not buried in the description text)
• System-filled parameters (DB session, current user, etc.) are marked hidden: True
• Framework auto-injected parameters (runtime, etc.) need no annotation; the framework detects them
• The function name is clear (fn.__name__ is what the LLM sees as the action name)
• No role-play, no empty directives, no metaphors in the docstring

12. References#

• openprogram/agentic_programming/function.py — @agentic_function decorator implementation
• openprogram/agentic_programming/decision.py — options-menu rendering, reply parsing, and the next-step decision primitive (decision.make, render_options, parse_args, DecisionError)
• docs/capabilities/agentic-programming/writing-functions/agentic-function.md — decorator usage guide
• docs/reference/design/function/calling-unification.md — function/tool calling framework
• docs/capabilities/agentic-programming/choosing-the-next-step/tool-calling.md — per-turn native tool-use loop mechanics