agentic-programming

name: agentic-programming description: "Write, edit, validate, save, and run Agentic Programming functions (@agentic_function) directly with your own file-editing tools. Covers next-step decision making — letting the LLM pick the next function/value via decision.make or runtime.exec(choices=). No dedicated meta functions — just follow the rules in this skill. Triggers: 'write an agentic_function', 'create a function', 'edit a function', 'improve a function', 'fix this function', 'add a function that', 'add a tool that', 'run a function', 'let the model decide', 'make the model pick', 'decision.make', 'next-step decision'."

Agentic Programming — author, edit, validate, save

This skill is a complete guide for writing and maintaining @agentic_function-style functions in this repo. You (the agent) read this, then use your own Read / Write / Edit / Bash tools to make the changes directly. There are no dedicated create() / edit() / improve() framework functions — they were removed because all they did was wrap a single LLM call plus file write, which you can do yourself.

When to invoke

Use this skill when the user asks to:

• write a new function (agentic or pure-Python) in this project
• edit, fix, improve, refactor an existing function in this project
• generate a SKILL.md for an existing function

Do not invoke this skill for unrelated work (downloads, web search, system commands).

The workflow

1. Pick the target file
2. Decide: agentic_function or plain Python?
3. Draft the code following the spec below
4. Self-validate against the rule checklist
5. Write the file (Write tool for new file, Edit for modify)
6. (Optional) Run a smoke test by importing + calling

That's it. Every step is something you do with your normal tools.

1. Picking the target file

Directory + filename convention: lowercase snake_case folder matching the function name (e.g. analyze_sentiment/__init__.py contains def analyze_sentiment). The folder layout (one directory per agentic function, code in __init__.py) replaced the old flat <name>.py layout in the function-calling unification — see docs/design/function/function-calling-unification.md. Single-file helpers inside the same logical agentic can sit next to __init__.py (e.g. analyze_sentiment/_prompt.py) without polluting the top-level namespace.

2. agentic_function vs plain Python vs @function

This skill is about @agentic_function. The @function decorator is a different mechanism for framework-level leaf tools and is out of scope here — see docs/design/function/function-calling-unification.md if you need it. Both decorators ultimately produce AgentTool entries in the same shared registry, but they target different kinds of work: @function for deterministic Python tools called by the LLM, @agentic_function for higher-order functions whose body itself drives an LLM round.

Don't decorate a function just to "make it discoverable"; @agentic_function implies an LLM call inside the body.

3. Function metadata specification

The framework's components (WebUI, catalog menus, provider-native tools=[...]) all read metadata from the same places. Use these as the only sources:

Single source of truth: anything expressible in the signature / annotations is not repeated in the decorator; anything expressible in input= is not repeated in the docstring.

4. The docstring vs content split

These two channels have different responsibilities. Neither replaces the other.

The docstring reaches the model — but as description, not as the operative instruction. The framework stores the docstring on the function's DAG node and renders it into the context of the LLM calls made inside the function; it also becomes the tool description when the function is exposed via tools=[fn]. So the model sees it. But it arrives as descriptive context, and some providers (codex CLI / chatgpt subscription) respond conversationally to whatever is in content, treating the rest as background. The operative per-call prompt — task, output format, constraints — must therefore live in content. Rule of thumb: the docstring describes what the function is; content instructs the call. Write the per-call prompt in content even if the docstring already explains the same thing.

5. Recommended style (new code must use this)

Minimal example:

from openprogram.agentic_programming.function import agentic_function
from openprogram.agentic_programming.runtime import Runtime


@agentic_function(input={
    "text": {"description": "Text to analyze."},
})
def analyze_sentiment(text: str, runtime: Runtime = None) -> str:
    """Classify the sentiment of a text into positive, negative, or neutral."""
    reply = runtime.exec(content=[{"type": "text", "text": (
        f"Classify the sentiment of the following text. Reply with exactly "
        f"one word: positive, negative, or neutral.\n\n"
        f"Text:\n{text}"
    )}])
    label = str(reply).strip().lower()
    return label if label in {"positive", "negative", "neutral"} else "neutral"

Fuller example exercising more metadata features:

from openprogram.agentic_programming.function import agentic_function
from openprogram.agentic_programming.runtime import Runtime


@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 = None,   # auto-injected
) -> dict:
    """Score an essay against a named rubric and return a structured report."""
    # ... real implementation here ...

The docstring stays one line + maybe a body paragraph. No Args: or Returns: sections. If the return shape matters to downstream callers, encode it with a structured return type (TypedDict / dataclass).

5b. Next-step decision making

When a function needs the LLM to decide what to do next — pick one of several follow-up functions or values — do not hand-roll it (render a menu, parse JSON, branch on the result). Use the framework's decision primitive. Two entry points, same options, same resolution:

The function still declares runtime: Runtime like any agentic function that calls the LLM (the decorator uses it to set up context). You just do not pass runtime= as an argument to decision.make — it reads the ambient runtime itself.

from openprogram.agentic_programming import agentic_function, decision
from openprogram.agentic_programming.runtime import Runtime


@agentic_function
def route_message(msg: str, runtime: Runtime = None) -> dict:
    """Decide how to handle an incoming message."""
    return decision.make(f"Pick how to handle this message:\n{msg}", {
        "analyze":  analyze_sentiment,        # function option — runs it, returns its result
        "fallback": fallback_reply,           # function option
        "done":     {"action": "ignored"},    # value option — returns the value as-is
    })


