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

Situation	Where the file goes
User said "save to X"	Exactly X.
Brand new general-purpose function	openprogram/functions/agentics/<name>/__init__.py
Editing an existing function	The file you found it in (don't move it).
User's project / non-framework function	Wherever fits their layout (ask if unclear).

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

What you're building	Decorator	Where it lives
LLM-reasoning logic (analyze / classify / generate / decide)	@agentic_function + runtime: Runtime + runtime.exec(content=[...])	openprogram/functions/agentics/<name>/__init__.py
Deterministic helper (parsing / math / file munging / API wrapper)	plain function, no decorator, no runtime parameter	wherever it's used; if shared, agentics/_utils/-style
Framework-level deterministic LLM tool (bash / read / web_search / etc.)	@function (different decorator!)	openprogram/functions/tools/<name>/

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:

Information	Where it lives	How it's read
Function name	def <name>(...)	fn.__name__
Parameter names	signature	inspect.signature(fn).parameters
Parameter types	annotation	param.annotation
Parameter defaults	annotation default	param.default
One-line summary (what / when-to-pick)	first paragraph of docstring	first paragraph of inspect.getdoc(fn)
Detailed function-level documentation	docstring body	rest of inspect.getdoc(fn)
Per-call LLM prompt + data	the content=[...] of that specific runtime.exec call	passed at call time
Per-parameter description	@agentic_function(input={"x": {"description": ...}})	fn.input_meta["x"]["description"]
Per-parameter enum	@agentic_function(input={"x": {"options": [...]}})	fn.input_meta["x"]["options"]
Hidden-from-LLM parameter	@agentic_function(input={"x": {"hidden": True}})	fn.input_meta["x"]["hidden"]
WebUI placeholder	@agentic_function(input={"x": {"placeholder": "..."}})	fn.input_meta["x"]["placeholder"]
WebUI multiline input	@agentic_function(input={"x": {"multiline": True}})	fn.input_meta["x"]["multiline"]
Dynamic option source	@agentic_function(input={"x": {"options_from": "functions"}})	fn.input_meta["x"]["options_from"]
Working-directory picker mode	@agentic_function(workdir_mode="optional"|"hidden"|"required")	AST-parsed from the decorator's source text by the WebUI (openprogram/webui/_functions.py), so write it as a literal in the decorator call
Auto-injected by the framework	param name in {"runtime", "exec_runtime", "review_runtime"}	framework checks signature
System-prompt override	@agentic_function(system="...")	fn.system
Context-tree visibility	@agentic_function(expose="io"|"full"|"hidden")	fn.expose
Context-tree render range	@agentic_function(render_range={"callers": ..., "subcalls": ...})	fn.render_range
Skill trigger keywords	sibling SKILL.md frontmatter	skill loader

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.

Channel	Scope	What goes here
docstring	Whole-function level. Read by humans, catalog menus, tool_use specs.	One-line summary (required). Optionally a body describing what each LLM call does, expected outputs, edge cases. As detailed as is useful for readers.
runtime.exec(content=[...])	One specific LLM call inside the function. A function may make several with different prompts.	The actual prompt + data for this call: the task, output format, constraints, plus the data to operate on. Required even if the docstring already explains the same thing.

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:

Entry	Use when
decision.make(prompt, options)	Pure decision — the model picks straight away, no work first.
runtime.exec(..., choices=options)	The model does a full turn (reasoning, tool calls) and only the finish is the pick.

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

#	Rule	How to check
1	File contains at most one entry function (one @agentic_function-decorated def at top level).	Eyeball / grep.
2	If the function makes any runtime.exec call, the entry function must be decorated with @agentic_function.	Eyeball.
3	If decorated, the signature must include runtime: Runtime — and give it a default (runtime: Runtime = None). A function passed to exec(tools=[...]) fails at tool dispatch with TypeError: missing a required argument: 'runtime' before injection if the parameter has no default; direct Python calls and the decision/choices path do inject.	Eyeball signature.
4	Every parameter has a type annotation; the return has an annotation.	Eyeball signature.
5	The function has a docstring whose first paragraph is a one-line summary.	Eyeball.
6	async def bodies are supported (the decorator wrapper has an async branch), but sync def remains the default recommendation: Runtime.async_exec exists but lacks tools= / choices= support.	Eyeball.
7	Every import / from ... import actually resolves in this environment. There is no import sandbox — any installed package works — but prefer the stdlib and openprogram.* so the function stays dependency-free and portable.	Read import lines; the §9 smoke test catches anything that doesn't resolve.
8	If you pull in a third-party package (not stdlib, not openprogram.*), confirm it's already installed and tell the user it's a new dependency.	Check / pip show <pkg>.
9	Code parses as Python (no syntax error).	Mentally compile; if unsure run python -c "import ast; ast.parse(open('<path>').read())".

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

#	Rule	How to check
10	content= is canonically a list[dict].	Eyeball.
11	Each item in a content list is a dict literal — content=[text] (a bare string inside the list) is wrong. Passing a plain string as content itself is accepted and auto-wrapped into a text block; the list-of-blocks form is canonical. content=[{"type":"text","text":text}] is the canonical shape.	Eyeball.
12	Each dict has "type": "text" (with "text") or "image" / "audio" / "file" (with "path").	Eyeball.
13	Allowed kwargs only: content, response_format, model, tools, toolset, tools_source, tools_allow, tools_deny, tool_choice, parallel_tool_calls, max_iterations, choices. tool_choice / parallel_tool_calls forward to the provider; max_iterations caps the tool-loop rounds at min(50, value).	Eyeball.
14	No system= kwarg. System instruction comes from the decorator (system="...") or the docstring, never from a runtime.exec kwarg.	Eyeball.
15	The per-call instruction lives inside the content text, not only in the docstring (see §4).	Eyeball — the text in content should describe the task.

6.3 @agentic_function(input=...) rules

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

#	Rule	How to check
16	The parameter appears as a key in input={...}.	Eyeball.
17	The entry has at least description.	Eyeball.
18	If options= is declared, all elements are strings (or other JSON-serializable scalars).	Eyeball.

6.4 Style rules (docstring + content)

#	Rule	How to check
19	No role-play in the docstring ("You are a helpful assistant").	Eyeball.
20	No empty directives ("Complete the task", "Do your best").	Eyeball.
21	The per-call content text defines the exact output format expected; don't leave it for the LLM to guess.	Eyeball.
22	The docstring may explain what the call does at any level of detail. But the LLM doesn't read it as instruction — the prompt in content does the work.	Eyeball.

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

The form sidebar renders each parameter by these rules:

Trait	Control
bool type	Yes / No toggle buttons
str type, multiline not set	Defaults to textarea (multiline=True implied)
str type, multiline: False	Single-line <input>
Non-str non-bool, no multiline	Single-line <input>
options: [...]	Clickable chips + free-form text input
options_from: "functions"	Dropdown populated from registered functions
hidden: True	Omitted from the form entirely
Has a Python default and no explicit placeholder	Placeholder set to "default: <value>"

workdir_mode controls the working-directory picker:

Value	Effect
"optional" (default)	Picker shown; can be empty
"hidden"	Picker hidden
"required"	Picker shown and required

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

Symptom	Likely cause
Generated function returns the wrong thing when run	Per-call prompt isn't in content=[...] — only in docstring. Codex / chatgpt subscription will reply conversationally. Move the instruction into content.
WebUI doesn't show your function	Filename starts with _, or the file isn't under one of the discovery roots.
Function crashes with ImportError	The imported package isn't installed in this environment. Install it, or rewrite using a stdlib / openprogram.* equivalent (see §6.1 rule 7).
Same function works on one provider, fails on another	Provider treats the rendered context tree differently. Make sure content=[...] is self-sufficient — the test should be: would this work if the function had no docstring at all? If yes, you're good.

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.