Typed inputs and outputs

Inputs

The parameters of an agent or a node will be its inputs. You will write them with ordinary types:

# nodes/review.node.ael
struct ReviewRequest {
    document: Str<4000>,
    strict: bool,
    max_findings: u16,
    locale: Option<Str<16>>,
}

node review(request: ReviewRequest) -> Review {
    config {
        prompt: file("prompts/review.md");
        model: binding("primary_model");
    }
    return write_review(request);
}

• Every input will have a maximum size: text and lists will have a fixed capacity, written in their type.
• A missing optional value, Option::None, will be different from a value that is present.
• An unknown field, a value out of range, text that is too long or invalid, and a wrong enum variant will be errors that name the field they concern.
• The same decoding and the same checks will apply wherever the input comes from: the console, an HTTP route or another agent. JSON gives the rules for input that arrives as JSON.

Input builders and input checks

• An input check will be a helper function that accepts or rejects a typed input before any work starts, with a typed error.
• An input builder will be a helper function that turns a typed input into what the model receives. The result may be text, or other parts such as images, audio or files when the model accepts them.

Structured input will need no special prompt field: the input builder will decide what the model sees. The size of the model's input will be checked before the call is sent. How a node names its input builder and checks will be confirmed when the syntax is final.

Outputs

A model's answer will become a typed output only through these steps, in this order:

1. receive the answer, within a size limit;
2. decode it into the node's output type;
3. check its structure: every field present, every value in range;
4. run your output checks, in the order you declare;
5. apply your transformation, if you declare one;
6. check the structure again;
7. accept it, or apply your failure policy.

A result that fails a step will never become a typed value. An answer that was cut off, or a stream that ended early, will never count as complete. The output type will be the authority: AEL will check it even if the prompt already asks for the right shape. Budgets, retries and validation describes output checks and repairs.

Raw or typed results

A node will be able to take the model's raw output instead and parse it with your own code. In that mode the answer will have a raw output type, not your application type: raw text will never be presented as a checked value. What your parser returns will go through the structural check before it becomes typed.

Several inputs

A node or agent will be able to take several inputs that arrive together, separately or continuously. When it takes more than one, it will choose how they are combined:

There will be no default: a node with several inputs will have to choose, so it never combines a stale camera frame with a new reading by accident. An observation older than its declared freshness will be refused.

Media and files

Text, structured data and media will be separate kinds of input part:

• Images, audio, files and video frames will travel as references to stored data, not as text inside a message. A reference will record the content type, the size, a fingerprint, an expiry and where the data came from.
• Access will be checked every time a reference is used, against the run's tenant and permissions.
• The content type, size, dimensions, duration and sample rate will be checked against what the input declares, before the data is decoded.
• Your own steps will be able to prepare media, such as extracting the text of a document, transcribing audio or sampling video frames, and they will keep a record of where each result came from.

A model endpoint accepts only some kinds of media; a kind it cannot take will be an error before the call. See Models and providers.

Streams

A stream will be a bounded sequence of typed chunks, such as a live camera or sensor feed.

• A stream will declare its limits: chunk size, buffered bytes, rate, duration and freshness.
• Backpressure will slow the sender when the receiver is behind. When the buffer is full, the stream will follow its declared policy: reject, drop the oldest, drop the newest, or pause the source when it can be paused.
• Chunks will carry timestamps and sequence numbers; duplicates and stale chunks will be rejected or discarded by a declared rule.
• A stream will end with an explicit completion, error or cancellation.

Limits

• Every input, output, reference and stream will have a fixed maximum size. Nothing will grow without bound.
• Large media will always travel as references, never inside a message.
• On the smallest boards, agents will take compact observations, such as samples or detected features, rather than raw video.

The JSON Schemas of these formats are listed under Agent inputs and outputs.