Browse the documentation

Early preview

A first agent

This walk-through builds a console agent in the Open Engineering Language. You give it a customer's support request, and it returns a short summary for your support team, written by a model that follows a system prompt you write. A console agent needs no server.

The project

One command creates the project:

oel init support

Besides the three root files that oel init creates, the agent needs three files: a system prompt, a node and the agent itself.

support/
  main.oel                       # the program's entry point
  pack.oel                       # packages; none needed here
  metadata.oel                   # the project's name
  prompts/summarize.md           # the system prompt
  src/
    nodes/summarize.node.oel     # the node: one business step
    agents/helpdesk.agent.oel    # the agent: the workflow

Apart from the three root files, the folder names are your choice.

metadata.oel holds the application's name, which main carries:

# metadata.oel
metadata {
    schema = 1;
    name = "support";
    source_profile = "oel-source/1";
}

The system prompt

The system prompt is the agent's business policy, written for its model in plain language. Here it is kept in its own file, prompts/summarize.md:

You summarize customer support requests for the support team.
Write two or three sentences: what the customer wants, and anything urgent.
Use only facts that are in the request.

You can also write a system prompt inline, or take it from the environment or from configuration. Without one, the agent runs on its input alone.

The node

A node is one business step. This one sends the request to a model, with the system prompt, and returns the model's summary:

# src/nodes/summarize.node.oel
node summarize(input: Str<4000>) -> Str<1000> {
    config {
        id: "summarize"; version: "1.0.0";
        policy: {
            kind: "model"; entry: "summarize"; model_binding: "primary_model";
            mode: "bounded_loop"; max_attempts: 2; max_repairs: 0;
        };
        ports: [
            { id: "request"; direction: "input"; schema_type: "String<4000>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 4000; join: "all"; },
            { id: "summary"; direction: "output"; schema_type: "String<1000>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 1000; join: "all"; }
        ];
        limits: {
            ram_bytes: 16777216; cpu_millicores: 1000; cpu_millis: 1000;
            duration_ms: 120000; input_tokens: 16384; output_tokens: 1024;
            model_calls: 2; tool_calls: 0; steps: 32; concurrency: 1;
            max_children: 0; max_depth: 1; 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: {
            schema_version: 0;
            sources: [{ kind: "project_file"; ref: "prompts/summarize.md"; }];
            input_renderer: "render_input";
            require_system: false; allow_run_override: false;
        };
        prompt_variables: [];
        binding: {
            schema_version: 0; binding_id: "primary_model";
            adapter_id: "openai_core"; adapter_version: "1.0.0";
            family: "openai_chat"; endpoint: "http://127.0.0.1:8080/v1";
            model_id: "primary-model"; auth: { kind: "env"; ref: "MODEL_API_KEY"; };
            max_attempts: 2; timeout_ms: 60000;
            defaults: {}; allowed_overrides: [];
            capabilities: {
                input_modalities: ["text"]; output_modalities: ["text"];
                instructions: true; structured_output: false; tools: false;
                streaming: false; max_context_tokens: 32768; max_output_tokens: 1024;
                parameters: []; usage: "bounded_estimate";
            };
        };
        binding_capability_revision: "1";
    }
    return write_summary(input);
}

fn write_summary(request: Str<4000>) -> Str<1000> {
    # Placeholder helper: only this node can call it. It returns an empty summary.
    return "";
}
  • Str<4000> is text of at most 4,000 bytes. The node's input and output are typed, and the Compiler checks them.
  • config is the node's checked record of settings: its identity, its ports, its limits and its model policy. The ports carry the node's typed input and output.
  • prompt names the system prompt. A project_file reference is relative to the project root, not to the node's own file, so this one names prompts/summarize.md beside main.oel.
  • binding describes the model endpoint, primary_model: an OpenAI-compatible API, a local model server or a major cloud provider. The credential is a reference to an environment variable, never the credential itself.
  • max_attempts: 2 in the policy lets the node try again if its first attempt fails, and every attempt draws on the run's budget.
  • write_summary is a private helper whose body is a placeholder on this page; see Placeholder bodies.

Models and providers describes model calls and bindings, and Budgets, retries and validation output checks and retries.

The agent

The agent is the workflow: which nodes it runs, where work starts, and what completes it. It is named helpdesk because the application, support, already has that name.

# src/agents/helpdesk.agent.oel
agent helpdesk(input: Str<4000>) -> Str<1000> {
    config {
        id: "helpdesk"; version: "1.0.0";
        ports: [
            { id: "request"; direction: "input"; schema_type: "String<4000>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 4000; join: "all"; },
            { id: "summary"; direction: "output"; schema_type: "String<1000>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 1000; join: "all"; }
        ];
        limits: {
            ram_bytes: 33554432; cpu_millicores: 1000; cpu_millis: 8000;
            duration_ms: 120000; input_tokens: 16384; output_tokens: 1024;
            model_calls: 2; tool_calls: 0; steps: 10000; concurrency: 2;
            max_children: 1; max_depth: 2; queue_items: 1; queued_bytes: 65536;
            stream_bytes_per_second: 0; storage_bytes: 0; connections: 0;
            cost_microunits: 0;
        };
        authority: []; capabilities: []; profile: "host"; state_domain: "request";
        nodes: [{ id: "summarizer"; source: "src/nodes/summarize.node.oel"; }];
        agents: []; edges: []; starts: ["summarizer"];
        inputs: [{ port: "request"; to: { instance: "summarizer"; port: "request"; }; }];
        dispatch: "sequential";
        completion: { kind: "all"; result: { instance: "summarizer"; port: "summary"; }; };
    }
}

summarizer is this agent's instance of the node summarize: the nodes list gives each instance its identity and the project-relative file of its node, and starts, inputs and completion say where work starts, where the request enters and which output completes the run. An agent with one node needs no edge. A larger workflow adds a node for each business step and an edge for each typed connection between two nodes.

The entry point

main carries the application's name, support, as metadata.oel records it, and takes no parameters. It imports the agent, gives it a request and receives its summary:

# main.oel
import "./src/agents/helpdesk.agent.oel";

main support() {
    let request: Str<4000> = "Where is my order?";
    let summary: Str<1000> = helpdesk(request);
}

Placeholder bodies

The helper write_summary on this page returns an empty summary: it is a placeholder, so that the page checks as shown. The page shows how an agent is put together, not the library's operations, such as the call that sends a request to a model. Other pages of this documentation use placeholder bodies in the same way, and a placeholder still passes the check, because every path through a function with a result ends in a return (Control flow).

Model client describes the call that sends a request to the model that a node's config block binds with prompt and binding.

Checking and running

You check and run the project from inside the support folder:

oel check
oel run

oel check checks the whole project before anything runs: the file names and roles, the path of the prompt file, the types that pass from main to the agent and its node, and the model binding. Its diagnostics point at your source.

oel run builds the project into a native program and starts it.

Where to go next

  • Checking the summaries. A second node can verify each summary, with an edge connecting the two nodes. Agents, nodes and edges shows such a verifying node, and Workflows describes workflows and edges in full.
  • Serving an API. Adding the HTTP package and declaring routes makes the agent a REST API; removing them takes it back to console-only. Services and APIs shows the HTTP package at work.
  • The whole layout. Project layout shows every kind of file a project can hold.
  • The whole command line. Your first agent, end to end takes this agent through its prompt sources, its model binding and budget, tests, an evaluation and a build.

Complete example agent systems and deployment recipes come with Compiler 1.0.0.