/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Agent

Keywords on this page
WordMeaningExample
LLMThe language model that writes the answerAny OpenAI-compatible provider
ToolSomething the model may ask the service to doRead a building’s sensors
HopOne round: the model answers, or asks for a toolHop 1 asks for sensors, hop 2 answers
ChunkA small piece of the documentation, searched on its ownOne section of a page
EmbeddingA list of numbers that stands for a text’s meaningUsed to find similar chunks
CitationA pointer from the answer to the chunk it came from[1]
TraceA record of every hop and tool, with time and costSent to Langfuse

Realises the Knowledge & Assistance domain, with chat. Python, PostgreSQL with pgvector. Code-level page: Agent Service.

Answers one question at a time: finds the right documentation, fetches live data if needed, writes an answer with citations. Remembers nothing between questions.


Who talks to it

flowchart LR
    Ch["chat"] -- "question, same claims" --> A["agent"]
    A -- "tool calls, same claims" --> Tw["digital-twin"]
    A -- "tool calls, same claims" --> T["telemetry"]
    A --> L["LLM provider"]
    A --> E["Embedding provider"]
    A --> DB[("PostgreSQL: chunks")]
    A -. "traces" .-> LF["Langfuse"]

Inside

flowchart LR
    R["/ask route"] --> LOOP["The loop"]
    LOOP --> LLM["Port: model"]
    LOOP --> REG["Tool registry"]
    REG --> T1["search_docs"]
    REG --> T2["sensors: 3 tools"]
    REG --> T3["buildings and rooms: 4 tools"]

The loop

flowchart TD
    Q["Question"] --> M["Ask the model, with every tool it may use"]
    M --> D{"Tool asked?"}
    D -- "no" --> C["Check citations"]
    D -- "yes" --> T["Run the tools, add their results"]
    T --> H{"Hop limit reached?"}
    H -- "no" --> M
    H -- "yes" --> I["Answer: I don't know"]
    C --> Out["Answer"]

Example. “Is room 2 too hot?” Hop 1: the model asks for room 2’s sensors. Hop 2: with 31 °C in hand, it answers, citing the limits page.

RuleWhy
A hop limitA model stuck calling tools cannot spend time and money forever
Citations checked after writingA citation to a chunk never retrieved is removed, not shown
Streamed and waited answers share one loopThe two cannot drift; only the model call differs
The final answer wins over streamed wordsRemoved citations may already have been streamed

Finding documentation

flowchart LR
    Q["Question"] --> V["Search by meaning"]
    Q --> K["Search by words"]
    V --> F["Merge both rankings"]
    K --> F
    F --> RR["Rerank, does nothing yet"]
    RR --> Top["Best chunks"]

Rights, checked twice

WhereChecks
SearchWhich documentation the person may read
ToolsWhich live data the person may read, with Cedar

Neither layer trusts the other to have checked.


How it is reached


Gaps