@agentic_function
def handle_ticket(ticket: str, runtime: Runtime = None) -> dict:
    """Investigate a ticket, then decide which workflow to route it to."""
    return runtime.exec(
        f"Handle this ticket:\n{ticket}",
        toolset="default",          # the model does the work with tools first
        choices={                   # the final return must be one of these
            "refund":   issue_refund,
            "escalate": escalate_to_human,
            "close":    {"status": "closed"},
        },
    )

Option forms — options / choices is a dict {name: handler} or a list of callables / option tuples. A handler can be:

• a callable — a function option; picking it runs the function, its return value is the result
• a value — a value option; picking it returns that value as-is ({name: (value, "description")} adds a description)
• a ("description", schema) pair — a schema option; the model fills the schema and the filled structure is returned as {"decision": name, **fields}. The schema is {field: type} and nests: [item] for a list, {sub: ...} for a nested object — so one option can ask for any structured JSON

The resolution leaves no if for you to write: a picked function runs, a picked value/structure comes back. The decision is the branch. If the model never produces a resolvable pick after retries, DecisionError (a ValueError subclass) is raised — catch it if you want a graceful fallback.

Rule: if you find yourself writing runtime.exec(...) followed by if "..." in reply: to route on what the model said, replace it with decision.make / exec(choices=).

6. Rule-based validation — run this before declaring done

Walk through every rule. If any fails, fix it before writing the file.

6.1 Structural rules

6.2 runtime.exec call-site rules (every runtime.exec(...) call)

6.3 @agentic_function(input=...) rules

For every LLM-visible parameter (not runtime, not hidden=True):

6.4 Style rules (docstring + content)

7. WebUI rendering behavior (good to know when designing parameters)

The form sidebar renders each parameter by these rules:

workdir_mode controls the working-directory picker:

8. Editing an existing function

Same rules, but:

• Use Read to load the current source.
• Preserve the function name, parameter names and order, type hints, and existing @agentic_function(input=..., ...) arguments unless the user's instruction explicitly asks to change them.
• Never change runtime: Runtime to Any.
• Apply Edit for targeted changes; only Write when rewriting the whole file.
• If there's a sibling tests/ file for this function, update or add a test for the change.

For "fix this bug" requests, look at the function's error log first if available (e.g. recent traceback in the conversation), then edit to address the root cause, not the symptom.

9. Smoke test after writing

When the function is new or significantly changed, run a quick import-and-call check:

python -c "
from <path.to.module> import <fn_name>
from openprogram.providers.registry import create_runtime
rt = create_runtime()
result = <fn_name>(..., runtime=rt)
print(result)
rt.close()
"

If it crashes, read the traceback and fix before declaring done. For functions whose output is hard to verify automatically (free-form text), the smoke test only proves "didn't crash" — write a real pytest test in tests/ for anything important.

10. Running an existing function

Once a function is saved, there are two ways to run it.

CLI — for functions discoverable under openprogram/functions/agentics/ (listed in openprogram/functions/_registry.py::AGENTIC_MODULES):

openprogram programs list                       # see what's available
openprogram programs run <name> --arg key=value  # --arg is repeatable

The CLI run path auto-injects a Runtime for functions that need one, so you don't pass runtime= yourself. --provider / --model override the LLM if the function calls one.

Python — import and call directly (any function, anywhere):

from openprogram.functions.agentics.<name> import <name>
from openprogram.providers.registry import create_runtime

rt = create_runtime()
result = <name>(..., runtime=rt)   # pass runtime= only if the signature has it
rt.close()

Direct calls do not auto-inject a runtime — construct one with create_runtime() and pass it. This is also the §9 smoke-test shape.

11. Generating a SKILL.md for a function

To make a function agent-discoverable, write a SKILL.md next to it:

<path>/<fn_name>/SKILL.md

Frontmatter format (YAML):

---
name: <fn_name>
description: "<one-sentence summary including 4-8 trigger phrases an agent might use>"
---

After the frontmatter, write a short body covering when to use this skill, brief usage example, and one or two natural-language triggers. Keep it concise — agents read this every message.

12. Sanity checks if something looks wrong

13. Quick-reference: the absolute minimum

If you remember nothing else from this skill, remember these:

1. Decorate with @agentic_function only when LLM reasoning is needed.
2. runtime: Runtime = None in the signature; runtime.exec(content=[{"type":"text","text":"..."}]) is the call shape.
3. Per-call prompt + data go in content. Docstring is documentation, not instruction.
4. No system= kwarg on runtime.exec.
5. Every LLM-visible parameter needs a description in input={...}.
6. No Args: / Returns: sections in the docstring.
7. Save to openprogram/functions/agentics/<name>/__init__.py unless the user said otherwise. Add ("<name>", None) to openprogram/functions/_registry.py::AGENTIC_MODULES so the loader actually imports it (otherwise the @agentic_function decorator never fires and the function won't be discoverable).
8. If the LLM should also see it as a callable tool, add "<name>" to openprogram/functions/__init__.py::TOOLSETS["full"]["tools"] (the Layer 2 exposure whitelist). Without this the function exists but is invisible to LLMs.