### Minimal Agent Setup

Source: https://sdk.rippletide.com/documentation/Agent

A basic setup guide to create an agent, add knowledge, and initiate a chat conversation.

```APIDOC
## Minimal Agent Setup

### Description
This example demonstrates the essential steps to set up an agent, add a question-and-answer pair, and perform a basic chat.

### Method
POST

### Endpoint
`/api/sdk/agent`, `/api/sdk/q-and-a`, `/api/sdk/chat/{agent_id}`

### Parameters
#### Request Body (Agent Creation)
- **name** (string) - Required - The name of the agent.
- **prompt** (string) - Required - The system prompt for the agent.

#### Request Body (Add Knowledge)
- **question** (string) - Required - The question to be added.
- **answer** (string) - Required - The answer to the question.
- **agent_id** (string) - Required - The ID of the agent to associate the knowledge with.

#### Request Body (Chat)
- **user_message** (string) - Required - The message from the user.
- **conversation_uuid** (string) - Required - A unique identifier for the conversation.

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

# Create agent
agent_response = requests.post(f"{BASE_URL}/agent", headers=headers, json={
    "name": "my-agent",
    "prompt": "You are a helpful assistant."
})
agent_id = agent_response.json()["id"]

# Add knowledge
requests.post(f"{BASE_URL}/q-and-a", headers=headers, json={
    "question": "What is your purpose?",
    "answer": "I help users with their questions.",
    "agent_id": agent_id
})

# Chat
conversation_id = str(uuid.uuid4())
chat_response = requests.post(f"{BASE_URL}/chat/{agent_id}", headers=headers, json={
    "user_message": "Hello!",
    "conversation_uuid": conversation_id
})
print(chat_response.json()["answer"])
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created agent.
- **answer** (string) - The agent's response to the user's message.
```

--------------------------------

### Python: Minimal Rippletide Agent Setup and Chat

Source: https://sdk.rippletide.com/documentation/Agent

Demonstrates the basic setup for a Rippletide agent, including API key configuration, agent creation, adding Q&A knowledge, and initiating a chat conversation. This template is a starting point for building interactive agents.

```python
import os, uuid, requests

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

# Create agent
agent_response = requests.post(f"{BASE_URL}/agent", headers=headers, json={
    "name": "my-agent",
    "prompt": "You are a helpful assistant."
})
agent_id = agent_response.json()["id"]

# Add knowledge
requests.post(f"{BASE_URL}/q-and-a", headers=headers, json={
    "question": "What is your purpose?",
    "answer": "I help users with their questions.",
    "agent_id": agent_id
})

# Chat
conversation_id = str(uuid.uuid4())
chat_response = requests.post(f"{BASE_URL}/chat/{agent_id}", headers=headers, json={
    "user_message": "Hello!",
    "conversation_uuid": conversation_id
})
print(chat_response.json()["answer"])
```

--------------------------------

### Setup Agent Knowledge Base with Tags - Python

Source: https://sdk.rippletide.com/documentation/get_started

Function that initializes the agent's knowledge base by creating or fetching tags from the Rippletide API. Checks for existing tags to avoid duplicates, then creates new tags as needed for categorizing Q&A content.

```python
def setup_agent_knowledge(agent_id):
    tag_ids = {}
    response = requests.get(f"{BASE_URL}/tag", headers=headers)
    if response.status_code == 200 and response.json():
        tag_ids = {t['name']: t['id'] for t in response.json()["tags"]}
    for tag in Tags:
        tag_name, tag_description = tag.value
        if tag_name in tag_ids.keys():
            continue
        tag_data = {"name": tag_name, "description": tag_description}
        response = requests.post(f"{BASE_URL}/tag", headers=headers, json=tag_data)
        response.raise_for_status()
        tag_ids[tag_name] = response.json()["id"]
```

--------------------------------

### Python: Main Execution Flow

Source: https://sdk.rippletide.com/documentation/get_started

The `main` function orchestrates the agent creation, knowledge setup, and interactive chat. It initializes an agent, sets up its knowledge, and then enters a loop to handle user input and display agent responses. It uses the `create_agent`, `setup_agent_knowledge`, and `chat` functions.

```Python
def main():
    print("Creating a new agent...")
    agent = create_agent()

    agent_id = agent["id"]
    print(f"Created agent with ID: {agent_id=}")

    print("adding knowledge to the agent")
    setup_agent_knowledge(agent_id)
    print("\nAgent is ready! Type your message or 'exit' to quit.")

    conversation_id = str(uuid.uuid4())

    # Example message exchange
    while True:
        user_input = input("\nYou: ")
        if user_input.lower() in ["exit", "quit"]:
            break

        response = chat(agent_id, user_input, conversation_id)
        if response:
            print(f"\nAssistant: {response['answer']}")
        else:
            print("Failed to get a response from the API")


if __name__ == "__main__":
    main()

```

--------------------------------

### Install Rippletide SDK Packages

Source: https://sdk.rippletide.com/documentation/Agent

Installs the necessary Python packages for interacting with the Rippletide SDK and LangChain. This includes the 'requests' library for making HTTP requests and 'langchain-openai' for potential OpenAI integrations.

