senEstate — Technical Blueprint

This is a complete technical implementation of senEstate, explaining APIs and Default Knowledge Base.

Index

1. Architectural Overview
2. Authentication & Headers
3. ASCII Workflow Diagram
4. Detailed Endpoint Breakdown
5. What is the Default Knowledge Base?
6. Notes

1. Architectural Overview

The senEstate application is a client-side React application that functions as a user interface for the Sensay API. There is no custom backend; all state, data, and AI logic are managed by Sensay. The application makes secure HTTPS requests directly to the Sensay API endpoints to perform all its functions.

2. Authentication & Headers

All API requests are authenticated using a secret API key provided in the .env file (VITE_SENSAY_API_KEY). This key is sent in the X-ORGANIZATION-SECRET header.

There are two primary contexts for API calls:

1. Admin/Organization Level: Actions performed by the real estate agent, such as creating other agents or managing knowledge bases. These requests use the organization’s secret key.
2. End-User Level: Actions performed by a potential client, such as chatting with an AI agent. These requests include a X-USER-ID header to track the conversation and user context.

3. ASCII Workflow Diagram

This diagram illustrates the flow of data between the users, the React frontend, and the Sensay API

+---------------------------+        +--------------------------------+
|  Real Estate Agent (Admin)|        |   Potential Client (End User)  |
| (Manages Agents/Knowledge)|        |   (Interacts with Live Chat)   |
+-------------+-------------+        +----------------+---------------+
              |                                      |
              v                                      v
+--------------------------------------------------------------------+
|                      senEstate React Frontend                      |
| (Dashboard, Create Agent Form, Knowledge Mgmt, Live Chat UI)       |
+--------------------------------------------------------------------+
              |                      |                      |
              | (Admin Actions)      | (User Actions)       |
              v                      v                      v
+--------------------------------------------------------------------+
|                         Sensay API Backend                         |
|--------------------------------------------------------------------|
|                                                                    |
|  [POST /users] <----------- 1. Initialize User on First Load       |
|                                                                    |
|  [GET /replicas] <----------- 2. Fetch Agents for Dashboard        |
|                                                                    |
|  [POST /replicas] <---------- 3. Create a New AI Agent             |
|                                                                    |
|  [POST /replicas/{id}/kb] <-- 4. Add Knowledge (Guide & Listings)  |
|                                                                    |
|  [GET /replicas/{id}/kb] <--- 5. View Knowledge Items              |
|                                                                    |
|  [DELETE /replicas/{id}/kb/{kb_id}] <--- 6. Delete Knowledge Item  |
|                                                                    |
|  [POST /replicas/{id}/chat] <--- 7. Send/Receive Chat Messages     |
|                                                                    |
+--------------------------------------------------------------------+

4. Detailed Endpoint Breakdown

Here is a step-by-step explanation of each API call in the application’s workflow.

1. Initialize User

• When: On the first application load if no VITE_SENSAY_USER_ID is set in .env and no user ID is found in local storage.
• Endpoint: POST /v1/users
• Purpose: To create a user entity within Sensay, which is required to be the “owner” of an AI agent.
• Sample Request{ "id": "testingUser" }

Sample Response (Success 200):

