Agents and LLM backends¶

TriageSim separates who is speaking (the agent, which owns a persona and a prompt) from what generates the text (the LLM backend). This page covers both layers and the schemas that connect them.

The two-layer design¶

flowchart LR
    P[Persona] --> A[NurseAgent / PatientAgent]
    H[Transcript] --> A
    A -->|prompt| B[BaseLLM]
    B -->|validated Pydantic model| A
    A -->|NurseOutput / PatientOutput| E[TriageEnv]

An agent builds a prompt from its persona, the transcript, and the triage protocol. The backend turns that prompt into a schema-validated object — not a string. Nothing downstream ever parses free text.

Output schemas¶

Both schemas inherit from BaseAgentOutput, which forbids extra fields. If the model invents a key, validation fails rather than the key being quietly accepted — the comment in the source calls this out as critical, and it is the main defence against a model smuggling unsanctioned state into the run.

PatientOutput¶

The patient has exactly one thing it can do: speak.

NurseOutput¶

Because triage, confidence and explanation are emitted at every step, the trace records how the decision evolved — including the turn at which the nurse first arrived at the correct level.

BaseLLM¶

The backend interface is a single abstract method:

from abc import ABC
from typing import List, Optional, Union

class BaseLLM(ABC):
    def generate(
        self,
        prompt: str,
        max_tokens: Optional[int] = None,
        stop: Optional[List[str]] = None,
        **kwargs,
    ) -> Union[str, BaseAgentOutput]:
        ...

Anything implementing generate can drive an agent.

OpenRouterLLM¶

The bundled backend routes through OpenRouter using pydantic-ai:

from triagesim.agents import OpenRouterLLM
from triagesim.core import NurseOutput, PatientOutput

nurse_llm = OpenRouterLLM(model_name="anthropic/claude-sonnet-4-5",
                          output_type=NurseOutput)
patient_llm = OpenRouterLLM(model_name="google/gemini-3-pro-preview",
                            output_type=PatientOutput)

The API key is read from triagesim.config.OPENROUTER_API_KEY, not passed in. See Configuration.

One backend per agent. The output schema is bound at construction, so a nurse backend physically cannot serve a patient agent. This turns a whole class of wiring mistakes into an obvious two-line setup instead of a confusing validation error twenty turns into a run.

PatientAgent¶

from triagesim.agents import PatientAgent

patient = PatientAgent(llm=patient_llm, persona=patient_persona)

Its single method is:

output = patient.act(
    history="Nurse: What brings you in today?",
    chief_complaint="Syncope",
    pain=7,
)
print(output.utterance)

The patient sees only the transcript, its chief complaint, and its pain score. It never sees vitals or the true acuity — it can only report what a person in that situation would plausibly know and choose to say.

NurseAgent¶

from triagesim.agents import NurseAgent

nurse = NurseAgent(llm=nurse_llm, persona=nurse_persona, algorithm="esi")

act¶

output = nurse.act(history=transcript, known_vitals={"heartrate", "o2sat"})

known_vitals is the set of vitals already released. The agent uses it to build the list of actions still available, so the nurse is not offered a vital it has already seen.

infer_belief_updates¶

After each patient utterance the runner asks the nurse to extract structured belief updates from what was just said:

updates = nurse.infer_belief_updates(
    history=transcript,
    last_utterance="I went dizzy and the next thing I knew I was on the floor.",
    turn=3,
)

These are merged into the environment's belief graph. This is a separate call from act — reasoning about what was learned is deliberately not entangled with deciding what to do next.

Custom backends¶

To use a provider other than OpenRouter, subclass BaseLLM:

from typing import List, Optional, Union

from triagesim.agents import BaseLLM
from triagesim.core import BaseAgentOutput, NurseOutput


class MyLLM(BaseLLM):
    def __init__(self, output_type: type[BaseAgentOutput]):
        self.output_type = output_type

    def generate(
        self,
        prompt: str,
        max_tokens: Optional[int] = None,
        stop: Optional[List[str]] = None,
        **kwargs,
    ) -> Union[str, BaseAgentOutput]:
        raw = my_provider_call(prompt, max_tokens=max_tokens, stop=stop)
        return self.output_type.model_validate_json(raw)


nurse_llm = MyLLM(output_type=NurseOutput)

Two requirements:

1. generate must return an instance of the bound output type, not a string, or the environment will reject it with a TypeError.
2. Your provider must be able to honour the schema. Prompting for JSON and validating with model_validate_json works, but budget for retries — an unconstrained model will occasionally emit prose.

Next: Running a simulation.