```bash
pip install requests langchain-openai
```

--------------------------------

### Define Agent Actions and States in Rippletide

Source: https://sdk.rippletide.com/documentation/get_started

Configure available actions that the agent can perform, such as adding products to cart, checkout, opening support tickets, or booking meetings. Each action includes a name, description, and what_to_do instruction that guides the agent's behavior in specific states.

```python
some_actions = [
    {
        "name": "add_product_to_cart",
        "description": "Add a product to the cart",
        "what_to_do": "Add the selected product to the user's cart"
    },
    {
        "name": "checkout",
        "description": "Check out the cart",
        "what_to_do": "Process the checkout for the products in the cart"
    },
    {
        "name": "open_support_ticket",
        "description": "Open a support ticket when the agent cannot answer",
        "what_to_do": "Collect user contact information and open a support ticket"
    },
    {
        "name": "book_meeting",
        "description": "Book a meeting with a sales person",
        "what_to_do": "Schedule a meeting based on sales person availability"
    }
]
```

--------------------------------

### Set Up Actions via HTTP POST

Source: https://sdk.rippletide.com/documentation/get_started

This code snippet demonstrates how to iterate through a list of actions and send them to the /action endpoint using an HTTP POST request. It includes setting up request headers and JSON payload, and checks for successful response.

```python
for action in some_actions:
    action_data = {"agent_id": agent_id, **action}
    response = requests.post(
        f"{BASE_URL}/action",
        headers=headers,
        json=action_data
    )
    response.raise_for_status()
```

--------------------------------

### Authentication and Setup

Source: https://sdk.rippletide.com/documentation/Agent

Configure authentication headers and environment variables required for all Rippletide SDK API requests.

```APIDOC
## Authentication

### Overview
All API requests to the Rippletide SDK require authentication via an API key passed in the request headers.

### Base URL
`https://agent.rippletide.com/api/sdk`

### Required Headers
```
x-api-key: your-api-key-here
Content-Type: application/json
```

### Environment Setup
Set your API key as an environment variable:
```bash
export RIPPLETIDE_API_KEY="your-api-key-here"
```

### Python Example
```python
import os
import requests

RIPPLETIDE_API_KEY = os.environ["RIPPLETIDE_API_KEY"]
BASE_URL = "https://agent.rippletide.com/api/sdk"

headers = {
    "x-api-key": RIPPLETIDE_API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/agent",
    headers=headers,
    json={
        "name": "my-agent",
        "prompt": "You are a helpful assistant."
    }
)
```

### Error Handling
- **401 Unauthorized**: Invalid or missing API key
- **403 Forbidden**: API key lacks required permissions
- **429 Too Many Requests**: Rate limit exceeded
```

--------------------------------

### Initialize Rippletide SDK with API Configuration - Python

Source: https://sdk.rippletide.com/documentation/get_started

Sets up the Rippletide SDK environment by loading the API key from environment variables and configuring request headers. This initialization is required before making any API calls to the Rippletide agent service.

```python
import os
import uuid
import requests
from enum import Enum

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

--------------------------------

### Complete Rippletide Agent Example (Python)

Source: https://sdk.rippletide.com/documentation/Agent

A complete Python script demonstrating the workflow of creating an agent, adding knowledge, and engaging in a conversation. This example utilizes the previously defined functions for agent creation, knowledge addition, and chatting.

```python
def main():
    # Create agent
    agent = create_agent()
    agent_id = agent["id"]
    print(f"Created agent: {agent_id}")

    # Add knowledge
    add_knowledge(agent_id, "What is Rippletide?", "Rippletide is a platform for building reliable AI agents with minimal hallucinations.")
    print("Added knowledge")

    # Start conversation
    conversation_id = str(uuid.uuid4())
    response = chat(agent_id, "What is Rippletide?", conversation_id)
    print(f"Agent response: {response['answer']}")

if __name__ == "__main__":
    main()
```

--------------------------------

### Basic Chat Usage - Python Example

Source: https://sdk.rippletide.com/documentation/Agent

Demonstrates instantiation of RippletideChat class and sending a message to retrieve an agent response. Shows typical usage pattern with API key initialization and message handling.

```python
# Usage
chat = RippletideChat(agent_id, RIPPLETIDE_API_KEY)
response = chat.send_message("Hello, I need help with my order")
print(response)
```

--------------------------------

### Python: Create Agent and Set Up Knowledge

Source: https://sdk.rippletide.com/documentation/get_started

This Python code snippet demonstrates the process of creating a new agent, setting up its knowledge base with Q&A pairs, tags, guardrails, state predicates, and actions. It utilizes the `requests` library to interact with the Rippletide API. Dependencies include the `requests` library and `uuid` for conversation IDs.

