Skip to main content

​
Overview

Rippletide provides a set of APIs for building agents with less than 1% hallucinations. You structure your agent’s knowledge as a hypergraph made of four building blocks: Q&A pairs, tags, actions, and state predicates. When data is updated within the graph, implications in other areas are evaluated automatically to cascade updates and maintain coherence.
All examples below use the SDK API at https://agent.rippletide.com/api/sdk with an x-api-key header. Get your API key from app.rippletide.com under Settings.

​
1. Create an Agent

First, create an agent with a name and system prompt: 
import os
import requests

API_KEY = os.environ["RIPPLETIDE_API_KEY"]
BASE_URL = "https://agent.rippletide.com/api/sdk"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# Create the agent
response = requests.post(f"{BASE_URL}/agent", headers=headers, json={
    "name": "order-taking-agent",
    "prompt": "You are an order-taking assistant for an electronics store. Help customers choose products, place orders, and track deliveries."
})
agent_id = response.json()["id"]
print(f"Agent created: {agent_id}")
API Reference: Agent Management

​
2. Add Q&A Pairs

Q&A pairs are the foundation of your agent’s knowledge. Each pair teaches the agent how to answer a specific question. 
qa_pairs = [
    {
        "question": "What products can be ordered?",
        "answer": "You can order our latest Samsung TV RED43."
    },
    {
        "question": "What is the price?",
        "answer": "The Samsung TV RED43 costs $990."
    },
    {
        "question": "How long will it take for my order to be delivered?",
        "answer": "Your Samsung TV can be delivered the next day."
    }
]

for qa in qa_pairs:
    requests.post(f"{BASE_URL}/q-and-a", headers=headers, json={
        "question": qa["question"],
        "answer": qa["answer"],
        "agent_id": agent_id
    })
API Reference: Q&A Management - Create, update, and manage your Q&A pairs

​
3. Organize with Tags

Tags group Q&A pairs by topic. This helps the agent retrieve the right knowledge more accurately. 
# Create tags
tags = {}
for tag_name, description in [
    ("high-tech-products", "All products in the high-tech category"),
    ("pricing", "Product prices and discounts"),
    ("delivery", "Delivery dates and shipping information"),
    ("discount", "All types of discounts that can apply on products"),
]:
    resp = requests.post(f"{BASE_URL}/tag", headers=headers, json={
        "name": tag_name,
        "description": description
    })
    tags[tag_name] = resp.json()["id"]

# Link Q&A pairs to tags
# Example: link the pricing Q&A to "high-tech-products" and "pricing" tags
requests.post(f"{BASE_URL}/q-and-a-tag", headers=headers, json={
    "q_and_a_id": "<qa-id-for-price-question>",
    "tag_id": tags["pricing"]
})
API Reference: Tag Management - Create and manage tags for organizing your knowledge base

​
4. Define Actions

Actions are things your agent can do beyond answering questions. Each action has requirements that must be met before it can be triggered. 
actions = [
    {
        "name": "answer_product_question",
        "description": "Answer a question about a product",
        "what_to_do": "Look up the product in the knowledge base and provide accurate information. Requirement: access to the product documentation."
    },
    {
        "name": "add_to_cart",
        "description": "Add a product to the cart",
        "what_to_do": "Add the selected product to the user's cart. Requirement: at least one product must be chosen."
    },
    {
        "name": "checkout",
        "description": "Process checkout",
        "what_to_do": "Process the order checkout. Requirements: at least one product in the cart, discount has been applied if applicable."
    },
    {
        "name": "open_ticket",
        "description": "Open a support ticket when the agent cannot answer",
        "what_to_do": "Create a support ticket for human follow-up. Requirement: collect a contact method (email or phone)."
    },
    {
        "name": "book_meeting",
        "description": "Book a meeting with a sales person",
        "what_to_do": "Schedule a meeting with an available sales person. Requirement: check sales person availability."
    }
]

for action in actions:
    requests.post(f"{BASE_URL}/action", headers=headers, json={
        "agent_id": agent_id,
        **action
    })
API Reference: Action Management - Define and manage actions your agent can perform

​
5. Define States and Transitions

State predicates control the conversation flow. Based on the user’s intent, the agent transitions between states and adapts its behavior. 
state_predicate = {
    "transition_kind": "branch",
    "question_to_evaluate": "What is the user trying to do?",
    "possible_values": ["browse_products", "checkout", "change_delivery"],
    "re_evaluate": True,
    "value_to_node": {
        "browse_products": {
            "transition_kind": "branch",
            "question_to_evaluate": "Has the user chosen a product?",
            "possible_values": ["yes", "no"],
            "value_to_node": {
                "yes": {
                    "transition_kind": "end",
                    "question_to_evaluate": "Great choice! Would you like to add it to your cart?"
                },
                "no": {
                    "transition_kind": "end",
                    "question_to_evaluate": "Let me recommend some products based on your needs."
                }
            }
        },
        "checkout": {
            "transition_kind": "end",
            "question_to_evaluate": "I'll help you complete your purchase."
        },
        "change_delivery": {
            "transition_kind": "branch",
            "question_to_evaluate": "Has the order already been shipped?",
            "possible_values": ["yes", "no"],
            "value_to_node": {
                "yes": {
                    "transition_kind": "end",
                    "question_to_evaluate": "The order has already shipped. Please contact support for address changes."
                },
                "no": {
                    "transition_kind": "end",
                    "question_to_evaluate": "What is the new delivery address?"
                }
            }
        }
    }
}

requests.put(f"{BASE_URL}/state-predicate/{agent_id}", headers=headers, json={
    "state_predicate": state_predicate
})
API Reference: State Predicate Management - Configure state transitions and agent behavior

​
6. Add Guardrails

Guardrails set safety boundaries that the agent enforces at the engine level (not just in the prompt): 
guardrails = [
    "Never reveal internal pricing logic or discount algorithms.",
    "Always direct customers to official policies for legal matters.",
    "Do not process orders for customers who have not confirmed their delivery address."
]

for instruction in guardrails:
    requests.post(f"{BASE_URL}/guardrail", headers=headers, json={
        "agent_id": agent_id,
        "type": "action",
        "instruction": instruction
    })
API Reference: Guardrails API - Ensure your agent operates within safe boundaries

​
Next Steps

Your agent is ready. You can now:

Chat with your agent

Send messages and integrate with LangChain

Evaluate your agent

Test for hallucinations before deploying to production