{"id": "testingUser", "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z"

2. Fetch Agents for Dashboard

• When: The main dashboard page (Index.tsx) loads.
• Endpoint: GET /v1/replicas
• Purpose: To retrieve a list of all AI agents created under the organization’s API key to display them on the dashboard.

Sample Response (Success 200):{ "items": [ { "uuid": "rep_a1b2c3d4e5", "name": "Oak Valley Homes Assistant", "slug": "oak-valley-homes", "short_description": "Your expert guide to properties in the Oak Valley area.", "introduction": "Hello! How can I help you today?", "profile_image": "https://path.to/image.png" } ]

3. Create a New AI Agent

• When: The “Create Agent” form (CreateAgent.tsx) is submitted.
• Endpoint: POST /v1/replicas
• Purpose: To create a new AI agent (a “replica” in Sensay terms) with a specific name, personality, and configuration.

Sample Request: { "name": "Oak Valley Homes Assistant", "shortDescription": "Your expert guide to properties in the Oak Valley area.", "greeting": "Hello! I'm the Oak Valley Homes Assistant. How can I help?", "slug": "oak-valley-homes", "ownerID": "testingUser", "llm": { "provider": "openai", "model": "gpt-4o" }

Sample Response (Success 201):{ "uuid": "rep_a1b2c3d4e5", "name": "Oak Valley Homes Assistant", "short_description": "Your expert guide to properties in the Oak Valley area.", "introduction": "Hello! I'm the Oak Valley Homes Assistant. How can I help?", "slug": "oak-valley-homes", "owner_id": "testingUser", "llm": { "provider": "openai", "model": "gpt-4o" }, "createdAt": "2023-10-27T10:05:00Z" }

4. Add Knowledge to an Agent

1. Immediately after a new agent is created, to add the REAL_ESTATE_AGENT_GUIDE. SEE THIS.
2. When the “Add Property Listing” form (ManageKnowledge.tsx) is submitted.

• Endpoint: POST /v1/replicas/{uuid}/knowledge-base
• Purpose: To upload text-based information that the AI agent will use to answer questions.

Sample Request (for a property listing):{ "title": "Property Listing: 123 Maple Lane", "text": "{\"address\":\"123 Maple Lane\",\"price\":750000,\"bedrooms\":3,\"bathrooms\":2.5,\"sqft\":2200,\"description\":\"A stunning, newly-renovated family home...\",\"virtualTourUrl\":\"https://tour.com/123\",\"photoUrls\":[]}" }

Get Anoop Singh’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Sample Response (Success 202):{ "id": 101, "type": "text", "status": "NEW", "title": "Property Listing: 123 Maple Lane", "createdAt": "2023-10-27T10:10:00Z", "updatedAt": "2023-10-27T10:10:00Z" }

5. View Knowledge Items

• When: The “Manage Knowledge” page (ManageKnowledge.tsx) loads.
• Endpoint: GET /v1/replicas/{uuid}/knowledge-base
• Purpose: To retrieve the list of all knowledge items associated with a specific agent.

Sample Response (Success 200):{ "items": [ { "id": 100, "type": "text", "status": "READY", "title": "Core Instructions: Real Estate Agent Guide", "createdAt": "2023-10-27T10:05:00Z", "updatedAt": "2023-10-27T10:06:00Z" }, { "id": 101, "type": "text", "status": "READY", "title": "Property Listing: 123 Maple Lane", "createdAt": "2023-10-27T10:10:00Z", "updatedAt": "2023-10-27T10:11:00Z" } ] }

6. Delete a Knowledge Item

• When: The user clicks the delete (trash) icon for a knowledge item on the “Manage Knowledge” page.
• Endpoint: DELETE /v1/replicas/{uuid}/knowledge-base/{kb_id}
• Purpose: To permanently remove a piece of information from the agent’s knowledge base.
• Sample Response (Success 200):
• { "success": true }

7. Chat with an Agent

• When: An end-user sends a message in the live chat interface (AgentChat.tsx).
• Endpoint: POST /v1/replicas/{uuid}/chat/completions
• Purpose: To send the user’s message to the AI and receive a generated response. This is the core conversational endpoint.

Sample Request:{ "content": "Tell me about the house on Maple Lane." }

Sample Response (Success 200):{ "content": "Of course! The property at 123 Maple Lane is a beautiful 3-bedroom, 2.5-bathroom home with 2,200 sqft. It features a newly-renovated kitchen and a spacious backyard. You can take a virtual tour here: https://tour.com/123" }

What is the Default Knowledge Base?

Immediately after a new AI agent (a “replica”) is successfully created, the application automatically adds a foundational piece of knowledge to it. This is not a property listing; it’s a detailed set of instructions and guidelines for the AI.

• Location in Code: createReplica function within src/lib/api.ts
• Stored As: Constant REAL_ESTATE_AGENT_GUIDE

What Does It Contain?

The REAL_ESTATE_AGENT_GUIDE provides the AI with a comprehensive “job description.” It’s broken down into three main parts:

1. Persona Definition

• Sets the AI’s personality and tone.
• Example Instructions:
• “You are professional, friendly, and highly knowledgeable.”
• “Your tone should be encouraging and supportive.”
• Purpose: Ensures the AI interacts with clients in a manner reflecting well on the real estate agent it represents.

1. Core Directives (The Rules)

• Fundamental rules the AI must follow in every conversation:

1. Provide Property Information: Use the knowledge base (JSON property listings) to answer questions clearly.
2. Highlight Virtual Tours & Photos: Always share links if they exist in a listing — crucial for client engagement.
3. Answer General Questions: Use general real estate knowledge for broader queries.
4. Be Honest: Do not invent details if information is missing — prevents misinformation and builds trust.
5. Example Interaction

• Demonstrates how to handle a property query:
• Input: Shows the AI the raw JSON format of a property listing.
• Output: Template for the ideal response — friendly, readable, and helpful, with links to virtual tours or photos.

Relevance and Importance

The default knowledge base is arguably the most vital piece of information the AI receives:

• Specialization: Transforms a general-purpose LLM (like GPT-4o) into a specialized real estate assistant.
• Consistency: Ensures every agent starts with the same professional and helpful baseline behavior.
• Structured Data Handling: Teaches the AI to correctly parse JSON property listings and present them conversationally.
• Prevents Hallucination: The “Be Honest” directive reduces the risk of generating incorrect property details.
• Enforces Business Goals: Mandates sharing virtual tours and photos to drive client engagement and potential lead conversion.

In short, the default knowledge base acts as the AI’s “employee handbook” and “training manual,” ensuring it performs professionally and consistently from the very first conversation.

Notes:

To maintain simplicity, and to showcase the MVP in a simpler and more easy to understand way, no new users are created, in a real world, each Real Estate Agent will have a own personal dashboard to manage and create agents under his/her own USER ID.