Programming model · migration plan

Fixed boundaries of Agentic Functions, Workflows and Skills

This page is the authoritative classification and migration contract. Directories organize source only; decorator-registered functions are executable entities. Ordinary Agentic Functions permit only one model call; all complex orchestration belongs to Workflows.

Status: source categorized by directory · not marked ImplementedScope: Programs source, registration, Skills migration and Programs UINo new execution abstraction

1. Fixed decisions

Vanilla Function

Deterministic Python capabilities: no model call, Agent launch or Goal creation.

Model calls = 0

Agentic Function

A single-model capability consisting of a prompt and minimal deterministic code, replacing some first-party text Skills.

Exactly one llm() call

Workflow

Compositions containing multistep control flow, Agent tool loops, Goals, multiple model calls, file side effects or persistence.

Complex execution belongs only here

Agent method is the existing registration decorator, not permission for arbitrary Agent behavior. Public Workflow entries may still register through it, but their source must reside in workflow/ or programs/workflow/ Workflow categories. Classification follows execution semantics, not decorator names.

Capability	Vanilla	Agentic Function	Workflow
`llm()`	Prohibited	Exactly once	One or more permitted
`agent()` / `goal()`	Prohibited	Prohibited	Permitted
Model tool loops	Prohibited	Prohibited	Permitted
Deterministic preprocessing, parsing and validation	Permitted	Permitted	Permitted
Multistage control flow, checkpoints and persistent side effects	Prohibited	Prohibited	Permitted

2. Current capabilities require reclassification

Current capability type	Target category	Treatment
Pure text classification, extraction, summarization, translation and polishing	Agentic Function	Retain one `llm()`, allowing deterministic input preparation and output validation.
Model judgment in PDF chart/table extraction	Agentic Function	Retain single-model judgment; move model-free PDF layout and file helpers into Vanilla or internal helpers.
`browser_agent`, `web_use`, docs question, security review, `goal`	Workflow	These contain Agents, tool loops, multistage execution or Goals and must no longer be ordinary Agentic Functions.
Composite processes such as research pipelines and deep work	Workflow	Preserve composition; individual pure-transformation stages may become reusable Agentic Functions.
Word count, JSON, file scanning and PDF layout helpers	Vanilla / internal helper	No model calls; register as a Function only when public calling is needed.
interaction demo, test framework, resume demo	Test or remove	Must not appear as product Programs in the catalog.

Do not classify automatically by filename, directory or line count. Implementers must inspect reachable call graphs for model-call counts, occurrences of agent()/goal(), loops and side effects.

3. Target execution model

Workflows continue using static Python imports and ordinary function calls. Registration, permissions, cancellation, DAG caller and Runtime retain existing implementations; this design adds no DSL, dispatcher, registry or database.

4. Skills retention and migration boundaries

Source	Treatment	Reason
Third-party or user-installed Skill	Retain `SKILL.md`, resource files and the existing loading mechanism	These are installable extension formats and must not be broken by repository Python migration.
First-party pure-prompt Skill that needs one model call	Migrate individually to Agentic Functions	Gain typed parameters, registry discovery, testing and DAG records.
First-party Skill with scripts/tools/multistage state	Migrate to a Workflow or retain as a Skill	Do not remove necessary control flow merely to satisfy the one-model-call rule.
Skill providing only documentation and reference material	Retain as a Skill	On-demand context resources are not executable functions.

Migrate one Skill at a time. Prove equivalent input/output contracts before removing each old first-party entry; do not mechanically convert all Skills or change third-party installation protocols.

Framework comparison and adoption scope

Reference	Official boundary	Adopted by OpenProgram	Not adopted
OpenAI Agents SDK · Tools	Ordinary Python functions become Function Tools with typed schemas; an Agent used as a tool creates nested Agent execution.	Retain typed parameters on registered functions; explicitly classify autonomous tool loops as Workflows.	Do not interpret every Agentic Function as an Agent.
LangGraph · Workflows and agents	Workflows follow predefined code paths; Agents dynamically choose processes and tools.	Workflows own Python control flow and may explicitly call `agent()`.	Do not introduce a graph DSL or second execution engine.
Anthropic · Agent Skills	A Skill is an on-demand `SKILL.md` with optional scripts, templates and resources.	Retain third-party, user-installed and reference Skills; migrate only first-party executable capabilities.	Do not force all Skills into Python functions.