```Python
import requests
import uuid

BASE_URL = "http://localhost:8000" # Replace with your actual API base URL
headers = {"Content-Type": "application/json"} # Replace with your actual headers if needed

def create_agent():
    response = requests.post(f"{BASE_URL}/agent")
    response.raise_for_status()
    return response.json()

def setup_agent_knowledge(agent_id):
    # Assume q_and_a, some_guardrails, predicate_state, some_actions are defined elsewhere
    # Example placeholders:
    q_and_a = {"question": "What is Rippletide?", "answer": "Rippletide is an AI platform.", "tags": ["general", "ai"]}
    tag_ids = {"general": "tag1", "ai": "tag2"} # Assume tag_ids are pre-fetched or managed
    some_guardrails = [{"name": "profanity_filter", "value": "block"}]
    predicate_state = {"state": "initial"}
    some_actions = [{"name": "send_email", "parameters": {"to": "test@example.com"}}]

    # Add Q and A
    q_and_a_data = {
        "answer": q_and_a["answer"],
        "agent_id": agent_id
    }
    response = requests.post(f"{BASE_URL}/q-and-a", headers=headers, json=q_and_a_data)
    response.raise_for_status()
    q_and_a_id = response.json()["id"]

    # Link QAndA to tags
    for tag_name in q_and_a["tags"]:
        if tag_name in tag_ids:
            q_and_a_tag_data = {"q_and_a_id": q_and_a_id, "tag_id": tag_ids[tag_name]}
            requests.post(f"{BASE_URL}/q-and-a-tag", headers=headers, json=q_and_a_tag_data)

    # Set up guardrails
    for guardrail in some_guardrails:
        guardrail_data = {"agent_id": agent_id, **guardrail}
        response = requests.post(f"{BASE_URL}/guardrail", headers=headers, json=guardrail_data)
        response.raise_for_status()

    # Set up state predicate
    response = requests.put(f"{BASE_URL}/state-predicate/{agent_id}", headers=headers, json={"state_predicate": predicate_state})
    response.raise_for_status()

    # Set up actions
    for action in some_actions:
        action_data = {"agent_id": agent_id, **action}
        response = requests.post(f"{BASE_URL}/action", headers=headers, json=action_data)
        response.raise_for_status()

```

--------------------------------

### Configure Q&A Knowledge Base - Python

Source: https://sdk.rippletide.com/documentation/get_started

Defines Q&A pairs with associated tags that form the agent's knowledge base. Each pair includes a question, answer, and relevant tags for context matching during user interactions.

```python
small_q_and_a = [
    {
        "question": "What is the price?",
        "answer": "The Samsung TV RED43 costs $990",
        "tags": [Tags.HIGH_TECH_PRODUCTS.value[0], Tags.DISCOUNT.value[0]]
    }
]
```

--------------------------------

### Setup Knowledge Base with Q&A and Tags (Python)

Source: https://sdk.rippletide.com/documentation/Agent

This function sets up a knowledge base by creating question-and-answer pairs and associating them with relevant tags. It makes POST requests to the Rippletide API to create Q&A entries, tags, and link them together. Dependencies include the 'requests' library and predefined BASE_URL and headers.

```python
import requests

BASE_URL = "http://your-rippletide-api.com"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

def setup_knowledge_base(agent_id):
    q_and_a_pairs = [
        {
            "question": "What are your business hours?",
            "answer": "We are open Monday through Friday from 9 AM to 6 PM EST, and Saturday from 10 AM to 4 PM EST. We are closed on Sundays.",
            "tags": ["business_hours", "contact_info"]
        },
        {
            "question": "How can I track my order?",
            "answer": "You can track your order by logging into your account and going to the 'My Orders' section, or by using the tracking number sent to your email.",
            "tags": ["orders", "tracking", "account"]
        },
        {
            "question": "What is your return policy?",
            "answer": "We offer a 30-day return policy for most items. Items must be in original condition with tags attached. Electronics have a 14-day return window.",
            "tags": ["returns", "policy", "electronics"]
        }
    ]

    for qa in q_and_a_pairs:
        # Create Q&A
        qa_response = requests.post(
            f"{BASE_URL}/q-and-a",
            headers=headers,
            json={
                "question": qa["question"],
                "answer": qa["answer"],
                "agent_id": agent_id
            }
        )
        qa_id = qa_response.json()["id"]

        # Create and link tags
        for tag_name in qa["tags"]:
            # Create tag if it doesn't exist
            tag_response = requests.post(
                f"{BASE_URL}/tag",
                headers=headers,
                json={
                    "name": tag_name,
                    "description": f"Tag for {tag_name} related content"
                }
            )
            tag_id = tag_response.json()["id"]

            # Link Q&A to tag
            requests.post(
                f"{BASE_URL}/q-and-a-tag",
                headers=headers,
                json={
                    "q_and_a_id": qa_id,
                    "tag_id": tag_id
                }
            )

```

--------------------------------

### Python: Configure Rippletide Agent State Management

Source: https://sdk.rippletide.com/documentation/Agent

Illustrates how to manage conversation flow using state predicates in Rippletide. This example sets up a branching logic based on user input to guide the conversation towards different outcomes.

