> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rippletide.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Decision runtime

> Build deterministic AI agents with the Rippletide hypergraph

## What is Decision runtime?

Decision runtime is the third pillar of Rippletide. After you've [evaluated your agent](/docs/evaluation_overview) and set up a [Context Graph](/docs/mcp/overview) for persistent memory, decision runtime lets you build agents that make **deterministic decisions** instead of probabilistic guesses.

You structure your agent's knowledge as a **hypergraph** of Q\&A pairs, tags, actions, and state transitions. The LLM handles language (understanding input, generating output), but all decisions are made by a deterministic reasoning engine.

**The result**: agents that hallucinate less than 1% of the time, with full explainability on every answer.

## When to use it

* You need guaranteed accuracy (less than 1% hallucination rate)
* Every decision must be traceable and explainable
* Guardrails must be enforced at the engine level, not just in prompts
* You're building customer-facing agents (support, sales, onboarding)

## How it differs from RAG

|                        | Traditional RAG                         | Rippletide Decision runtime                                 |
| ---------------------- | --------------------------------------- | ----------------------------------------------------------- |
| **Knowledge storage**  | Unstructured text chunks in a vector DB | Structured Q\&A pairs, tags, actions, and state transitions |
| **Decision-making**    | LLM generates answers probabilistically | Deterministic reasoning engine selects the best answer      |
| **Hallucination rate** | Variable, hard to control               | Less than 1% by design                                      |
| **Explainability**     | Black box                               | Every decision is traceable to a knowledge node             |
| **Guardrails**         | Prompt-based, easy to bypass            | Enforced at the engine level, 100% compliance               |

## Core Building Blocks

Your agent's knowledge is composed of four types of building blocks:

<CardGroup cols={2}>
  <Card title="Q&A Pairs" icon="circle-question">
    The questions your agent can answer and their expected responses. This is the foundation of your agent's knowledge.
  </Card>

  <Card title="Tags" icon="tags">
    Labels that organize Q\&A pairs by topic (e.g. "pricing", "shipping", "returns"). Tags improve retrieval accuracy and let you structure a glossary.
  </Card>

  <Card title="Actions" icon="bolt">
    Things your agent can do beyond answering questions: create a ticket, process a return, escalate to a human. Each action has requirements that must be met.
  </Card>

  <Card title="State Predicates" icon="diagram-project">
    Rules that define conversation flow. Based on what the user says, the agent transitions between states (e.g. "user described needs" -> "recommend product" -> "checkout").
  </Card>
</CardGroup>

## Architecture Overview

```
User message
    |
    v
[ Language Understanding (LLM) ]       Parses the user's intent
    |
    v
[ Hypergraph Reasoning Engine ]       Matches against Q&A, evaluates state, selects action
    |                                 (deterministic, no hallucination)
    v
[ Response Generation (LLM) ]        Formulates a natural language response
    |                                 from the selected knowledge node
    v
Agent response
```

The LLM is only used for **language** (understanding input, generating output). All **decisions** (which answer to give, which action to take, which state to transition to) are handled by the deterministic reasoning engine.

## Getting Started

<Steps>
  <Step title="Create an agent">
    Start with an evaluated agent and define the behavior it should make deterministic.
  </Step>

  <Step title="Add Q&A pairs">
    Populate your agent's knowledge base with questions and answers.
  </Step>

  <Step title="Organize with tags">
    Tag your Q\&A pairs by topic for better retrieval.
  </Step>

  <Step title="Define actions">
    Specify what your agent can do and the requirements for each action.
  </Step>

  <Step title="Set up state predicates">
    Design the conversation flow with states and transitions.
  </Step>

  <Step title="Chat">
    Send messages to your agent and get hallucination-free responses.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Evaluate your agent" icon="vial" href="/docs/evaluation_overview">
    Test the agent behavior before making decisions deterministic
  </Card>

  <Card title="Add memory" icon="diagram-project" href="/docs/mcp/overview">
    Give the agent persistent context with the Context Graph
  </Card>
</CardGroup>