Retrieval over your documents — AEL documentation

Agents written in AEL, the Agent Engineering Language, ground their answers in your own documents. Retrieval (RAG) covers the whole lifecycle (ingest, chunk, embed, index, update and delete, then retrieve with ranking and provenance), and you can bring your own knowledge connectors.

A retrieval agent

A typical agent retrieves evidence, asks a model to answer from it, and checks the answer's citations before it returns:

# agents/advisor.agent.ael
agent advisor(input: Question) -> Answer {
    config {
        nodes: [retriever = retrieve, writer = answer, checker = check_citations];
        edges: [evidence_to_answer(retriever, writer), answer_to_check(writer, checker)];
        starts: [retriever];
        completion: checker.result;
    }
}

# nodes/answer.node.ael
node answer(input: Evidence) -> Answer {
    config {
        prompt: file("prompts/answer.md");
        model: binding("primary_model");
        max_attempts: 2;
    }
    return write_answer(input);
}

fn write_answer(input: Evidence) -> Answer {
    # Asks the model for an answer that cites the evidence it used.
}

retrieve and check_citations are deterministic nodes: they call no model. The body of write_answer is a placeholder, as A first agent explains.

From documents to knowledge

Stage	What happens
Ingest	Only documents the run is permitted to ingest are read, within byte, page and record limits. Instructions inside a document are treated as content, never as commands.
Chunk	Each document is split into chunks with fixed IDs that keep their source, location, metadata and version. The chunking settings are part of the index's identity, so changing them means a different index.
Embed	Chunks are embedded in batches within request, token and memory limits. The embedding model, its version and its dimension are recorded, and a mismatch is refused.
Index	A new version of a source becomes visible to queries only when all its chunks are indexed, so a query never sees half of an update.
Update	Updates are checked against the version they replace, and old chunks are replaced. Two writers updating the same source get a typed conflict, not a silent overwrite.
Delete	Deleted sources and chunks stop appearing in results once the deletion is committed. When the stored data itself is reclaimed is reported separately.

An interrupted ingestion resumes without duplicating chunks, and a cancelled one cleans up what it had staged. A failure keeps the previous committed version of your knowledge.

Retrieving evidence

Three modes. You choose whether retrieval is off, runs before a model call or is a tool the model calls.
Your policy. You choose the query, metadata filters, the number of results, reranking, freshness rules and the size limit of the retrieved context.
Typed results. Each result carries its source, version, location, score, retrieval time and the scope it was read under.
Evidence, not instructions. Retrieved text reaches the model as evidence with a citation handle, separate from the system prompt. It never overwrites the prompt or widens what the node may do.
Checked citations. Your checks can confirm that every cited handle exists, names an allowed source and version, and is fresh enough, before the normal output checks run.
Clear outcomes. An unavailable source, a failed check and an empty result are different typed outcomes, each with the fallback you declared.

Queries, reranking and any model calls they make draw on the run's shared budget, so retrieval cannot quietly multiply cost; see Budgets, retries and validation.

Scopes and permissions

Reading and writing knowledge are separate permissions. Every store and every query is scoped by the trusted tenant identity of the run, and results never reveal sources the caller may not see. See Memory and state for scopes, retention and deletion rules.

Your own connectors

You write your own connectors for services, models, knowledge sources, transports and log sinks, in AEL. For retrieval, a connector can provide:

a knowledge store, such as a search service or a document system you already run;
a retriever or a ranking policy;
an embedding provider, such as a model endpoint you run yourself;
a context policy that decides what reaches the model;
a verifier that accepts or rejects an answer, is unavailable, fails in a way that can be retried, or hands the answer to a person for review.

A read-only store says so: an update or a deletion it cannot perform returns an explicit error.

Where your knowledge lives

AEL itself contains no database: the memory, knowledge and durable state of your runs live in the storage, database and vector-store packages you select. Optional vector-store packages index and search your knowledge for retrieval, in a database you run.

An agent, subagent or node declares the memory, skills, knowledge, storage and database it uses, each bound to a package you select, and the check refuses any use it did not declare. The advisor's knowledge store is a vector-store package that it binds through its knowledge binding, over a database you run. Bindings and storage describes the bindings, and the Package catalog the vector-store packages.

Where it runs

Ingestion, embedding and indexing run on desktop and server targets, in containers, on AEL Gateway, or on a larger board qualified for it. The smallest boards send bounded requests to retrieval running elsewhere and never hold an index themselves.

Honest limits

Retrieval quality depends on your documents, chunking and ranking, and no retrieval is guaranteed to find the relevant document. AEL checks where evidence came from and whether it is allowed and fresh; it does not decide whether an answer is true. Keeping retrieved text apart from the prompt does not make a model immune to instructions hidden in a document: your checks and the node's permissions limit what such text can cause. The built-in ingestion reads a reference document format; for other formats, you write a connector.