> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/platform-overview/design-principles.md). # Design Principles Four principles guide architecture and operating decisions in the Amigo platform. Some are enforced by code, while others depend on authored configuration, testing, and human release or governance decisions. ## 1. Measurement-First Decisions Agent behavior should be evaluated before it ships. Teams define relevant measures, run representative simulations, and compare results against an explicit baseline before making a release decision. Measurement is essential in healthcare because both structured and unstructured data vary in completeness, timeliness, and accuracy. Clinical notes reflect documentation practices, external records can be stale, and conversation-derived observations reflect what was said rather than independently proving it. Teams need explicit measures and provenance to decide how much evidence supports an outcome. In practice: * Teams associate important Context Graph paths with metrics or assertions that define success * Changes are tested against representative synthetic conversations before reaching real patients * Promotion from development to release follows an explicit human decision informed by quantitative criteria * Supported production interactions generate evidence that can feed later measurement * Data quality is evaluated alongside source provenance and confidence classes used for projection conflict resolution The practical effect is that teams can answer "did this change improve outcomes?" with comparable evidence rather than opinion. Metric trends can reveal degradation, but the platform does not automatically turn a trend threshold into an alert, promotion block, or rollback. Data provenance and confidence also help teams see when weak inputs may explain an outcome. ## 2. Composable Capabilities Agents are assembled from discrete, reusable components that can be combined, reviewed, and tested within the capabilities of the selected runtime. The building blocks: * **Context graphs** define what the agent should accomplish (goals, transitions, constraints) * **State guidance and transitions** add conditional behavior based on conversation and patient context * **Memory** can supply bounded, generated cross-session context and observed preferences * **Actions/Skills** let agents perform work in external systems These components can be combined where their runtime and tool contracts are compatible. A scheduling context graph can combine with insurance-verification guidance, a memory layer, and an EHR booking skill; changing the graph can reuse those compatible components for a different workflow. This matters for healthcare because safety reviews need inspectable configuration and evidence. Teams can review the authored state, available tools, relevant memory context, transcript, and recorded tool activity, while recognizing that evidence coverage varies by runtime and retained data. ## 3. Risk-Calibrated Autonomy Not all agent decisions carry the same risk. Teams encode different tool access, verification steps, approval policy, and escalation instructions based on the data source and the stakes of the action. The underlying data in healthcare is unreliable. Patients provide incomplete information, external systems return stale or inconsistent results, and records can conflict. The platform preserves source and confidence so an authored workflow can request verification, avoid an external mutation, or escalate rather than treating every observation as authoritative. {% hint style="warning" %} **Confidence hierarchy** - On governed projections that use the standard confidence fold, higher-confidence source classes win across classes and recency breaks ties within a class. Other projections can apply type-specific rules. {% endhint %} Modeled world events can carry a confidence class on the current eight-level hierarchy, from rejected through authoritative. EHR ingestion commonly enters the verified class, selected trusted clinical data can use the EHR-trusted class, patient self-report uses its own class, and raw agent inference remains lower. The world model page defines these source classes and the projection paths that use them: {% content-ref url="/pages/C9AEWitaAS9949s6XJTG" %} [World Model](/data/world-model.md) {% endcontent-ref %} Tool and delivery policy should follow the same logic: * Read-only lookups execute under the runtime's normal tool and authorization policy * Direct integration mutations follow their endpoint authorization and integration-specific validation * A supported text integration can pause a top-level tool call under its conversation-scoped `approval_policy` * Unattended connector write-back applies source, confidence, destination, and operation-specific eligibility * A private-preview review destination stages a source-eligible connector event at any confidence and requires approval of the specific proposal A patient lookup and a prescription change are fundamentally different operations. Teams should encode that difference through tool exposure, server-side authorization, validation, approval policy, and authored boundaries rather than relying on prompts alone. ## 4. Information Sufficiency, Not Script Completion Agents pursue goals, not fixed scripts. A context graph defines what needs to happen (verify identity, find available slots, confirm booking) and the constraints around it (what data is required, when to escalate). The agent figures out how to get there based on what the caller actually says. Real conversations are unpredictable - a patient might answer the identity verification question and immediately ask about their billing. A goal-oriented system handles the transition because the goals remain the same even when the conversation path changes. The context graph is a hierarchical state machine, not a decision tree. States represent objectives rather than dialogue turns. Model-driven navigation evaluates authored exit conditions from the available context; those conditions guide transitions but do not make the decision deterministic. More specifically, teams can author agents around information sufficiency - what is known, what is still needed, and what evidence supports each fact. Much of a front desk call, triage interaction, or intake workflow involves collecting enough information to take the next permitted action. A well-authored scheduling workflow can avoid asking for facts the patient already supplied and can pause when patient-provided information conflicts with an external record. The workflow should gather or verify only the evidence required for its next action and use an authored fallback when that evidence remains unavailable. The world model makes this practical by exposing current projected state with source and confidence. A Context Graph can instruct the agent to gather identity or scheduling facts before a transition and to clarify a lower-confidence observation or verify it through an authoritative tool. Use server-side validation for facts that must be present before an external action can execute. The practical mechanics: * Safety-sensitive Context Graph states define the information or evidence needed before they advance * Conversation context can retain what is known, missing, or conflicting * Transitions fire when authored exit conditions are met, not merely when a question count is reached * If required data cannot be verified, the authored fallback should avoid guessing and choose an appropriate clarification, refusal, callback, or escalation path Workflows can be as short as the available evidence allows and as thorough as the situation demands. A verified reschedule can take a shorter path than a new-patient workflow with unresolved insurance information because the latter has not yet met its authored evidence requirements. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/platform-overview/design-principles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.