```python
# Set conversation flow
state_predicate = {
    "transition_kind": "branch",
    "question_to_evaluate": "What does the user need?",
    "possible_values": ["help", "info", "support"],
    "value_to_node": {
        "help": {"transition_kind": "end", "question_to_evaluate": "How can I help?"},
        "info": {"transition_kind": "end", "question_to_evaluate": "What information do you need?"},
        "support": {"transition_kind": "end", "question_to_evaluate": "I'll connect you with support."}
    }
}

requests.put(f"{BASE_URL}/state-predicate/{agent_id}", headers=headers, json={
    "state_predicate": state_predicate
})
```

--------------------------------

### Initialize Ecommerce Support Agent (Python)

Source: https://sdk.rippletide.com/documentation/Agent

Initializes the complete agent setup by creating the agent, setting up its knowledge base, actions, guardrails, and state predicate. It then prints the agent ID upon readiness. This function is crucial for preparing the agent for interaction.

```python
def initialize(self):
    """Initialize the complete agent setup."""
    print("Creating agent...")
    self.create_agent()

    print("Setting up knowledge base...")
    self.setup_knowledge_base()

    print("Setting up actions...")
    self.setup_actions()

    print("Setting up guardrails...")
    self.setup_guardrails()

    print("Setting up state predicate...")
    self.setup_state_predicate()

    print(f"Agent ready! ID: {self.agent_id}")
```

--------------------------------

### Create Rippletide Agent via API - Python

Source: https://sdk.rippletide.com/documentation/get_started

HTTP POST request function that creates a new agent instance on the Rippletide platform with a name and system prompt. Returns the agent configuration including the assigned agent ID for subsequent operations.

```python
def create_agent():
    url = f"{BASE_URL}/agent"
    data = {"name": "example-agent", "prompt": "Interact with the user to understand which product he might be interested in and suggest him the best offer. Once done, complete his order."}
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()
```

--------------------------------

### LangChain Integration

Source: https://sdk.rippletide.com/documentation/Agent

Provides an example of integrating the Rippletide agent with LangChain for advanced LLM applications.

```APIDOC
## LangChain Integration

### Description
This example shows how to configure LangChain's `AzureChatOpenAI` to work with a Rippletide agent, enabling complex agentic workflows within the LangChain ecosystem.

### Method
N/A (Client-side configuration)

### Endpoint
N/A

### Parameters
This is a client-side code configuration. Parameters are specific to the LangChain `AzureChatOpenAI` class and Rippletide's required headers.

### Request Example
```python
from langchain_openai import AzureChatOpenAI

rippletide_llm = AzureChatOpenAI(
    model="v1",
    api_key=RIPPLETIDE_API_KEY,
    azure_endpoint="https://agent.rippletide.com",
    azure_deployment="v1",
    api_version="2024-12-01-preview",
    openai_api_type="azure",
    default_headers={
        "x-rippletide-agent-id": agent_id,
        "x-rippletide-conversation-id": conversation_id,
    },
)
```

### Response
This integration does not directly involve an API response but rather the instantiation of a LangChain LLM object configured for Rippletide.
```

--------------------------------

### Set Up Actions for E-commerce Agent (Python)

Source: https://sdk.rippletide.com/documentation/Agent

Defines and sets up available actions for the e-commerce support agent. This involves specifying action names and descriptions, which can then be used by the agent to perform tasks. The example provided shows the structure for defining a 'create_support_ticket' action.

```python
    def setup_actions(self):
        """Set up available actions for the agent."""
        actions = [
            {
                "name": "create_support_ticket",
                "description": "Create a support ticket for complex issues",

```

--------------------------------

### Create Agent with Rippletide API

Source: https://sdk.rippletide.com/documentation/get_started

Initialize a Rippletide agent by making a POST request to the agent endpoint with a name and initial prompt. Requires authentication via API key stored in environment variables. Returns agent object containing the agent ID needed for subsequent operations.

```python
import os
import uuid
import requests
from enum import Enum

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

def create_agent():
    url = f"{BASE_URL}/agent"
    data = {"name": "example-agent", "prompt": "Interact with the user to understand which product he might be interested in and suggest him the best offer. Once done, complete his order."}

    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# Create the agent
agent = create_agent()
agent_id = agent["id"]
```

--------------------------------

### Error Handling and Troubleshooting

Source: https://sdk.rippletide.com/documentation/Agent

A guide to common issues, error handling strategies, and debugging tips for the Rippletide SDK.

```APIDOC
## Error Handling and Troubleshooting

### Description
This section covers common problems encountered when using the Rippletide SDK, including authentication, rate limiting, and invalid inputs, along with practical debugging advice.

### Common Issues
1. **Authentication Errors**: Ensure the `RIPPLETIDE_API_KEY` environment variable is correctly set.
2. **Rate Limiting**: Implement retry logic with exponential backoff for requests that return a `429` status code.
3. **Invalid Agent ID**: Validate agent IDs using `uuid.UUID` to ensure they are in the correct format.

### Debugging Tips
1. **Enable Request Logging**: Configure Python's `logging` module to capture detailed information about requests.
2. **Test API Connectivity**: Use a health check endpoint (e.g., `/health`) to verify basic API accessibility.

### Common Patterns
#### Error Handling
A `safe_api_call` function can be implemented to wrap API requests, catching exceptions and returning `None` or logging errors.

```python
def safe_api_call(url, headers, json_data):
    try:
        response = requests.post(url, headers=headers, json=json_data)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API Error: {e}")
        return None