5. Target directories describe source categories only

openprogram/programs/
├── functions/
│   ├── vanilla/                         # 0 model calls
│   └── agentic/
│       ├── document/                    # Single-model document capabilities
│       ├── text/                        # Summarization, translation, rewriting, classification
│       ├── research/                    # Single-model stages only
│       └── workflow/                    # Reusable Workflow management/runtime support
│           ├── search_workflows.py
│           ├── create_workflow.py
│           ├── revise_workflow.py
│           ├── resume_workflow.py
│           ├── errors.py
│           ├── _generation/             # Internal generation, not displayed as Skills
│           ├── _project/                # Internal project management, not displayed as Skills
│           ├── _runtime/                # Internal execution, not displayed as Skills
│           ├── browser/
│           ├── docs_question/
│           ├── security_review/
│           └── goal/
├── workflows/                           # Complete directly executable Workflows
│   ├── auto_workflow.py                 # Built-in automatic selection, creation and execution
│   └── <workflow-project>/             # Generated, published, reusable Git projects
└── applications/

Directory nodes are navigation only. Organize entry files, helpers and subdirectories as normal Python code; split files only for separate responsibilities. Do not pre-create empty runtime.py, legacy.py or one-function-per-directory layouts; Programs displays only actual folder paths and registered functions.

6. Five independent implementation tasks

Freeze the classification contract

Add static contract tests: Vanilla reachable call graphs must never reach a model; ordinary Agentic Functions must reach exactly one llm() and must never reach agent()/goal(); Workflow categories are unrestricted by this rule.

RED: first detect the current incorrect browser/docs/security/goal classification.

Organize true Agentic Functions

Classify by actual responsibilities such as document, text and research. Preserve deterministic pre/postprocessing; move model-free helpers into Vanilla or internal modules. Moving files must not change registry names, schemas or public calling conventions.

Gate: equivalent registration inventories before/after; every Agentic Function satisfies one llm call.

Move complex capabilities into Workflow categories

Migrate browser/web, docs question, security review, goal, deep work and composite research. Move only code ownership and imports, without a new runtime; organize directories by subsystem.

Gate: call graphs show real entries and dependencies; a directory itself never becomes a Program.

Handle first-party Skills individually

Create an inventory marked keep / agentic / workflow. Migrate pure-prompt single-call capabilities to Agentic Functions and complex flows to Workflows; leave third-party/user Skills unchanged.

Gate: every deleted first-party Skill has equivalent parameter, output and failure-semantics tests.

Remove demos and structures without responsibilities

Move interaction demos, test frameworks and resume demos to tests or delete them; remove empty directories, empty entries and unused helpers. Retain compatibility aliases only for actual public external contracts.

Gate: no demos, empty directories or helpers posing as entities in Programs.

7. Acceptance and completion conditions

Classification contract

Vanilla = 0 model calls; Agentic Function = 1 llm(); complex execution = Workflow.

Directory display

Programs follows actual folder paths without fabricated directories, empty folders or helpers.

Execution identity

Only registered functions are executable; moving files does not change names, schemas, exposure or execution IDs.

Skills

Third-party/user Skills remain compatible; first-party migrations have per-item inventories and equivalence tests.

Architectural limits

No new @workflow, call_workflow(), DSL, second registry or second Runtime.

Product acceptance

The default-App Programs tree has no empty entries; function-detail call graphs derive from the selected function’s actual reachable calls.

Minimum verification: classification contracts, Programs discovery/graph tests, related unit/component tests, Ruff, Web typecheck, documentation links and git diff --check. The default-App Programs tree must still be verified in /Applications/OpenProgram.app before this page can be marked Implemented.

Workflow package imports

from workflows.NAME import NAME references the same authorized public callable in the active directory; snapshot execution explicitly owns its workflows namespace and retains fixed dependency versions. Package helpers use relative imports and execution remains ordinary Python function calls. Both authored and generated packages pass structural validation and mandatory sandbox behavior tests before publication. See Workflow package contract.