Retrieval over your documents

A retrieval agent

A typical agent will retrieve evidence, ask a model to answer from it, and check 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 will be deterministic nodes: they will call no model. How a node names its knowledge store and retrieval settings will be confirmed when the syntax is final. The body of write_answer is a placeholder, as A first agent explains.

From documents to knowledge

An interrupted ingestion will resume without duplicating chunks, and a cancelled one will clean up what it had staged. A failure will keep the previous committed version of your knowledge.

Retrieving evidence

• Three modes. Retrieval will be off, run before a model call, or be a tool the model calls, as you choose.
• Your policy. You will choose the query, metadata filters, the number of results, reranking, freshness rules and the size limit of the retrieved context.
• Typed results. Each result will carry its source, version, location, score, retrieval time and the scope it was read under.
• Evidence, not instructions. Retrieved text will reach the model as evidence with a citation handle, separate from the system prompt. It will never overwrite the prompt or widen what the node may do.
• Checked citations. Your checks will be able to 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 will be different typed outcomes, each with the fallback you declared.

Queries, reranking and any model calls they make will 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 will be separate permissions. Every store and every query will be scoped by the trusted tenant identity of the run, and results will never reveal sources the caller may not see. See Memory and state for scopes, retention and deletion rules.

Your own connectors

You will write your own connectors for services, models, knowledge sources, transports and log sinks, in AEL. For retrieval, a connector will be able to 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 will say so: an update or a deletion it cannot perform will return an explicit error. The beta will include a reference knowledge store that covers the whole lifecycle above.

Where it runs

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

Honest limits

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