```

#### Batch Knowledge Addition
For efficiency, knowledge can be added in batches using a loop and the `add_knowledge_batch` function.

```python
def add_knowledge_batch(agent_id, qa_pairs):
    for question, answer in qa_pairs:
        requests.post(f"{BASE_URL}/q-and-a", headers=headers, json={
            "question": question,
            "answer": answer,
            "agent_id": agent_id
        })
```
```

--------------------------------

### Python Environment Setup for Rippletide SDK

Source: https://sdk.rippletide.com/documentation/Agent

Initializes Python environment variables and headers required for making authenticated requests to the Rippletide SDK API. It retrieves the API key from environment variables and defines the base URL and content type for requests.

```python
import os
import uuid
import requests

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

--------------------------------

### Set Agent Guardrails and Instructions - Python

Source: https://sdk.rippletide.com/documentation/get_started

Defines behavioral guardrails as action-type instructions that constrain the agent's responses and actions. These guardrails ensure the agent maintains professional conduct and adheres to business rules during conversations.

```python
some_guardrails = [
    {"type": "action", "instruction": "Always stay professional"},
    {"type": "action", "instruction": "Never talk about pricing"}
]
```

--------------------------------

### Define Q&A Knowledge Base with Tags in Rippletide

Source: https://sdk.rippletide.com/documentation/get_started

Create question-answer pairs and organize them using tags that describe glossary terms. This snippet defines tag enums, fetches existing tags, creates new tags via API, then creates Q&A entries and links them to tags. Tags help the agent categorize and retrieve relevant knowledge.

```python
from enum import Enum

class Tags(Enum):
    HIGH_TECH_PRODUCTS = ("high_tech_products", "all products in high-tech category")
    DELIVERY_DATE = ("delivery_date", "the date the customer will receive his product")
    PURCHASE_HISTORY = ("purchase_history", "the list of all product bought")
    DISCOUNT = ("discount", "all types of discount that can apply on products")

small_q_and_a = [
    {
        "question": "What is the price?",
        "answer": "The Samsung TV RED43 costs $990",
        "tags": [Tags.HIGH_TECH_PRODUCTS.value[0], Tags.DISCOUNT.value[0]],
    },
]
# Fetch already existing tags
response = requests.get(
    f"{BASE_URL}/tag",
    headers=headers,
)
if response.status_code == 200 and response.json():
    tag_ids = {t['name']: t['id'] for t in response.json()["tags"]}

for tag in Tags:
    tag_name, tag_description = tag.value

    if tag_name in tag_ids.keys():
        continue

    tag_data = {"name": tag_name, "description": tag_description}

    # create tag
    response = requests.post(
        f"{BASE_URL}/tag",
        headers=headers,
        json=tag_data
    )
    response.raise_for_status()
    tag_ids[tag_name] = response.json()["id"]

# Create Q&As and link them to tags
for faq in small_q_and_a:
    faq_data = {
        "question": faq["question"],
        "answer": faq["answer"],
        "agent_id": agent_id
    }

    response = requests.post(
        f"{BASE_URL}/q-and-a",
        headers=headers,
        json=faq_data
    )
    response.raise_for_status()
    faq_id = response.json()["id"]

    # Link FAQ to tags
    for tag_name in faq["tags"]:
        if tag_name in tag_ids:
            faq_tag_data = {"q_and_a_id": faq_id, "tag_id": tag_ids[tag_name]}
            requests.post(
                f"{BASE_URL}/q-and-a-tag",
                headers=headers,
                json=faq_tag_data
            )
