Concepts¶

Overview¶

A chatomon agent is an atom: a nucleus that answers the user, surrounded by orbitals that check what goes in and what comes out. This page explains the pieces, what an orbital can decide, and what happens to a message during one conversation turn.

The Atom¶

The nucleus is the native agent the connector builds: the model with the instructions and the knowledge. Atom.build() validates the configuration and returns it; from then on you use the framework's own API.

Orbitals never inherit the atom's instructions or knowledge. Each orbital gets a definition written for its own job, because guard models perform much better with purpose-written descriptions than with the assistant's prompt. Sharing is always explicit — for example, passing the same Knowledge object to a judge.

Verdicts¶

Every orbital returns a Verdict (src/chatomon/schemas.py):

A verdict can also carry annotations (data for later orbitals, see Chaining Orbitals), a short reason label for the audit report, and escalate, which marks the turn as needing a human.

A Turn, Step by Step¶

sequenceDiagram
    participant User
    participant Input as Input orbitals
    participant Nucleus as Nucleus (framework model)
    participant Output as Output orbitals
    User->>Input: message
    alt respond or block with a reply
        Input-->>User: reply (model not called)
    else allow, or block with guidance
        Input->>Nucleus: message (or placeholder) + guidance
        Nucleus->>Output: draft reply
        alt allow
            Output-->>User: reply
        else block with guidance (within max_retries)
            Output->>Nucleus: regenerate with all guidance so far
        else respond or block with a reply
            Output-->>User: replacement reply
        end
    end

The engine that implements these rules is Engine in src/chatomon/engine.py; connectors only translate its decisions into framework hooks.

Guided Refusals¶

When an input orbital blocks a message with guidance, the nucleus writes the refusal without seeing the message. For the message I want a refund, blocked with the guidance Explain that refunds are handled by email., this is what the model receives:

System prompt

    You are the customer assistant of SpeedyPack.

    <guidance>
    - The user's last message is withheld from you and a placeholder stands in its place. Do not mention the placeholder or that a message was removed: reply as the guidance says.
    - Explain that refunds are handled by email.
    </guidance>

User message

    [message removed by chatomon]

The second item of the guidance is the orbital's. The first is chatomon's, and it is there because of the placeholder. A model that receives the placeholder and is not told what it is can answer about it: it tells the user that a message was removed and asks to send it again, or it only greets. The user then never gets the refusal the orbital asked for.

Both texts are settings of the atom:

Atom(blocked_guidance="...") gives the nucleus your own text in place of the default. Atom(blocked_guidance=None) gives it the orbital's guidance alone: the guidance of each orbital then has to say what to do with the placeholder.

• Try it on your model. How a model treats the placeholder changes from one model to another. Run a guided refusal on yours a few times: if a reply speaks of a removed message, or does not follow the orbital's guidance, reword blocked_guidance.
• It does not quote the placeholder. The default speaks of a placeholder without repeating its text, so it holds for a blocked_placeholder of your own.
• It is given in a guided refusal only. A turn whose message passes never gets it. A guided refusal that an output orbital sends back to the nucleus keeps it, with the orbital's guidance, because the placeholder is still in place of the message.
• It is not in the turn report. The report records the guidance of each orbital. blocked_guidance is the same in every turn: read it on the atom.

Rules That Always Hold¶

• Blocked messages never reach the nucleus. In the stored conversation history a blocked user message is replaced by a placeholder ([message removed by chatomon] by default), so it cannot resurface in later turns. (LangGraph checkpointers also keep earlier snapshots of a thread; see Connectors.)
• Guidance lives for one model call. It is added to the system prompt of that call only and never stored in the history.
• Everything the nucleus writes goes through the output orbitals, including a guided refusal. What an orbital writes does not.
• Regenerations are capped. After max_retries regenerations (2 by default) the user receives the default refusal. Each regeneration carries every output guidance received so far in the turn, so the model does not reintroduce a problem already fixed.
• Output orbitals see input annotations of the same turn; each output attempt starts again from them.
• Fail-closed. An orbital that raises or exceeds its timeout counts as block, unless it is configured with on_error="allow".
• Only final text replies are checked. Intermediate model responses that call tools are not.

Related Documentation¶

• Orbitals — writing and chaining orbitals
• Connectors — how the rules map onto PydanticAI, LangChain, MAF and Google ADK
• Observability and Audit — what each turn records

Last Updated: October 2026 Status: Implemented