Calling your existing programs
You do not need to rewrite what already works. Agents written in the Open Engineering Language call your existing Python, JavaScript, Java or .NET programs, shell commands and operating-system operations as typed tools, with runtimes you provide, locally or on a remote worker.
The packages
| Package | What it runs |
|---|---|
execution/process | A program, started with a list of arguments. No shell is involved. |
execution/shell | A command, through a shell you choose by name. |
execution/terminal | An interactive terminal session with a program. |
execution/python, execution/javascript | Your Python or JavaScript programs, scripts and modules. |
execution/jvm, execution/dotnet | Your Java or .NET programs. |
execution/remote | Any of these on a remote worker that you authorize. |
You add only the ones you use, with oel pack add:
oel pack add execution/python
Like every package, these are written in the language and ship in compiled, verified form, with no bundled native code and no install scripts. The programs they start are yours: the packages carry no Python, JavaScript, Java or .NET code of their own.
A function in your application, or a program you already have
The language gives you two ways to use code in another language, for two different jobs:
- You call your existing Python, JavaScript, Java or .NET programs, shell commands and operating-system operations as typed tools, with runtimes you provide, locally or on a remote worker. This page describes that way.
- Your application can hold private functions written in other languages, with typed signatures in the Open Engineering Language, built and run with your own toolchains, pinned by version. Functions in other languages describes them.
| Aspect | An existing program, through a package | A function in another language |
|---|---|---|
| The code | A program, script or command you already have, outside your source. | A function you write in your application: a language file, such as profile.python.oel, or fn python … beside a component's helpers. |
| How you call it | Through execution/process, execution/python or another package of the table above, as a typed tool. | Like any private function, through its typed signature in the Open Engineering Language. |
| When it is built | Never by the Compiler: it runs as it is. | When you build, by your own toolchain, at the version it pins. |
| Where it runs | On your machine, or on a remote worker you authorize. | On the same machine as your program, or in a sandbox. |
| Use it for | Programs and commands that exist already and keep their own life cycle. | Short code that belongs to your application and is built and versioned with it. |
A function in another language runs on the same machine by default or in a sandbox, which needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it, and a missing toolchain, a wrong version or a missing sandbox is refused before anything runs.
A shell function or the shell package
Shell code has the same two ways in. A bash or shell function is a script you write inside your application, in profile.bash.oel, profile.shell.oel or as fn bash … beside a component's helpers. Your build checks its syntax with your own shell, and the function is called through its typed signature in the Open Engineering Language, with its parameters passed as separate positional arguments and its result decoded into the type you declared. The execution/shell package is the other way: it runs a command you give it at run time, through a shell you choose by name, as a typed tool.
| Aspect | A bash or shell function | The execution/shell package |
|---|---|---|
| The script | Written by you, in your application source; it is part of what you build and version. | A command text your program supplies when it calls the package. |
| Arguments | Each typed parameter is one positional argument ($1, $2, …); a value with spaces, quotes, a leading hyphen or $(…) stays one argument. | Shell syntax in the command text is read by the shell, as you wrote it. |
| Checked | Its syntax, when you build, by the shell you name. | Never by the Compiler: the command runs as given. |
| Runs | On the same machine as your program, or in a sandbox when the function declares sandbox mode. | On your machine, or on a remote worker you authorize. |
| Use it for | Short scripts that belong to your application. | Commands that exist already or are built at run time. |
Choose a function when the script is part of your application and a package when the command is not. Functions in other languages describes the function form, including the shell option that names the interpreter.
A program as a typed tool
From your agent's side, an existing program looks like any other typed operation: it takes typed arguments and returns a typed result.
# nodes/score.node.oel
node score(input: Str<1000>) -> Str<64> {
config {
id: "score"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "score"; };
ports: [{ id: "claim"; direction: "input"; schema_type: "String<1000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 1000; join: "all"; },
{ id: "score"; direction: "output"; schema_type: "String<64>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 64; join: "all"; }];
limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
}
return run_scorer(input);
}
fn run_scorer(input: Str<1000>) -> Str<64> {
# Runs your scoring script through execution/python,
# with typed arguments, a deadline and output limits.
# This placeholder returns an empty score.
return "";
}
A model-driven node can offer the same call to its model as a tool, with its own permission; see Tools and MCP. The body of run_scorer is a placeholder, as A first agent explains.
What each call declares
| Part | Meaning |
|---|---|
| Program | The script, module, application file or executable to run, and its entry point. |
| Runtime | The runtime and version it needs, checked before the call runs. |
| Arguments | A list of typed values, never joined into one command line. |
| Environment | The working directory and the environment values you list; secrets passed by reference. |
| Permissions | The folders, network destinations and process rights the program may use. |
| Limits | A deadline, output size, CPU, memory, process count and temporary storage. |
| Result | The type its output must decode into, and your checks on it. |
Results you can rely on
- Exit does not mean success. A program that exits normally still has to produce output that decodes into your result type and passes your checks.
- Every outcome is typed. A failure status, a program stopped by the operating system, a program that could not start, a deadline passed, a cancellation, a resource limit and unreadable output are separate outcomes.
- Arguments stay data. A file name with spaces, quotes or a leading hyphen stays one argument. Only the shell package reads shell syntax, and only in the command text you give it.
- Output is bounded. Standard output and error are bounded byte streams; when output passes its limit, the result says how much was kept and, where it is known, how much was produced.
- Cancellation is thorough. Canceling a call stops the program and the programs it started, first gracefully, then by force after a grace period.
- Limits are real or refused. Where a platform cannot enforce a limit you asked for, the call is refused rather than run without it.
Runtimes you provide
Each call names the runtime it needs, and the program checks the runtime's identity and version before running anything. It does not fall back to whatever happens to be installed.
- On your machine or server, you install the runtimes your programs need.
- In a minimal container image, there is no shell, Python, Java or .NET unless your deployment includes it deliberately; the alternative is a remote worker.
- On a remote worker, the program runs on a machine you operate. The worker is authenticated, receives only the permissions, remaining budget and deadline of the call, and keeps the caller's tenant identity across reconnects. If the connection is lost after a call started, its outcome is reported as unknown, and work that cannot be repeated safely is never run again automatically.
- On the smallest boards, there are no processes: a call needs OEL Gateway, and without it the build or deployment is refused before anything runs.
Starting a runtime takes real time, and that time is reported like any other.
Isolation
Permissions keep your own program from reaching what it should not. They are not a sandbox for a hostile program: run code you do not trust in isolation, for example on a remote worker you dedicate to it.
Inside your application, you mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process, outside the shared communication layer, reachable only through the edges you declare and holding only the resources it declares itself. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on macOS, on Windows, on microcontroller boards, on other Linux targets and on any host without those facilities, an isolated component is refused, never run without isolation. A function in another language runs in a sandbox when it declares sandbox mode. Isolated components and Functions in other languages describe both.
Reports
Time and token usage is reported by default on every channel. The time a call takes is measured on your side. Model tokens that your external program uses on its own are reported as unknown unless they are measured; they are never guessed from its output.
Related
- Files and processes: the full reference for files, processes and their outcomes.
- Functions in other languages: private functions in other languages inside your application.
- Distributions: the components a distribution includes.
- Effects and capabilities: how permissions are granted and checked.
- Tools and MCP: starting a local MCP server as a separate process.