```

--------------------------------

### Configure State Machine Predicate Logic - Python

Source: https://sdk.rippletide.com/documentation/get_started

Defines complex conversation flow logic using a tree-based state machine with branching conditions and transitions. The predicate evaluates user needs and routes to appropriate next states based on possible values and node mappings.

```python
predicate_state = {
    "transition_kind": "branch",
    "question_to_evaluate": "The user described his needs",
    "possible_values": ["recommend_product", "describe_discount_mechanism"],
    "re_evaluate": True,
    "value_to_node": {
        "recommend_product": {
            "transition_kind": "go_to_next",
            "question_to_evaluate": "A product has been chosen",
            "next_node": {
                "transition_kind": "branch",
                "question_to_evaluate": "What would you like to do next?",
                "possible_values": ["ask_delivery_date", "checkout", "add_discount", "delete_product"],
                "value_to_node": {
                    "ask_delivery_date": {
                        "transition_kind": "end",
                        "question_to_evaluate": "When would you like your product delivered?"
                    },
                    "checkout": {
                        "transition_kind": "end",
                        "question_to_evaluate": "Proceeding to checkout."
                    },
                    "add_discount": {
                        "transition_kind": "end",
                        "question_to_evaluate": "Applying available discounts."
                    },
                    "delete_product": {
                        "transition_kind": "end",
                        "question_to_evaluate": "Product removed from cart."
                    }
                }
            }
        },
        "describe_discount_mechanism": {
            "transition_kind": "end",
            "question_to_evaluate": "Let me explain how discounts work."
        }
    }
}
```

--------------------------------

### Define and Set Up State Predicate via HTTP PUT

Source: https://sdk.rippletide.com/documentation/get_started

This snippet shows how to define a complex state predicate, which governs the conversational flow of an agent, and then set it up using an HTTP PUT request to the /state-predicate/{agent_id} endpoint. It includes nested branching logic and transition types.

```python
predicate_state = {
    "transition_kind": "branch",
    "question_to_evaluate": "The user described his needs",
    "possible_values": ["recommend_product", "describe_discount_mechanism"],
    "re_evaluate": True,
    "value_to_node": {
        "recommend_product": {
            "transition_kind": "go_to_next",
            "question_to_evaluate": "A product has been chosen",
            "next_node": {
                "transition_kind": "branch",
                "question_to_evaluate": "What would you like to do next?",
                "possible_values": ["ask_delivery_date", "checkout", "add_discount", "delete_product"],
                "value_to_node": {
                    "ask_delivery_date": {
                        "transition_kind": "end",
                        "question_to_evaluate": "When would you like your product delivered?"
                    },
                    "checkout": {
                        "transition_kind": "end",
                        "question_to_evaluate": "Proceeding to checkout."
                    },
                    "add_discount": {
                        "transition_kind": "end",
                        "question_to_evaluate": "Applying available discounts."
                    },
                    "delete_product": {
                        "transition_kind": "end",
                        "question_to_evaluate": "Product removed from cart."
                    }
                }
            }
        },
        "describe_discount_mechanism": {
            "transition_kind": "end",
            "question_to_evaluate": "Let me explain how discounts work."
        }
    }
}

# Set up state predicate
response = requests.put(
    f"{BASE_URL}/state-predicate/{agent_id}",
    headers=headers,
    json={"state_predicate": predicate_state}
)
response.raise_for_status()
```

--------------------------------

### Agent Management API

Source: https://sdk.rippletide.com/documentation/Agent

Endpoints for creating, retrieving, and updating agents.

```APIDOC
## POST /agent

### Description
Creates a new agent.

### Method
POST

### Endpoint
/agent

### Parameters
#### Request Body
- **name** (string) - Required - The name of the agent.
- **description** (string) - Optional - A description for the agent.

### Request Example
```json
{
  "name": "Customer Support Bot",
  "description": "Handles customer inquiries."
}
```

### Response
#### Success Response (200)
- **agent_id** (string) - The unique identifier of the created agent.

#### Response Example
```json
{
  "agent_id": "agent_123"
}
```

## GET /agent/{id}

### Description
Retrieves details for a specific agent.

### Method
GET

### Endpoint
/agent/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **agent_id** (string) - The unique identifier of the agent.
- **name** (string) - The name of the agent.
- **description** (string) - The description of the agent.

#### Response Example
```json
{
  "agent_id": "agent_123",
  "name": "Customer Support Bot",
  "description": "Handles customer inquiries."
}
```

## PUT /agent/{id}

### Description
Updates an existing agent.

### Method
PUT

### Endpoint
/agent/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent to update.
#### Request Body
- **name** (string) - Optional - The new name for the agent.
- **description** (string) - Optional - The new description for the agent.

### Request Example
```json
{
  "description": "Updated description for the bot."
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the agent was updated.

#### Response Example
```json
{
  "message": "Agent updated successfully."
}
```
```

--------------------------------

### Action Management API

Source: https://sdk.rippletide.com/documentation/Agent

APIs for creating and managing agent actions.

```APIDOC
## Action Management API

### Create Action

#### Description
Creates a new action for an agent.

#### Method
POST

#### Endpoint
/action

#### Request Body
- **name** (string) - Required - The name of the action.
- **description** (string) - Optional - A description of the action.
- **what_to_do** (string) - Required - Detailed instructions on how to perform the action.
- **agent_id** (string) - Required - The ID of the agent this action belongs to.
```

--------------------------------

### Tag Management API

Source: https://sdk.rippletide.com/documentation/Agent

APIs for managing tags and linking them to Q&A pairs.

```APIDOC
## Tag Management API

### Create Tag

#### Description
Creates a new tag.

#### Method
POST

#### Endpoint
/tag

#### Request Body
- **name** (string) - Required - The name of the tag.
- **description** (string) - Optional - A description for the tag.

### Link Q&A to Tag

#### Description
Associates a Q&A pair with a tag.

#### Method
POST

#### Endpoint
/q-and-a-tag

#### Request Body
- **q_and_a_id** (string) - Required - The ID of the Q&A pair.
- **tag_id** (string) - Required - The ID of the tag.
```

--------------------------------

### State Predicate Management API

Source: https://sdk.rippletide.com/documentation/Agent

APIs for setting and managing state predicates for agents.

```APIDOC
## State Predicate Management API

### Set State Predicate

#### Description
Sets or updates the state predicate for an agent, defining conversational flow and branching logic.

#### Method
PUT

#### Endpoint
/state-predicate/{agent_id}

#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent to set the state predicate for.

#### Request Body
- **state_predicate** (object) - Required - The state predicate configuration.
    - **transition_kind** (string) - Required - The type of transition (e.g., 'branch', 'end').
    - **question_to_evaluate** (string) - Required - The question to evaluate for determining the next state.
    - **possible_values** (array of strings) - Required - A list of possible values for the evaluated question.
    - **value_to_node** (object) - Required - Maps possible values to their corresponding next states.
        - **[value]** (object) - Represents a specific next state.
            - **transition_kind** (string) - Required - The transition kind for this state (e.g., 'end').
            - **question_to_evaluate** (string) - Required - The message to display when ending the conversation.
```

--------------------------------

### Install Langchain and OpenAI Dependencies

Source: https://sdk.rippletide.com/documentation/agent_chat

Install required Python packages for Langchain integration with OpenAI. This step is necessary before using Rippletide agents as LLMs in Langchain workflows.

```bash
pip install langchain langchain-openai
```

--------------------------------

### Agent Action Management API

Source: https://sdk.rippletide.com/documentation/Agent

Endpoint for creating agent actions.

```APIDOC
## POST /action

### Description
Creates a new action for an agent.

### Method
POST

### Endpoint
/action

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent to associate the action with.
- **name** (string) - Required - The name of the action.
- **description** (string) - Optional - A description of the action.
- **action_type** (string) - Required - The type of action (e.g., 'API_CALL', 'FUNCTION').
- **config** (object) - Required - Configuration details for the action.

### Request Example
```json
{
  "agent_id": "agent_123",
  "name": "GetOrderStatus",
  "action_type": "API_CALL",
  "config": {
    "url": "https://api.example.com/orders/{order_id}",
    "method": "GET"
  }
}
```

### Response
#### Success Response (200)
- **action_id** (string) - The unique identifier of the created action.

#### Response Example
```json
{
  "action_id": "action_pqr"
}
```
```

--------------------------------

### Guardrail Management API

Source: https://sdk.rippletide.com/documentation/Agent

APIs for creating and managing guardrails for agents.

```APIDOC
## Guardrail Management API

### Create Guardrail

#### Description
Creates a new guardrail for an agent, defining constraints or instructions.

#### Method
POST

#### Endpoint
/guardrail

#### Request Body
- **type** (string) - Required - The type of guardrail (e.g., 'action').
- **instruction** (string) - Required - The specific instruction or rule for the guardrail.
- **agent_id** (string) - Required - The ID of the agent this guardrail applies to.
```

--------------------------------

### Tag Management API

Source: https://sdk.rippletide.com/documentation/Agent

Endpoints for creating tags and linking knowledge entries to tags.

```APIDOC
## POST /tag

### Description
Creates a new tag.

### Method
POST

### Endpoint
/tag

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tag.

### Request Example
```json
{
  "name": "pricing"
}
```

### Response
#### Success Response (200)
- **tag_id** (string) - The unique identifier of the created tag.

#### Response Example
```json
{
  "tag_id": "tag_xyz"
}
```

## POST /q-and-a-tag

### Description
Links a knowledge entry to a tag.

### Method
POST

### Endpoint
/q-and-a-tag

### Parameters
#### Request Body
- **q_and_a_id** (string) - Required - The ID of the knowledge entry.
- **tag_id** (string) - Required - The ID of the tag.

### Request Example
```json
{
  "q_and_a_id": "knowledge_abc",
  "tag_id": "tag_xyz"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the link was created.

#### Response Example
```json
{
  "message": "Knowledge linked to tag successfully."
}
```
```

--------------------------------

### Chat Interface API

Source: https://sdk.rippletide.com/documentation/Agent

APIs for interacting with agents through a chat interface.

```APIDOC
## Chat Interface API

### Send Message

#### Description
Sends a user message to an agent and receives a response.

#### Method
POST

#### Endpoint
/chat/{agent_id}

#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent to chat with.

#### Request Body
- **user_message** (string) - Required - The message sent by the user.
- **conversation_uuid** (string) - Optional - The unique identifier for the current conversation. If not provided, a new conversation will be initiated.

#### Success Response (200)
- **answer** (string) - The agent's response to the user's message.
- **conversation_uuid** (string) - The unique identifier for the conversation.
```

--------------------------------

### GET /agent/{agent_id}

Source: https://sdk.rippletide.com/documentation/Agent

Retrieves the configuration and details of a specific agent by its unique identifier.

```APIDOC
## GET /agent/{agent_id}

### Description
Retrieves detailed information about a specific agent including its configuration and system prompt.

### Method
GET

### Endpoint
`https://agent.rippletide.com/api/sdk/agent/{agent_id}`

### Path Parameters
- **agent_id** (string) - Required - The UUID of the agent to retrieve

### Authentication
Required header: `x-api-key` with your API key

### Response
#### Success Response (200)
- **id** (string) - UUID of the agent
- **name** (string) - The agent name
- **prompt** (string) - The agent system prompt

#### Response Example
```json
{
  "id": "agent-uuid",
  "name": "my-agent",
  "prompt": "You are a helpful assistant that provides accurate information based on your knowledge base."
}
```
```

--------------------------------

### Set Up Knowledge Base for E-commerce Agent (Python)

Source: https://sdk.rippletide.com/documentation/Agent

Configures the knowledge base for the e-commerce support agent by creating tags and then question-answer pairs linked to these tags. It iterates through a predefined list of Q&A items, making POST requests to '/tag' and '/q-and-a' endpoints, and then linking them via '/q-and-a-tag'. Requires the agent to be created first.

```python
    def setup_knowledge_base(self):
        """Set up the complete knowledge base."""
        knowledge_items = [
            {
                "question": "What are your business hours?",
                "answer": "We are open Monday through Friday from 9 AM to 6 PM EST, and Saturday from 10 AM to 4 PM EST. We are closed on Sundays and major holidays.",
                "tags": ["business_hours", "contact_info"]
            },
            {
                "question": "How can I track my order?",
                "answer": "You can track your order in three ways: 1) Log into your account and go to 'My Orders', 2) Use the tracking number sent to your email, or 3) Contact us with your order number.",
                "tags": ["orders", "tracking", "account"]
            },
            {
                "question": "What is your return policy?",
                "answer": "We offer a 30-day return policy for most items. Items must be in original condition with tags attached. Electronics have a 14-day return window. Returns are free for defective items.",
                "tags": ["returns", "policy", "electronics"]
            },
            {
                "question": "How long does shipping take?",
                "answer": "Standard shipping takes 3-5 business days. Express shipping takes 1-2 business days. International shipping takes 7-14 business days depending on the destination.",
                "tags": ["shipping", "delivery", "international"]
            },
            {
                "question": "Do you offer international shipping?",
                "answer": "Yes, we ship to most countries worldwide. International shipping takes 7-14 business days and additional customs fees may apply. Check our shipping page for specific country restrictions.",
                "tags": ["shipping", "international", "customs"]
            }
        ]

        # Create tags first
        tag_ids = {}
        for item in knowledge_items:
            for tag_name in item["tags"]:
                if tag_name not in tag_ids:
                    tag_response = requests.post(
                        f"{self.base_url}/tag",
                        headers=self.headers,
                        json= {
                            "name": tag_name,
                            "description": f"Tag for {tag_name.replace('_', ' ')} related content"
                        }
                    )
                    tag_ids[tag_name] = tag_response.json()["id"]

        # Create Q&A pairs and link to tags
        for item in knowledge_items:
            qa_response = requests.post(
                f"{self.base_url}/q-and-a",
                headers=self.headers,
                json= {
                    "question": item["question"],
                    "answer": item["answer"],
                    "agent_id": self.agent_id
                }
            )
            qa_id = qa_response.json()["id"]

            # Link to tags
            for tag_name in item["tags"]:
                requests.post(
                    f"{self.base_url}/q-and-a-tag",
                    headers=self.headers,
                    json= {
                        "q_and_a_id": qa_id,
                        "tag_id": tag_ids[tag_name]
                    }
                )
```

--------------------------------

### Python: Test API Connectivity

Source: https://sdk.rippletide.com/documentation/Agent

Checks if the application can successfully connect to the Rippletide API by making a GET request to the /health endpoint. Returns True if the status code is 200, indicating a successful connection, and False otherwise.

```python
def test_api_connection():
    try:
        response = requests.get(f"{BASE_URL}/health", headers=headers)
        return response.status_code == 200
    except:
        return False
```

--------------------------------

### Python: Set Up Technical Support Actions

Source: https://sdk.rippletide.com/documentation/Agent

Defines and registers a list of technical support actions that the agent can perform. Each action includes a name, description, and a 'what_to_do' field. These actions are posted to the SDK's action endpoint.

```python
import requests

# (Assuming TechnicalSupportAgent class is defined as above)

    def setup_technical_actions(self):
        """Set up technical support actions."""
        actions = [
            {
                "name": "collect_system_info",
                "description": "Collect system information for troubleshooting",
                "what_to_do": "Ask user to provide system specs, OS version, and error messages"
            },
            {
                "name": "schedule_remote_session",
                "description": "Schedule a remote support session",
                "what_to_do": "Collect user availability and schedule a remote support session"
            },
            {
                "name": "escalate_to_engineering",
                "description": "Escalate complex technical issues to engineering team",
                "what_to_do": "Document the issue and escalate to the engineering team for investigation"
            }
        ]

        for action in actions:
            requests.post(
                f"{self.base_url}/action",
                headers=self.headers,
                json={
                    "agent_id": self.agent_id,
                    **action
                }
            )
```

--------------------------------

### Define Tags Enum for Agent Knowledge - Python

Source: https://sdk.rippletide.com/documentation/get_started

Creates an enumeration of tags used to categorize and organize the agent's knowledge base. Tags help the system understand and categorize Q&A pairs, enabling better context matching during conversations.

```python
class Tags(Enum):
    HIGH_TECH_PRODUCTS = ("high_tech_products", "all products in high-tech category")
    DELIVERY_DATE = ("delivery_date", "the date the customer will receive his product")
    PURCHASE_HISTORY = ("purchase_history", "the list of all product bought")
    DISCOUNT = ("discount", "all types of discount that can apply on products")
```